HTL (formerly Sightly) is AEM's server-side template language. It completely replaces JSP and serves as the standard for rendering components. HTL'

HTL Templates

HTL (HTML Template Language) in AEM

HTL (formerly Sightly) is AEM's server-side template language. It completely replaces JSP and serves as the standard for rendering components. HTL's core philosophy is secure by default — automatically escaping output data to prevent XSS attacks.

1. Expressions

Expressions print values to HTML using $\{\} syntax:

<!-- Print JCR property directly -->
<h1>${properties.jcr:title}</h1>

<!-- Fetch data from Sling Model -->
<p>${model.description}</p>

<!-- Literal string -->
<span>${'Hello, World!'}</span>

1.1. Expression Options

Modify how data is rendered by adding @ following the variable:

<!-- Context (Specify security context) -->
<a href="${link.url @ context='uri'}">${link.text}</a>

<!-- Format (String formatting) -->
<p>${'Price: {0}' @ format=product.price}</p>

<!-- i18n (Internationalization translation) -->
<span>${'Read More' @ i18n}</span>

<!-- Join (Join array elements) -->
<p>${model.tags @ join=', '}</p>

1.2. Display Contexts

Although HTL chooses security context automatically, you can (and sometimes must) override it. Common contexts include:

Context	Usage Location	HTL Example
`html` (default)	Safe HTML content	`<p>$\{text\}</p>`
`text`	Plain text (Strips HTML)	`<title>$\{title @ context='text'\}</title>`
`attribute`	HTML tag attribute	`<div class="$\{cssClass @ context='attribute'\}">`
`uri`	URL path	`<a href="$\{url @ context='uri'\}">`
`scriptString`	Assign to JavaScript variable	`var x = "$\{val @ context='scriptString'\}"`
`unsafe`	Bypass security	`$\{richText @ context='unsafe'\}`

Security Warning: NEVER use context='unsafe' unless completely certain content is safe. For Rich Text Editor (RTE) output, RTE sanitizes malicious code on save, and default html context provides extra protection on render. RTE output called via $\{model.richText\} is safe!

2. Block Statements

Block statements are HTML attributes prefixed with data-sly-. They control HTL logic execution.

2.1. `data-sly-use` (Initialize Model)

Loads a Sling Model or template file into a variable.

<!-- Load Sling Model -->
<div data-sly-use.model="com.mysite.core.models.ArticleModel">
    <h1>${model.title}</h1>
</div>

<!-- Load another HTL file -->
<div data-sly-use.template="partials/header.html"></div>

<!-- Pass parameters into Model -->
<div data-sly-use.model="${'com.mysite.core.models.ListModel' @ limit=5}"></div>

(Variable identifier follows dot — e.g. .model — used in HTL).

2.2. `data-sly-test` (Conditional Rendering)

Functions like an if statement. Can also be used for variable assignment.

<!-- Render <h1> only if title exists -->
<h1 data-sly-test="${model.title}">${model.title}</h1>

<!-- If/Else pattern with variable assignment (.hasItems) -->
<div data-sly-test.hasItems="${model.items.size > 0}">
    <p>Found ${model.items.size} results</p>
</div>
<div data-sly-test="${!hasItems}">
    <p>No results found.</p>
</div>

Note: Values evaluated as false: null, empty string "", number 0, boolean false, and empty collections/arrays.

2.3. `data-sly-list` vs `data-sly-repeat` (Loops)

Both iterate over arrays/collections, but impact DOM structure differently.

Loop Helper Variable (itemList): Inside loops, HTL automatically generates itemList object with properties:

Variable	Function
`itemList.index`	Current index (0-based)
`itemList.count`	Current count (1-based)
`itemList.first` / `last`	Returns `true` if first / last element
`itemList.middle`	Returns `true` if middle element
`itemList.odd` / `even`	Returns `true` if index is odd / even

<ul data-sly-list.item="${model.articles}">
    <li>${item.title} - Viewing item ${itemList.count}</li>
</ul>

2.4. `data-sly-resource` vs `data-sly-include`

