Announcement: You can find the guides for Commerce 7.5 and later on the new Elastic Path Documentation site. The Developer Center continues to support Commerce 6.13.0 through 7.4.1.Visit new site

Content Wrapper XML file

Content Wrapper XML file

When the storefront web application is launched, the <assets>/content-wrappers directory is read and all valid Content Wrappers XML files in that directory are parsed and cached. This directory is checked periodically and the Content Wrappers (XML files and CWT files) are reloaded. By default, this occurs every 600 seconds (10 minutes). You can configure the reload interval by editing the COMMERCE/SYSTEM/CONTENTWRAPPERS/reloadInterval setting. If you are testing changes to Content Wrappers and want to see your changes reflected more quickly, decrease the reload interval.

The structure of the Content Wrapper XML file is:

template-name

This setting specifies the name of the Content Wrapper template file that contains the template code used to render the Content Wrapper.

Note:

The CWT file must be located in the same directory as the Content Wrapper.

wrapper-id

The ID is used internally by Elastic Path Commerce to identify the Content Wrapper. Each Content Wrapper must have a unique ID. If there are multiple Content Wrappers with the same ID, only one of them will be loaded.

wrapper-name

The name is the human-readable name displayed to the user in the Commerce Manager.

script-language

Currently, only groovy is supported.

service-definitions

(Optional.) The service definitions block is used to add references to Elastic Path service beans. If the script code in the Content Wrapper needs to refer to Elastic Path services, add references to the service beans here.

service-definition

A references to an Elastic Path service bean. The name attribute specifies the name you want to use within the Content Wrapper to refer to the service. For example, the following adds a reference to the productService bean:

<service-definition name="myProductService">productService</service-definition>

To refer to this bean within the Content Wrapper, you would use the name myProductService.

user-input-settings

(Optional.) The user input settings block contains parameters that the marketing user configures when creating Dynamic Content.

user-input-setting

A parameter that the marketing user configures when creating Dynamic Content.

<user-input-setting id="productCode"
    name="Product Code"
    required="true"
    pass-to-template="false"
    localizable="false"
    type="Product"/>
  • id is the name that can be used to refer to the setting in the <init> block and all <template-parameter> blocks.
  • name is the text displayed to the user in the Commerce Manager when configuring the Dynamic Content.
  • required sets whether this is a mandatory setting (i.e., the Commerce Manager user must configure it when creating Dynamic Content with this Content Wrapper).
  • pass-to-template sets whether the setting can be accessed from the Content Wrapper template file. By default, the setting is passed as a parameter to the template. To prevent this, set pass-to-template to false. Also note that all settings passed to the template are automatically required, regardless of the required attribute.
  • localizable indicates whether the value can have different values for different locales. If it is set to true, the person configuring the Dynamic Content can specify a different value for each supported language.
  • type determines what kind of values it supports. The following type values are supported:
    Type Comments

    StringLong

    Displays a multiline text box.

    StringShort

    Displays a text box.

    StringShortMultiValue

    Displays a special list edit that allows the user to specify multiple string values.

    Boolean

    The user can select either true or false.

    Decimal

    The user can specify a numeric value containing non-whole (or fractional) numbers.

    Integer

    The user can specify a numeric value containing whole numbers.

    Image

    Displays a file dialog that prompts the user to select an image in the <assets>/dynamiccontent directory.

    File

    Displays a file dialog that prompts the user to select a file in the <assets>/dynamiccontent directory.

    Date

    Prompts the user to select a date using a date picker.

    Datetime

    Prompts the user to select a date using a date picker.

    Url

    User input is validated to ensure that a proper URL is set. Only http, https, and ftp protocols are supported.

    Product

    Displays a product search dialog.

    Category

    Displays a category search dialog.

    HTML

    The user can specify a string of HTML in a multi-line text box.

init

The initialization block lets you add initialization logic to the Content Wrapper. This code is executed each time the Content Wrapper is loaded. For more information, see Writing Code in Content Wrappers.

template-parameters

(Optional.) Additional parameters that are available in the Content Wrapper template file.

template-parameter

An additional parameter that is available in the CWT.

<template-parameter id="image" name="image">
      product.getImage();
</template-parameter>

You can include business logic to resolve the parameter values. The code inside each template parameter element must return the value that will be passed to the CWT. The value must not be null.

Note:

The return keyword is optional. If there is no return, the value returned by the last line of code is used as the return value.

Writing Code in Content Wrappers

The <init> block in the Content Wrapper XML file lets you add initialization logic to the Content Wrapper. You can also include code in the <template-parameter> blocks. The code in these blocks is executed each time the Content Wrapper is loaded.

Because the code is embedded in XML, you need to wrap it in a CDATA block to ensure XML special characters in your code are not interpreted by the XML parser. Alternatively, you can manually escape special characters (converting < to <, & to &, etc.).

<init><![[DATA[
// Groovy code here
]] >
</init>

Importing packages

By default, all Java packages and all packages in the storefront web application's classpath are imported automatically. It is not necessary to import them explicitly.

Variable scope

It's important to note that if you declare a variable with def, its scope is local to the current block. Thus, if you create a variable in the init block and you want to access it inside a template-parameter block, do not declare it with the def keyword. You only need to assign it a value.

Available objects

In addition to any variables you declare, the following objects are available in your script code:

  • CS: a CustomerSession object representing the shopper
  • locale: a string containing the current locale