HTML Template Language Specification

Version: 1.4
Authors: Radu Cotescu, Marius Dănilă, Peeter Piegaze, Senol Tas, Gabriel Walt, Honwai Wong
License: Apache License 2.0
Status: Final release
Release: 18 June 2018

Contents

1. Expression language, syntax and semantics
   1. Syntax
      1. Grammar
      2. Expressions
      3. Context-Sensitive
      4. Operators
         1. Logical Operators
         2. Comparison Operators
         3. Relational Operators
      5. Casting
         1. Boolean
         2. String
      6. Options
      7. Parametric Expressions
      8. Whitespace
      9. Comments
   2. Available Expression Options
      1. Display Context
      2. Format
         1. Strings
         2. Dates
         3. Numbers
      3. i18n
      4. Array Join
      5. URI Manipulation
2. Block Statements
   1. Syntax
      1. Identifiers
   2. Available Block Statements
      1. Use
      2. Text
      3. Attribute
         1. Detailed Examples
      4. Element
      5. Test
      6. List
      7. Repeat
      8. Include
      9. Resource
      10. Template & Call
          1. Template
          2. Call
          3. Examples
      11. Unwrap
      12. Set
   3. Block Statements Priority
3. Special HTML tags
   1. <sly>
4. Use-API
   1. Java Use-API
   2. JavaScript Use-API

#1. Expression language, syntax and semantics

#1.1. Syntax

1.1.1. Grammar

The grammar of the HTL Expression Language is pretty simple and can be summarised to the following definitions:

expression = '${' , [exprNode] , [ , '@' , optionList] , '}' ;

optionList = option {',' , option} ;

option = id [ , '=' , optionValues] ; 

optionValues = exprNode
             | '[' , valueList , ']' ;

valueList = exprNode {',' exprNode} ;

exprNode = orBinaryOp , '?' , orBinaryOp , ws , ':' , ws , orBinaryOp
         | orBinaryOp ;

orBinaryOp = andBinaryOp {, '||', andBinaryOp};

andBinaryOp = inBinaryOp {, '&&', inBinaryOp};

inBinaryOp = comparisonOp [, 'in', comparisonOp];

comparisonOp = factor [, comparisonOperator, factor];

comparisonOperator = '<'
     | '<='
     | '=='
     | '>='
     | '>'
     | '!=' ;

factor = term
       | '!' , term ;

term = propertyAccess
     | '(' , exprNode  , ')'
     | '[', valueList, ']' ;

/* Note the 'comma rule' means zero or more whitespace characters. Used to indicate optional whitespace around terminals above */
, = {ws} ;

ws = ' '
   | '\t'
   | '\r'
   | '\n'
   | '\u000B'
   | '\u00A0';

/* Note that unlike terminals above, the field access character '.' cannot have optional whitespace around it */
propertyAccess = atom {'.' id}
               | atom {'[' , exprNode , ']'};

atom = string
     | id
     | int
     | float
     | bool ;

bool = 'true'
     | 'false' ;

id = ('a'..'z'|'A'..'Z'|'_') {'a'..'z'|'A'..'Z'|'0'..'9'|'_'|':'} ;

int = ['-']('1'..'9'){'0'..'9'}
    | '0' ;

float = ['-']('1'..'9'){'0'..'9'} '.' {'0'..'9'} [exponent]
      | ['-']'0.' ('0'..'9') {'0'..'9'} [exponent]
      | ['-']('1'..'9'){'0'..'9'} exponent ;

/* An HTL comment can contain any character sequence other than '*/-->' */
comment = '<!--/*' {-('*/-->')} '*/-->' ;

/* A string can be delimited by either double or single quotes. Within these delimiters it may contain either escape sequences or any characters other than backslash and whichever quote was used for delimiting. */
string = '"' {escSeq | -('\\' | '"')} '"'
       | '\'' {escSeq | -('\\'|'\'')} '\'' ;

exponent = ('e'|'E') ['+'|'-'] ('0'..'9'){'0'..'9'} ;

escSeq = '\\' ('b'|'t'|'n'|'f'|'r'|'\"'|'\''|'\\')
       | unicodeEsc;

unicodeEsc = '\\' 'u' hexDigit hexDigit hexDigit hexDigit ;

hexDigit = ('0'..'9'|'a'..'f'|'A'..'F') ;

The above grammar is adapted from the source ANTLR files. It uses the following conventions:

foo   Alphabetic words and comma (',') are rule names.
/**/  Slash-star and star-slash delimit comments.
      Whitespace within a rule production indicates direct concatenation.
=     Equals sign indicates the rule production.
;     Semicolon indicates end of production.
' '   Single quotes delimit terminals.
|     Pipe indicates OR.
[]    Square brackets indicate an option (zero or one times).
{}    Curly brackets indicate repetition (zero or more times).
-     Minus sign indicates 'any character or character sequence other than the following'.
..    Ellipses indicates a range between two single-character terminals, by collation order.