Embeds another component or HTML file into current template.

data-sly-resource: Embeds a component. Triggers Sling Resolution (invokes Java logic, loads child component Dialog).

<!-- Call component with resourceType -->
<div data-sly-resource="${'header' @ resourceType='mysite/components/header'}"></div>

<!-- Call with selector -->
<div data-sly-resource="${'sidebar' @ resourceType='mysite/components/sidebar', selectors='compact'}"></div>

<!-- Change wrapper tag of child component -->
<div data-sly-resource="${'text' @ resourceType='mysite/components/text', decorationTagName='article'}"></div>

data-sly-include: Includes a static HTML snippet directly. Does NOT trigger Sling Resolution.

<div data-sly-include="partials/footer.html"></div>
<div data-sly-include="/apps/mysite/components/shared/utils.html"></div>

2.5. `data-sly-template` / `data-sly-call` (UI Reuse)

Defines an HTML block as a function and calls it in multiple places.

<!-- Define template -->
<template data-sly-template.card="${@ title, description, link}">
    <div class="card">
        <h3>${title}</h3>
        <p>${description}</p>
        <a href="${link @ context='uri'}">Read More</a>
    </div>
</template>

<!-- Call template with arguments -->
<div data-sly-list="${model.articles}">
    <div data-sly-call="${card @ title=item.title, description=item.excerpt, link=item.path}"></div>
</div>

2.6. `data-sly-element` (Dynamic HTML Tag)

Dynamically changes HTML element based on configuration.

<!-- If model.headingLevel is 'h2', tag renders as <h2> -->
<h1 data-sly-element="${model.headingLevel || 'h1'}">${model.title}</h1>

2.7. `data-sly-attribute` (HTML Attributes)

<!-- Set single attribute -->
<div data-sly-attribute.id="${model.anchorId}">Content</div>

<!-- Set multiple attributes via Map -->
<div data-sly-attribute="${model.attributes}">Content</div>

<!-- Conditional attribute (removed automatically if empty/false) -->
<input data-sly-attribute.disabled="${model.isDisabled ? 'disabled' : ''}"/>

2.8. `data-sly-text` (Override Text)

Retains mockup text for frontend design time, automatically replaced when rendered.

<p data-sly-text="${model.description}">Mock text replaced at runtime.</p>

2.9. `data-sly-unwrap` (Remove Wrapper Tag)

Keeps inner content while unwrapping host HTML tag from DOM. Useful for logical wrappers without introducing unnecessary wrapper <div/> elements.

<div data-sly-unwrap>
    <p>This paragraph will not be wrapped in div in browser DOM.</p>
</div>

2.10. `data-sly-set` (Local Variable Assignment)

Introduced in HTL 1.4, assigns calculated values to local variables without creating HTML tags.

<sly data-sly-set.fullName="${model.firstName} ${model.lastName}"/>
<p>Hello, ${fullName}</p>

3. Global Objects

HTL templates automatically inject global objects:

Object	Type	Description
`properties`	`ValueMap`	Properties of current resource (JCR node).
`pageProperties`	`ValueMap`	Properties of current page (`jcr:content` node).
`inheritedPageProperties`	`ValueMap`	Inherited properties from ancestor pages.
`currentPage`	`Page`	Current AEM Page object.
`currentNode`	`Node`	Current JCR Node object.
`resource`	`Resource`	Current Sling Resource object.
`request`	`SlingHttpServletRequest`	Current HTTP request object.
`response`	`SlingHttpServletResponse`	Current HTTP response object.
`log`	`Logger`	Output log to AEM error.log.
`wcmmode`	`WCMMode`	Current UI mode (edit, preview, disabled).
`currentStyle`	`Style`	Current component Policy configuration.

Practical Example:

<!-- Get page title -->
<title>${currentPage.title || currentPage.name}</title>

<!-- Check Edit mode to render placeholder for authors -->
<div data-sly-test="${wcmmode.edit || wcmmode.preview}">
    <p>Component is empty. Drag and drop data here.</p>
</div>

<!-- Print debug log -->
${'Component rendering started' @ log}

