Sightly

You are reading the AEM 6.0 version of Sightly.
This documentation is also available for the following versions: Adobe Experience Manager 6.1 

Note

While Sightly has been introduced as part of AEM 6.0, there is also a feature pack available that offers a backport of the implementation included in AEM 6.1 for use in AEM 6.0.

Sightly FP 1.1 - AEM 6.1 Sightly scripting engine for CQ 5.6.1 - 6.0

You may download and install the above feature pack from Package Share and replicate to the publish server. If you do use the feature pack offering this packport, please refer to the 6.1 version of the Sightly documentation.

This section introduces the Sightly HTML templating system and provides an introduction to its syntax and a reference of available expressions, block statements and APIs.

Tools

Code Samples

  • Sightly Page Components Example (running instance required on localhost:4502)
    The Activities section of Geometrixx Outdoors is fully implemented using Sightly and server-side JavaScript for the logic. Enter developer mode and inspect the components on the page to see how they are built.
  • Sightly TodoMVC Example
    A feature-complete implementation of the famous TodoMVC exercise. In just about 300 lines of code, this sample shows how to build web applications with Sightly, getting status persisted on the server using the Apache Sling REST framework.

And follow Sightly on Twitter to keep posted about what's going on in the world of Sightly.

What is Sightly?

Sightly is an HTML templating language, introduced with AEM 6.0. It takes the place of JSP (Java Server Pages) and ESP (ECMAScript Server Pages) as the preferred templating system for HTML. The name “Sightly” (meaning “pleasing to the eye”) highlights its focus on keeping your markup beautiful, and thus maintainable, once made dynamic.

As in all HTML server-side templating systems, a Sightly file defines the output sent to the browser by specifying the HTML itself, some basic presentation logic and variables to be evaluated at runtime.

But, Sightly differs from other templating systems in three main ways:

  • Security by Default: Sightly automatically filters and escapes all variables being output to the presentation layer to prevent cross-site-scripting (XSS) vulnerabilities. As Sightly understands the HTML syntax, it is capable to automatically detect the scope in which variables are placed, and automatically do proper context-aware escaping and XSS protection. Yet, it is possible to manually control the display context if needed.
  • Separation of Concerns: The expressiveness of the Sightly template language is purposely limited, in order to make sure that a real programming language is used to express the corresponding presentation logic. This optional logic is invoked from Sightly expressions with the Use-API pattern, making it easy to understand what is called for a given view, and to potentially have different logic for different views of the same resource.
  • Sightly is HTML5: A Sightly file is itself a valid HTML5 file. All Sightly-specific syntax is expressed either within a data attribute, or within HTML text. Any Sightly file opened as HTML in an editor will automatically benefit from any features provided by that editor for regular HTML.

Sightly aims to reduce the time to market and the total cost of ownership for AEM projects:

  • Reducing project costs
    by making components editable for front-end developers.
  • Reducing operational costs
    by securing the templates against XSS injections.
  • Reducing maintenance costs
    by keeping templates readable and valid HTML5.

Getting Started

Every Sightly file is an HTML5 document or fragment, augmented with a specific syntax that adds the dynamic functionality. Here's a first example:

<h1 data-sly-test="${properties.jcr:title}">
    ${properties.jcr:title}
</h1>
        

Code samples are intended for illustration purposes only.

Two different kind of syntaxes have to be distinguished:

  • Sightly Block Statements
    To define structural block elements within Sightly file, Sightly employs HTML5 data attributes. This allows to attach behavior to existing HTML elements. All Sightly-specific attributes are prefixed with data-sly-.
  • Sightly Expressions
    Sightly expressions are delimited by characters
     ${ and }. At runtime, these expressions are evaluated and their value is injected into the outgoing HTML stream. They can occur within the HTML text or within HTML attribute values.
<p data-sly-use.logic="logic.js">
    <a href="${logic.link}">
        ${logic.text}
    </a>
</p>
        

Code samples are intended for illustration purposes only.

<h1 data-sly-test="${currentPage.title}">
    <a href="${currentPage.path}.html">
        ${currentPage.title}
    </a>
</h1>
        

Code samples are intended for illustration purposes only.

