Assistants Handlebars SCF scf-handlebars-helpers

Les assistants Handlebars (helpers) sont des méthodes appelables à partir des scripts Handlebars pour faciliter l’utilisation des composants SCF.

L’implémentation comprend une définition côté client et côté serveur. Il est également possible pour les développeurs de créer des assistants personnalisés.

Les assistants SCF personnalisés fournis avec AEM Communities sont définis dans la bibliothèque cliente :

Abréger abbreviate

Helper permettant de renvoyer une chaîne abrégée conforme aux propriétés maxWords et maxLength.

La chaîne à abréger est fournie en tant que contexte. Si aucun contexte n’est fourni, une chaîne vide est renvoyée.

Tout d’abord, le contexte est réduit à maxLength, puis il est découpé en mots et réduit à maxWords.

Si safeString est défini sur true, la chaîne renvoyée est une chaîne SafeString.

Paramètres parameters

Exemples 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

Un helper permettant d’ajouter deux plages sous une balise <div>, l’une pour le texte complet et l’autre pour le texte inférieur, avec la possibilité de basculer entre les deux vues.

Paramètres parameters-1

Exemple 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

Helper permettant de renvoyer une chaîne de date formatée.

Paramètres parameters-2

Exemples 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"

Égal equals

Helper permettant de renvoyer du contenu en fonction d’une condition d’égalité.

Paramètres parameters-3

Exemple 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

Assistant de bloc qui teste la valeur actuelle du mode de gestion de contenu web par rapport à une liste de modes séparés par une chaîne.

Paramètres parameters-4

Exemple example-2

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

i18n i-n

Cet helper remplace l’helper Handlebars ‘i18n’.

Voir aussi Internationalisation de chaînes dans le code JavaScript.

Paramètres parameters-5

Exemple example-3

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

Inclure include

Helper permettant d’inclure un composant en tant que ressource non existante dans un modèle.

Cette méthode permet de personnaliser plus facilement la ressource par programmation que pour une ressource ajoutée en tant que nœud JCR. Voir Ajouter ou inclure un composant de communautés.

Seuls quelques composants sélectionnés de Communities sont disponibles.

Cet helper, approprié uniquement du côté serveur, fournit des fonctionnalités similaires à cq:include pour les scripts JSP.

Paramètres parameters-6

Exemple example-4

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

Inclut un nouveau composant de commentaires sous this.id + /comments.

IncludeClientLib includeclientlib

Un helper qui inclut une bibliothèque cliente HTML AEM, qui peut être de type js, css ou theme. Pour plusieurs inclusions de types différents (js et css, par exemple), cette balise doit être utilisée plusieurs fois dans le script Handlebars.

Cet helper, approprié uniquement du côté serveur, fournit des fonctionnalités similaires à ui:includeClientLib pour les scripts JSP.

Paramètres parameters-7

Exemples 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">

Joli pretty-time

Un helper permettant d’afficher le temps écoulé jusqu’à un point limite, après quoi un format de date normal est affiché.

Par exemple :

Paramètres parameters-8

Exemple 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

Helper qui code une chaîne source pour le contenu de l’élément HTML afin de vous protéger contre XSS.

REMARQUE : cet helper n’est pas un programme de validation et ne doit pas être utilisé pour écrire des valeurs d’attribut.

Paramètres parameters-9

Exemple example-6

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

Xss-htmlAttr xss-htmlattr

Helper qui code une chaîne source pour l’écriture d’une valeur d’attribut HTML afin de se protéger contre XSS.

REMARQUE : cet helper n’est pas un programme de validation et ne doit pas être utilisé pour écrire des attributs exploitables (href, src, gestionnaires d’événements).

Paramètres parameters-10

Exemple example-7

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

Xss-jsString xss-jsstring

Helper qui code une chaîne source pour écrire du contenu de chaîne JavaScript afin de se protéger contre XSS.

REMARQUE : cet helper n’est pas un programme de validation et ne doit pas être utilisé pour écrire dans un JavaScript arbitraire.

Paramètres parameters-11

Exemple example-8

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

Xss-validHref xss-validhref

Helper qui assainit une URL pour l’écriture en tant que valeur d’attribut href ou source HTML afin de se protéger contre XSS.

REMARQUE : cet helper peut renvoyer une chaîne vide.

Paramètres parameters-12

Exemple example-9

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

Présentation de base de Handlebars.js handlebars-js-basic-overview

Exemple d’assistant simple de la documentation Handlebars.js : 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);

Effectuerait le rendu :

<ul>
<li><a href=« /posts/hello-world »>Publication !</a></li>
</ul>

Exemple d’assistant de bloc de la documentation Handlebars.js : 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);

Effectuerait le rendu :
<ul>
<li><a href=« /people/1 »>Alan</a></li>
<li><a href=« /people/2 »>Yehuda</a></li>
</ul>

Assistants SCF personnalisés custom-scf-helpers

Les assistants personnalisés doivent être implémentés côté serveur et côté client, en particulier lors de la transmission de données. Pour SCF, la plupart des modèles sont compilés et rendus côté serveur, car le serveur génère l’HTML pour un composant donné lorsque la page est demandée.

Assistants personnalisés côté serveur server-side-custom-helpers

Pour implémenter et enregistrer un assistant SCF personnalisé côté serveur, il vous suffit d’implémenter l’interface Java™ TemplateHelper, d’en faire un service OSGi et de l’installer dans le cadre d’un lot OSGi.

Par exemple :

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;
    }
}

Assistants personnalisés côté client client-side-custom-helpers

Les assistants côté client sont des scripts Handlebars enregistrés en appelant Handlebars.registerHelper().
Par exemple :

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);

Les assistants côté client personnalisés doivent être ajoutés à une bibliothèque cliente personnalisée.
La bibliothèque cliente doit :

Remarque : les assistants SCF sont définis dans /etc/clientlibs/social/commons/scf/helpers.js.