Assistant de Handlebars SCF

⇐ Notions fondamentales sur les fonctionnalités ⇒ de personnalisation côté serveur
⇒ de personnalisation côté client

Handlebars Helpers (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 une définition 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 :

  • /etc/clientlibs/social/commons/scf/helpers.js
REMARQUE

Veillez à installer le dernier Feature Pack Communities.

Abréger

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

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

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

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

Paramètres

  • context : Chaîne

    (facultatif) La valeur par défaut est la chaîne vide

  • maxLength : Nombre

    (facultatif) La valeur par défaut est la longueur du contexte.

  • maxWords : Nombre

    (facultatif) La valeur par défaut est le nombre de mots de la chaîne rognée.

  • safeString : Booléen

    (facultatif) Renvoie une valeur Handlebars.SafeString() si la valeur est true. La valeur par défaut est false.

Exemples

{{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

Permet d’ajouter deux étendues sous une balise div, l’une pour le texte intégral, l’autre pour le texte secondaire, avec la possibilité de basculer entre les deux vues.

Paramètres

  • context : Chaîne

    (facultatif) La valeur par défaut est la chaîne vide.

  • numChars : Nombre

    (facultatif) Nombre de caractères à afficher lorsque le texte intégral ne s’affiche pas. La valeur par défaut est 100.

  • moreText : Chaîne

    (facultatif) Texte à afficher indiquant qu’il y a plus de texte à afficher. La valeur par défaut est "plus".

  • ellipsesText : Chaîne

    (facultatif) Texte à afficher indiquant qu’il existe du texte masqué. La valeur par défaut est "…".

  • safeString : Booléen

    (facultatif) Valeur booléenne indiquant s’il faut appliquer Handlebars.SafeString() avant de renvoyer le résultat. La valeur par défaut est false.

Exemple

{{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

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

Paramètres

  • context : Nombre

    (facultatif) un décalage de valeur en millisecondes par rapport au 1er janvier 1970 (époque). La date par défaut est la date actuelle.

  • format : Chaîne

    (facultatif) Format de date à appliquer. La valeur par défaut est "AAAA-MM-JJTHH:mm:ss.sssZ" et le résultat apparaît comme "2015-03-18T18:17:13-07:00".

Exemples

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

Est égal à

Un assistant pour renvoyer du contenu en fonction d’une condition d’égalité.

Paramètres

  • lvalue : Chaîne

    Valeur de gauche à comparer

  • rvalue : Chaîne

    Valeur de droite à comparer

Exemple

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

If-wcm-mode

Une aide par bloc qui teste la valeur actuelle du mode WCM par rapport à une liste de modes séparés par des chaînes.

Paramètres

  • context : Chaîne

    (facultatif) Chaîne à traduire. Obligatoire si aucune valeur par défaut n’est fournie.

  • mode : Chaîne

    (facultatif) Liste séparée par des virgules de modes de gestion de contenu web à tester si défini.

Exemple

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

i18n

Cette aide remplace l’aide Handlebars "i18n".

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

Paramètres

  • context : Chaîne

    (facultatif) Chaîne à traduire. Obligatoire si aucune valeur par défaut n’est fournie.

  • default : Chaîne

    (facultatif) Chaîne par défaut à traduire. Obligatoire si aucun contexte n’est fourni.

  • commentaire : Chaîne

    (facultatif) Conseil de traduction

Exemple

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

Inclure

Une aide pour inclure un composant en tant que ressource non existante dans un modèle.

Cela permet à la ressource d’être personnalisée par programmation plus facilement qu’il n’est possible pour une ressource ajoutée en tant que noeud JCR. Voir Ajout ou inclusion d’un composant Communities.

Seuls quelques-uns des composants Communities sont incluables. Pour AEM 6.1, les inclusions sont commentaires, note, révisions et vote.

Cette aide, appropriée uniquement côté serveur, fournit des fonctionnalités similaires à cq:include pour les scripts JSP.

Paramètres

  • context : Chaîne ou objet

    (facultatif, sauf si vous fournissez un chemin relatif)

    utiliser thispour transmettre le contexte actuel ;

    Utilisez this.id pour obtenir la ressource à id pour effectuer le rendu du type de ressource demandé.

  • resourceType : Chaîne

    (facultatif) le type de ressource est défini par défaut sur le type de ressource du contexte.

  • modèle : Chaîne

    chemin d’accès au script du composant

  • path : Chaîne

    (obligatoire) chemin d’accès à la ressource. Si le chemin est relatif, un contexte doit être fourni, sinon la chaîne vide est renvoyée.

  • authoringDisabled : Booléen

    (facultatif) La valeur par défaut est false. usage interne uniquement.

Exemple

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

Cela inclura un nouveau composant de commentaires à this.id + /comments

IncludeClientLib

Une aide qui comprend une bibliothèque cliente HTML AEM, qui peut être une bibliothèque js, css ou thème. Pour plusieurs inclusions de différents types, par exemple js et css, cette balise doit être utilisée plusieurs fois dans le script Handlebars.

Cette assistance, appropriée uniquement côté serveur, fournit des fonctionnalités similaires à ui:includeClientLib pour les scripts JSP.

Paramètres

  • categories : Chaîne

    (facultatif) Une liste de catégories de bibliothèques clientes séparées par des virgules. Cela inclut toutes les bibliothèques JavaScript et CSS pour les catégories données. Le nom du thème est extrait de la requête.

  • thème : Chaîne

    (facultatif) Une liste de catégories de bibliothèques clientes séparées par des virgules. Cela inclut toutes les bibliothèques (CSS et JS) relatives au thème pour les catégories données. Le nom du thème est extrait de la requête.

  • js : Chaîne

    (facultatif) Une liste de catégories de bibliothèques clientes séparées par des virgules. Cela inclut toutes les bibliothèques JavaScript et CSS pour les catégories données.

  • css : Chaîne

    (facultatif) Une liste de catégories de bibliothèques clientes séparées par des virgules. Cela inclut toutes les bibliothèques CSS pour les catégories données.

Exemples

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

Plutôt temps

Une aide permettant d’afficher le temps écoulé jusqu’à un point de coupure, après lequel un format de date normal est affiché.

Par exemple :

  • Il y a 12 heures
  • 7 jours auparavant

Paramètres

  • context : Nombre

    Un temps dans le passé à comparer avec "maintenant". Le temps est exprimé sous la forme d’un décalage de valeur en millisecondes par rapport au 1er janvier 1970 (époque).

  • daysCutoff : Nombre

    Nombre de jours auparavant avant de passer à une date réelle. La valeur par défaut est 60.

Exemple

{{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

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

REMARQUE : il ne s’agit pas d’un programme de validation et il ne doit pas être utilisé pour écrire des valeurs d’attribut.

Paramètres

  • context : objet

    le code HTML à coder

Exemple

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

Xss-htmlAttr

Une aide qui code une chaîne source pour l’écriture dans une valeur d’attribut HTML afin de vous aider à vous protéger contre XSS.

REMARQUE : il ne s’agit pas d’un programme de validation et il ne doit pas être utilisé pour écrire des attributs activables (href, src, gestionnaires d’événements).

Paramètres

  • context : Objet

    Le code HTML à coder

Exemple

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

Xss-jsString

Une aide qui code une chaîne source pour l’écriture dans du contenu de chaîne JavaScript afin de vous protéger contre XSS.

REMARQUE : il ne s’agit pas d’un validateur et ne doit pas être utilisé pour écrire du code JavaScript arbitraire.

Paramètres

  • context : Objet

    Le code HTML à coder

Exemple

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

Xss-validHref

Une assistance qui assainit une URL pour l’écriture en tant que valeur HTML href ou d’attribut source afin de vous aider à vous protéger contre XSS.

REMARQUE : cela peut renvoyer une chaîne vide

Paramètres

  • context : Objet

    URL à assainir

Exemple

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

Présentation de base de Handlebars.js

  • Un appel d’assistance Handlebars est un identifiant simple (le nom de l’assistant), suivi de zéro ou de plusieurs paramètres séparés par des espaces.

  • Les paramètres peuvent être un simple objet String, Number, boolean ou JSON, ainsi qu’une séquence facultative de paires clé-valeur (arguments de hachage) comme dernier(s) paramètre(s).

  • Les clés des arguments de hachage doivent être des identifiants simples.

  • Les valeurs des arguments de hachage sont des expressions Handlebars : identifiants, chemins ou chaînes simples.

  • Le contexte actuel, this, est toujours disponible pour les assistants Handlebars.

  • Le contexte peut être une chaîne, un nombre, une valeur booléenne ou un objet de données JSON.

  • Il est possible de transmettre un objet imbriqué dans le contexte actuel comme contexte, par exemple this.url ou this.id (voir les exemples suivants d’assistants simples et de blocs).

  • Les assistants de bloc sont des fonctions qui peuvent être appelées à partir de n’importe quel emplacement du modèle. Ils peuvent appeler un bloc du modèle zéro ou plusieurs fois avec un contexte différent à chaque fois. Ils contiennent un contexte entre {{#name}} et {{/name}.

  • Handlebars fournit un paramètre final aux assistants nommés "options". L’objet spécial "options" inclut

    • Données privées facultatives (options.data)
    • Propriétés de clé-valeur facultatives de l’appel (options.hash)
    • Possibilité d’appeler lui-même (options.fn())
    • Possibilité d’appeler l’inverse de lui-même (options.inverse())
  • Il est recommandé que le contenu de chaîne HTML renvoyé par un assistant soit une SafeString.

Exemple d’un simple assistant de la documentation Handlebars.js :

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

Rendre :

<ul>
<li><a href="/posts/hello-world">Publiez !</a></li>
</ul>

Exemple d’assistance de bloc à partir de la documentation Handlebars.js :

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

Rendre :
<ul>
<li><a href="/people/1">Alan</a></li>
<li><a href="/people/2">Yehuda</a></li>
</ul>

Aide SCF personnalisée

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 le code HTML pour un composant donné lorsque la page est demandée.

Aide personnalisée côté serveur

Pour mettre en oeuvre et enregistrer un assistant SCF personnalisé côté serveur, implémentez simplement l’interface Java TemplateHelper, créez-le un service OSGi et installez-le dans le cadre d’un lot OSGi.

Par exemple :

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

Une assistance créée côté serveur doit également être créée côté client.

Le composant est de nouveau rendu côté client pour l’utilisateur connecté. Si l’assistant côté client est introuvable, le composant disparaît.

Aide personnalisée côté client

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

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 client personnalisée.
La bibliothèque cliente doit :

  • Inclure une dépendance sur cq.social.scf
  • Chargement après le chargement des Guidons
  • Être inclus

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

⇐ Notions fondamentales sur les fonctionnalités ⇒ de personnalisation côté serveur
⇒ de personnalisation côté client

Sur cette page