What is htl in aem?

Aem Introduction

OSGI

Sling

Repository

Component & Template

Servlet

Service

Client Library

Workflow

Schedular

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

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

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

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 (\${).

Here are some examples of HTL expressions:

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

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:

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:

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

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:

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.

The in relational operator can be used to:

These expressions evaluate to false:

These evaluate to true:

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

Expression options can act on the expression and modify it.

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

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

HTL comments combine HTML and JavaScript multi-line comments:

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

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

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.

The following table lists the available contexts:

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

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:

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:

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

will generate the following output

assuming that

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.

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

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.

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

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.

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:

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

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

This option internationalises strings.

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

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

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

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

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.

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

A block statement can also be followed by an identifier:

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

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.

data-sly-use:

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

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):

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

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.

data-sly-text:

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:

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

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

data-sly-attribute:

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:

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:

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

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.

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

Attributes are processed left-to-right:

Empty string values lead to the removal of the attribute:

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

Boolean values allow to control the display of boolean attributes:

Arrays are cast to strings:

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

data-sly-element:

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

The element name is automatically XSS-protected with the elementName context, which by the way doesn't allow elements like