SCF Handlebars Helpers

⇐ Funktionsgrundlagen Server-seitige Anpassung imetall
Client-seitige Anpassung imetall

Handlebars Helpers (helpers) sind Methoden, die von Handlebars-Skripten aufgerufen werden können, um die Arbeit mit SCF-Komponenten zu erleichtern.

Die Implementierung umfasst eine Client-seitige und eine Server-seitige Definition. Es ist auch möglich, dass Entwickler benutzerdefinierte Helfer erstellen.

Die benutzerdefinierten SCF-Helfer, die mit AEM Communities bereitgestellt werden, sind in der Client-Bibliothek definiert:

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

Installieren Sie unbedingt das neueste Feature Pack für Communities.

Abkürzung

Hilfsmittel zum Zurückgeben einer abgekürzten Zeichenfolge, die den Eigenschaften maxWords und maxLength entspricht.

Die abzukürzende Zeichenfolge wird als Kontext bereitgestellt. Wenn kein Kontext angegeben wird, wird eine leere Zeichenfolge zurückgegeben.

Zunächst wird der Kontext auf maxLength reduziert, dann wird der Kontext in Wörter aufgeteilt und auf maxWords reduziert.

Wenn safeString auf "true"gesetzt ist, ist die zurückgegebene Zeichenfolge ein SafeString.

Parameter

  • context: Zeichenfolge

    (Optional) Der Standardwert ist die leere Zeichenfolge.

  • maxLength: Zahl

    (Optional) Der Standardwert ist die Länge des Kontexts.

  • maxWords: Zahl

    (Optional) Die Standardeinstellung ist die Anzahl der Wörter in der gekürzten Zeichenfolge.

  • safeString: Boolesch

    (Optional) Gibt einen Handlebars.SafeString() zurück, wenn "true". Der Standardwert lautet false.

Beispiele

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

Ein Hilfsprogramm zum Hinzufügen von zwei Bereichen unter einem div, einer für den Volltext und der andere für den weniger Text, mit der Möglichkeit, zwischen den beiden Ansichten umzuschalten.

Parameter

  • context: Zeichenfolge

    (Optional) Der Standardwert ist die leere Zeichenfolge.

  • numChars: Zahl

    (Optional) Die Anzahl der Zeichen, die angezeigt werden sollen, wenn kein Volltext angezeigt wird. Der Standardwert ist 100.

  • moreText: Zeichenfolge

    (Optional) Der anzuzeigende Text, der angibt, dass mehr Text angezeigt werden soll. Der Standardwert ist "more".

  • ellipsesText: Zeichenfolge

    (Optional) Der Text, der anzeigt, dass ausgeblendeter Text vorhanden ist. Der Standardwert ist "…".

  • safeString: Boolesch

    (Optional) Boolescher Wert, der angibt, ob Handlebars.SafeString() angewendet werden soll, bevor das Ergebnis zurückgegeben wird. Der Standardwert lautet false.

Beispiel

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

Hilfsmittel zum Zurückgeben einer formatierten Datums-Zeichenfolge.

Parameter

  • context: Zahl

    (Optional) ein Millisekunden-Wert, der vom 1. Januar 1970 (Epoche) versetzt wurde. Der Standardwert ist das aktuelle Datum.

  • format: Zeichenfolge

    (Optional) Das anzuwendende Datumsformat. Der Standardwert ist "YYYY-MM-DDTHH:mm:ss.sssZ"und das Ergebnis wird als "2015-03-18T18:17:13-07:00"angezeigt.

Beispiele

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

Gleich

Hilfsmittel zum Zurückgeben von Inhalten in Abhängigkeit von einer Gleichheitsbedingung.

Parameter

  • value: Zeichenfolge

    Der zu vergleichende linke Wert.

  • rvalue: Zeichenfolge

    Der zu vergleichende Wert auf der rechten Seite.

Beispiel

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

If-wcm-mode

Ein Block-Helfer, der den aktuellen Wert von WCM-Modus anhand einer durch Zeichenfolgen getrennten Liste von Modi testet.

Parameter

  • context: Zeichenfolge

    (Optional) Die zu übersetzende Zeichenfolge. Erforderlich, wenn kein Standardwert angegeben wurde.

  • mode: Zeichenfolge

    (Optional) Eine kommagetrennte Liste von WCM-Modi, die getestet werden sollen, falls festgelegt.

Beispiel

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

i18n

Dieser Helfer überschreibt den Handlebars-Helfer 'i18n'.

Siehe auch Internationalisierung von Zeichenfolgen in JavaScript-Code.

Parameter

  • context: Zeichenfolge

    (Optional) Die zu übersetzende Zeichenfolge. Erforderlich, wenn kein Standardwert angegeben wurde.

  • Standard: Zeichenfolge

    (Optional) Die zu übersetzende Standardzeichenfolge. Erforderlich, wenn kein Kontext angegeben wurde.

  • Kommentar: Zeichenfolge

    (Optional) Ein Übersetzungshinweis

Beispiel

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

Einbeziehen

