As part of your template design, take into account whether you need to translate the values users enter into values appropriate for the promotion repository item. For example, you may have a field that allows the user to input a Cents value between 0 and 99. The PMDL expects a dollar amount; therefore, the 25 the user enters must be converted to 0.25. This task is handled by Nucleus components called translators.
Translator components are based on classes that implement the ElementTranslator
interface (see the ATG Platform API Reference for details). Translators are called after any client-side validation takes place. They take the following input:
The element ID
The element type
The raw value to be translated, as entered by the user
A list of
ElementState
objects, which can be used if the translation for the current element is affected by input to another elementA set of known repository property names and values for the item type
The output is a value that can be directly applied to the property based on the placeholder-name
. If further translation is required at this point, you should use a multi-element translator instead.
In addition to basic translation, you may need to combine user-entered values in order to provide a valid PMDL input. For example, it is common to combine the output of an “excludes” product set criteria with an “includes” product set criteria. Components that handle this advanced processing are called multi-element translators; they can take multiple inputs and supply multiple output values.
For example, the provided item discount templates include the UnlimitedDiscountTranslator
. These templates have a discount section that contains a textInput
element, in which the user can enter the number of times a customer can use the discount, and a checkbox
element to indicate unlimited use. The checkbox
element has the following attribute:
placeholder-value-checked="-1"
This attribute means that if the checkbox is selected, the output value is -1.
The UnlimitedDiscountTranslator
takes the user-entered value or the unlimited option and provides a single placeholder
value as output, which either contains the number of items to discount or a -1 to indicate unlimited. The placeholder
value is then inserted in the location of its corresponding placeholder-name
.
For example, the following snippet shows PMDL before translation:
<iterator name="up-to-and-including"
number="${no_of_items_to_discount}" sort-by="priceInfo.listPrice"
sort-order="${sort_order}">
After translation, if the user enters a value, the PMDL looks like the following::
<iterator name="up-to-and-including" number="5" sort
-by="priceInfo.listPrice" sort-order="${sort_order}">
If the user checks unlimited, the PMDL looks like the following:
<iterator name="up-to-and-including" number="-1" sort-
by="priceInfo.listPrice" sort-order="${sort_order}">
Multi-element translators are defined in the ui-description
section of the template within a multi-element-translators
element. For example, the following code shows how the multiElementTranslator
for the unlimited discount functionality is implemented:
<multi-element-translators> <multi-element-translator id="unlimited_discount_translator" translator-path="/atg/remote/promotion/template/translators /UnlimitedDiscountTranslator"> <placeholder-info placeholder-name="no_of_items_to_discount" translator-output-name="itemNumber"/> <element-info element-id="numberOfItemsToDiscount_textInput" translator-input-name="itemNumber"/> <element-info element-id="unlimited_checkbox" translator-input-name="unlimited"/> </multi-element-translator> </multi-element-translators>
The UnlimitedDiscountTranslator
accepts two inputs, which are mapped to the translator-input-name
element’s itemNumber
and to unlimited
in the element-info
child element. The placeholder-info
element maps the placeholder-name
to the translator’s output-name
key.
Input and output names for each translator are defined in its properties file. The properties file for the example UnlimitedDiscountTranslator
above is:
$class=atg.remote.promotion.template.translators.UnlimitedDiscount Translator $scope=session # # Translator inputs # itemNumberInputName=itemNumber unlimitedInputName=unlimited # # Translator outputs # itemNumberOutputName=itemNumber
By default, Oracle ATG Web Commerce includes the following translators:
AssetCollectorTranslator
- Translates selected asset IDs into PMDLRawPMDLTranslator
– Retrieves the PMDL from the promotion item
Commerce also includes the following multi-element translators:
DiscountStructureTranslator
– translates the discount structure PMDLQualifierTranslator
– translates the qualifier PMDLTargetTranslator
– translates the target PMDLDiscountTranslator
– Converts separatediscount type
andadjuster
user interface inputs into separatediscount-type
andadjuster
output values, allowing for a discount type of free.UnlimitedDiscountTranslator
– Sets up the iterator number attribute for PMDL iterators based on amount to discount or unlimited if a checkbox on the user interface is checked.
You can create your own translators based on the provided framework; see the ATG Platform API Reference. Translators should implement either the ElementTranslator.java
or the MultiElementTranslator.java
interface.