Like in JavaScript, strings quotes can be escaped by prefixing a backslash to the quote (\') or double-quote (\").

Single character escape sequences: \t \b \n \r \f \' \" \\

Unicode escape sequences: \u followed by 4 hexadecimal digits (e.g.: \u0022 for ", \u0027 for ', \u003c for <, or \u003e for >)

Like in JSP (see section "1.2.2 Literal-expression" from the JSP 2.1 Expression Language Specification), to escape an expression (the ${), it can be prefixed it with a backslash (\${).

1.1.2. Expressions

Here are some examples of HTL expressions:

1<!--/* Identifiers: */-->
2${myVar}
3
4<!--/* Accesses a member of an object: */-->
5${myObject.key}
6${myObject['key']}
7${myObject[keyVar]}
8
9<!--/* Accesses an index of an array: */-->
10${myArray[1]}
11${myArray[indexVar]}
12
13<!--/* Literals: */-->
14${true}
15${42}
16${'string'}
17${"string"}
18${[1, 2, 3, true, 'string']}

1.1.3. Context-Sensitive

Expressions can be used in following contexts for outputting identifiers into the markup with automatic context-aware XSS protection.

1<tag>Some text ${myText}</tag>
2<tag attr="Some text ${myAttrValue}"></tag>
3<tag href="${myHrefValue}"></tag>

HTL expressions used to output values for the following HTML attributes that provide URIs or URLs will automatically be processed with the uri display context, unless an explicit context is provided:

• action (<form>)
• cite (<blockquote>, <del>, <ins>, <q> tags)
• data (<object>)
• formaction (<button>, <input>)
• href (<a>, <area>, <link>, <base>)
• manifest (<html>)
• poster (<video>)
• src (<audio>, <embed>, <iframe>, <img>, <input>, <script>, <source>, <track>, <video>)

For style and script contexts, it is mandatory to set a context. If the context isn't set, the expression shouldn't output anything. Some examples:

1<!--/* Scripts */-->
2<a href="#whatever" onclick="${myFunctionName @ context='scriptToken'}()">Link</a>
3<script>var ${myVarName @ context="scriptToken"}="Bar";</script>
4<script>var bar='${someText @ context="scriptString"}';</script>
5 
6<!--/* Styles */-->
7<a href="#whatever" style="color: ${colorName @ context='styleToken'};">Link</a>
8<style>
9    a.${className @ context="styleToken"} {
10        font-family: '${fontFamily @ context="styleString"}', sans-serif;
11        color: #${colorHashValue @ context="styleToken"};
12        margin-${side @ context="styleToken"}: 1em; /* E.g. for bi-directional text */
13    }
14</style>

1.1.4. Operators

1.1.4.1. Logical Operators

Only the following logical operators are currently supported, all other operations have to be prepared through the Use-API:

1${varOne && !(varTwo || varThree)} <!--/* 1. Grouping parenthesis */-->
2${!myVar}                          <!--/* 2. Logical NOT */-->
3${varOne && varTwo}                <!--/* 3. Logical AND */-->
4${varOne || varTwo}                <!--/* 4. Logical OR */-->
5${varChoice ? varOne : varTwo}     <!--/* 5. Conditional (ternary) (note that the ':' separator must be surrounded by a space) */-->

The numbers written in the comments above correspond to the precedence of the operators.

The logical && and || operators work like the JavaScript || and && operators: they return the value of one of the specified operands, so if these operators are used with non-Boolean values, they may return a non-Boolean value. This offers a handy way to use the || operator to specify default string values:

1<!--/*
2    For example in following case it will show pageTitle if it exists,
3    else it shows jcr:title, and if that doesn't exist either, then
4    resource.name is shown.
5*/-->
6${properties.pageTitle || properties.jcr:title || resource.name}

1.1.4.2. Comparison Operators

HTL also provides a set of strict comparison operators which can be used for comparing values of operands of the same type; no type conversion will be applied to any of the operands. The equality operators (==, !=) work similarly to the JavaScript === and the JavaScript !== identity operators.

1${nullValueOne == nullValueTwo}        <!-- null comparison -->
2${nullValueOne != nullValueTwo}        <!-- null comparison -->
3${stringValueOne == stringValueTwo}    <!-- string comparison -->
4${stringValueOne != stringValueTwo}    <!-- string comparison -->
5${numberValueOne < numberValueTwo}     <!-- number comparison -->
6${numberValueOne <= numberValueTwo}    <!-- number comparison -->
7${numberValueOne == numberValueTwo}    <!-- number comparison -->
8${numberValueOne >= numberValueTwo}    <!-- number comparison -->
9${numberValueOne > numberValueTwo}     <!-- number comparison -->
10${numberValueOne != numberValueTwo}    <!-- number comparison -->
11${booleanValueOne == booleanValueTwo}  <!-- boolean comparison -->
12${booleanValueOne != booleanValueTwo}  <!-- boolean comparison -->
13${enumConstant == 'CONSTANT_NAME'}     <!-- Java Enum comparison -->

1.1.4.3. Relational Operators

The in relational operator can be used to:

1. Check if a String is contained by another String (case-sensitive):

   1${'a' in 'abc'} <!--/* returns true */-->
   2${'ab' in 'abc'} <!--/* returns true */-->
   3${'bc' in 'abc'} <!--/* returns true */-->
   4${'abc' in 'abc'} <!--/* returns true */-->
   5${'d' in 'abc'} <!--/* returns false */-->

2. Check if an Array or a List contains an object:

   1<!--/*
   2  Assuming myArray would be in scope and would have the following content:
   3  [100, 200, 300, 400, 500]
   4*/-->
   5${100 in myArray} <!--/* returns true */-->
   6${300 in myArray} <!--/* returns true */-->
   7${1 in myArray} <!--/* returns false */-->

3. Check if an object has a property or a Map has a key:

   Assuming the following use object (more details in the Use-API section) provided by a logic.js file:

   1use(function () {
   2    return {
   3        a: true,
   4        b: 'two',
   5        c: 3
   6    };
   7});

   1<sly data-sly-use.logic="logic.js" />
   2${'a' in logic} <!--/* returns true */-->
   3${'b' in logic} <!--/* returns true */-->
   4${'c' in logic} <!--/* returns true */-->
   5${'two' in logic} <!--/* returns false */-->

1.1.5. Casting

1.1.5.1. Boolean

These expressions evaluate to false:

• false
• 0 (zero)
• '' or "" (empty string)
• [] (empty iterable)

These evaluate to true:

• "false" (non-empty string)
• [0] (non-empty iterable)

1.1.5.2. String

This is how non-string types are converted when being output:

1${0}              <!--/* outputs: 0 */-->
2${true}           <!--/* outputs: true */-->
3${false}          <!--/* outputs: false */-->
4${[1, 2, 3]}      <!--/* outputs: 1,2,3 */-->
5${[true, false]}  <!--/* outputs: true,false */-->
6${['foo', 'bar']} <!--/* outputs: foo,bar */-->
7${['foo', '']}    <!--/* outputs: foo, */-->

1.1.6. Options

Expression options can act on the expression and modify it.

1<!--/* An option without a value: */-->
2${myVar @ optName}
3 
4<!--/* Values can be in the form of identifiers or of literals: */-->
5${myVar @ optName=myVar}
6${myVar @ optName=true}
7${myVar @ optName=42}
8${myVar @ optName='string'}
9${myVar @ optName="string"}
10${myVar @ optName=[myVar, 'string']}
11 
12<!--/* Values can also use operators: */-->
13${myVar @ optName=(varOne && varTwo) || !varThree}
14 
15<!--/* Multiple options: */-->
16${myVar @ optOne, optTwo=myVar, optThree='string', optFour=[myVar, 'string']}

1.1.7 Parametric Expressions

Expressions with only options can be used for passing parameters to block elements.

1<tag data-sly-BLOCK="${@ paramOne, paramTwo=myVar, paramThree='string', paramFour=[myVar, 'stringing']}">element content</tag>

1.1.8. Whitespace

Whitespace characters (spaces and tabs) are allowed between any part of an expression:

1<!--/* No spaces: */-->
2${myVar@argOne,argTwo=myVar,argThree='string',argFour=[myVar,'string']}
3 
4<!--/* Spaces everywhere: */-->
5${ myVar @ argOne , argTwo = myVar , argThree = 'string' , argFour = [ myVar , 'string' ] }
6 
7<!--/* This is the recommended spacing style though: */-->
8${myVar @ argOne, argTwo=myVar, argThree='string', argFour=[myVar, 'string']}

1.1.9. Comments

HTL comments combine HTML and JavaScript multi-line comments: <!--/* */-->

HTL comments are not evaluated and are removed from the result.

1<!--/* The content of this comment will be removed from the output. */-->

HTL expressions inside HTML comments are evaluated, but not block statements:

1<!-- Page title: ${currentPage.jcr:title} -->

#1.2. Available Expression Options

1.2.1. Display Context

To protect against cross-site scripting (XSS) vulnerabilities, HTL automatically recognises the context within which an output string is to be displayed within the final HTML output, and escapes that string appropriately.

It is also possible to override the automatic display context handling with the context option.

1${properties.jcr:title @ context='text'}

The following table lists the available contexts:

Note that context='elementName' allows only the following element names:

1section, nav, article, aside, h1, h2, h3, h4, h5, h6, header, footer, address, main, p, pre, blockquote, ol, li, dl, dt, dd, figure, figcaption, div, a, em, strong, small, s, cite, q, dfn, abbr, data, time, code, var, samp, kbd, sub, sup, i, b, u, mark, ruby, rt, rp, bdi, bdo, span, br, wbr, ins, del, table, caption, colgroup, col, tbody, thead, tfoot, tr, td, th

If you want to use HTL expressions within HTML comments you might need to adjust the context depending on what you want to output, as the automatically implied context will be comment:

1<!--[if IE]><link rel="shortcut icon" href="${site.root @ context='uri'}/images/favicon/favicon.ico?v2"><![endif]-->

1.2.2. Format

This option can be used to format Strings, Dates and Numbers. A formatting pattern string must be supplied in the expression and the format option will contain the value(s) to be used. Type of formatting will be decided based on:

1. the type option, if present (accepted values are string, date and number)
2. placeholders (eg: {0}) in the pattern, triggers string formatting
3. type of format option object, when the type is a Date or a Number
4. default, fallback to string formatting

1.2.2.1. Strings

String formatting can be combined with the i18n option so that placeholders are replaced after the string has been run through the dictionary.

Examples

1<!--/* Numbered parameters for injecting variables: */-->
2${'Asset {0}' @ format=properties.assetName}   <!--/* Basically a shortcut of the array notation, useful when it has only one element */-->
3${'Asset {0}' @ format=[properties.assetName]}
4${'Asset {0} out of {1}' @ format=[properties.current, properties.total]}
5${'Asset {0} out of {1}' @ format=[properties.current, properties.total], i18n, locale='de'}

will generate the following output

1Asset Night Sky
2Asset Night Sky
3Asset 3 out of 5
4Bild 3 von 5

assuming that

properties.assetName = 'Night Sky'
properties.current   = 3
properties.total     = 5
formatter 'Asset {0} out of {1}' will be translated to 'Bild {0} von {1}' for the 'de' locale by i18n

1.2.2.2. Dates

Date formatting supports timezones and localisation. In case internationalisation is also specified (i18n), it will be applied to the formatting pattern and the locale will be passed forward to formatting.

1<!--/* Formatting pattern: */-->
2${'yyyy-MM-dd' @ format=myDate}
3${'yyyy-MM-dd' @ format=myDate, type='date'}                <!--/* Forced formatting type */-->
4${'yyyy-MM-dd HH:mm' @ format=myDate, timezone='GMT+00:30'} <!--/* Timezone */-->
5${'EEEE, dd MMMM yyyy' @ format=obj.date, locale='de'}      <!--/* Locale */-->

The formatting pattern supports, at minimum, the following letters:

• y - Year. Variants: yy, yyyy
• M - Month in year. Variants: MM, MMM, MMMM
• w - Week in year. Variants: ww
• D - Day in year. Variants: DD, DDD
• d - Day in month. Variants: dd
• E - Day name in week. Variants: EEEE
• a - Am/pm marker
• H - Hour in day (0-23). Variants: HH
• h - Hour in am/pm. Variants: hh
• m - Minute in hour. Variants: mm
• s - Second in minute. Variants: ss
• S - Millisecond. Variants: SSS
• z - General time zone
• Z - RFC 822 time zone
• X - ISO 8601 time zone. Variants: XX, XXX

All other characters from 'A' to 'Z' and from 'a' to 'z' are reserved for future possible use; if needed, they can be escaped using single quotes. Single quotes are escaped as two in a row. Other characters are not interpreted.

Examples

1${'yyyy-MM-dd HH:mm:ss.SSSXXX' @ format=obj.date, timezone='UTC'}
2${'yyyy-MM-dd HH:mm:ss.SSSXXX' @ format=obj.date, timezone='GMT+02:00'}
3${'yyyy-MM-dd HH:mm:ss.SSS(z)' @ format=obj.date, timezone='GMT+02:00'}
4${'yyyy-MM-dd HH:mm:ss.SSSZ' @ format=obj.date, timezone='GMT+02:00'}
5${'dd MMMM \'\'yy hh:mm a; \'day in year\': D; \'week in year\': w' @ format=obj.date, timezone='UTC'}
6${'EEEE, d MMM y' @ format=obj.date, timezone='UTC', locale='de'}
7${'EEEE, d MMM y' @ format=obj.date, timezone='UTC', locale='en_US', i18n}

will generate the following output for the date 1918-12-01 00:00:00Z

1918-12-01 00:00:00.000Z
1918-12-01 02:00:00.000+02:00
1918-12-01 02:00:00.000(GMT+02:00)
1918-12-01 02:00:00.000+0200
01 December '18 12:00 AM; day in year: 335; week in year: 49
Sonntag, 1 Dez 1918
Sunday, Dec 1, 1918  <!--/* assuming the formatter 'EEEE, d MMM y' will be translated to 'EEEE, MMM d, y' for the 'en_US' locale by i18n */--> 

1.2.2.3. Numbers

Number formatting supports localisation. In case internationalisation is also specified (i18n), it will be applied to the formatting pattern and the locale will be passed forward to formatting.

1<!--/* Formatting pattern: */-->
2${'#.00' @ format=42}
3${'#.00' @ format=myNumber, type='number'} <!--/* Forced formatting type */-->
4${'#.00' @ format=myNumber, locale='de'}   <!--/* Locale */-->

The formatting pattern supports both a positive and negative pattern, separated by semicolon. Each sub-pattern can have a prefix, a numeric part and a suffix. The negative sub-pattern can only change the prefix or/and suffix. The following characters are supported, at minimum:

• 0 - digit, shows as 0 if absent
• # - digit, does not show if absent
• . - decimal separator
• - - minus sign
• , - grouping separator
• E - separator between mantissa and exponent
• ; - sub-pattern boundary
• % - multiply by 100 and show as percentage

Characters can be escaped in prefix or suffix using single quotes. Single quotes are escaped as two in a row.

Examples

1${'#,###.00' @ format=1000}
2${'#.###;-#.###' @ format=obj.number}
3${'#.00;(#.00)' @ format=obj.number}
4${'#.000E00' @ format=obj.number}
5${'#%' @ format=obj.number}
6${ 'curr #,###.##' @ format=1000.14, locale='de_CH', i18n}

will generate the following output if obj.number evaluates to -3.14:

1,000.00
-3.14
(3.14)
-.314E01
-314%
CHF 1'000.14 <!--/* assuming the formatter 'curr #,###.##' will be translated to 'CHF #,###.##' for the 'de_CH' locale by i18n */-->

1.2.3. i18n

This option internationalises strings.

1${'Assets' @ i18n} <!--/* Translates the string to the resource language */-->

When this option is used, two more options take a special meaning:

• locale: When set, it overrides the language from the source. For e.g.: en_US or fr_CH
• hint: Allows to provide some information about the context for the translators.

1${'Assets' @ i18n, locale='en-US', hint='Translation Hint'}

1.2.4. Array Join

The join option allows to control the output of an array object by specifying the separator string.

1${['one', 'two'] @ join='; '} <!--/* outputs: one; two */-->
2 
3<!--/* This can for e.g. be useful for setting class-names */-->
4<span class="${myListOfClassNames @ join=' '}"></span>

Applying the join option to simple strings should just output the string:

1${'test' @ join=', '} <!--/*  outputs: test */-->

1.2.5. URI Manipulation

URI manipulation can be performed by adding any of the following options to an expression:

• scheme - allows adding or removing the scheme part for a URI

  1${'//example.com/path/page.html' @ scheme='http'}
  2<!-- outputs: http://example.com/path/page.html -->
  3
  4${'http://example.com/path/page.html' @ scheme='https'}
  5<!-- outputs: https://example.com/path/page.html -->
  6
  7${'http://example.com/path/page.html' @ scheme=''}
  8<!-- outputs: http://example.com/path/page.html -->
  9
  10${'http://example.com/path/page.html' @ scheme}
  11<!-- outputs: http://example.com/path/page.html -->

• domain - allows adding or replacing the host and port (domain) part for a URI

  1${'///path/page.html' @ domain='example.org'}
  2<!-- outputs: //example.org/path/page.html -->
  3
  4${'http:///path/page.html' @ domain='example.org'}
  5<!-- outputs: http://example.org/path/page.html -->
  6
  7${'http://www.example.com/path/page.html' @ domain='www.example.org'}
  8<!-- outputs: http://www.example.org/path/page.html -->

• path - modifies the path that identifies a resource

• prependPath - prepends its content to the path that identifies a resource

• appendPath - appends its content to the path that identifies a resource

  1${'one' @ appendPath='two'}
  2<!-- outputs: one/two -->
  3
  4${'/one/' @ appendPath='/two/'}
  5<!-- outputs: /one/two/ -->
  6
  7${'path' @ prependPath='..'}
  8<!-- outputs: ../path -->
  9
  10${'path' @ prependPath='/', appendPath='/'}
  11<!-- outputs: /path/ -->
  12
  13${'http://example.com/path/page.html' @ prependPath='foo'}
  14<!-- outputs: http://example.com/foo/path/page.html -->
  15
  16${'path/page.selector.html/suffix?key=value#fragment' @ appendPath='appended'}
  17<!-- outputs: path/page/appended.selector.html/suffix?key=value#fragment -->
  18
  19${'http://example.com/this/one.selector.html/suffix?key=value#fragment' @ path='that/two'}
  20<!-- outputs: http://example.com/that/two.selector.html/suffix?key=value#fragment -->
  21
  22${'http://example.com/this/one.selector.html/suffix?key=value#fragment' @ path=''}
  23<!-- outputs: http://example.com/this/one.selector.html/suffix?key=value#fragment -->
  24
  25${'http://example.com/this/one.selector.html/suffix?key=value#fragment' @ path}
  26<!-- outputs: http://example.com/this/one.selector.html/suffix?key=value#fragment -->

• selectors - modifies or removes the selectors from a URI; the selectors are the URI segments between the part that identifies a resource (the resource's path) and the extension used for representing the resource

• addSelectors - adds the provided selectors (selectors string or selectors array) to the URI

• removeSelectors - removes the provided selectors (selectors string or selectors array) from the URI

  1${'path/page.woo.foo.html' @ selectors='foo.bar'}
  2<!-- outputs: path/page.foo.bar.html -->
  3
  4${'path/page.woo.foo.html' @ selectors=['foo', 'bar']}
  5<!-- outputs: path/page.foo.bar.html -->
  6
  7${'path/page.woo.foo.html' @ addSelectors='foo.bar'}
  8<!-- outputs: path/page.woo.foo.foo.bar.html -->
  9
  10${'path/page.woo.foo.html' @ addSelectors=['foo', 'bar']}
  11<!-- outputs: path/page.woo.foo.foo.bar.html -->
  12
  13${'path/page.woo.foo.html' @ removeSelectors='foo.bar'}
  14<!-- outputs: path/page.woo.html -->
  15
  16${'path/page.woo.foo.html' @ removeSelectors=['foo', 'bar']}
  17<!-- outputs: path/page.woo.html -->
  18
  19${'path/page.woo.foo.html' @ selectors}
  20<!-- outputs: path/page.html -->
  21
  22${'path/page.woo.foo.html' @ selectors=''}
  23<!-- outputs: path/page.html -->

• extension - adds, modifies or removes the extension from a URI

  1${'path/page' @ extension='html'}
  2<!-- outputs: path/page.html -->
  3
  4${'path/page.json' @ extension='html'}
  5<!-- outputs: path/page.html -->
  6
  7${'path/page.selector.json' @ extension='html'}
  8<!-- outputs: path/page.selector.html -->
  9
  10${'path/page.json/suffix' @ extension='html'}
  11<!-- outputs: path/page.html/suffix -->
  12
  13${'path/page.json?key=value' @ extension='html'}
  14<!-- outputs: path/page.html?key=value -->
  15
  16${'path/page.json#fragment' @ extension='html'}
  17<!-- outputs: path/page.html#fragment -->
  18
  19${'path/page.json' @ extension}
  20<!-- outputs: path/page -->

• suffix - adds, modifies or removes the suffix part from a URI; the suffix is the URI segment between the extension and the query segment

• prependSuffix - prepends its content to the existing suffix

• appendSuffix - appends its content to the existing suffix

  1${'path/page.html' @ suffix='my/suffix'}
  2<!-- outputs: path/page.html/my/suffix -->
  3
  4${'path/page.html/some/suffix' @ suffix='my/suffix'}
  5<!-- outputs: path/page.html/my/suffix -->
  6
  7${'path/page.html?key=value' @ suffix='my/suffix'}
  8<!-- outputs: path/page.html/my/suffix?key=value -->
  9
  10${'path/page.html#fragment' @ suffix='my/suffix'}
  11<!-- outputs: path/page.html/my/suffix#fragment -->
  12
  13${'path/page.html/suffix' @ prependSuffix='prepended'}
  14<!-- outputs: path/page.html/prepended/suffix -->
  15
  16${'path/page.html/suffix' @ appendSuffix='appended'}
  17<!-- outputs: path/page.html/suffix/appended -->
  18
  19${'path/page.html/suffix' @ suffix}
  20<!-- outputs: path/page.html -->

• query - adds, replaces or removes the query segment of a URI, depending on the contents of its map value

• addQuery - adds or extends the query segment of a URI with the contents of its map value

• removeQuery - removes the identified parameters from an existing query segment of a URI; its value can be a string or a string array

  1<!--
  2    assuming that jsuse.query evaluates to:
  3    
  4    {
  5      "query": {
  6        "q" : "htl",
  7        "array" : [1, 2, 3]
  8      }
  9    }
  10-->
  11
  12${'http://www.example.org/search' @ query=jsuse.query, context='uri'}
  13<!-- outputs: http://www.example.org/search?q=htl&array=1&array=2&array=3 -->
  14
  15${'http://www.example.org/search?s=1' @ addQuery=jsuse.query, context='uri'}
  16<!-- outputs: http://www.example.org/search?s=1&q=htl&array=1&array=2&array=3 -->
  17
  18${'http://www.example.org/search?s=1&q=htl' @ removeQuery='q', context='uri'}
  19<!-- outputs: http://www.example.org/search?s=1 -->
  20
  21${'http://www.example.org/search?s=1&q=htl' @ removeQuery=['s', 'q'], context='uri'}
  22<!-- outputs: http://www.example.org/search -->
  23
  24${'http://www.example.org/search?s=1&q=htl' @ query, context='uri'}
  25<!-- outputs: http://www.example.org/search -->

• fragment - adds, modifies or replaces the fragment segment of a URI

  1${'path/page' @ fragment='fragment'}
  2<!-- outputs: path/page#fragment -->
  3
  4${'path/page#one' @ fragment='two'}
  5<!-- outputs: path/page#two -->
  6
  7${'path/page#one' @ fragment}
  8<!-- outputs: path/page -->

#2. Block Statements

#2.1. Syntax

HTL block plugins are defined by data-sly-* attributes set on HTML elements. Elements can have a closing tag or be self-closing. Attributes can have values (which can be static strings or expressions), or simply be boolean attributes (without a value). The attribute values can be single-quoted, double-quoted or unquoted.

1<tag data-sly-BLOCK></tag>                                 <!--/* A block is simply consists in a data-sly attribute set on an element. */-->
2<tag data-sly-BLOCK/>                                      <!--/* Empty elements (without a closing tag) should have the trailing slash. */-->
3<tag data-sly-BLOCK="string value"/>                       <!--/* A block statement usually has a value passed, but not necessarily. */-->
4
5<!--/* The passed value can be an expression as well. */-->
6<tag data-sly-BLOCK="${expression}"
7     data-sly-BLOCK='${expression}'
8     data-sly-BLOCK=${expression}/>
9     
10<tag data-sly-BLOCK="${@ myArg='foo'}"/>                   <!--/* Or a parametric expression with arguments. */-->
11<tag data-sly-BLOCKONE="value" data-sly-BLOCKTWO="value"/> <!--/* Several block statements can be set on a same element. */-->

All evaluated data-sly-* attributes are removed from the generated markup.

2.1.1. Identifiers

A block statement can also be followed by an identifier:

1<tag data-sly-BLOCK.IDENTIFIER="value"></tag>

The identifier can be used by the block statement in various ways, here are some examples:

1<!--/* Example of statements that use the identifier to set a variable with their result: */-->
2<div data-sly-use.navigation="MyNavigation">${navigation.title}</div>
3<div data-sly-test.isEditMode="${wcmmode.edit}">${isEditMode}</div>
4<div data-sly-list.child="${currentPage.listChildren}">${child.properties.jcr:title}</div>
5<div data-sly-template.nav>Hello World</div>
6 
7<!--/* The attribute statement uses the identifier to know to which attribute it should apply it's value: */-->
8<div data-sly-attribute.title="${properties.jcr:title}"></div> <!--/* This will create a title attribute */-->

Top top-level identifiers are case-insensitive (because they can be set through HTML attributes which are case-insensitive), but all their properties are case-sensitive.

#2.2. Available Block Statements

2.2.1. Use

data-sly-use:

• Exposes logic to the template.

• Element: always shown.

• Attribute value: required; evaluates to String; the object to instantiate.

• Attribute identifier: optional; customised identifier name to access the instantiated logic; if an identifier is not provided, the instantiated logic will be available under the useBean identifier name.

• Scope: The identifier set by the data-sly-use block element is global to the script and can be used anywhere after its declaration:

  1${customPage.foo} <!--/* this fails */-->
  2<div data-sly-use.customPage="CustomPage">Hello World</div>
  3${customPage.foo} <!--/* but this works */-->

Initialises the specified logic and makes it available to the current template:

1<div data-sly-use.page="customPage.js">${page.foo}</div>

The element on which a data-sly-use has been set as well as its content is rendered (simply removing the data-sly-use attribute from the output):

1<div class="foo" data-sly-use.customPage="CustomPage">Hello World</div>
2<!--/* outputs: */-->
3<div class="foo">Hello World</div>

Parameters can be passed to the Use-API by using expression options:

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

More informations about how the Use-API is working can be found in the Use-API section.

The use statement can also be used to load external templates. See the Template & Call section for this usage.

2.2.2. Text

data-sly-text:

• Sets the content for the current element.
• Element: always shown.
• Content of element: replaced with evaluated result.
• Attribute value: required; evaluates to String; the element content.
• Attribute identifier: none.

Content can be written either simply by writing an expression, or by specifying a data-sly-text attribute. This allows to annotate a designer's HTML without modifying the mock content:

1<p data-sly-text="${properties.jcr:title}">This text would never be shown.</p>

The content of the data-sly-text attribute is automatically XSS-protected with the text context, unless stated otherwise:

1<p data-sly-text="${'<strong>Bold and Proud</strong>' @ context='html'}"></p>
2<!--/* outputs: */-->
3<p><strong>Bold and Proud</strong></p>

Falsy variables are not treated specially, they are simply cast to strings:

1<p data-sly-text="${''}"></p>    <!--/* outputs: */--> <p></p>
2<p data-sly-text="${[]}"></p>    <!--/* outputs: */--> <p></p>
3<p data-sly-text="${0}"></p>     <!--/* outputs: */--> <p>0</p>
4<p data-sly-text="${false}"></p> <!--/* outputs: */--> <p>false</p>

2.2.3. Attribute

data-sly-attribute:

• Sets an attribute or a group of attributes on the current element.
• Element: always shown.
• Content of element: always shown.
• Attribute value: optional; String for setting attribute content, or Boolean for setting boolean attributes, or Object for setting multiple attributes; removes the attribute if the value is omitted.
• Attribute identifier: optional; the attribute name; must be omitted only if attribute value is an Object.

Attributes can be written either simply by writing an expression, or by specifying a data-sly-attribute.* attribute. This allows to annotate a designer's HTML without modifying the mock content:

1<tag class="className" data-sly-attribute.class="${myVar}"></tag> <!--/* This will overwrite the content of the class attribute */-->
2<tag data-sly-attribute.data-values="${myValues}"></tag>          <!--/* This will create a data-values attribute */-->

The data-sly-attribute block element (without specifying an attribute name) allows to inject at once several attributes that have been prepared in a map object that contains key-value pairs:

1<input data-sly-attribute="${foobar}" type="text"/>
2<!--/* outputs for instance: */-->
3<input id="foo" class="bar" type="text"/>
4<!--
5    assuming that foobar = {'id' : 'foo', 'class' : 'bar'}
6-->

The attribute name and content are automatically XSS-protected accordingly, unless stated otherwise:

1<input type="number" name="quantity" min="${qttMin @ context='number'}" max="${qttMax @ context='number'}"/>

Event handler attributes (on*) and the style attribute cannot be generated with data-sly-attribute due to the fact that none of the available display contexts can fully protect against XSS attacks given the range of values that these attributes can contain.

2.2.3.1. Detailed Examples

For all examples below, consider that following object is available in the context:

1foobar = {'id': 'foo', 'class': 'bar', 'lang': ''}

Attributes are processed left-to-right:

1<div class="bar1" data-sly-attribute.class="bar2" data-sly-attribute="${foobar}"></div>
2<!--/* outputs: */-->
3<div id="foo" class="bar"></div>
4 
5<div data-sly-attribute="${foobar}" data-sly-attribute.class="bar2" id="foo2"></div>
6<!--/* outputs: */-->
7<div id="foo2" class="bar2"></div>

Empty string values lead to the removal of the attribute:

1<div lang="${''}"></div>
2<div lang="en" data-sly-attribute.lang></div>
3<div lang="en" data-sly-attribute.lang=""></div>
4<div lang="en" data-sly-attribute.lang="${''}"></div>
5<!--/* All of the above output: */-->
6<div></div>
7
8<div lang="en" data-sly-attribute="${foobar}"></div>
9<!--/* outputs: */-->
10<div id="foo" class="bar"></div>

Still, empty attributes are left as they are if no data-sly-attribute applies to them

1<div title="" data-sly-attribute="${foobar}"></div>
2<!--/* outputs: */-->
3<div title="" id="foo" class="bar"></div>

Boolean values allow to control the display of boolean attributes:

1<input checked="${true}"/>
2<input data-sly-attribute.checked="${true}"/>
3<!--/* Both output: */-->
4<input checked/>
5 
6<input checked="${false}"/>
7<input data-sly-attribute.checked="${false}"/>
8<!--/* Both output: */-->
9<input/>
10 
11<!--/* But 'true' or 'false' strings don't work the same way: */-->
12<input checked="${'true'}"/>  <!--/* outputs: */--> <input checked="true"/>
13<input checked="${'false'}"/> <!--/* outputs: */--> <input checked="false"/>
14 
15<!--/* Consider having attrs={'checked': true} */-->
16<input data-sly-attribute="${attrs}"/>
17<!--/* outputs: */-->
18<input checked/>

Arrays are cast to strings:

1<div title="${['one', 'two', 'three']}"></div>
2<!--/* outputs: */-->
3<div title="one,two,three"></div>
4 
5<!--/* Like empty strings, empty arrays remove the attribute: */-->
6<div title="${[]}"></div>
7<!--/* outputs: */-->
8<div></div>
9 
10<!--/* But an array containing just an empty string doesn't get removed: */-->
11<div title="${['']}"></div>
12<!--/* outputs: */-->
13<div title=""></div>

Numbers are cast to strings (i.e. zero doesn't remove the attribute):

1<div class="${0}"></div>
2<!--/* outputs: */-->
3<div class="0"></div>

2.2.4. Element

data-sly-element:

• Replaces the element's tag name.
• Element: always shown.
• Content of element: always shown.
• Attribute value: required; String; the element's tag name.
• Attribute identifier: none.

Changes the element, mostly useful for setting element tags like h1..h6, th, td, ol, ul.

1<div data-sly-element="${'h1'}">Blah</div>
2<!--/* outputs: */-->
3<h1>Blah</h1>

The element name is automatically XSS-protected with the elementName context, which by the way doesn't allow elements like <script>, <style>, <form>, or <input> (see the Display Context section for the exact list).

2.2.5. Test

data-sly-test:

• Keeps or removes the element depending on the attribute value.
• Element: shown if test evaluates to true.
• Content of element: shown if test evaluates to true.
• Attribute value: optional; evaluated as Boolean (but not type-casted to Boolean when exposed in a variable); evaluates to false if the value is omitted.
• Attribute identifier: optional; identifier name to access the result of the test.
• Scope: The identifier set by the data-sly-test block element is global to the script and can be used anywhere after its declaration:

1<p data-sly-test.editOrDesign="${wcmmode.edit || wcmmode.design}">displays the content when in `edit` or `design` mode</p>
2<p data-sly-test="${!editOrDesign && pageProperties.jcr:title}">displays the content when in `edit` or `design` mode and the `pageProperties` contain a non-empty `jcr:title` property</p>

Removes the whole element from the markup if the expression evaluates to false.

1<p data-sly-test="${wcmmode.edit}">You are in edit mode</p>
2<p data-sly-test>This paragraph will never display</p>

Note that the identifier contains the value of the condition as it was (not casting it to a Boolean value):

1<p data-sly-test.myVar="${'foo'}">${myVar}</p>
2<!--/* outputs: */-->
3<p>foo</p>

2.2.6. List

data-sly-list:

• Iterates over the content of each item in the attribute value, allowing to control the iteration through the following options:
  • begin - iteration begins at the item located at the specified index; first item of the collection has index 0
  • step - iteration will only process every step items of the collection, starting with the first one
  • end - iteration ends at the item located at the specified index (inclusive)
• Element: shown only if the number of items from the attribute value is greater than 0, or if the attribute value is a string or number; when the begin value is used the element will be shown only if the begin value is smaller than the collection's size.
• Content of element: repeated as many times as there are items in the attribute value.
• Attribute value: optional; the item to iterate over; if omitted the content will not be shown.
• Attribute identifier: optional; customised identifier name to access the item within the list element; if an identifier is not provided, the block element will implicitly make available an item identifier to access the element of the current iteration.
• Scope: The identifier set by the data-sly-list block element is available only in the element's content scope. The identifier will override other identifiers with the same name available in the scope, however their values will be restored once outside of the element's scope.

Repeats the content of the element for each item of the provided object (which can be an array, or any iterable object).

1<!--/* By default the 'item' identifier is defined within the loop. */-->
2<ul data-sly-list="${currentPage.listChildren}">
3    <li>${item.title}</li>
4</ul>
5
6<!--/* This is how the name of the 'item' identifier can be customised. */-->
7<ul data-sly-list.childPage="${currentPage.listChildren}">
8    <li>${childPage.title}</li>
9</ul>
10
11<!--/* Iteration control; start from the beginning, stop after the first 10 elements (index 9) */-->
12<ul data-sly-list="${currentPage.listChildren @ begin = 0, end = 9}">
13    <li>${item.title}</li>
14</ul>
15
16<!--/* Iteration control; start from the 11th element (index 10), stop after the next 10 elements (index 19) */-->
17<ul data-sly-list="${currentPage.listChildren @ begin = 10, end = 19}">
18    <li>${item.title}</li>
19</ul>

An additional itemList (respectively <variable>List in case a custom identifier/variable was defined using data-sly-list.<variable>) identifier is also available within the scope, with the following members:

• index: zero-based counter (0..length-1);
• count: one-based counter (1..length);
• first: true for the first element being iterated;
• middle: true if element being iterated is neither the first nor the last;
• last: true for the last element being iterated;
• odd: true if count is odd;
• even: true if count is even.

When iterating over Map objects, the item variable contains the key of each map item:

1<dl data-sly-list="${myMap}">
2    <dt>key: ${item}</dt>
3    <dd>value: ${myMap[item]}</dd>
4</dl>

2.2.7. Repeat

data-sly-repeat:

• Iterates over the content of each item in the attribute value and displays the containing element as many times as items in the attribute value, allowing to control the iteration through the following options:
  • begin - iteration begins at the item located at the specified index; first item of the collection has index 0
  • step - iteration will only process every step items of the collection, starting with the first one
  • end - iteration ends at the item located at the specified index (inclusive)
• Element: shown only if the number of items from the attribute value is greater than 0, or if the attribute value is a string or number.
• Content of element: repeated as many times as there are items in the attribute value.
• Attribute value: optional; the item to iterate over; if omitted the containing element and its content will not be shown.
• Attribute identifier: optional; customised identifier name to access the item within the repeat element; if an identifier is not provided, the block element will implicitly make available an item identifier to access the element of the current iteration.
• Scope: The identifier set by the data-sly-repeat block element is available only in the element's scope. The identifier will override other identifiers with the same name available in the scope, however their values will be restored once outside of the element's scope.

Repeats the content of the element for each item of the provided object (which can be an array, or any iterable object).

1<!--/* By default the 'item' identifier is defined within the loop. */-->
2<p data-sly-repeat="${resource.listChildren}">${item.text}</p>
3
4<!--/* This is how the name of the 'item' identifier can be customised. */-->
5<p data-sly-repeat.childResource="${resource.listChildren}">${childResource.text}</p>
6
7<!--/* The 'item' identifier can be used on the defining element. */-->
8<div data-sly-repeat.article="${articlesCollection}" id="${article.id}">${article.excerpt}</div>
9
10<!--/* Iteration control; start from the beginning, stop after the first 10 elements (index 9) */-->
11<div data-sly-repeat.article="${articlesCollection @ begin = 0, end = 9}" id="${article.id}">${article.excerpt}</div>

An additional itemList (respectively <variable>List in case a custom identifier/variable was defined using data-sly-repeat.<variable>) identifier is also available within the scope, with the following members:

• index: zero-based counter (0..length-1);
• count: one-based counter (1..length);
• first: true for the first element being iterated;
• middle: true if element being iterated is neither the first nor the last;
• last: true for the last element being iterated;
• odd: true if count is odd;
• even: true if count is even.

When iterating over Map objects, the item variable contains the key of each map item:

1<p data-sly-repeat="${myMap}">
2    <span>key: ${item}</span>
3    <span>value: ${myMap[item]}</span>
4</p>

2.2.8. Include

data-sly-include:

• Includes the output of a rendering script run with the current context.
• Element: always shown.
• Content of element: replaced with the content of the included script.
• Attribute value: required; the file to include.
• Attribute identifier: none.

Includes the output of a rendering script run with the current request context, passing back control to the current HTL script.

Note: this is comparable to the JSP <%@ include file="" %>.

1<div data-sly-include="template.html"></div>
2<div data-sly-include="template.jsp"></div>
3 
4<!--/* Following statements are equivalent: */-->
5<div data-sly-include="template.html"></div>
6<div data-sly-include="${'template.html'}"></div>

With an expression more path manipulation options can be specified. Paths are resolved relative to the current rendering context:

• appendPath - appends its content to the passed path

• prependPath - prepends its content to the passed path

  1<div data-sly-include="${'partials' @ appendPath='template.html'}"></div>
  2<!--/* will include partials/template.html */-->
  3
  4<div data-sly-include="${'template.html' @ prependPath='partials'}"></div>
  5<!--/* will include partials/template.html */-->
  6
  7<div data-sly-include="${'components' @ prependPath='partials', appendPath='template.html'}"></div>
  8<!--/* will include partials/components/template.html */-->

The element on which a data-sly-include has been set is ignored and not displayed:

1<!--/* Following will simply output the rendered content of the template, the complete <div> element will be ignored */-->
2<div id="test-one" class="test-two" data-sly-include="template.html">Foo</div>
3<!--/* outputs only the result of template.html */-->

The scope of the data-sly-include statement isn't passed to the template of the included resource.

2.2.9. Resource

data-sly-resource:

• Includes a rendered resource.
• Element: always shown.
• Content of element: replaced with the content of the resource.
• Attribute value: required; the path to include.
• Attribute identifier: none.

Includes a rendered resource from the same server, using an absolute or relative path. An implementation should create a new request context when retrieving the output.

Note: this is comparable to a <jsp:include page="" />.

1<!--/* Following statements are equivalent: */-->
2<section data-sly-resource="./path"></section>
3<section data-sly-resource="${'./path'}"></section>

With an expression more options can be specified:

• appendPath - appends its content to the passed path

• prependPath - prepends its content to the passed path

  1<section data-sly-resource="${'my/path' @ appendPath='appended/path'}"></section>
  2<!--/* Will include my/path/appended/path */-->
  3<section data-sly-resource="${'my/path' @ prependPath='prepended/path'}"></section>
  4<!--/* Will include prepended/path/my/path */-->

• selectors - replaces all selectors from the original request with the selectors passed in a selector string or a selector array before including the passed path:

  1<!--/* Manipulating selectors: */-->
  2<section data-sly-resource="${'my/path' @ selectors='selector1.selector2'}"></section>
  3<section data-sly-resource="${'my/path' @ selectors=['selector1', 'selector2']}"></section>

• addSelectors - adds the selectors from the passed selector string or selector array to the original request before including the passed path:

  1<section data-sly-resource="${'my/path' @ addSelectors='selector1.selector2'}"></section>
  2<section data-sly-resource="${'my/path' @ addSelectors=['selector1', 'selector2']}"></section>

• removeSelectors - removes the selectors found in the passed selector string or selector array from the original request before including the passed path; when the option doesn't have a value, all the selectors will be removed from the original request:

  1<section data-sly-resource="${'my/path' @ removeSelectors='selector1.selector2'}"></section>
  2<section data-sly-resource="${'my/path' @ removeSelectors=['selector1', 'selector2']}"></section>
  3<section data-sly-resource="${'my/path' @ removeSelectors}"></section>

• resourceType - forces the rendering of the passed path with a script mapped to the overridden resource type:

  1<section data-sly-resource="${'./path' @ resourceType='my/resource/type'}"></section>

The scope of the data-sly-resource statement isn't passed to the template of the included resource.

2.2.10 Template & Call

Template blocks can be used like function calls: in their declaration they can get parameters, which can then be passed when calling them. They also allow recursion.

2.2.10.1 Template

data-sly-template:

• Declares an HTML block, naming it with an identifier and defining the parameters it can get.
• Element: never shown.
• Content of element: shown upon calling the template with data-sly-call.
• Attribute value: optional; an expression with only options, defining the parameters it can get.
• Attribute identifier: required; the template identifier to declare.
• Scope: The identifier set by the data-sly-template block element is global and available no matter if it's accessed before or after the template's definition. An identically named identifier created with the help of another block element can override the value of the identifier set by data-sly-template.

2.2.10.2. Call

data-sly-call:

• Calls a declared HTML block, passing parameters to it.
• Element: always shown.
• Content of element: replaced with the content of the called data-sly-template element.
• Attribute value: required; an expression defining the template identifier and the parameters to pass.
• Attribute identifier: none.

2.2.10.3. Examples

Static template that has no parameters:

1<template data-sly-template.one>blah</template>
2<div data-sly-call="${one}"></div>

The scope of the data-sly-call statement isn't inherited by the data-sly-template block. To pass variables, they must be passed as parameters:

1<template data-sly-template.two="${@ title, resource='The resource of the parent node'}"> <!--/* Notice the usage hint on the resource parameter. */-->
2    <h1>${title}</h1>
3    <p>Parent: ${resource.name}</p>
4</template>
5<div data-sly-call="${two @ title=properties.jcr:title, resource=resource.parent}"></div>

When templates are located in a separate file, they can be loaded with data-sly-use:

1<div data-sly-use.lib="templateLib.html" data-sly-call="${lib.one}"></div>
2<div data-sly-call="${lib.two @ title=properties.jcr:title, resource=resource.parent}"></div>

When some parameters are missing in a template call, that parameter would be initialised to an empty string within the template.

2.2.11. Unwrap

data-sly-unwrap:

• Unwraps the element.
• Element: shown if expression evaluates to false.
• Content of element: always shown.
• Attribute value: optional; an expression evaluated as Boolean; defaults to true if the value is omitted.
• Attribute identifier: optional; identifier name to access the result of the test.
• Scope: The identifier set by the data-sly-unwrap block element is global to the script and can be used anywhere after its declaration.

data-sly-unwrap can be used to hide the element itself, only showing its content:

1<!--/* This will only show "Foo" (without a <div> around) if the test is true: */-->
2<div data-sly-test="${myTest}" data-sly-unwrap>Foo</div>
3 
4<!--/* This would show a <div> around "Foo" only if the test is false: */-->
5<div data-sly-unwrap="${myTest}">Foo</div>
6
7<!--/* Scope: script global */-->
8<p data-sly-unwrap.richText="${configuration.text.isRich}">${sectionA}</p>
9<p data-sly-unwrap="${richText}">${sectionB}</p>

2.2.12. Set

data-sly-set:

• Defines a new identifier with a pre-defined value.
• Element: always shown.
• Content of element: always shown.
• Attribute value: optional; the value to store in the provided identifier.
• Attribute identifier: required; identifier name to access the stored value.
• Scope: The identifier set by the data-sly-set block element is global to the script and can be used anywhere after its declaration.

1<span data-sly-set.profile="${user.profile}">Hello, ${profile.firstName} ${profile.lastName}!</span>
2<a class="profile-link" href="${profile.url}">Edit your profile</a>

#2.3. Block Statements Priority

When used on the same element, the following priority list defines how block statements are evaluated:

1. data-sly-template
2. data-sly-set, data-sly-test, data-sly-use
3. data-sly-call
4. data-sly-text
5. data-sly-element, data-sly-include, data-sly-resource
6. data-sly-unwrap
7. data-sly-list, data-sly-repeat
8. data-sly-attribute

When two block statements have the same priority, their evaluation order is from left to right.

#3. Special HTML tags

#3.1. <sly>

The <sly> HTML tag can be used to remove the current element, allowing only its children to be displayed. Its functionality is similar to the data-sly-unwrap block element:

1<!--/* This will display only the output of the 'header' resource, without the wrapping <sly> tag */-->
2<sly data-sly-resource="./header"></sly>

Although not a valid HTML 5 tag, the <sly> tag can be displayed in the final output using data-sly-unwrap:

1<sly data-sly-unwrap="${false}"></sly> <!--/* outputs: <sly></sly> */-->

#4. Use-API

HTL encourages separation of concerns by not allowing business logic to mix with markup. However, business logic can be implemented through the Use-API.

#4.1. Java Use-API

The Java Use-API can be used for loading business logic objects to be used in HTL scripts through data-sly-use. A Java Use-API object can be a simple POJO, instantiated by a particular implementation through the POJO's default constructor.

The Use-API POJOs can also expose a public method, called init, with the following signature:

1    /**
2     * Initialises the Use bean.
3     *
4     * @param bindings All bindings available to the HTL scripts.
5     **/ 
6    public void init(javax.script.Bindings bindings);

The bindings map can contain objects that provide context to the currently executed HTL script that the Use-API object can use for its processing.

#4.2. JavaScript Use-API

The JavaScript Use API has been deprecated for use with AEM as a Cloud Service. Please use the Java Use API instead.

Please see the AEM as a Cloud Service release notes for more information on deprecated and removed features.

Use objects can also be defined with JavaScript, using the following conventions:

1/**
2 * In the following example '/libs/dep1.js' and 'dep2.js' are optional
3 * dependencies needed for this script's execution. Dependencies can
4 * be specified using an absolute path or a relative path to this
5 * script's own path.
6 *
7 * If no dependencies are needed the dependencies array can be omitted.
8 */
9use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
10    // implement processing
11    
12    // define this Use object's behaviour
13    return {
14        propertyName: propertyValue
15        functionName: function () {}
16    }
17});

#4.3. Object Resolution and their Properties or Methods

HTL implementations have to provide the appropriate support for the Use-API depending on the platform on which they run. However, property or method resolution on a target object must obey the following rules:

1. expression.identifier is equivalent to expression["identifier"] and to expression['identifier']

2. the identifier resolution uses the following algorithm:

   1. try to resolve the identifier as a publicly accessible field of the object returned by the expression; if found, return;

   2. try to resolve the identifier as a publicly accessible method without formal parameters of the object returned by the expression:

      1. try to find a method whose name is identifier; if found, call method and return;
      2. try to find a getter called getIdentifier (notice the camelCase); if found, call method and return;
      3. try to find an isIdentifier method (notice the camelCase); if found, call method and return;
      4. return null