HTL In Depth

What HTL is and is not

HTL (HTML Template Language, formerly Sightly) is AEM's server-side templating language. It replaced JSP, and the replacement was motivated by two things: JSP let people put arbitrary Java in templates, and JSP made XSS easy. HTL fixes both by design — it is deliberately not a programming language. There are no loops you control, no arithmetic, no method calls with arguments. If you need logic, you write a Sling Model.

Everything is an HTML attribute, so a template is always valid HTML that a designer can open.

Expressions

<h1>${properties.jcr:title}</h1>
<h1>${model.title}</h1>
<p>${model.text || 'No text yet'}</p>
<a href="${model.link @ context='uri'}">Read more</a>
<p>${'Hello {0}, you have {1} messages' @ format=[user, count]}</p>
<p>${'Read more' @ i18n}</p>

Objects always available to you: properties (current resource's properties), pageProperties, resource, currentPage, request, wcmmode.

Block statements

• data-sly-use — bind a Sling Model or Use-object to a name.
• data-sly-test — conditional. Assign the result to reuse it: data-sly-test.hasTitle="${model.title}".
• data-sly-list — iterate, exposing item and itemList (with index, count, first, last, odd, even).
• data-sly-repeat — like list, but repeats the element itself rather than its children.
• data-sly-resource — render another resource through the full Sling pipeline.
• data-sly-include — include a script directly, with no resource resolution.
• data-sly-template / data-sly-call — define and call a reusable markup fragment.
• data-sly-element — set the element's tag name dynamically.
• data-sly-attribute — set attributes from a map.
• data-sly-unwrap — remove the host element, keeping its contents.

<div data-sly-use.model="com.adobe.aem.guides.wknd.core.models.Byline"
     data-sly-test="${model.name}">
  <h2>${model.name}</h2>
  <ul data-sly-list.occupation="${model.occupations}">
    <li class="${occupationList.first ? 'is-first' : ''}">${occupation}</li>
  </ul>
</div>

Display context: the XSS protection

HTL escapes every expression automatically, and it picks the escaping strategy from where the expression appears. Inside an element it uses HTML escaping; in an attribute, attribute escaping; in an href, URI validation; inside a <script>, JavaScript escaping.

You can override it when you genuinely need to:

• @ context='html' — allow a safe subset of HTML. This is what rich text fields need.
• @ context='uri' — validate as a URI.
• @ context='attribute', 'scriptString', 'styleToken', 'number'.
• @ context='unsafe' — no escaping at all.

Templates and calls

<template data-sly-template.card="${@ title, image}">
  <article class="card">
    <img src="${image @ context='uri'}" alt="">
    <h3>${title}</h3>
  </article>
</template>

<div data-sly-call="${card @ title=model.title, image=model.imagePath}"></div>

Put shared templates in their own file and pull them in with data-sly-use to reuse across components.

The boundary

HTL's restrictions are the point. When you find yourself wanting a conditional chain, a computed value or string manipulation in a template, that is the signal to move it into a Sling Model getter — where it is testable, debuggable and reusable. Tomorrow is exactly that.