Sightly – Quick Reference

Sightly was introduced by AEM 6.0 to replace JSP by a new HTML Templating System. This post is a quick reference about Sightly. A list of best practices and things to know.

Java class or server side Javascript

With Sightly, you can create a component with two methods. By using Java Class or Javascript Server-Side File. Personnaly, I always use Java Class, but Javascript seems to be a really good deal if you want to develop your components with one language. But keep in mind that AEM Java API offer more functionnalities than Javascript API.

  • Sigthly component with Java

  • Sightly Component with server side Javascript

You do have to know that you cannot pass argument to the method. But it is possible to pass argument at the activation of the Java/Javascript class. Example with Java Class :

Context Objects

With Sightly you can directly use component/page properties in HTML file like JSP does. You can access to a wide range of Java Objects (currentPage, currentNode….) too :

Variable Name Description
properties List of properties of the current Resource.
pageProperties List of page properties of the current Page.
inheritedPageProperties List of inherited page properties of the current Page.
Variable Name Description
component com.day.cq.wcm.api.components.Component
componentContext com.day.cq.wcm.api.components.ComponentContext
currentDesign com.day.cq.wcm.api.designer.Design
currentNode javax.jcr.Node
currentPage com.day.cq.wcm.api.Page
currentSession javax.servlet.http.HttpSession
currentStyle com.day.cq.wcm.api.designer.Style
designer com.day.cq.wcm.api.designer.Designer
editContext com.day.cq.wcm.api.components.EditContext
log org.slf4j.Logger
out java.io.PrintWriter
pageManager com.day.cq.wcm.api.PageManager
reader java.io.BufferedReader
request org.apache.sling.api.SlingHttpServletRequest
resource org.apache.sling.api.resource.Resource
resourceDesign com.day.cq.wcm.api.designer.Design
resourcePage com.day.cq.wcm.api.Page
response org.apache.sling.api.SlingHttpServletResponse
sling org.apache.sling.api.scripting.SlingScriptHelper
slyWcmHelper com.adobe.cq.sightly.WCMScriptHelper
wcmmode com.day.cq.wcm.api.WCMMode (in Sightly, evaluates to a string, either“EDIT” or “DESIGN”)
xssAPI com.adobe.granite.xss.impl.XSSAPImpl

All these objects are accessible using Sightly, server side Javascript and Java class.

If you want to modify the value before accessing a property you can obviously use a Java Class/Server side Javascript as shown in the first part.

Conditional operators

With sightly you can use conditional operators :

You should mix conditional operators and data-sly-test block statement.

String Formatting

I18n / Internationalization

Display Context

If you want to write a resource property as an HTML attribute or as an JS comment, the display context is different. That’s why sightly provides some context which will format/filter the property value.

HTML context:

Context Name
When to use What it does
text Default for content inside elements Encodes all HTML special characters.
html To safely output markup Filters HTML to meet the AntiSamy policy rules,
removing what doesn’t match the rules.
attribute Default for attribute values Encodes all HTML special characters.
uri To display links and paths
Default for href and src attribute values
Validates URI for writing as an href or src attribute value,
outputs nothing if validation fails.
number To display numbers Validates URI for containing an integer,
outputs zero if validation fails.
attributeName Default for data-sly-attribute when setting attribute names Validates the attribute name,
outputs nothing if validation fails.
elementName Default for data-sly-element Validates the element name,
outputs nothing if validation fails.

Javascript context:

Context When to use What it does
scriptToken For JS identifiers, literal numbers, or literal strings Validates the JavaScript token,
outputs nothing if validation fails.
scriptString Within JS strings Encodes characters that would break out of the string.
scriptComment Within JS comments Validates the JavaScript comment,
outputs nothing if validation fails.

CSS context:

Context When to use What it does
styleToken For CSS identifiers, numbers, dimensions, strings, hex colours or functions. Validates the CSS token,
outputs nothing if validation fails.
styleString Within CSS strings Encodes characters that would break out of the string.
styleComment Within CSS comments Validates the CSS comment,
outputs nothing if validation fails.

Other context :

Context When to use What it does
unsafe Only if none of the above does the job Disables escaping and XSS protection completely.

Display context can be used as bellow

Block statement

data-sly-use : Initializes a helper object (defined in JavaScript or Java) and exposes it through a variable.

data-sly-unwrap : Removes the host HTML element.

data-sly-attribute : Adds HTML attributes to the host element.

With a map of attributes

data-sly-test : Conditionally removes the HTML host element.

data-sly-list : Repeats the content of the host element for each enumerable property in the provided object.

ItemList is an object that is available in the data-sly-list statement and provide the following properties :

  • index : counter (0-n)
  • count : counter (1-n)
  • first : if the current item is the first item
  • middle: if the current item is neither the first nor the last item
  • last: if the current item is the last item
  • odd: if index is odd
  • even: if index is even

data-sly-resource : Includes the indicated resource.

data-sly-templatedata-sly-call : Defines a template and call it.

You can define your template in a different file :

Other

Clientlibs

Some examples :

11 Comments

  1. Pingback: Tips of using Sightly in AEM6 | AEM Treasury

  2. Very Useful! Thank you!

  3. You spelled “template” wrong in the last example:
    tempalte

  4. assuming if I would like to inject an html tag inside a given HTML, how can I do that?

    ${properties[‘jcr:title’]}

    in the above example what if I want to inject “class=’something'” (the whole thing) based on a condition inside an href. can you guide?

    • Hi,

      You should use the data-sly-attribute with a map of attributes. I added an example in the data-sly-attribute paragraph

  5. this is awesome. It fills the massive gap in adobes very poor documentation

  6. Pingback: A Very, Very, Quick Sightly Reference | Terra Beata

  7. Very helpful. Thank you so much for the article.

  8. nice article…

Leave a Reply