Assistant de Handlebars SCF scf-handlebars-helpers

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 :

Abréger abbreviate

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

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

Une aide 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"

Est égal à equals

Un assistant pour 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

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

Paramètres parameters-4

Exemple example-2

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

i18n i-n

Cette aide remplace l’aide 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

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

Cette méthode 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 disponibles à inclure.

Cette assistance, appropriée uniquement 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 à l’emplacement this.id + /comments.

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

Plutôt temps pretty-time

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 :

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

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

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

Paramètres parameters-9

Exemple example-6

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

Xss-htmlAttr xss-htmlattr

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

REMARQUE : Cette assistance n’est pas un programme de validation et ne doit pas être utilisée 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

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

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

Paramètres parameters-11

Exemple example-8

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

Xss-validHref 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 : cette assistance 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’un simple assistant 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);

Rendre :

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

Exemple d’assistance de bloc à partir 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);

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

Aide SCF personnalisée 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 d’un composant donné lorsque la page est demandée.

Aide personnalisée côté serveur server-side-custom-helpers

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

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