Creating the PMDT File

This section describes the main sections that make up the PMDT file from which the template user interface is created.

Template Header

The first part of the template PMDT file is the header, which provides basic information about the template. The header includes the following attributes:

The template header attributes are:

For example:

<template   item-type="Item Discount"
            repository="some/repository/path"
            author="Template Author"
            last-modified-by="Template Author"
            creation-date="28/09/2009">
UI Description Element

If you want your template to appear in the Oracle ATG Web Commerce Merchandising user interface, you must include a ui-description element as part of the template.

If the template has no ui-description section, it is not displayed in Merchandising’s template list. If the template does have a ui-description section then it will appear in the template list unless the available-in-ui attribute is explicitly set to false.

Note: You may not want the template to appear in the UI if the template is intended for importing or exporting promotions (see Importing and Exporting Promotions), or if you want to remove the template from the list from which users can select.

The ui-description tag includes the following attributes, all of which are optional:

  • display-name—String used to label the template in the template list and in the template screen title bar.

  • resource-bundle—Optional. The location of the resource bundle used to represent this template in the UI.

  • display-name-resource—Optional. If the resource-bundle attribute is present, the display-name-resource is used as a key to retrieve the localized value from the indicated resource bundle. If resource-bundle is not present or the specified resource bundle cannot be found, the display-name-resource attribute value is used for display. This attribute overrides the display-name attribute.

  • available-in-ui—Optional. If this attribute is not included in the XML, it defaults to true. If explicitly set to false, the template is not displayed on the template selection screen, even if it has a ui-description section.

UI Description Child Elements

The ui-description can include a number of sub-elements.

The multi-element-translators element is used to combine, translate, or insert values into the item properties. See Translating User Input Values in Templates.

The optional group-info element is used to create the template selection menu. The group-info element has two optional attributes:

  • groupId—If groupId is specified, that template appears grouped with other templates that have the same groupId. If no groupId is specified, the templates are grouped into a default group. Templates within a group appear in ascending alphabetical order unless a templatePriorityId is specified.

  • templatePriorityId—If specified for a template, templates are displayed in ascending priority order rather than ascending alphabetical (the default). Zero designates the highest priority.

Additional elements are structural, and provide layout information for the template page:

  • The screen-segment element provides a means of grouping elements within the template. A screen-segment has a name and however many line elements you want to include.

  • The line element contains user interface items you want to appear as one line to the user, for example a label and its corresponding input area.

A line element is the smallest structural unit of a template.

This example shows a screen segment with a single line of input:

<screen-segment display-name="Condition"
  <line>
    <label id="spendLabel"
           display-name="Spend:"
    <textInput id="spend_textInput"
               placeholder-name="spend_value"/>
    <label id="spend_example_label"
           display-name="ex. 100" styleName="infoText"/>
  </line>
</screen-segment>

The resulting user interface resembles the following:

Line Child Elements

The line element can include any of the following sub-elements

Most of these elements represent standard user interface components. Each can include a number of attributes such as height, label, and a resource bundle reference; see the PMDT.DTD for detailed information.

The following elements are unique to promotions templates, and are described in the sections that follow:

Each element in the user interface has an id attribute, which can be used to identify the user input for that element elsewhere in the template. Elements can also have a place-holder-name attribute. The place-holder-name attribute is used to insert user input into the PMDL statement the template constructs.

Expression Elements

The expression element allows you to support complex, freeform conditional statements such as those used in the Advanced Condition & Offer template. It does this using an independent grammar file, and appears in the user interface as an expression editor.

The expression element functionality is available through the Advanced Condition & Offer page, and has the following attributes:

SwitchableDiscount Element

If the offer type is not Gift with Purchase, the switchableDiscount element allows a user to toggle between the views defined by the beneath it; for example, between the discount amount and a discount structure grid view.

The examples shown are from the Advanced Condition & Offer:

Discount Amount

Discount Structure

The following code sample illustrates the use in the template:

<line>
  <switchableDiscount id="switchable_discount">
    <view>
      <label id="discount_structure_label" display-name-
resource="template.common.discountStructureLabel" container-width="100" container-
h-align="right"/>
      <grid id="discountStructureData"
validator="/atg/remote/promotion/template/validators/TieredItemDiscountValidator">
        <content-source
path="/atg/remote/promotion/template/contentSource/BandedDiscountStructureContents
">
          <attribute-value-reference name="calculatorType" element-
id="calculatorType"/>
        </content-source>
      </grid>
    </view>
    <view>
      <label id="discount_amount_label" display-name-
resource="template.common.discountAmountLabel" container-width="100" container-h-
align="right"/>
      <textInput id="discountAmount" required="true" restrict="0-9\."