Hilfsmittel zum Einfügen einer Komponente als nicht vorhandene Ressource in eine Vorlage.

Dadurch kann die Ressource programmgesteuert einfacher angepasst werden als für eine Ressource, die als JCR-Knoten hinzugefügt wird. Siehe Hinzufügen oder Einfügen einer Communities-Komponente.

Es sind nur einige ausgewählte Communities-Komponenten eingeschlossen. Für AEM 6.1 sind die inkludierten Kommentare, Bewertung, Bewertungen und Abstimmung.

Dieser Helfer, der nur serverseitig geeignet ist, bietet Funktionen, die cq:include für JSP-Skripte ähneln.

Parameter

  • context: Zeichenfolge oder Objekt

    (Optional, sofern kein relativer Pfad angegeben wird)

    Verwenden Sie this , um den aktuellen Kontext zu übergeben.

    Verwenden Sie this.id, um die Ressource unter id zum Rendern des angeforderten Ressourcentyps abzurufen.

  • resourceType: Zeichenfolge

    (Optional) Der Ressourcentyp wird standardmäßig auf Ressourcentyp aus dem Kontext festgelegt.

  • template: Zeichenfolge

    Pfad zum Komponentenskript.

  • path: Zeichenfolge

    (Erforderlich) Der Pfad zur Ressource. Wenn der Pfad relativ ist, muss ein Kontext angegeben werden. Andernfalls wird die leere Zeichenfolge zurückgegeben.

  • authoringDisabled: Boolesch

    (Optional) Der Standardwert ist "false". Nur zur internen Verwendung.

Beispiel

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

Dies umfasst eine neue Kommentarkomponente unter this.id + /comments.

IncludeClientLib

Ein Hilfsprogramm, das eine AEM HTML-Client-Bibliothek enthält, die eine JS-, CSS- oder Design-Bibliothek sein kann. Für mehrere Einschlüsse verschiedener Typen, z. B. js und css, muss dieses Tag mehrmals im Handlebars-Skript verwendet werden.

Dieser Helfer, der nur serverseitig geeignet ist, bietet Funktionen, die ui:includeClientLib für JSP-Skripte ähneln.

Parameter

  • categories: Zeichenfolge

    (Optional) Eine Liste mit kommagetrennten Client-Bibliothekskategorien. Dies bezieht alle Javascript-Dateien und CSS-Bibliotheken für die betreffenden Kategorien mit ein. Der Designname wird aus der Abfrage extrahiert.

  • Design: Zeichenfolge

    (Optional) Eine Liste mit kommagetrennten Client-Bibliothekskategorien. Dies beinhaltet alle designbezogenen Bibliotheken (CSS und JS) für die entsprechenden Kategorien. Der Designname wird aus der Abfrage extrahiert.

  • js: Zeichenfolge

    (Optional) Eine Liste mit kommagetrennten Client-Bibliothekskategorien. Dies bezieht alle Javascript-Bibliotheken für die betreffenden Kategorien mit ein.

  • css: Zeichenfolge

    (Optional) Eine Liste mit kommagetrennten Client-Bibliothekskategorien. Dies bezieht alle CSS-Bibliotheken für die betreffenden Kategorien mit ein.

Beispiele

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

Pretty-time

Ein Hilfsmittel, mit dem angezeigt wird, wie viel Zeit bis zu einem Cutoff-Punkt vergangen ist, nach dem ein reguläres Datumsformat angezeigt wird.

Beispiel:

  • Vor 12 Stunden
  • Vor 7 Tagen

Parameter

  • context: Zahl

    Eine Zeit in der Vergangenheit, um mit "jetzt"zu vergleichen. Die Zeit wird als Millisekunden-Wertversatz ab dem 1. Januar 1970 (Epoche) ausgedrückt.

  • daysCutoff: Zahl

    Die Anzahl der Tage vor dem Wechsel zu einem tatsächlichen Datum. Der Standardwert ist 60.

Beispiel

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

Ein Hilfsprogramm, das eine Quellzeichenfolge für HTML-Elementinhalte codiert, um den Schutz vor XSS zu unterstützen.

HINWEIS: Dies ist kein Validator und sollte nicht zum Schreiben von Attributwerten verwendet werden.

Parameter

  • context: Objekt

    Der zu kodierende HTML-Code.

Beispiel

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

Xss-htmlAttr

Ein Hilfsprogramm, das eine Quellzeichenfolge zum Schreiben in einen HTML-Attributwert kodiert, um den Schutz vor XSS zu unterstützen.

HINWEIS: Dies ist kein Validator und sollte nicht zum Schreiben von umsetzbaren Attributen (href, src, event handlers) verwendet werden.

Parameter

  • context: Objekt

    Der zu kodierende HTML-Code.

Beispiel

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

Xss-jsString

Ein Hilfsprogramm, das eine Quellzeichenfolge zum Schreiben in JavaScript-Zeichenfolgeninhalte kodiert, um den Schutz vor XSS zu unterstützen.

