SCF Handlebars-Helfer scf-handlebars-helpers

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

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

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

kürzen abbreviate

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

Die Zeichenfolge, die abgekürzt werden soll, wird als Kontext bereitgestellt. Wenn kein Kontext angegeben wird, wird eine leere Zeichenfolge zurückgegeben.

Zuerst wird der Kontext auf maxLength gekürzt, dann wird der Kontext in Wörter aufgeteilt und auf maxWords reduziert.

Wenn safeString auf „true“ gesetzt ist, dann ist die zurückgegebene Zeichenfolge ein SafeString.

Parameter parameters

Beispiele 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

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

Parameter parameters-1

Beispiel 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

Ein Helper zum Zurückgeben einer formatierten Datumszeichenfolge.

Parameter parameters-2

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

Gleich equals

Ein Helper zum Zurückgeben von Inhalten abhängig von einer bedingten Gleichheit.

Parameter parameters-3

Beispiel 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

Ein Block-Helper, der den aktuellen Wert von WCM-Modus anhand einer durch eine Zeichenfolge getrennten Liste von Modi testet.

Parameter parameters-4

Beispiel example-2

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

i18n i-n

Dieser Helper überschreibt den Handlebars-Helper „i18n“.

Siehe auch Internationalisieren von Zeichenfolgen in JavaScript-Code.

Parameter parameters-5

Beispiel example-3

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

Einschließen include

Ein Helper zum Einschließen einer Komponente als nicht vorhandene Ressource in einer Vorlage.

Mit dieser Methode kann die Ressource programmgesteuert einfacher angepasst werden, als dies für eine Ressource möglich ist, die als JCR-Knoten hinzugefügt wird. Siehe Hinzufügen oder Einschließen einer Communities-Komponente.

Es stehen nur einige ausgewählte Communities-Komponenten zum Einschließen zur Verfügung.

Dieser Helper, der nur für die Serverseite geeignet ist, bietet für JSP-Skripte ähnliche Funktionen cq:include.

Parameter parameters-6

Beispiel example-4

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

Beinhaltet eine neue Kommentarkomponente unter this.id + /comments.

includeClientLib includeclientlib

Ein Helper mit einer AEM-HTML-Client-Bibliothek, bei der es sich um eine JS-, CSS- oder Design-Bibliothek handeln kann. Für mehrere Einschlüsse verschiedener Typen, z. B. js und css, muss dieses Tag mehrmals im Handlebars-Skript verwendet werden.

Dieser Helper, der nur für die Serverseite geeignet ist, bietet für JSPSkripte ähnliche Funktionen wie ui:includeClientLib.

Parameter parameters-7

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

hübsche Zeit pretty-time

Ein Helper, der anzeigt, wie viel Zeit bis zu einem Cutoff-Punkt vergangen ist. Danach wird ein reguläres Datumsformat angezeigt.

Zum Beispiel:

Parameter parameters-8

Beispiel 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

Ein Helper, der eine Quellzeichenfolge für das HTML von Elementinhalten kodiert, um XSS zu verhindern.

HINWEIS: Dieser Helper ist kein Validator und darf nicht zum Schreiben von Attributwerten verwendet werden.

Parameter parameters-9

Beispiel example-6

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

Xss-htmlAttr xss-htmlattr

Ein Helper, der eine Quellzeichenfolge zum Schreiben in einen HTML-Attributwert codiert, um XSS zu verhindern.

HINWEIS: Dieser Helper ist kein Validator und darf nicht zum Schreiben von verwertbaren Attributen (href, src, Ereignis-Handler) verwendet werden.

Parameter parameters-10

Beispiel example-7

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

Xss-jsString xss-jsstring

Ein Helper, der eine Quellzeichenfolge zum Schreiben in JavaScript-Zeichenfolgeninhalte kodiert, um XSS zu verhindern.

HINWEIS: Dieser Helper ist kein Validator und darf nicht zum Schreiben in beliebige JavaScript verwendet werden.

Parameter parameters-11

Beispiel example-8

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

Xss-validHref xss-validhref

Ein Helper, der eine URL bereinigt, damit sie als HTML href- oder srce-Attributwert geschrieben wird, um XSS zu verhindern.

HINWEIS: Dieser Helper kann eine leere Zeichenfolge zurückgeben.

Parameter parameters-12

Beispiel example-9

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

Grundlegende Übersicht über Handlebars.js handlebars-js-basic-overview

Ein Beispiel für einen einfachen Helper aus der Dokumentation zu 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);

würde Folgendes rendern:

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

Beispiel für einen Block-Helper aus der Dokumentation zu 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);

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

Benutzerdefinierte SCF-Helfer custom-scf-helpers

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

Server-seitige benutzerdefinierte Helper server-side-custom-helpers

Um einen benutzerdefinierten SCF-Helper Server-seitig zu implementieren und zu registrieren, implementieren Sie einfach die Java™-Schnittstelle TemplateHelper, machen Sie sie zu einem OSGi-Service und installieren Sie sie als Teil eines OSGi-Bundles.

Zum Beispiel:

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

Client-seitige benutzerdefinierte Helper client-side-custom-helpers

Die Client-seitigen Helper sind Handlebars-Skripte, die durch Aufrufen von Handlebars.registerHelper() registriert werden.
Zum Beispiel:

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

Die benutzerdefinierten Client-seitigen Helper müssen zu einer benutzerdefinierten Client-Bibliothek hinzugefügt werden.
Die clientlib muss:

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