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:
- <content-wrapper>
template-name
This setting specifies the name of the Content Wrapper template file that contains the template code used to render the Content Wrapper.
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.
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"/commerce-legacy/>
- 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.
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.