Some additional comments to understand the example from above in detail:

  • Line 1: The data-sly-test statement checks if the page title exists and is not empty. If so, the <h1> element and its content is displayed, otherwise it is removed altogether.
  • Line 2: This expression renders the page path into the href attribute. Since Sightly knows the HTML syntax, href and src attributes are automatically protected against cross-site scripting (XSS) injections accordingly. For instance if the variable contained a javascript: URL, it would have been removed.
  • Line 3: This expression displays the page title as text. Many special characters are escaped to make it impossible to inject cross-site scripts.

The AEM implementation of Sightly is doing all the rendering work on the server, so from the example above, the following HTML result would be sent to the client:

<h1>
    <a href="/content/my%20page.html">
        My page title&#x21;
    </a>
</h1>
        

Code samples are intended for illustration purposes only.

Notice how the whitespace in the link has been URL encoded, while the exclamation mark in the content has been HTML encoded. Because these characters can be instrumental in XSS attacks, Sightly automatically escapes them.

Related Articles

Comments in Sightly Files

Sightly comments are HTML comments with additional syntax. They are delimited like this:

<!--/* A Sightly Comment */-->

Anything within a Sightly comment will be entirely ignored by the Sightly processor and removed from the output.

However, the content of standard HTML comments, delimited like this:

<!-- An HTML Comment -->

will be passed through the Sightly processor and expressions within the comment will be evaluated. But it is not possible to have structural block elements within comments because HTML comments are pure text, even if they contain something that looks like HTML elements.

Example

So, if we have following variable in our context:

obj = {
    foo: "Foo.",
    bar: "Bar."
}
        

Code samples are intended for illustration purposes only.

then this template:

<!--/* The value of foo is: ${obj.foo} */-->
<!--
    The value of bar is: ${obj.bar}
    <span data-sly-test="${obj.foobar}">${obj.foo} ${obj.bar}</span>
-->
        

Code samples are intended for illustration purposes only.

will output this HTML:

 
<!--
    The value of bar is: Bar.
    <span data-sly-test="">Foo. Bar.</span>
-->
        

Code samples are intended for illustration purposes only.

Loading Client Libraries

Prior to Sightly, client libraries were loaded on a page using a JSP taglib. However, JSP taglibs cannot be used in Sightly scripts. Therefore, some helper templates provide this functionality.

The client libraries helper template library (/libs/granite/sightly/templates/clientlib.html) can be loaded through data-sly-use and stored in a clientLib block element variable. Loading the library's CSS style sheets and JavaScript is done through data-sly-call. The clientLib template library exposes three templates:

  • css - loads only the CSS files of the referenced client libraries
  • js - loads only the JavaScript files of the referenced client libraries
  • all - loads all the files of the referenced client libraries

Each helper template defines a categories option that accepts either an array of string values or a string containing a comma separated values list for referencing the desired client libraries.

Here are a few short examples:

Referencing client libraries components in different sections of a page
<head data-sly-use.clientLib="${'/libs/granite/sightly/templates/clientlib.html'}">
    <css data-sly-call="${clientLib.css @ categories=['category1', 'category2']}" data-sly-unwrap/>
</head>
<body>
    <!-- content -->
    <js data-sly-call="${clientLib.js @ categories=['category1', 'category2']}" data-sly-unwrap/>
</body>
        

Code samples are intended for illustration purposes only.

Referencing client libraries in the <head> tag of a page
<head data-sly-use.clientLib="${'/libs/granite/sightly/templates/clientlib.html'}">
    <clientlib data-sly-call="${clientLib.all @ categories=['category1', 'category2']}" data-sly-unwrap/>
</head>
        

Code samples are intended for illustration purposes only.

Moving from JSP to Sightly

It is recommended for new AEM projects to use Sightly as it offers multiple benefits compared to JSP. For existing projects though, a migration only makes sense if it is estimated to be less effort than maintaining the existing JSPs for the coming years.

But moving to Sightly is not necessarily an all-or-nothing choice, because components written in Sightly are compatible with components written in JSP or ESP. Meaning that existing projects can without a problem use Sightly for new components, while keeping JSP for existing components.

Even within the same component, Sightly files can be used alongside JSPs and ESPs. For example, a JSP can include a Sightly file like this,

<cq:include script="footer.html"/>

and a Sightly file can include a JSP like this,

<div data-sly-include="footer.jsp"></div>


Any questions?
Find tips, tricks, and solutions to common issues in our support community:
https://helpx.adobe.com/marketing-cloud/experience-manager.html
​