Helper manubrio SCF

Gli Helper Handlebars (helper) 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:

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

Abbrevia

Un helper che restituisce 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.

In primo luogo, il contesto viene troncato su maxLength, quindi il contesto viene suddiviso in parole e ridotto a maxWords.

Se safeString è impostato su true, la stringa restituita è SafeString.

Parametri

• contesto: Stringa

  (facoltativo) La stringa predefinita è vuota

• maxLength: Numero

  (facoltativo) L'impostazione predefinita è la lunghezza del contesto.

• maxWords: Numero

  (facoltativo) Il valore predefinito è il numero di parole nella stringa tagliata.

• safeString: Booleano

  (facoltativo) Restituisce un oggetto Handlebars.SafeString() se true. Il valore predefinito è false.

Esempi

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

Un helper per per aggiungere due pagine 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

• contesto: Stringa

  (facoltativo) L'impostazione predefinita è la stringa vuota.

• numChars: Numero

  (facoltativo) Il numero di caratteri da visualizzare quando non viene visualizzato il testo completo. Il valore predefinito è 100.

• moreText: Stringa

  (Facoltativo) Il testo da visualizzare che indica che c'è più testo da visualizzare. Il valore predefinito è "more".

• ellissiText: Stringa

  (Facoltativo) Il testo da visualizzare che indica l’esistenza di testo nascosto. Il valore predefinito è "…".

• safeString: Booleano

  (facoltativo) Valore booleano che indica se applicare o meno Handlebars.SafeString() prima di restituire il risultato. Il valore predefinito è false.

Esempio

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

Un helper che restituisce una stringa data formattata.

Parametri

• contesto: Numero

  (facoltativo) offset di un valore di millisecondi dal 1° gennaio 1970 (epoch). Il valore predefinito è la data corrente.

• format: Stringa

  (facoltativo) Il formato della data da applicare. Il valore predefinito è "YYYY-MM-DDTHH":mm:ss.sssZ" e il risultato appare come "2015-03-18T18:17:13-07:00"

Esempi

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

Un helper per per restituire il contenuto in base a una condizione di uguaglianza.

Parametri

• lvalue: Stringa

  Valore sinistro da confrontare

• valore: Stringa

  Valore a destra da confrontare

Esempio

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

Modalità If-wcm

Un supporto per blocchi che verifica il valore corrente di Modalità WCM in un elenco di modalità separate da stringa.

Parametri

• contesto: Stringa

  (facoltativo) Stringa da tradurre. Obbligatorio se non è stato fornito alcun valore predefinito.

• modalità: Stringa

  (facoltativo) Un elenco separato da virgole di Modalità WCM da verificare se impostato.

Esempio

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

i18n

Questo helper sostituisce l'helper Handlebars 'i18n'.

Vedi anche Internazionalizzazione delle stringhe nel codice JavaScript.

Parametri

• contesto: Stringa

  (facoltativo) Stringa da tradurre. Obbligatorio se non è stato fornito alcun valore predefinito.

• default: Stringa

  (Facoltativo) La stringa predefinita da tradurre. Obbligatorio se non viene fornito alcun contesto.

• commento: Stringa

  (facoltativo) Un suggerimento di traduzione

Esempio

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

Includi

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

Questo consente di personalizzare la risorsa in modo programmatico più facilmente di quanto sia possibile per una risorsa aggiunta come nodo JCR. Vedi Aggiungere o includere un componente Community.

Sono inclusi solo alcuni componenti di Communities. Per AEM 6.1, quelli inclusi sono commenti, valutazione, recensionie votazione.

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

Parametri

• contesto: Stringa o oggetto

  (facoltativo, a meno che non venga fornito un percorso relativo)

  use thisper passare il contesto corrente

  use this.id per ottenere la risorsa in id per il rendering del resourceType richiesto

• resourceType: Stringa

  (facoltativo) per impostazione predefinita il tipo di risorsa viene impostato sul tipo di risorsa dal contesto

• template: Stringa

  percorso dello script componente

• path: Stringa

  (obbligatorio) Il percorso della risorsa. Se il percorso è relativo, è necessario fornire un contesto, altrimenti viene restituita la stringa vuota.

• authoringDisabled: Booleano

  (facoltativo) L'impostazione predefinita è false. Solo per uso interno.

Esempio

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

Questo include un nuovo componente Commenti in this.id + /commenti

IncludeClientLib

Un helper che include una libreria client HTML AEM, che può essere un js, un css o una libreria di temi. 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

• categorie: Stringa

  (facoltativo) Elenco di categorie di librerie client separate da virgola. Questo includerà tutte le librerie JavaScript e CSS per le categorie specificate. Il nome del tema viene estratto dalla richiesta.

