The sections that follow describe how to expose and use repository item properties as part of your promotions template.
Note: If creating a template using a custom discount type, make sure the PMDL in that template sets the discount-type
attribute correctly.
The item-properties
section of the PMDT file complements the ui-description
and allows you to set promotion properties using the place-holder-value
attributes of the template elements. The property
statements are based around a separate grammar from that used in the UI portion of the template.
The item-properties
section of the template for a beginUsable
and endUsable
looks like the following sample. Note the $ marking where place-holder-value information is inserted:
<property name="beginUsable"> ${beginUsableValue} </property> <property name="endUsable"> ${endUsableValue} </property>
Displaying Static Values in Templates
The default behavior for generating a display name for a property is:
If the resource bundle includes an entry of
"psc.property.<full property name>"
use that value.psc.property.item.auxiliaryData.productRef.ancestorCategoryIds=Categories
If not, get the supported bean from which the property came and check the resource bundle for an entry of
psc.bean.<supported bean name>
. This forms the first part of the display name. If no entry is found, use the display name of the DynamicBeanDescriptor for that bean.psc.bean.product=Product
For each sub-property part of the property name, check the resource bundle for an entry of
psc.property.<sub property part name>
and append that value to the display name. If no entry is found, use the display name of theDynamicPropertyDescriptor
instead.psc.property.amount=Price
Displaying Dynamic Properties in Templates
The content-source
element dynamically obtains information for display in the template. One common use is populating combo boxes (see the Product Set Criteria Elements section), but you can use it to populate any user interface element, provided that the content source’s Nucleus component provides the correct output.
For example, consider this template XML:
<comboBox id="discountType"> <content-source path="/atg/remote/promotion/template/contentSource/ CustomDiscountListContent"> <attribute-value-reference name="calculatorType" element-id="calculatorType"/> </content-source> </comboBox>
The path
attribute is required, and identifies the location of the Nucleus component that returns the dynamic information.
You can use the optional child attribute
element to specify parameters to pass to the Nucleus component. Parameter values are either set explicitly or obtained from the user input to another field in the template user interface. The component returns a ContentState
object that contains the information used to populate the field.
For example, the attribute-value-reference
element in the code shown above tells the content source to watch a second user interface element, that has the element-id="calculatorType"
. The user’s currently selected value for the calculatorType
is assigned the name calculatorType
and sent to the CustomDiscountListContent
component. The component obtains a valid discount list for that calculatorType
.
If the user changes the selected calculatorType
, the new value is sent to the component to obtain an updated discount list for display.
Content source Nucleus components should implement the atg.remote.promotion.
interface. See the ATG Platform API Reference for information on this interface.
template.contentSource.java
Using an Asset Picker in a Promotions Template
If you have included repository item properties in your template, you need to provide a map to the Asset Picker editor needed to manipulate that property. The asset picker is a Flex RepositoryItemSetEditor
component used in many Oracle ATG Web Commerce applications (see the Business Control Center Administration and Development Guide for general information on asset pickers).
The asset picker requires three pieces of information:
A Nucleus path to the repository in which the assets are found
The assets’ repository item type
Whether not multiple assets can be selected
To provide this information, configure the assetPickerPropertyMap
and the assetPickerRepositoryMap
components in the PSCExpressionContext
component.
The assetPickerRepositoryMap
property provides a map of properties to their repositories. The assetPickerPropertyMap
property provides a map of properties to their repository item types. If a property appears in this map, the promotions user interface uses the asset picker editor for that property; otherwise, it defaults to a simple text editor.
Whether or not the asset picker allows multiple selections depends on the operator the user selects; for example, “is” allows only single selection, but “is one of” permits multiple selections.
If a property is included in the assetPickerPropertyMap
, the promotions expression editor displays an asset picker for that property on the right hand side of the product set criteria expression, using the value of the map as the asset type. If an entry for the property is also in the assetPickerRepositoryMap
, the value of this map is used as the repository path for the asset picker.
If a property is in the assetPickerPropertyMap
but not in the assetPickerRepositoryMap
, then the asset picker defaults to using the RepositoryPropertyDescriptor
for that property to determine the repository to use.
This sample shows configuration for the two properties:
assetPickerPropertyMap+=\
item.auxiliaryData.catalogRef.sites=siteConfiguration
assetPickerRepositoryMap+=\
item.auxiliaryData.catalogRef.sites=/atg/multisite/SiteRepository
The resulting user interface would display the Sites
property of the sku
repository item in an asset picker. The picker would use the siteConfiguration
asset type and SiteRepository
.
Automatic Property Filtering in Templates
Oracle ATG Web Commerce repository items used in promotions tend to have many properties that are not useful as promotion criteria. Therefore, the list of properties is filtered by default.
If you add custom properties to your Oracle ATG Web Commerce repository, note that category properties do not appear in the PSC; only product and SKU properties are exposed.
The /atg/remote/promotion/expreditor/psc/PSCExpressionContext
component includes the excludedProperties
property. The value for this property can end in * to exclude all sub-properties of a property. Note that a * does not exclude the referenced property itself, but only its sub-properties. The actual property must be excluded separately. For example:
excludedProperties+=\
item.auxiliaryData.productRef.template.*
The example above excludes all sub-properties of the template
property, but does not exclude the template
property itself. To exclude the template
property, use the following configuration:
excludedProperties+=\
item.auxiliaryData.productRef.template\
item.auxiliaryData.productRef.template.*
The PSCPropertyChoiceExpression
class on which the PSCExpressionContext
component is based extends the PricingPropertyChoiceExpression
class; therefore, it inherits a standard filtering mechanism which by default filters out properties marked as expert = true
or queryable = false
in the repository definition. You can override this behavior using the mandatoryProperties
property of PSCExpressionContext
.
Note that the mandatoryProperties
property does not support wildcards; all mandatory properties must be specified explicitly. This example shows mandatoryProperties
in use:
mandatoryProperties+=\
item.auxiliaryData.productRef.ancestorCategoryIds
This configuration results in the ancestorCategoryIds
property being included, even though this property is marked as expert in the repository.