HINWEIS: Dies ist kein Validator und soll nicht zum Schreiben in beliebiges JavaScript verwendet werden.

Parameter

  • context: Objekt

    Der zu kodierende HTML-Code.

Beispiel

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

Xss-validHref

Ein Helfer, der eine URL zum Schreiben als HTML-href- oder -srce-Attributwert bereinigt, um den Schutz vor XSS zu unterstützen.

HINWEIS: dies kann eine leere Zeichenfolge zurückgeben

Parameter

  • context: Objekt

    Die URL, die bereinigt werden soll.

Beispiel

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

Handlebars.js Grundlegende Übersicht

Ein kurzer Überblick über Hilfsfunktionen aus der Handlebars.js-Dokumentation:

  • Ein Handlebars helper -Aufruf ist eine einfache Kennung (der Name des Helfers), gefolgt von null oder mehr durch Leerzeichen getrennten Parametern.

  • Parameter können ein einfaches String-, number-, boolesches oder JSON-Objekt sowie eine optionale Sequenz von Schlüssel-Wert-Paaren (Hash-Argumenten) als letzte Parameter sein.

  • Die Schlüssel in Hash-Argumenten müssen einfache Bezeichner sein.

  • Die Werte in den Hash-Argumenten sind Handlebars-Ausdrücke: einfache Bezeichner, Pfade oder Zeichenfolgen.

  • Der aktuelle Kontext, this, ist immer für Handlebars-Helfer verfügbar.

  • Der Kontext kann ein String-, number-, boolesches oder JSON-Datenobjekt sein.

  • Es ist möglich, ein im aktuellen Kontext verschachteltes Objekt als Kontext zu übergeben, z. B. this.url oder this.id (siehe die folgenden Beispiele für einfache und Blockhilfen).

  • Block Helpers sind Funktionen, die von überall in der Vorlage aufgerufen werden können. Sie können einen Block der Vorlage jedes Mal null oder mehrmals mit einem anderen Kontext aufrufen. Sie enthalten einen Kontext zwischen {{#name}} und {{/name}}.

  • Handlebars bietet einen letzten Parameter für Hilfedateien namens "options". Das Sonderobjekt 'options' enthält

    • Optionale private Daten (options.data)
    • Optionale Tastenwerteigenschaften aus dem Aufruf (options.hash)
    • Möglichkeit, sich selbst aufzurufen (options.fn())
    • Möglichkeit, das Umkehren von sich selbst aufzurufen (options.inverse())
  • Es wird empfohlen, dass der HTML String-Inhalt, der von einem Helfer zurückgegeben wird, ein SafeString ist.

Ein Beispiel für einen einfachen Helfer aus der Handlebars.js-Dokumentation:

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

würde rendern:

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

Ein Beispiel für einen Block-Helfer aus der Handlebars.js-Dokumentation:

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

würde rendern:
<ul>
<li><a href="/people/1">Alan</a></li>
<li><a href="/people/2">Yehuda</a></li>
</ul>

Benutzerdefinierte SCF-Helfer

Benutzerdefinierte Helfer müssen sowohl serverseitig als auch Client-seitig implementiert werden, insbesondere bei der Übergabe von Daten. Bei SCF werden die meisten Vorlagen serverseitig kompiliert und gerendert, da der Server den HTML-Code für eine bestimmte Komponente generiert, wenn die Seite angefordert wird.

Serverseitige benutzerdefinierte Helfer

Um einen benutzerdefinierten SCF-Helfer serverseitig zu implementieren und zu registrieren, implementieren Sie einfach die Java-Schnittstelle TemplateHelper, machen Sie sie zu einem OSGi-Dienst und installieren Sie sie als Teil eines OSGi-Bundles.

Beispiel:

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

Ein für die serverseitige Benutzeroberfläche erstellter Helfer muss auch für die Client-Seite erstellt werden.

Die Komponente wird für den angemeldeten Benutzer clientseitig erneut gerendert. Wenn der clientseitige Helfer nicht gefunden wird, verschwindet die Komponente.

Clientseitige benutzerdefinierte Helfer

Die clientseitigen Helfer sind Handlebars-Skripte, die durch Aufrufen von Handlebars.registerHelper() registriert werden.
Beispiel:

custom-helpers.js

function(Handlebars, SCF, $CQ) {

    Handlebars.registerHelper('foo-text', function(context, options) {
        if (!context) {
            return "";
        }
        return "foo-" + context;
    });

})(Handlebars, SCF, $CQ);

Die benutzerdefinierten clientseitigen Helfer müssen einer benutzerdefinierten Client-Bibliothek hinzugefügt werden.
Die clientlib muss:

  • Fügen Sie eine Abhängigkeit von cq.social.scf hinzu.
  • Laden nach Laden der Handlebars.
  • Sei included.

Hinweis: Die SCF-Helfer sind in /etc/clientlibs/social/commons/scf/helpers.js definiert.

⇐ Funktionsgrundlagen Server-seitige Anpassung imetall
Client-seitige Anpassung imetall

Auf dieser Seite