SCF Handlebars Helpers scf-handlebars-helpers

Handlebars Helpers (helpers) are methods callable from Handlebars scripts to facilitate working with SCF components.

The implementation includes a client-side and a server-side definition. It is also possible for developers to create custom helpers.

The custom SCF helpers delivered with AEM Communities are defined in the client libarry:

Abbreviate abbreviate

A helper to return an abbreviated string conforming to the maxWords and maxLength properties.

The string to be abbreviated is provided as the context. If no context is provided, an empty string is returned.

First, the context is trimmed to maxLength, and then the context is sliced into words and reduced to maxWords.

If safeString is set to true, then the returned string is a SafeString.

Parameters parameters

Examples examples

{{abbreviate subject maxWords=2}}

/*
If subject =
    "AEM Communities - Site Creation Wizard"

Then abbreviate would return
    "AEM Communities".
*/

{{{abbreviate message safeString=true maxLength=30}}}

/*
If message =
    "The goal of AEM Communities is to quickly create a community engagement site."

Then abbreviate would return
    "The goal of AEM Communities is"
*/

Content-loadmore content-loadmore

A helper to add two spans under a div, one for the full text and the other for the less text, with the ability to toggle between the two views.

Parameters parameters-1

Example example

{{content-loadmore  context numChars=32  moreText="go on"  ellipsesText="..." }}

/*
If context =
    "Here is the initial less content and this is more content."

Then content-loadmore would return
    "Here is the initial less content<span class="moreelipses">...</span> <span class="scf-morecontent"><span>and this is more content.</span>  <a href="" class="scf-morelink" evt="click=toggleContent">go on</a></span>"
*/

DateUtil dateutil

A helper to return a formatted date string.

Parameters parameters-2

Examples examples-1

{{dateUtil this.memberSince format="dd MMM yyyy, hh:mm"}}

// returns "18 Mar 2015, 18:17"

{{dateUtil this.birthday format="MM-DD-YYYY"}}

// returns "03-18-2015"

Equals equals

A helper to return content depending on an equality conditional.

Parameters parameters-3

Example example-1

