Ayudantes de manillares SCF

Handlebars Helpers (ayudantes) son métodos que se pueden llamar desde scripts Handlebars para facilitar el trabajo con componentes SCF.

La implementación incluye una definición de cliente y de servidor. También es posible que los desarrolladores creen asistentes personalizados.

Los asistentes personalizados de SCF que se entregan con AEM Communities se definen en la biblioteca del cliente:

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

Abreviar

Un asistente para devolver una cadena abreviada que se ajuste a las propiedades maxWords y maxLength.

La cadena que se va a abreviar se proporciona como contexto. Si no se proporciona ningún contexto, se devuelve una cadena vacía.

En primer lugar, el contexto se recorta a maxLength y, a continuación, se divide en palabras y se reduce a maxWords.

Si safeString se establece en true, la cadena devuelta es SafeString.

Parámetros

• contexto: Cadena

  (Opcional) El valor predeterminado es la cadena vacía

• maxLength: Número

  (Opcional) El valor predeterminado es la longitud del contexto.

• maxWords: Número

  (Opcional) El valor predeterminado es el número de palabras de la cadena recortada.

• safeString: Booleano

  (Opcional) Devuelve Handlebars.SafeString() si es true. El valor predeterminado es false.

Ejemplos

{{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 ayudante para agregar dos grupos debajo de un div, uno para el texto completo y el otro para el menos texto, con la capacidad de alternar entre las dos vistas.

Parámetros

• contexto: Cadena

  (Opcional) El valor predeterminado es la cadena vacía.

• numChars: Número

  (Opcional) El número de caracteres que se mostrarán cuando no se muestre texto completo. El valor predeterminado es 100.

• moreText: Cadena

  (Opcional) El texto que se va a mostrar que indica que hay más texto para mostrar. El valor predeterminado es "more".

• elipsesText: Cadena

  (Opcional) El texto que se va a mostrar y que indica que hay texto oculto. El valor predeterminado es "…".

• safeString: Booleano

  (Opcional) Valor booleano que indica si se deben aplicar o no Handlebars.SafeString() antes de devolver el resultado. El valor predeterminado es false.

Ejemplo

{{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 asistente para devolver una cadena de fecha con formato.

Parámetros

• contexto: Número

  (Opcional) un valor de milisegundos compensado con respecto al 1 de enero de 1970 (epoch). El valor predeterminado es la fecha actual.

• formato: Cadena

  (Opcional) El formato de fecha que se va a aplicar. El valor predeterminado es "AAAA-MM-DDTHH:mm:ss.sssZ" y el resultado aparece como "2015-03-18T18:17:13-07:00"

Ejemplos

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

Es igual a

Un asistente para devolver contenido según una condición de igualdad.

Parámetros

• lvalue: Cadena

  El valor que se va a comparar a la izquierda.

• rvalue: Cadena

  El valor de la derecha que se va a comparar.

Ejemplo

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

If-wcm-mode

Asistente de bloque que prueba el valor actual de modo WCM con una lista de modos separada por cadenas.

Parámetros

• contexto: Cadena

  (Opcional) La cadena que se va a traducir. Necesario si no se proporciona ningún valor predeterminado.

• modo: Cadena

  (Opcional) Una lista separada por comas de modos WCM para probar si está configurada.

Ejemplo

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

i18n

Este asistente anula el asistente de Handlebars 'i18n'.

Consulte también Internacionalización de cadenas en código JavaScript.

Parámetros

• contexto: Cadena

  (Opcional) La cadena que se va a traducir. Necesario si no se proporciona ningún valor predeterminado.

• predeterminado: Cadena

  (Opcional) La cadena predeterminada que se va a traducir. Necesario si no se proporciona ningún contexto.

• comentario: Cadena

  (Opcional) Una sugerencia de traducción

Ejemplo

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

Incluir

Un asistente para incluir un componente como recurso no existente en una plantilla.

Esto permite que el recurso se personalice mediante programación más fácilmente de lo que es posible para un recurso agregado como nodo JCR. Consulte Añadir o incluir un componente de comunidades.

Solo se pueden incluir algunos componentes de Comunidades. Para AEM 6.1, los que son inclusibles son comentarios, clasificación, revisiones y votación.

Este asistente, adecuado sólo en el servidor, proporciona una funcionalidad similar a cq:include para scripts JSP.

Parámetros

• contexto: Cadena u objeto

  (Opcional, a menos que se proporcione una ruta relativa)

  Utilice this para pasar el contexto actual.

  Utilice this.id para obtener el recurso en id para procesar el resourceType solicitado.

• resourceType: Cadena

  (Opcional) El tipo de recurso predeterminado será el tipo de recurso de contexto.

• plantilla: Cadena

  Ruta al script de componente.

• path: Cadena

  (Requerido) La ruta al recurso. Si la ruta es relativa, se debe proporcionar un contexto; de lo contrario, se devuelve la cadena vacía.

• authoringDisabled: Booleano

  (Opcional) El valor predeterminado es false. Solo para uso interno.

Ejemplo

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

Esto incluirá un nuevo componente de comentarios en this.id + /comments.

IncludeClientLib

Un asistente que incluye una biblioteca de cliente HTML AEM, que puede ser un js, un css o una biblioteca de temas. Para varias inclusiones de diferentes tipos, por ejemplo js y css, esta etiqueta debe usarse varias veces en la secuencia de comandos Handlebars.

Este asistente, adecuado solo en el servidor, proporciona una funcionalidad similar a ui:includeClientLib para scripts JSP.

Parámetros

• categorías: Cadena

  (Opcional) Una lista de categorías de biblioteca de cliente separadas por coma. Esto incluirá todas las bibliotecas Javascript y CSS de las categorías determinadas. El nombre del tema se extrae de la solicitud.

• tema: Cadena

  (Opcional) Una lista de categorías de biblioteca de cliente separadas por coma. Esto incluirá todas las bibliotecas relacionadas con el tema (CSS y JS) para las categorías dadas. El nombre del tema se extrae de la solicitud.

• js: Cadena

  (Opcional) Una lista de categorías de biblioteca de cliente separadas por coma. Esto incluirá todas las bibliotecas Javascript de las categorías dadas.

• css: Cadena

  (Opcional) Una lista de categorías de biblioteca de cliente separadas por coma. Esto incluirá todas las bibliotecas CSS de las categorías dadas.

Ejemplos

// 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?lang=es" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css?lang=es" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=es" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js?lang=es" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js?lang=es" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=es" 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?lang=es" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/socialgraph.js?lang=es" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=es" 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?lang=es" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=es" rel="stylesheet" type="text/css">
    <script src="/etc/clientlibs/social/hbs/tally/voting.js?lang=es" type="text/javascript"></script>
    <script src="/etc/clientlibs/social/hbs/comments.js?lang=es" 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?lang=es" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/socialgraph.css?lang=es" rel="stylesheet" type="text/css">
    <link href="/etc/clientlibs/social/hbs/comments.css?lang=es" rel="stylesheet" type="text/css">

Pretty-time

Un asistente para mostrar cuánto tiempo ha pasado a un punto de corte, después del cual se muestra un formato de fecha normal.

Por ejemplo:

• Hace 12 horas
• 7 días antes

Parámetros

• contexto: Número

  Un tiempo en el pasado para comparar con 'ahora'. El tiempo se expresa como un valor de milisegundos compensado con respecto al 1 de enero de 1970 (epoch).

• daysCutoff: Número

  El número de días antes de cambiar a una fecha real. El valor predeterminado es 60.

Ejemplo

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

Un asistente que codifica una cadena de origen para contenido de elementos HTML para ayudar a protegerse de XSS.

NOTA: no es un validador y no se utiliza para escribir valores de atributos.

Parámetros

• contexto: object

  El HTML que se va a codificar.

Ejemplo

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

Xss-htmlAttr

Un asistente que codifica una cadena de origen para escribir en un valor de atributo HTML para ayudar a protegerse de XSS.

NOTA: no es un validador y no se utiliza para escribir atributos procesables (href, src, controladores de evento).

Parámetros

• contexto: Objeto

  El HTML que se va a codificar.

Ejemplo

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

Xss-jsString

Un asistente que codifica una cadena de origen para escribir en contenido de cadena JavaScript para ayudar a protegerse de XSS.

NOTA: no es un validador y no se utiliza para escribir en JavaScript arbitrario.

Parámetros

• contexto: Objeto

  El HTML que se va a codificar.

Ejemplo

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

Xss-validHref

Un asistente que lisa una URL para escribir como href HTML o valor de atributo de origen para ayudar a proteger contra XSS.

NOTA: esto puede devolver una cadena vacía

Parámetros

• contexto: Objeto

  Dirección URL que se va a sanear.

Ejemplo

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

Información general básica de Handlebars.js

Información general rápida sobre las funciones de ayuda de la documentación de Handlebars.js:

• Una llamada de ayuda de Handlebars es un identificador simple (el nombre del asistente), seguido de cero o más parámetros separados por espacios.

• Los parámetros pueden ser un objeto String, number, booleano o JSON sencillo, así como una secuencia opcional de pares de clave-valor (argumentos hash) como los últimos parámetros.

• Las claves de los argumentos hash deben ser identificadores simples.

• Los valores de los argumentos hash son expresiones Handlebars: identificadores simples, rutas o cadenas.

• El contexto actual, this, siempre está disponible para los ayudantes de Handlebars.

• El contexto puede ser un objeto de datos String, number, booleano o JSON.

• Es posible pasar un objeto anidado dentro del contexto actual como contexto, como this.url o this.id (vea los siguientes ejemplos de asistentes simples y de bloques).

• Los asistentes de bloque son funciones a las que se puede llamar desde cualquier lugar de la plantilla. Pueden invocar un bloque de la plantilla cero o más veces con un contexto diferente cada vez. Contienen un contexto entre {{#name}} y {{/name}.

• Handlebars proporciona un parámetro final a los asistentes llamados 'options'. El objeto especial 'options' incluye

  • Datos privados opcionales (options.data)
  • Propiedades de clave-valor opcionales de la llamada (options.hash)
  • Capacidad para invocarse (options.fn())
  • Capacidad de invocar lo contrario de sí mismo (options.inverse())

• Se recomienda que el contenido de cadena HTML devuelto por un asistente sea SafeString.

Ejemplo de un asistente sencillo de la documentación de Handlebars.js:

Handlebars.registerHelper('link_to', function(title, options) {
    return new Handlebars.SafeString('<a href="/posts'%20+%20this.url%20+%20'?lang=es">' + 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);

Se procesaría:

<ul>
<li><a href="/posts/hello-world">¡Publicación!</a></li>
</ul>

Ejemplo de un asistente de bloque de la documentación de Handlebars.js:

Handlebars.registerHelper('link', function(options) {
    return new Handlebars.SafeString('<a href="/people/'%20+%20this.id%20+%20'?lang=es">' + 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);

Se procesaría:
<ul>
<li><a href="/people/1">Alan</a></li>
<li><a href="/people/2">Yehuda</a></li>
</ul>

Ayuda personalizada de SCF

Los asistentes personalizados deben implementarse en el lado del servidor y en el lado del cliente, especialmente al pasar datos. Para SCF, la mayoría de las plantillas se compilan y procesan en el servidor, ya que el servidor genera el código HTML para un componente determinado cuando se solicita la página.

Ayudas personalizadas del lado del servidor

Para implementar y registrar un asistente personalizado de SCF en el servidor, simplemente implemente la interfaz de Java TemplateHelper, conviértala en un servicio de OSGi e instálelo como parte de un paquete de OSGi.

Por ejemplo:

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

Ayudas personalizadas del lado del cliente

Los ayudantes del lado del cliente son secuencias de comandos Handlebars registradas invocando Handlebars.registerHelper().
Por ejemplo:

custom-helpers.js

function(Handlebars, SCF, $CQ) {

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

})(Handlebars, SCF, $CQ);

Los asistentes personalizados del lado del cliente deben agregarse a una biblioteca de cliente personalizada.
La clientlib debe:

• Incluya una dependencia en cq.social.scf.
• Cargue después de cargar las barras de controladores.
• Esté incluido.

Nota: los ayudantes de SCF se definen en /etc/clientlibs/social/commons/scf/helpers.js.