Sightly:

Cheatsheet

Part 1
Tushar Bhite
 HTL (SIghtly) Introduction :
HTL Intro :

The HTML Template Language (HTL) provides separation of concerns between

the logic and the markup. Compared to JSP , HTL provides a good security model
and ensures project e ciency. HTL has powerful extension mechanisms for reuse
of logic and of mark-up.
The HTML Template Language comprises

i). Expression language : Used to insert pieces of content into the rendered
markup.
ii). Block Statements: Used to define statements over blocks of markup
(conditions/iterations)

HTL is strict so that it does not allow to

mix code inside the markup. HTL uses
the 'Use-API extension' technique to
easily execute code from the HTL
template.

Common and recommended method

is to write business logic in Java.In case
the component needs some view-
specific changes from what the Java
API provide, it is recommended to use
server-side executed JavaScript.

Advantages:
Increased Security
HTL gets compiled into Java Servlets, during this process the expressions and
the HTL data attributes are both evaluated entirely server-side, thus the view
source option of HTML page does not show anything.

Reduced Costs
HTL Provides increased security, simplified development and improved team
collaboration, faster time to market (TTM), reduced e ort and lower total cost of
ownership (TCO).

Simplified Development
The HTML Template Language is easy to learn for a developer who knows basic
HTML and its syntax and features are purposely limited to ensure that it stays
simple and straight-forward.
 HTL Syntax :
HTL Syntax
HTL is strict with the syntax. Considering the types there are two types of
HTL syntax.

Block Statements :

Basically they are custom data attributes added directly to existing HTML.
Block statements are prefixed with data-sly.

Below are the block statements.

HTL sly-test
HTL sly-use
HTL sly-unwrap
HTL sly-text
HTL sly-attribute
HTL sly-element
HTL sly-repeat
HTL sly-list
HTL sly-resource
HTL sly-include
HTL sly-template
HTL sly-call

Expression Language :
HTL expressions are evaluated at run time and their value is injected into the
outgoing HTML stream.
HTL expressions are delimited by characters ${ and }.

Below given the Expression Languages.

HTL Variables
HTL Literals(Boolean, Number,Strings,Arrays)
HTL Operators(Logical Operators,Conditional (ternary) Operator, Comparison
Operators, Grouping parentheses)
HTL Options(String Formatting,Internationalization,Array Join,Display Context)
 HTL Options :
HTL Options

Options are used with block statements, Symbol @ starts the option expression.
Options can have a value, which may be either a variable or a literal. Options are
mainly used for String Formatting, Internationalization, Array Join.

String Formatting :
${'Page {0} of {1}' @ format=[current, total]}

Internationalization :
${'Page' @ i18n, hint='Direction for translators', source='user'}

Array Join :
${['1', '2'] @ join='; '}

Display Context :

HTL will automatically detect the context of expressions and escape them
appropriately to ensure the security and avoid XSS vulnerability. The context
behavior may need to be adjusted as our coding needs. This can be explicitly set
to override the automatic behavior of HTL. HTL display context refers to its
location within the structure of the HTML page.

Display Context Settings are given below

● text
● html
● attribute
●uri
● number
● attributeName
● elementName
● scriptToken
● scriptString
● scriptComment
● styleToken
● styleString
● styleComment
● unsafe
//Safely output the markup
${properties.richText@context='html'}
color: ${red @ context=’scriptToken’} //No spaces in css
fonntfamily:${bold italic strikethrough @ context=’styleString’} //spaces in
between values
 HTL Variables :
HTL Variables

Variables holds the data values or objects.

Below given the list of global objects which can be accessed

--Enumerable Objects-- --Java-backed Objects --

1. properties component,componentContext,currentDesign
2 pageProperties currentNode, currentPage, currentSession,
. InheritedPageProperti currentStyle, designer, editContext, log out,
3 es pageManager, reader, request resolver, resource,
. resourceDesign, resourcePage, response, sling,
slyWcmHelper,wcmmode,xssAPI.

We can access the properties of variables in two ways .

Notations :

1)Dot notation: simpler,preferred for most cases.

//access the page title
${currentPage.title}

2)Bracket notation: to access properties dynamically or to access properties that

contain invalid identifier characters.
//access the page title
${currentPage['title']} or ${currentPage["title"]}

Accessing :
Thumb rule for valid names
start with a letter (A-Z and a-z), or an underscore (_), and subsequent characters
can also be digits (0-9) or colon (:).

Access unicode or invalid identifier characters

${properties['title propertyå']}

Access Members Dynamically

${properties[myVarProperty]}

Access variables which has 'Null' Values