{{#equals  value "some-value"}}
  <div>They are EQUAL!</div>
{{else}}
  <div>They are NOT equal!</div>
{{/equals}}

If-wcm-mode if-wcm-mode

A block helper that tests the current value of WCM mode against a string separated list of modes.

Parameters parameters-4

Example example-2

{{#if-wcm-mode mode="DESIGN, EDIT"}}
 ...
{{else}}
 ...
{{/if-wcm-mode}}

i18n i-n

This helper overrides the Handlebars helper ‘i18n’.

See also Internationalizing Strings in JavaScript Code.

Parameters parameters-5

Example example-3

{{i18n "hello"}}
{{i18n "hello" comment="greeting" default="bonjour"}}

Include include

A helper to include a component as a non-existing resource in a template.

This allows the resource to be programmatically customized more easily than is possible for a resource added as a JCR node. See Add or Include a Communities Component.

Only a select few of Communities components are includable. For AEM 6.1, those that are includable are comments, rating, reviews, and voting.

This helper, appropriate only on the server-side, provides functionality similar to cq:include for JSP scripts.

Parameters parameters-6

Example example-4

{{include this.id path="comments" resourceType="social/commons/components/hbs/comments"}}

This will include a new comments component at this.id + /comments

IncludeClientLib includeclientlib

A helper that includes an AEM html client library, which can be a js, a css or a theme library. For multiple inclusions of different types, for example js and css, this tag needs to be used multiple times in the Handlebars script.

This helper, appropriate only on the server-side, provides functionality similar to ui:includeClientLib for JSP scripts.

Parameters parameters-7

Examples examples-2

// all: js + theme (theme-js + css)
{{includeClientLib categories="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js" type="text/javascript"></script>

// only js libs
{{includeClientLib js="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <script src="/etc/clientlibs/social/hbs/tally/voting.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js" type="text/javascript"></script>

// theme only (theme-js + css)
{{includeClientLib theme="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js" type="text/javascript"></script>

// css only
{{includeClientLib css="cq.social.hbs.comments, cq.social.hbs.voting"}}

// returns
    <link href="/etc/clientlibs/social/hbs/tally/voting.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css" rel="stylesheet" type="text/css">

Pretty-time pretty-time

A helper to display how much time has passed up to a cutoff point, after which a regular date format is displayed.

For example:

Parameters parameters-8

Example example-5

{{pretty-time this.published daysCutoff=7}}

/*
Depending on how long in the past, may return

  "3 minutes ago"

  "3 hours ago"

  "3 days ago"
*/

Xss-html xss-html

A helper that encodes a source string for HTML element content to help guard against XSS.

NOTE: this is not a validator and is not to be used for writing attribute values.

Parameters parameters-9

Example example-6

<p>{{xss-html forum-ugc}}</p>

Xss-htmlAttr xss-htmlattr

A helper that encodes a source string for writing to an HTML attribute value to help guard against XSS.

NOTE: this is not a validator and is not to be used for writing actionalable attributes (href, src, event handlers).

Parameters parameters-10

Example example-7

<div id={{xss-htmlAttr id}} />

Xss-jsString xss-jsstring

A helper that encodes a source string for writing to JavaScript string content to help guard against XSS.

NOTE: this is not a validator and is not to be used for writing to arbitrary JavaScript.

Parameters parameters-11

Example example-8

var input = {{xss-jsString topic-title}}

Xss-validHref xss-validhref

A helper that sanitizes an URL for writing as an HTML href or srce attribute value to help guard against XSS.

NOTE: this may return an empty string

Parameters parameters-12

Example example-9

<a href="{{xss-validHref url}}">my link</a>

Handlebars.js Basic Overview handlebars-js-basic-overview

An example of a simple helper from Handlebars.js documentation: an-example-of-a-simple-helper-from-handlebars-js-documentation

Handlebars.registerHelper('link_to', function(title, options) {
    return new Handlebars.SafeString('<a href="/posts' + this.url + '">' + title + "!</a>");
});

var context = {posts: [
    {url: "/hello-world",
      body: "Hello World!"}
  ] };

// when link_to is called, posts is the current context
var source = '<ul>{{#posts}}<li>{{{link_to "Post"}}}</li>{{/posts}}</ul>'

var template = Handlebars.compile(source);

template(context);

Would render:

<ul>
<li><a href=“https://experienceleague.adobe.com/posts/hello-world?lang=en”>Post!</a></li>
</ul>

An example of a block helper from Handlebars.js documentation: an-example-of-a-block-helper-from-handlebars-js-documentation

Handlebars.registerHelper('link', function(options) {
    return new Handlebars.SafeString('<a href="/people/' + this.id + '">' + options.fn(this) + '</a>');
});

var data = { "people": [
  { "name": "Alan", "id": 1 },
  { "name": "Yehuda", "id": 2 }
]};

// when link is called, people is the current context
var source = "<ul>{{#people}}<li>{{#link}}{{name}}{{/link}}</li>{{/people}}</ul>";

var template = Handlebars.compile(source);

template(data);

Would render:
<ul>
<li><a href=“https://experienceleague.adobe.com/people/1?lang=en”>Alan</a></li>
<li><a href=“https://experienceleague.adobe.com/people/2?lang=en”>Yehuda</a></li>
</ul>

Custom SCF Helpers custom-scf-helpers

Custom helpers must be implemented on the server-side as well as the client-side, especially when passing data. For SCF, most templates are compiled and rendered on the server-side as the server generates the HTML for a given component when the page is requested.

Server-side Custom Helpers server-side-custom-helpers

To implement and register a custom SCF helper on the server-side, simply implement the Java interface TemplateHelper, make it an OSGi Service and install it as part of an OSGi bundle.

For example:

FooTextHelper.java footexthelper-java

/** Custom Handlebars Helper */

package com.my.helpers;

import java.io.IOException;

import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Service;

import com.adobe.cq.social.handlebars.api.TemplateHelper;
import com.github.jknack.handlebars.Options;

@Service
@Component
public class FooTextHelper implements TemplateHelper<String>{

    @Override
    public CharSequence apply(String context, Options options) throws IOException {
        return "foo-" + context;
    }

    @Override
    public String getHelperName() {
        return "foo-text";
    }

    @Override
    public Class<String> getContextType() {
        return String.class;
    }
}

Client-side Custom Helpers client-side-custom-helpers

The client-side helpers are Handlebars scripts registered by invoking Handlebars.registerHelper().
For example:

custom-helpers.js custom-helpers-js

function(Handlebars, SCF, $CQ) {

    Handlebars.registerHelper('foo-text', function(context, options) {
        if (!context) {
            return "";
        }
        return "foo-" + context;
    });

})(Handlebars, SCF, $CQ);

The custom client-side helpers must be added to a custom client library.
The clientlib must:

Note: the SCF helpers are defined in /etc/clientlibs/social/commons/scf/helpers.js.