Helper Handlebars SCF scf-handlebars-helpers

Handlebars Helpers (helpers) sono metodi richiamabili dagli script Handlebars per facilitare l’utilizzo dei componenti SCF.

L’implementazione include una definizione lato client e lato server. È inoltre possibile per gli sviluppatori creare helper personalizzati.

Gli helper SCF personalizzati forniti con AEM Communities sono definiti nella libreria client:

Abbrevia abbreviate

Helper per restituire una stringa abbreviata conforme alle proprietà maxWords e maxLength.

La stringa da abbreviare viene fornita come contesto. Se non viene fornito alcun contesto, viene restituita una stringa vuota.

Innanzitutto, il contesto viene ridotto a maxLength, quindi viene suddiviso in parole e ridotto a maxWords.

Se safeString è impostato su true, la stringa restituita sarà una stringa provvisoria.

Parametri parameters

Esempi 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

Un helper per aggiungere due estensioni sotto un div, una per il testo completo e l’altra per il testo meno, con la possibilità di passare da una visualizzazione all’altra.

Parametri parameters-1

Esempio 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

Un helper per restituire una stringa di data formattata.

Parametri parameters-2

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

Uguale a equals

Un helper per restituire il contenuto a seconda di un condizionale di uguaglianza.

Parametri parameters-3

Esempio 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

Helper per blocchi che verifica il valore corrente di modalità WCM in base a un elenco di modalità separato da stringhe.

Parametri parameters-4

Esempio example-2

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

i18n i-n

Questo helper sostituisce l'helper Handlebars 'i18n'.

Vedi anche Internazionalizzazione delle stringhe nel codice JavaScript.

Parametri parameters-5

Esempio example-3

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

Includi include

Un helper per includere un componente come risorsa non esistente in un modello.

Questo metodo consente di personalizzare la risorsa a livello di programmazione più facilmente di quanto non sia possibile per una risorsa aggiunta come nodo JCR. Vedi Aggiungere o includere un componente community.

Sono disponibili solo alcuni componenti di Communities da includere.

Questo helper, appropriato solo sul lato server, fornisce funzionalità simili a cq:include per gli script JSP.

Parametri parameters-6

Esempio example-4

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

Include un nuovo componente commenti in this.id + /comments.

IncludeClientLib includeclientlib

Helper che include una libreria client HTML AEM, che può essere una libreria js, css o theme. Per più inclusioni di tipi diversi, ad esempio js e css, questo tag deve essere utilizzato più volte nello script Handlebars.

Questo helper, appropriato solo sul lato server, fornisce funzionalità simili a ui:includeClientLib per gli script JSP.

Parametri parameters-7

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

Bel tempo pretty-time

Un helper per visualizzare il tempo trascorso fino a un punto di interruzione, dopo il quale viene visualizzato un formato di data regolare.

Ad esempio:

Parametri parameters-8

Esempio 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

Helper che codifica una stringa di origine per il contenuto dell’elemento HTML per evitare attacchi XSS.

NOTA: questo helper non è un validatore e non deve essere utilizzato per la scrittura di valori di attributo.

Parametri parameters-9

Esempio example-6

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

Xss-htmlAttr xss-htmlattr

Helper che codifica una stringa di origine per la scrittura in un valore di attributo HTML per evitare attacchi XSS.

NOTA: questo helper non è un validatore e non deve essere utilizzato per scrivere attributi utilizzabili (href, src, gestori eventi).

Parametri parameters-10

Esempio example-7

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

Xss-jsString xss-jsstring

Helper che codifica una stringa di origine per la scrittura nel contenuto della stringa JavaScript per evitare attacchi XSS.

NOTA: questo helper non è un validatore e non deve essere utilizzato per la scrittura su JavaScript arbitrari.

Parametri parameters-11

Esempio example-8

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

Xss-validHref xss-validhref

Helper che bonifica un URL per la scrittura come valore di attributo HTML href o di risorsa per proteggersi da XSS.

NOTA: questo helper potrebbe restituire una stringa vuota.

Parametri parameters-12

Esempio example-9

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

Panoramica di base di Handlebars.js handlebars-js-basic-overview

Un esempio di un semplice helper dalla documentazione di 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);

Esegue il rendering:

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

Un esempio di helper per blocchi tratto dalla documentazione di 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);

Esegue il rendering:
<ul>
<li><a href="/people/1">Alan</a></li>
<li><a href="/people/2">Yehuda</a></li>
</ul>

Helper SCF personalizzati custom-scf-helpers

Gli helper personalizzati devono essere implementati sul lato server e sul lato client, soprattutto durante il trasferimento dei dati. Per l'SCF, la maggior parte dei modelli viene compilata e riprodotta sul lato server mentre il server genera le HTML per un determinato componente quando la pagina viene richiesta.

Helper personalizzati lato server server-side-custom-helpers

Per implementare e registrare un helper SCF personalizzato sul lato server, è sufficiente implementare l'interfaccia Java™ TemplateHelper, trasformarlo in servizio OSGi e installarlo come parte di un bundle OSGi.

Ad esempio:

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

Helper personalizzati lato client client-side-custom-helpers

Gli helper lato client sono script Handlebars registrati richiamando Handlebars.registerHelper().
Ad esempio:

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

Gli helper lato client personalizzati devono essere aggiunti a una libreria client personalizzata.
La libreria client deve:

Nota: gli helper SCF sono definiti in /etc/clientlibs/social/commons/scf/helpers.js.