${currentNode.lastModified.time.toString}
 HTL Literals :
HTL Literals

Literals holds a constant(fixed) value. It can be of 4 types mainly.

Boolean : Represents on o condition. It can be accessed as

${true} ${false}

Numbers : HTL Supports only positive digits , not negative numbers or

${11}
floating.
Strings : Holds text values
${'mytext1'} ${"mytext2"}

For eg:
<p>${'John\'s car is "awesome !", Maria said'}</p>

Below special characters are allowed in HTL Strings.

\\ Backslash character
\' Single quote
\" Double quote
\t Tabulation
\n New line
\r Carriage return
\f Form feed
\b Backspace
\uXXXX
digits) (Unicode character specified by the four hexadecimal

Arrays :
An array is a collection of values that can be represented with a common
name. An array will have an index ans ordered.

Samples:
//Array of 2 elements
${utilityArray[2]}
// Array of 5 digits
${[1,2,3,4,5]}
//print an array by names separated
by ':' ${utilityArray.names @ join=':'}

//Dynamically accessing Array

<ul data-sly-
list="${utilityArray.names}">
<li>${ properties[item]}</li>
</ul>
 HTL Operators :

Logical Operators :
Logical Operators are used with Boolean values, where the operator returns the
value of one of the specified operands. While using with non-Boolean values,
they may return a non-Boolean value. They are of 3 types.

● AND:<Pdata-sly-test="${properties.jcr:title&&
properties.jcr:description}">DISPLAY</p>
● OR:<Pdata-sly-test="${properties.jcr:title||
properties.jcr:description}">DISPLAY</P>
● NOT:<pdata-sly-test="${!currentPage.hasChild}">DISPLAY</p>
Conditional/Ternary Operators :
Conditional operator can be used to define conditions within expressions.
${condition ? resultExpressionWhenTrue : resultExpressionWhenFalse}

Comparison Operators :
Comparison Operators(equality and inequality operators) used to compare
identical type operands.

● Strings-equal-havingthesamesequenceofcharacters.
● Numbers-equalhavingthesamevalue
● Booleans-equal-whenbotharetrueorbotharefalse.
● Nullorundefinedvariables-equal-tothemselvesandtoeachother.
Samples:

<div data-sly-test="${properties.jcr:title == 'true'}">TRUE</div>

<div data-sly-test="${properties.jcr:title != 'true'}">FALSE</div>

<div data-sly-test="${properties['jcr:title'].length > 5}">Title is longer than

5</div>
<div data-sly-test="${properties['jcr:title'].length >= 5}">Title is longer or equal
to 5 </div>

<div data-sly-test="${properties['jcr:title'].length > myArray.MAX_LENGTH}">

Title is longer than the limit of ${myArray.MAX_LENGTH}
</div>

Grouping Parenthesis :
As in other languages HTL supports bracketing to ensure the preference of
operation.

${thirdVar && (firstVar || secondVar)}

HTL sly-test :

<data-sly-test/> Validates and conditionally removes the host element and it's
content. Returned 'False' removes the element; Returned value 'true' retains the
element.

For eg:
Here the h1 element and its content will only be rendered if 'display' is true.

<h1 data-sly-test="${display}">text</h1>

Create if-else in HTL.

We can construct if-else by utilizing data-sly-test. The result of a test can be
assigned to a variable. This can be utilized for future validations.

For eg:

<h1 data-sly-test.myVar="${x || y || z}">is

true</h1> <h1 data-sly-test="${!myVar}">Else
This</h1>

HTL sly-use :

Used to initialize a Java class or JavaScript object. Parameters can be passed to

the initialization using options
Java

<div data-sly-use.nav="org.company.Navigation">${nav.foo}</div>

JavaScript

<div data-sly-use.nav="navigation.js">${nav.foo}</div>
HTL sly-unwrap :

HTL sly-unwrap
Trims the html element from the generated markup.

For eg:
<p data-sly-use.sort="sorting.js" data-sly-unwrap>Sort Text</p>

will avoid <p> in the output html.

HTL sly-text

HTL sly-text
Inserts the content of its host element with the specified text by replacing it.

For eg:

<div data-sly-text="${currentPage.title}">My page title</div>

. Prints the current page title, still helpful for searching in html source using
term 'My Page Title'

HTL sly-attribute

HTL sly-attribute

Helps to add attributes to the host element.

For eg:

<div title="Page Title" data-sly-attribute.title="${properties.jcr:title}"></div>

HTL sly-element

HTL sly-element

Used to replaces the element name of the host element of html tags.

For eg:

<h6 data-sly-element="${headerLevel}">Title Text</h6>

This replaces the h6 with the value of headerLevel. (Say the returned value for
'headerLevel' is h1, the <h6> will be replaced to h1)

HTL sly-repeat :

HTL sly-repeat
This tag helps to repeat an element multiple times based on the list which
is specified.

For eg:

<div data-sly-repeat="${currentPage.listChildren}">${item.name}</div>

The di erence with <data-sly-list/> is that list needs a container element where
repeat does not require it.
HTL sly-list :
HTL sly-list

List tag repeats the content of the host element for each enumerable property
in the provided object.

For eg:

<h6 data-sly-list="${currentPage.listChildren}">
<dt>index: ${itemList.index}</dt>
<dd>value: ${item.title}</dd>
</h6>

Where 'item' is the current item in the iteration & itemList is the object holding
the properties.
ItemList Properties:
Property Description

index: zero-based counter (0..length-1).

count: one-based counter (1..length).

first: true if the current item is the first item.

middle: true if the current item is neither the first nor the last

last: item. true if the current item is the last item.

odd: true if the index is odd.

even: true if the index is even.

Accessing an HTL list value dynamically,

<h6 data-sly-list.child="${myList}">
<dt>key: ${child}</dt>

<dd>value: ${myList[child]}</dd>
</h6>
HTL sly-resource ;

HTL sly-resource

Helps to include the result of a resource from a path specified. The sling
resolution and rendering process will process the indicated resource from
the path and the result will be included.

<file data-sly-resource="path/to/myresource"></file>

We can mention various methods for referring resource path. Shown below.

● "${ @ path='path/to/myresource'}"
● "${'myresource' @ prependPath='my/path'}"
● "${'my/path' @ appendPath='myresource'}"

We have also options to modify path using selectors as @ selectors, @

addSelectors, @ removeSelectors

HTL sly-include :
HTL sly-include

Helps to replace the content of the host element with the markup generated by
the specified HTML template file (It can be any of the HTL, JSP, ESP formats.)

For eg: a JSP Can be included by,

<section data-sly-include="path/to/jsptemplate.jsp"></section>
HTL sly-template :

HTL sly-template

Used to define a template where the host element and its content are not
output by HTL. Always used with <data-sly-call/>

For eg:

<template data-sly-template.mytemplate>TEST</template>
<div data-sly-call="${mytemplate}"></div>

HTL sly-call

HTL sly-call
Used to call a template defined with <data-sly-template/>. The content of the
called template replaces the content of the host element of the call.

For eg:

<template data-sly-template.mytemplate>TEST</template>
<div data-sly-call="${mytemplate}"></div>
HTL Formatting :
HTL allows rich way of URL Formatting.
HTML Extension

<a href="${item.path @ extension = 'html'}">${item.name}</a>

Adds the html extension to a path.

<a href="${item.path @ extension = 'html', selectors ='products'}">${item.name}</a>

Adds the html extension and a selector to a path.

<a href="${item.path @ extension html',fragment=item.name}"> ${item.name}</a>

Adds the html extension and a fragment (#value) to a path.

HTL Date & Number formatting

The latest AEM versions support numbers and dates formatting which includes
timezone and locale formatting. We don't have to write custom code any more.
The syntax for formatting is format is specified first, then the value which needs
to be formatted.
For eg
Date formatting

<h6>${ 'dd-MMMM-yyyy hh:mm:ss' @

format=currentPage.lastModified, timezone='PST', locale='fr'}</h6>

Number formatting

<h6>${ '#.00' @ format=500}</h6>

 HTL request attributes :

HTL request attributes

While using <data-sly-include/> and <data-sly-resource/> it is now easy to pass
'requestAttributes'. These 'requestAttributes' can be accessed or processed in
receiving HTL-script.

For eg.

<sly data-sly-use.settings="com.adobe.examples.htl.core.hashmap.Settings"
data-sly-include="${ 'productdetails.html' @
requestAttributes=settings.settings}" />

And 'requestAttributes' can be passed from Java class.

public class Settings extends WCMUsePojo {

// used to pass is requestAttributes to data-sly-resource

public Map<String, Object> settings = new HashMap<String, Object>();

@Override
public void activate() throws Exception {
settings.put("order", "ascending");
}
}

Using requestAttributes using the Sling-Model way.

@Model(adaptables=SlingHttpServletRequest.class
) public class ProductSettings {
@Inject @Optional @Default(values="empty")
public String order;

}
 Thank You

Connect or Follow for regular updates

Feel free to ask any queries or

corrections or any help on this.

Tushar Bhite