HTL/Sightly in AEM 6.3

HTL/Sightly in AEM 6.3

The term “sightly” or “HTL” is not very new to all of us. We have been developing our components in HTL in place of “JSP” since long.

But as it is little hard to remember all the syntax, In this blog I am trying to cover all the possible block statements in HTL/sightly with use cases as well.

How to include parsys in HTL/Sightly

<div data-sly-resource="${'parsys' @resourceType = 'wcm/foundation/components/parsys'}"></div>

While included parsys in the Page Component, you need to add init.jsp in the page.

<sly data-sly-include="/libs/wcm/core/components/init/init.jsp"/>

Note: Don’t add init.jsp on every page or component, where you need parsys to include. Just add it in base page component and use it everywhere.

How to include clientlibs in a page OR a component in HTL/Sightly

While using single clientlibs:

<sly data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html"

data-sly-call="${clientLib.all @ categories='apps.aem-learning'}"/>

While using multiple clientlibs:

<sly data-sly-use.clientlib="/libs/granite/sightly/templates/clientlib.html"

data-sly-call="${clientlib.all @ categories=['myCategory1', 'myCategory2']}"/>

Note: Here keyword “all” stands for all the JS and CSS files. If you want to call JS and CSS specifically, replace all keyword with “CSS” or “JS”.

Difference between data-sly-list and data-sly-repeat

The difference between these two is data-sly-list just iterates the items written on its condition. Example:

<ul data-sly-list="${currentPage.listChildren }">

    <li>  ${item.name} </li>

</ul>

The DOM structure of the above statement will be:

Add caption

But if you put the same statement with data-sly-repeat, it will iterate the complete structure including the conditional statement as well.

Example: 

<ul data-sly-repeat="${ currentPage.listChildren }">

   <li>  ${item.name} </li>

</ul>

The DOM structure of the above statement will be:

Add caption

If you want to have the same output from repeat, like list, you need to write something like:

<ul>

      <li data-sly-repeat.child="${ currentPage.listChildren }">

  ${child.name} 

      </li>

</ul>

• 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 index is odd.
• even: true if index is even

<ul data-sly-list="${currentPage.listChildren}"

       <li data-sly-test="${itemList.even}">${item.title}</li>

</ul>

How to iterate map objects in HTL/sightly

<p data-sly-repeat.mapItem="${myMap}">

   <span>key: ${ mapItem }</span>

   <span>value: ${myMap[mapItem]}</span>

</p>

Note:Always use the identifier instead of default “item” variable for list of block and repeat statements.

How to use data-sly-use in HTL/Sightly

data-sly-use "is used to add JS/JAVA". You declare component-beans with this statement for instance:

<sly data-sly-use.example="com.example.project.helloWorld"/>

       ${example.path}

data-sly-use with input parameters:

<div data-sly-use.example="${'com.sling.models.core.models.TestModel' @ color='red'}">

Note: Try to place use data-sly-use statements only on top-level elements.

How to declare variables in HTL/Sightly

Always cache test block statement results in an identifier if it repeats itself. There may be a need of using a value at various place in a single HTML, so it’s good to have a variable having that value and use it at all places.

<sly data-sly-test.path="${currentPage.path}"/>

Now ${path} can be used to show the path of currentPage.

What is the use of sly tag?

Sly tag don’t let be the statements the part of DOM and clears out the rendered HTML and get rid of additional divs. You can also use data-sly-unwrap to remove the element from DOM.

Note: Always use existing HTML elements for your block statements if possible.

data-sly-resource in HTL/Sightly

Includes the result of rendering the indicated resource through the sling resolution and rendering process. It works completely on the concept of sling resolution.

Manipulating the path of the resource.

<article data-sly-resource=”${@path=’path/to/resource’}”/>

<article data-sly-resource=”${‘resource’ @prependPath=’my/path’}”/>

<article data-sly-resource=”${my/path @appendPath=’‘resource’’}”/>

Replace the selector from the existing ones.

<article data-sly-resource=”${‘path/to/resource’ @selectors=’selectors’}”></article>

<article data-sly-resource=”${‘path/to/resource’ @selectors=[’s1’,’s2’]}”></article>

Add a selector to the existing ones.

<article data-sly-resource=”${‘path/to/resource’ @addSelectors=’selector’}”></article>

Remove the selectors from the existing ones.

<article data-sly-resource=”${‘path/to/resource’ @removeSelectors=’selector’}”></article>

Remove all selectors.

<article data-sly-resource=”${‘path/to/resource’ @removeSelectors}”></article>

Overrides the resourceType of a resource.

<article data-sly-resource=”${‘path/to/resource’ @resourceType=’my/resource/type’}”>

</article>

Changes the WCMMode

<article data-sly-resource=”${‘path/to/resource’ @wcmmode=’disabled’}”></article>

By default, The AEM Decoration Tags are disabled, the decoration tagName option allows

 to bring them back and the cssClassName to add classes to that element.

<article data-sly-resource="${'path/to/resource' @ decorationTagName='span',

cssClassName='className'}"></article>

data-sly-include in HTL/Sightly

data-sly-include is used to include other HTML files like:

<sly data-sly-include=”content.html”> </sly>

<div data-sly-include=”${‘template.html’}”></div>

<div data-sly-include=”${‘template.html’ @appendPath=’appended/path’}”></div>

<div data-sly-include=”${‘template.html’ @prependPath=prepended/path’}”></div>

<div data-sly-include=”${@file = ‘‘template.html’,@prependPath=prepended/path’,

@appendPath=’appended/path’}”></div>

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

<!--/* Following will simply output the rendered content of the template, the complete <div> element will be ignored.*/-->

<div id=”test-one” class=”test-two” data-sly-include=”template.html”>Foo </div> 

<!--/* Outputs only the result of the template. */-->

Try to unwrap all includes resources and other HTML elements that are not part of the markup.

data-sly-template in HTL/Sightly

Template blocks can be used like function calls: in their declaration, they can get parameters, 

which can then be passed when calling them. 

Static template that has no parameters:

<template data-sly-template.one>blah</template>

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

<template data-sly-template.two="${@ title, resource='The resource of the parent node'}">

    <h1>${title}</h1>

    <p>Parent: ${resource.name}</p>

</template>

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

<div data-sly-use.lib="templateLib.html" data-sly-call="${lib.one}"></div>

<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.

Note: Always define your templates in a separate file.

Note: Always place block statements after the normal HTML attributes.