validator="/atg/remote/promotion/template/validators/NumberValidator"/>
      <label id="discount_amount_example_label" display-name-
resource="template.common.discountInfoLabel" styleName="infoText"/>
    </view>
  </switchableDiscount>
</line>

If the offer type is Gift with Purchase, the SwitchableDiscount element displays the UI for that offer type.

Grid Elements

The grid element allows you to include a DataGrid component as part of your template’s user interface. The main use for grids is to provide users with an easy means to enter data when creating banded promotions. For example:

Users can add or subtract rows in the grid using the – and + buttons.

The grid element supports two approaches to defining the DataGrid component; these approaches are described in the sections that follow.

When the template is validated on startup, if a grid element has both a content-source and one or more grid columns, or if it has neither a content-source nor a grid-column, an error is logged, and the template is not included in the template list in the user interface.

Dynamically Determining Grid Structure at Runtime

The first method for creating a grid in a template dynamically generates the grid contents at runtime. The XML used for the user interface would resemble this example:

<line>
  <label display-name="Discount Structure:"/>
  <grid id="tieredPromo" placeholder-name="tiered_promo_value">
      <content-source path="/atg/xxx/yyy">
          <attribute name="calculator-type" value="bulk"/>
      </content-source>
  </grid>
</line>

If you use this approach, the grid element must include a content-source element. The content-source points to a Nucleus that provides the grid with the necessary data structure. The provided /atg/remote/promotion/template/contentSource/BandedDiscountStructureContents component is specific to discount structures; if you want the grid for some other purpose, you can write your own component.

The component should obtain a CalculatorInfo object for the appropriate calculator type (defined in the child attribute element of the content-source) and the promotion type (Item, Order, Shipping or Tax), both of which are passed to the component as the page is generated.

Explicitly Defining Table Structure

As an alternative to dynamic grid generation, you can also explicitly define the DataGrid. In this case, the XML used would resemble the following example:

<line>
  <label display-name="Discount Structure:"/>
  <grid id="tieredPromo"
      placeholder-name="tiered_promo_value">
    <grid-column display-name="band">
      <textInput />
    </grid-column>
    <grid-column display-name="adjuster">
      <textInput />
    </grid-column>
  </grid>
</line>

The grid element in this case explicitly lists the components needed to let the user interface render and build the grid. The child grid-column elements control the display and data-input characteristics of each column in the table. The display-name attribute of the grid-column contains the column header (in this example, it uses a resource bundle). The child elements of the grid-column specify the editor type to be presented in the user interface, which can be either textInput or comboBox.

AssetTable Elements

The assetTable element provides a way for merchandisers to add assets to a promotion condition or offer, either by selecting from an asset picker or using drag and drop.

To override the default set of draggable assets, you can define a content-source element, as shown in the example below. This element limits the draggable assets to products and product subtypes:

<assetTable id="gwpAssetTable" container-width="100" container-h-align="right">
   <content-source
path="/atg/remote/promotion/template/contentSource/AssetParentChildInfo">
   <attribute name="assetBaseTypes"
        value="atg/commerce/catalog/ProductCatalog:product/>
   </content-source>
</assetTable>
Product Set Criteria Elements

The includesProductSetCriteria and excludesProductSetCriteria elements can be used within a line element. They allow users to construct statements for determining products to include in or exclude from the promotion. Each element consists of multiple combo boxes that allow users to specify a sequence of comparative values for properties. The output is a placeholder value that can be used in a PMDL rule.

The includesProductSetCriteria and excludesProductSetCriteria elements have the following attributes:

Four additional attributes control basic display options:

This example shows an includesProductSetCriteria element in a ui-description:

<includesProductSetCriteria id="PSC" required="true" model
-path="/atg/remote/promotion/expreditor/psc/PSCExpressionModel" />

The user interface representation of an expression element consists of three parts:

The resulting combination box looks like the following example:

The user can add can add criteria by clicking the Add Criteria button in the UI (button inclusion and placement is automatic), and join these criteria as AND or OR combinations.

When the user makes selections and saves the template-based promotion, the information is translated into a PMDL statement by the PSCExpressionModel.

Using Optional Fields

It may be necessary to mark fields as optional in your template. You can do this by including an required="false" attribute in any user interface element tag. When this attribute is not present, the element is marked with an asterisk as usual for template fields.

If you make a field optional and the user submits no content for that field, a blank area is substituted for the placeholder associated with the field in the associated item property (as linked by the placeholder-name), which could render the PMDL invalid. If you do make fields optional, make sure that your PMDL blueprint permits an empty string.

For example, if the user interface element for a particular placeholder value is optional and might be left empty, the placeholder should include both the start and end tags of the PMDL, or should be positioned so that an empty string does not break the PMDL.