4. The Use API

3 ways to connect HTL with Backend Logic:

Level 1: Call Sling Model Directly (Recommended)

Standard approach for 99% of components.

<div data-sly-use.model="com.mysite.core.models.ArticleModel">
    ${model.title}
</div>

Level 2: Call Sling Model with Parameters

Pass parameters from HTL to Java model.

HTL Template:

<div data-sly-use.pagination="${'com.mysite.core.models.PaginationModel' @ currentPage=3, totalPages=10}">
    Page ${pagination.currentPage} / ${pagination.totalPages}
</div>

Java Sling Model:

@Model(adaptables = SlingHttpServletRequest.class)
public class PaginationModel {
    @RequestAttribute
    private int currentPage;

    @RequestAttribute
    private int totalPages;
}

Level 3: Use Javascript Use Objects (Deprecated)

Server-side JS files. Deprecated on AEM as a Cloud Service (AEMaaCS). Always use Sling Models.

5. Practical Example: Article Card Component

<!-- file: article-card.html -->

<!-- 1. Define reusable template -->
<template data-sly-template.articleCard="${@ article}">

    <!-- 2. Verify article object is not null -->
    <article class="cmp-article-card" data-sly-test="${article}">

        <!-- Render image if available -->
        <div data-sly-test="${article.image}" class="cmp-article-card__image">
            <img src="${article.image @ context='uri'}" alt="${article.imageAlt}" loading="lazy"/>
        </div>

        <div class="cmp-article-card__content">
            <!-- 3. Dynamic Element: Render h2, h3, or h4 -->
            <h3 data-sly-element="${article.headingLevel || 'h3'}" class="cmp-article-card__title">
                <a href="${article.link @ context='uri'}">${article.title}</a>
            </h3>

            <p data-sly-test="${article.excerpt}" class="cmp-article-card__excerpt">
                ${article.excerpt}
            </p>

            <span class="cmp-article-card__date">${article.formattedDate}</span>

            <!-- 4. Repeat loop for Tags -->
            <ul data-sly-test="${article.tags}" class="cmp-article-card__tags">
                <li data-sly-repeat="${article.tags}" class="cmp-article-card__tag">
                    ${item}
                </li>
            </ul>
        </div>
    </article>
</template>

<!-- Call Java model and pass model to template -->
<div data-sly-use.model="com.mysite.core.models.ArticleCardModel"
     data-sly-call="${articleCard @ article=model}">
</div>

6. HTL Best Practices

Always Use Sling Models: Keep complex logic in Java; HTL should only handle UI rendering.
Never Use context='unsafe': Unless fully aware of security implications.
Keep Templates Simple: If conditional statements become complex, move logic to Java.
Use Template & Call: Split UI into reusable fragments (data-sly-template/data-sly-call).
Follow BEM Naming: Use cmp- prefix for CSS classes to align with Core Components standards.
Provide Placeholders: Use wcmmode.edit to show placeholder messages when component is unconfigured.
Guard with data-sly-test: Check variables for null before rendering markup.

HTL Templates#

#HTL (HTML Template Language) in AEM

#1. Expressions

#1.1. Expression Options

#1.2. Display Contexts

#2. Block Statements

#2.1. data-sly-use (Initialize Model)

#2.2. data-sly-test (Conditional Rendering)

#2.3. data-sly-list vs data-sly-repeat (Loops)

#2.4. data-sly-resource vs data-sly-include

#2.5. data-sly-template / data-sly-call (UI Reuse)

#2.6. data-sly-element (Dynamic HTML Tag)

#2.7. data-sly-attribute (HTML Attributes)

#2.8. data-sly-text (Override Text)

#2.9. data-sly-unwrap (Remove Wrapper Tag)

#2.10. data-sly-set (Local Variable Assignment)

#3. Global Objects

#4. The Use API

#Level 1: Call Sling Model Directly (Recommended)

#Level 2: Call Sling Model with Parameters

#Level 3: Use Javascript Use Objects (Deprecated)

#5. Practical Example: Article Card Component

#6. HTL Best Practices