HTML Template Language (HTL) Specification

HTL provides automatic context-aware XSS protection. When outputting values into HTML attributes that represent URIs (like href, src, action), HTL defaults to the uri context.

For style and script contexts, you must explicitly set a context, otherwise the expression will output nothing. Use the context option to specify the required protection level.

<!--/* Scripts */-->
<a href="#whatever" onclick="${myFunctionName @ context='scriptToken'}()">Link</a>
<script>var ${myVarName @ context="scriptToken"}="Bar";</script>
<script>var bar='${someText @ context="scriptString"}';</script>
 
<!--/* Styles */-->
<a href="#whatever" style="color: ${colorName @ context='styleToken'};">Link</a>
<style>
    a.${className @ context="styleToken"} {
        font-family: '${fontFamily @ context="styleString"}', sans-serif;
        color: #${colorHashValue @ context="styleToken"};
    }
</style>

HTL block plugins are implemented using data-sly-* attributes on HTML elements.

Key syntax rules:

• Element types: Elements can have a closing tag or be self-closing (use a trailing slash for empty elements).
• Attribute values: Can be static strings, expressions (using ${...}), or boolean attributes (no value).
• Quoting: Values can be single-quoted, double-quoted, or unquoted.
• Parametric expressions: You can pass arguments to a block using the @ syntax within an expression.
• Multiple blocks: Several different data-sly-* statements can be applied to the same element.
• Cleanup: All data-sly-* attributes are automatically removed from the final generated markup.

Note on Identifiers: A block statement can be followed by an identifier (e.g., data-sly-BLOCK.IDENTIFIER="value") to assign the result to a specific variable name. Top-level identifiers are case-insensitive, but their properties are case-sensitive.

<tag data-sly-BLOCK></tag>                                 <!--/* Standard block */-->
<tag data-sly-BLOCK/>                                      <!--/* Self-closing */-->
<tag data-sly-BLOCK="string value"/>                       <!--/* With static value */-->
<tag data-sly-BLOCK="${expression}"/>                      <!--/* With expression */-->
<tag data-sly-BLOCK='${expression}'/>                      <!--/* Single quoted expression */-->
<tag data-sly-BLOCK=${expression}/>                         <!--/* Unquoted expression */-->
<tag data-sly-BLOCK="${@ myArg='foo'}"/>                 <!--/* Parametric expression */-->
<tag data-sly-BLOCKONE="value" data-sly-BLOCKTWO="value"/> <!--/* Multiple blocks */-->

<!--/* Using an identifier */-->
<tag data-sly-BLOCK.IDENTIFIER="value"></tag>

HTL expressions are enclosed in ${ ... }. The grammar supports identifiers, literals (strings, integers, floats, booleans), property access via dot notation (obj.key) or bracket notation (obj['key']), and array indexing.

Key Syntax Rules:

• Escaping Expressions: To output a literal ${, use a backslash: \${.
• String Escaping: Use backslashes for single-character escapes (\t, \n, \r, \f, \', \", \\) or Unicode escapes (\uXXXX).
• Comments: HTL comments use the syntax <!--/* comment content */-->. Expressions inside HTML comments are evaluated, but block statements are not.

<!--/* Identifiers: */-->
${myVar}

<!--/* Accesses a member of an object: */-->
${myObject.key}
${myObject['key']}
${myObject[keyVar]}

<!--/* Accesses an index of an array: */-->
${myArray[1]}
${myArray[indexVar]}

<!--/* Literals: */-->
${true}
${42}
${'string'}
${[1, 2, 3, true, 'string']}

HTL supports standard logical and strict comparison operators.

Logical Operators:

• ! (NOT)
• && (AND)
• || (OR)
• ? : (Ternary/Conditional) - Note: The : separator must be surrounded by whitespace.

Comparison Operators (Strict): HTL uses strict comparison; no type conversion is applied. Equality operators (==, !=) behave like JavaScript's === and !==.

• <, <=, ==, >=, >, !=

Relational Operator:

• in: Checks if a String is contained in another String, if an Array/List contains an object, or if an object has a property/Map key.

${varOne && !(varTwo || varThree)} <!--/* Grouping */-->
${!myVar}                          <!--/* Logical NOT */-->
${varOne && varTwo}                <!--/* Logical AND */-->
${varOne || varTwo}                <!--/* Logical OR */-->
${varChoice ? varOne : varTwo}     <!--/* Conditional (ternary) */-->

${'a' in 'abc'}                   <!--/* String containment */-->
${100 in [100, 200]}              <!--/* Array containment */-->
${'a' in logic}                   <!--/* Property/Key check */-->

The data-sly-use block is used to instantiate logic (like a JavaScript file or an object) and make it available to the template.

• Element: Always rendered (the attribute is removed).
• Attribute value: Required; a String representing the object to instantiate.
• Attribute identifier: Optional; the name used to access the logic. If omitted, the identifier defaults to useBean.
• Scope: The identifier is global to the script and can be used anywhere after its declaration.
• Parameters: You can pass parameters to the logic using expression options.
• Usage: Can also be used to load external templates.

Example: Instantiating a JS file and passing parameters

<!--/* Basic usage with custom identifier */}
<div data-sly-use.page="customPage.js">${page.foo}</div>

<!--/* Usage with parameters */}
<div data-sly-use.nav="${'Navigation' @ depth=1, showVisible=!wcmmode.edit}">${nav.foo}</div>

Both data-sly-list and data-sly-repeat are used for iteration, but they behave differently regarding the containing element.

data-sly-list (Iterate inside element)

• Behavior: The element is shown once. Its content is repeated for each item in the collection.
• Element visibility: Shown only if the collection has > 0 items (or is a string/number).
• Identifier: Defaults to item. Can be customized via data-sly-list.name.

data-sly-repeat (Iterate the element itself)

• Behavior: The element itself is repeated for each item in the collection.
• Identifier: Defaults to item. Can be customized via data-sly-repeat.name.

Shared Iteration Options and Helpers

• Options: begin (start index), step (increment), end (inclusive end index).
• itemList (or <variable>List): An object available in the loop containing:
  • index: 0-based counter.
  • count: 1-based counter.
  • first, middle, last: Boolean flags for position.
  • odd, even: Boolean flags based on count.

Example: Using data-sly-list to build a list

<!--/* data-sly-list: repeats content inside the <ul> */}
<ul data-sly-list.childPage="${currentPage.listChildren}">
    <li>${childPage.title}</li>
</ul>

<!--/* data-sly-repeat: repeats the <p> tag itself */}
<p data-sly-repeat.article="${articlesCollection}">${article.excerpt}</p>