Article updated on July 27, 2016.

Here are some examples on how you can use the JavaScript Use-API with the HTML Template Language (HTL), formerly known as Sightly. If you’re new to the language, I’d recommend that you also have a look that the getting started guide for HTL.

Hello World

Let’s start with the “Hello World” example, to get a basic idea how the Use-API works.

I have this in the .html file of my component:

<div data-sly-use.logic="logic.js">
    ${logic.hello}
</div>

And this is my logic.js:

use(function () {
    var message = "Hello World";

    return {
        // anything exposed here can be used inside your template
        hello: message
    };
});

I hope this example is quite self-explanatory. First, the data-sly-use attribute executes the content of the “logic.js” file and makes the result available in a variable named “logic”. Then, the “logic.js” file provides a function that returns an object with a property named “hello”.

Note that all of this is executed server-side, and the result sent to the client is the markup without any data-sly- arguments.

Using predefined objects

Here now an example on how to use predefined objects within your JS file. In this sample I am simply outputting some values in order to show you how to use the predefined objects.

This is in my HTL component:

<div data-sly-use.predefined="predefined.js">
    <p>${predefined.pageName}</p>
    <p>${predefined.title}</p>
    <p>${predefined.resourceName}</p>
    <p>${predefined.resourceTitle}</p>
</div>

This is my predefined.js file:

use(function () {
    var pageName = currentPage.name;
    var title = currentPage.properties.get("jcr:title");
    var resourceName = granite.resource.name;
    var resourceTitle = properties.get("jcr:title");

    return {
        pageName: pageName,
        title: title,
        resourceName: resourceName,
        resourceTitle: resourceTitle
    };
});

Passing parameters to the JavaScript Use-API

In this example I will pass on some parameters to the JS file.

This is my HTL component:

<div data-sly-use.params="${'params.js' @ value1='feike', value2='visser', seperator=' '}">
    ${params.newValue}
</div>

Please note the ${‘ ‘} notation used to define the Use-API that is called: using an HTL expression allows to specify options (everything that follows the “@” symbol), which will be passed as parameters to the Use-API.

This is in my HTL JavaScript logic file “params.js”:

use(function () {
    // you can reference the parameters via the this keyword.
    var retValue = this.value1 + this.seperator + this.value2;

    return {
        newValue: retValue
    };
});

Passing objects to HTL templates

In HTL, it is possible to isolate pieces of markup in templates, and to call them in a similar fashion with data-sly-call. In this example, I will create a template to list the children of the provided page object. Strictly speaking, this isn’t related to the JS Use-API but it introduces the data-sly-template feature that is necessary to understand for the next section.

This is the .html file of my component:

<h2>Child Pages</h2>
<div data-sly-use.template="templates.html"
     data-sly-call="${template.pageChildren @ parent=currentPage}"></div>

I can then have a templates.html file with commonly reused templates, like following one:

<sly data-sly-template.pageChildren="${@ parent}">
    <ul data-sly-list="${parent.listChildren}">
        <li>${item.title}</li>
    </ul>
</sly>

This is how it works:

  • The component first initializes the “templates.html” file with data-sly-use, which makes it available as a “template” variable. This also makes all contained data-sly-template blocks available as properties of that “template” variable.
  • With data-sly-call, I can then execute my template, placing the parameters that the template accepts after the “@” sign.

Passing Java-backed objects to the JavaScript Use-API

Most of the time, passing Java-backed objects to the JS files is not necessary, because the same objects available in HTL are also available in the Use-API logic. But there’s one case where this is needed, when a piece of HTML has been isolated in a reusable template, like in the previous example. If the template receives some parameters and needs to execute some logic on them, then the received parameters must be passed as well to the JS logic.

My HTL component still remains the same as previous example:

<h2>Child Pages</h2>
<div data-sly-use.template="templates.html"
     data-sly-call="${template.pageChildren @ parent=currentPage}"></div>

But my template now uses the associated “pageChildren.js” JS file, and maks its result available in a “logic” variable, which is then used to iterate with data-sly-list:

<sly data-sly-template.pageChildren="${@ parent}"
     data-sly-use.logic="${'pageChildren.js' @ parent=parent}">
    <ul data-sly-list="${logic.children}">
        <li>${item.title}</li>
    </ul>
</sly>

And this is the associated JS file, which will remove all invalid and hidden pages from the list:

var PageFilter = Packages.com.day.cq.wcm.api.PageFilter;

use(function () {
    var filter = new PageFilter(request);
    var children = this.parent.listChildren(filter);

    return {
        children: children
    };
});

You can see how I access the passed “parent” variable via “this.parent”.
Also notice how Java classes can be accessed over the “Packages” variable.

I hope you found these examples useful and that they allow you to start using the HTML Template Language JavaScript Use-API.

@heervisscher

Read-on

Other posts on the topic:

And here other resources to learn more about it:

0 comments