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 element

  • A 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:


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"

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-translator id="unlimited_discount_translator"
        <placeholder-info placeholder-name="no_of_items_to_discount"

              <element-info element-id="numberOfItemsToDiscount_textInput"

              <element-info element-id="unlimited_checkbox"

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:

# Translator inputs
# Translator outputs

By default, Oracle ATG Web Commerce includes the following translators:

  • AssetCollectorTranslator - Translates selected asset IDs into PMDL

  • RawPMDLTranslator – Retrieves the PMDL from the promotion item

Commerce also includes the following multi-element translators:

  • DiscountStructureTranslator – translates the discount structure PMDL

  • QualifierTranslator – translates the qualifier PMDL

  • TargetTranslator – translates the target PMDL

  • DiscountTranslator – Converts separate discount type and adjuster user interface inputs into separate discount-type and adjuster 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 or the interface.