• tema: Stringa

  (facoltativo) Elenco di categorie di librerie client separate da virgola. Questo includerà tutte le librerie correlate al tema (sia CSS che JS) per le categorie specificate. Il nome del tema viene estratto dalla richiesta.

• js: Stringa

  (facoltativo) Elenco di categorie di librerie client separate da virgola. Questo includerà tutte le librerie JavaScript per le categorie specificate.

• css: Stringa

  (facoltativo) Elenco di categorie di librerie client separate da virgola. Questo includerà tutte le librerie CSS per le categorie specificate.

Esempi

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

Tempo utile

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

Ad esempio:

• 12 ore fa
• 7 giorni fa

Parametri

• contesto: Numero

  Un'epoca in passato da paragonare a "ora". Il tempo è espresso come valore in millisecondi offset dal 1 gennaio 1970 (epoch).

• daysCutoff: Numero

  Il numero di giorni fa prima del passaggio a una data effettiva. Il valore predefinito è 60.

Esempio

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

Helper che codifica una stringa sorgente per il contenuto dell’elemento HTML per proteggerlo da XSS.

NOTA: questo non è un validatore e non deve essere utilizzato per scrivere i valori degli attributi.

Parametri

• contesto: oggetto

  il HTML da codificare

Esempio

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

Xss-htmlAttr

Un helper che codifica una stringa di origine per la scrittura in un valore di attributo di HTML per proteggere XSS.

NOTA: non si tratta di un validatore e non deve essere utilizzato per la scrittura di attributi actionable (href, src, gestori eventi).

Parametri

• contesto: Oggetto

  HTML da codificare

Esempio

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

Xss-jsString

Un helper che codifica una stringa di origine per la scrittura nel contenuto della stringa JavaScript per proteggerlo da XSS.

NOTA: questo non è un validatore e non deve essere utilizzato per scrivere in JavaScript arbitrario.

Parametri

• contesto: Oggetto

  HTML da codificare

Esempio

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

Xss-validHref

Un helper che igienizza un URL per la scrittura come valore di attributo HTML href o srce per proteggere XSS.

NOTA: potrebbe restituire una stringa vuota

Parametri

• contesto: Oggetto

  URL da bonificare

Esempio

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

Panoramica di base di Handlebars.js

• Una chiamata dell'helper Handlebars è un identificatore semplice (il *nome *dell'helper), seguito da zero o più parametri separati dallo spazio.

• I parametri possono essere un semplice oggetto String, number, boolean o JSON, oltre a una sequenza facoltativa di coppie chiave-valore (argomenti hash) come ultimo parametro/i.

• Le chiavi negli argomenti hash devono essere identificatori semplici.

• I valori negli argomenti hash sono espressioni Handlebars: identificatori semplici, percorsi o stringhe.

• Il contesto attuale, this, è sempre disponibile per gli helper Handlebars.

• Il contesto può essere un oggetto dati String, number, boolean o JSON.

• È possibile passare un oggetto nidificato nel contesto corrente come contesto, ad esempio this.url o this.id (vedere i seguenti esempi di aiutanti semplici e a blocchi).

• Gli helper a blocchi sono funzioni che possono essere richiamate da qualsiasi punto del modello. Possono richiamare ogni volta un blocco del modello zero o più volte con un contesto diverso. Contengono un contesto tra {{#name}} and {{/name}}.

• Handlebars fornisce un parametro finale agli helper denominati "options". L'oggetto speciale "options" include

  • Dati privati opzionali (options.data)
  • Proprietà chiave-valore facoltative dalla chiamata (options.hash)
  • Possibilità di richiamarsi (options.fn())
  • Possibilità di richiamare l'inverso di se stesso (options.inverse())

• È consigliabile che il contenuto di HTML String restituito da un helper sia SafeString.

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

Rendering:

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

Esempio di un helper per per blocchi nella documentazione di 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);

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

Helper SCF personalizzati

Gli helper personalizzati devono essere implementati sia sul lato server che sul lato client, soprattutto quando si trasmettono i dati. Per SCF, la maggior parte dei modelli viene compilata e sottoposta a rendering sul lato server, in quanto il server genera HTML per un determinato componente quando la pagina viene richiesta.

Helper personalizzati lato server

Per implementare e registrare un helper SCF personalizzato sul lato server, è sufficiente implementare l’interfaccia Java TemplateHelper, rendilo un Servizio OSGi e installalo come parte di un bundle OSGi.

Ad esempio:

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

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

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 personalizzati lato client devono essere aggiunti a una libreria client personalizzata.
La clientlib deve:

• Includi una dipendenza in cq.social.scf
• Carica dopo il caricamento di Handlebars
• Essere incluso

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

Risorse Business.Adobe.com

Multichannel Communication Auto Form Fill Targeted Content Embedded Charts Document Generation Content As A Service