Aide-mémoire SCF

⇐ Fonctionnalités Essentials Personnalisation côté serveur
Personnalisation côté client

Handlebars Les aides (aides) sont des méthodes que l'on peut appeler à 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 client :

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

Veillez à installer le dernier pack de fonctionnalitésdes communautés.

Abrévier

Aide à 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 ajusté à maxLength, puis il 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 contenus dans la chaîne rognée.

  • safeString: Boolean

    (facultatif) Renvoie une valeur Handlebars.SafeString() si 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

Aide permettant d’ajouter deux plages sous une balise div, l’une pour le texte complet et l’autre pour le texte plus petit, 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 n’est pas affiché. 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 y a du texte masqué. La valeur par défaut est "…".

  • safeString: Boolean

    (facultatif) Valeur booléenne indiquant si Handlebars.SafeString() doit être appliqué 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

Aide à renvoyer une chaîne de date formatée.

Paramètres

  • contexte: Nombre

    (facultatif) décalage de la 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-DTHH:mm:ss.sssZ" et le résultat est "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"

Equals

Aide permettant de renvoyer du contenu selon une condition d’égalité.

Paramètres

  • lvalue: Chaîne

    Valeur à 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}}

Si-wcm-mode

Aide de bloc qui teste la valeur actuelle du mode WCM par rapport à une liste de modes séparée 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 des modes WCM à tester si elle est définie.

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 du codeJavaScript.

Paramètres

  • contexte: Chaîne

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

  • par défaut: 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

Aide permettant d’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 Ajouter ou Inclure un composantCollectivités.

Seuls quelques composants de communautés sélectionnés sont inclus. Pour AEM 6.1, ceux qui sont inclus sont les commentaires, la cotation, les révisionset le vote.

Cette aide, qui s’applique 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)

    utiliser thispour transmettre le contexte actuel

    utiliser this.id pour obtenir la ressource à id des fins de rendu de la ressourceType demandée

  • 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 de composant

  • chemin: Chaîne

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

  • authoringDisabled: Boolean

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

Exemple

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

Ceci inclura un nouveau composant de commentaires dans this.id + /commentaires.

IncludeClientLib

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

Cette aide, qui s’applique uniquement côté serveur, fournit des fonctionnalités similaires à ui:includeClientLib pour les scripts JSP.

Paramètres

  • catégories: Chaîne

    (Facultatif) liste de catégories de lib client 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) liste de catégories de lib client 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) liste de catégories de lib client 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) liste de catégories de lib client 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

Aide permettant d’afficher le temps passé jusqu’à un point de coupure, après lequel un format de date standard est affiché.

Par exemple :

  • Il y a 12 heures
  • il y a 7 jours

Paramètres

  • contexte: Nombre

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

  • daysCutoff: Nombre

    Nombre de jours 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

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

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

Paramètres

  • contexte: objet

    le code HTML à coder

Exemple

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

Xss-htmlAttr

Aide qui code une chaîne source à des fins d’écriture sur une valeur d’attribut HTML afin de vous aider à vous protéger contre le format XSS.

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

Paramètres

  • contexte: Objet

    Le code HTML à coder

Exemple

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

Xss-jsString

Aide qui code une chaîne source pour l’écriture de contenu de chaîne JavaScript afin de vous protéger contre le format XSS.

REMARQUE : ce n'est pas un validateur et ne doit pas être utilisé pour écrire sur JavaScript arbitraire.

Paramètres

  • contexte: Objet

    Le code HTML à coder

Exemple

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

Xss-validHref

Aide qui analyse une URL pour l’écriture en tant que valeur d’attribut href ou d’attribut de ressource HTML afin de vous aider à vous protéger contre le format XSS.

REMARQUE : cela peut renvoyer une chaîne vide

Paramètres

  • contexte: Objet

    L'URL à utiliser pour l'assainissement

Exemple

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

Présentation de base de Handlebars.js

Aperçu rapide des fonctions d’aide de la documentation deHandlebars.js :

  • Un appel Handlebars helper est un identifiant simple (le *nom *de l’aide), 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, booléen ou JSON, ainsi qu’une séquence facultative de paires clé-valeur (arguments de hachage) en tant que dernier paramètre.

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

  • Les valeurs des arguments de hachage sont les expressions des barres de contrôle : identificateurs simples, chemins ou chaînes.

  • Le contexte actuel thisest toujours disponible pour les aides 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, tel que this.url ou this.id (voir les exemples suivants d’aides simples et de blocs).

  • Les assistants de bloc sont des fonctions qui peuvent être appelées n’importe où dans le 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)
    • Capacité à s’appeler (options.fn())
    • Possibilité d’appeler l’inverse d’elle-même (options.inverse())
  • Il est recommandé que le contenu de la chaîne HTML renvoyé par un assistant soit une chaîne de sécurité.

Exemple d’aide simple 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);

Rendu :

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

Exemple d’aide de bloc provenant 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);

Rendu :
<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 tant côté serveur que 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.

Assistance 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, d'en faire un service OSGi et de l'installer 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

Un assistant créé côté serveur doit également être créé côté client.

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

Assistance 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 personnalisés côté client doivent être ajoutés à une bibliothèque cliente personnalisée.
clientlib doit :

  • Inclure une dépendance sur cq.social.scf
  • Charger après le chargement des barres de main
  • Être inclus

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

⇐ Fonctionnalités Essentials Personnalisation côté serveur
Personnalisation côté client

Sur cette page