XML definitions

Section 1 contains XML definitions for the module and template XML files.

1. Module

1.1. Legacy Type

Legacy Type is used to indicate where a current module XML definition can serve an old/alternate module type. This is used on CMS upgrade or Layout import to convert a widget from its old state to a state compatible with this release.

For example, the countdown module from v2/v3 has been split into 4 separate countdown modules in v4, each one serving a different “templateId” in the v3 version of that module. Adding a legacy type definition to the new module means that it will match and convert an old widget into the new module.

2. Template

Note: Template id cannot contain hyphens (-). This is because it will be used to generate a unique method name for onTemplateRender.

3. Property

Common structure for all properties.

3.1. Rule

Rules can be used for visibility and validation of properties. Rules consist of an array of tests which are evaluated individually (they are ANDed).

3.1.1. Test

A test is a set of conditions which are assessed in sequence.

3.1.2. Condition

Rules used as validation always test the current property value against the value resolved by the condition. Rules used as visibility tests always test the value in the field attribute against the value in the node.

For rules used as validation this means that when a field name is provided it is the value of that field which is used to test against the current property value. For example:

A rule which ensures that the current property value is required and is of type uri.

<rule>
    <test type="and">
        <condition type="required"></condition>
        <condition type="uri"></condition>
    </test>
</rule>

A rule which ensures that the current property value is less than or equal to the duration.

<rule message="Warning duration needs to be lower than the widget duration.">
    <test type="and">
        <condition field="duration" type="lte"></condition>
    </test>
</rule>

Rules which need a comparison value such as gt must either have a field to get the comparison value from, or a value in the condition.

<rule message="Warning duration needs to be lower than 10">
    <test type="and">
        <condition type="lt">10</condition>
    </test>
</rule>

When using or tests, all conditions must fail for the test to fail.

Condition Type

Default values

If the property defines a default value, this value is also tested against the rules and conditions defined on the property.

3.2. Player Compatibility

3.3. Property Types

All properties have the options listed in the Property section. They can be of the following types:

3.4. Property Additional Options

These properties have additional options.

Dropdown

Option

Code

Rich Text

Date

Connector Properties

A dropdown/search field which returns a set of options/values from a connector which handles the request.

4. Stencil

4.1. Twig

Twig will be rendered directly into the module HTML. It can be used to add custom CSS or HTML to the module.

It needs to be provides as a CDATA block, to prevent the XML parser from interpreting the HTML.

By setting a width and height attribute, the template will be scaled to match those dimensions in the player.

4.2. Handlebars (hbs)

When set in the template, the hbs node value will be used as a template for each item provided.

If it’s defined in the module, it will be used as a template for the module itself.

We can use {{ }} with module or item properties, data can be rendered to the template.

5. Sample data

When developing a module with a data provider, it’s important to have a sample data to test the rendering. The sample data can be provided as a JSON string, in the sampleData node.

Data can be provided as a single item:

<sampleData><![CDATA[
{
    "id": "1",
    "name": "One",
    "description": "This is the first item",
    "value": "1"
}
]]></sampleData>

Or as an array of items:

<sampleData><![CDATA[
[
    {
        "id": "1",
        "name": "One",
        "description": "This is the first item",
        "value": "1"
    },
    {
        "id": "2",
        "name": "Two",
        "description": "This is the second item",
        "value": "2"
    },
    {
        "id": "3",
        "name": "Three",
        "description": "This is the third item",
        "value": "3"
    }
]
]]></sampleData>

6. Assets

When assets are required for the module, they can be added to the assets node.

Asset

And then the asset can be referenced in the module with the [[assetId=newImage]] syntax.

7. Data Type

Each datatype.xml file should have a top level node called <dataTypes>, inside which is each <dataType> node.

7.1. Field

7.1. Field Attributes