Assistant de Handlebars SCF

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 variable bibliothèque cliente:

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

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

• contexte: 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

• contexte: 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) Le texte à afficher indiquant qu’il y a 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

• contexte: Nombre

  (Facultatif) 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:s.sssZ" et le résultat apparaît sous la forme "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 assistance par bloc qui teste la valeur actuelle de Mode WCM dans une liste de modes séparés par des chaînes.

Paramètres

• contexte: 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 WCM pour 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 de chaînes dans un code JavaScript.

Paramètres

• contexte: 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.

• comment: 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 Communautés.

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

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

Paramètres

• contexte: Chaîne ou objet

  (Facultatif, sauf si vous fournissez un chemin relatif)

  Utilisation this pour transmettre le contexte actuel.

  Utilisation this.id pour obtenir la ressource à l’adresse id pour effectuer le rendu de resourceType demandé.

• resourceType: Chaîne

  (Facultatif) le type de ressource est défini par défaut sur le type de ressource à partir 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 à l’adresse 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

• contexte: 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 de 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

• contexte: objet

  HTML à coder.

Exemple

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

Xss-htmlAttr

Une aide qui code une chaîne source pour l’écriture sur une valeur d’attribut de 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

• contexte: Objet

  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

• contexte: Objet

  HTML à coder.

Exemple

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

Xss-validHref

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

REMARQUE : cela peut renvoyer une chaîne vide

Paramètres

• contexte: 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 name de l’assistant), suivie de zéro ou plusieurs paramètres séparés par de l’espace.

• 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 en tant que contexte, par exemple this.url ou this.id (voir les exemples suivants d’aides simples et par 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}} and {{/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 de 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 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, il vous suffit de mettre en oeuvre l’interface Java. TemplateHelper, faites en sorte qu’il soit Service OSGi et installez-le dans le cadre d’un regroupement 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;
    }
}

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.
• Be included.

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

Ressources Business.Adobe.com

Ecommerce Integrations Asset Collections Content Intelligence Embedded Charts Dynamic Forms Digital Asset Management