Personalización del lado del cliente

Para personalizar el aspecto y/o el comportamiento de un componente de AEM Communities en el lado del cliente, existen varios enfoques.

Dos enfoques principales son superponer o ampliar un componente.

Al superponer un componente, se cambia el componente predeterminado y se afectan todas las referencias al mismo.

La extensión de un componente, con un nombre exclusivo, limita el alcance de los cambios. El término 'extender' se utiliza indistintamente con 'anular'.

Superposiciones

La superposición de un componente es un método para realizar modificaciones en un componente predeterminado y afectar a todas las instancias que lo utilicen.

La superposición se realiza modificando una copia del componente predeterminado en el directorio /apps, en lugar de modificar el componente original en el directorio /libs. El componente se construye con una ruta relativa idéntica, excepto que 'libs' se sustituye por 'apps'.

El directorio /apps es el primer lugar en el que se busca para resolver solicitudes y, si no se encuentra, se utiliza la versión predeterminada ubicada en el directorio /libs.

El componente predeterminado en el directorio /libs nunca debe modificarse, ya que los parches futuros y las actualizaciones son libres de alterar el directorio /libs de cualquier manera necesaria mientras se mantienen las interfaces públicas.

Esto es diferente a ampliar un componente predeterminado donde el deseo es realizar modificaciones para un uso específico, crear una ruta única al componente y confiar en hacer referencia al componente predeterminado original en el directorio /libs como el tipo de recurso superior.

Para ver un ejemplo rápido de superposición del componente de comentarios, pruebe el tutorial Overlay Comments Component.

Extensiones

Ampliar (anular) un componente es un método para realizar modificaciones para un uso específico sin afectar a todas las instancias que utilizan el valor predeterminado. El componente extendido tiene un nombre exclusivo en la carpeta /apps y hace referencia al componente predeterminado de la carpeta /libs, por lo que el diseño y el comportamiento predeterminados del componente no se modifican.

Esto es diferente de superponer el componente predeterminado donde la naturaleza de Sling resuelve referencias relativas a las aplicaciones o la carpeta antes de buscar en la carpeta libs/, por lo tanto el diseño o el comportamiento de un componente se modifica de forma global.

Para ver un ejemplo rápido de cómo ampliar el componente de comentarios, pruebe el tutorial Extend Comments Component.

Enlace Javascript

La secuencia de comandos de HBS para el componente debe enlazarse a los objetos, modelos y vistas de JavaScript que implementan esta función.

El valor del atributo data-scf-component puede ser el valor predeterminado, como social/tally/components/hbs/rating, o un componente extendido (personalizado) para la funcionalidad personalizada, como weretail/components/hbs/rating.

Para enlazar un componente, toda la secuencia de comandos del componente debe estar encerrada dentro de un elemento <div> con los atributos siguientes:

• data-component-id="{{id}}"

  se resuelve en la propiedad id del contexto

• data-scf-component="<resourcetype>

Por ejemplo, desde /apps/weretail/components/hbs/rating/rating.hbs:

<div class="we-Rating" data-component-id="{{id}}" data-scf-component="weretail/components/hbs/rating">

     <!-- HTML with HBS accessing the rating component -->

</div>

Propiedades personalizadas

Al ampliar o superponer un componente, es posible añadir propiedades a un cuadro de diálogo modificado.

Se puede acceder a todas las propiedades establecidas en un componente o recurso haciendo referencia a las claves de propiedad de la plantilla de controladores:

{{properties.<property_name>}}

Aplicación de apariencia a CSS

La personalización de componentes para que coincidan con el tema general del sitio web se puede lograr 'desollando': cambiando colores, fuentes, imágenes, botones, vínculos, espaciado e incluso posicionamiento hasta cierto punto.

La apariencia se puede conseguir anulando selectivamente los estilos de marco o escribiendo hojas de estilo completamente nuevas. Los componentes SCF definen clases CSS con espacio de nombres, modulares y semánticas que afectan a los distintos elementos que conforman un componente.

Para aplicar máscara a un componente:

1. Identifique los elementos que desea cambiar (por ejemplo: área del compositor, botones de la barra de herramientas, fuente del mensaje, etc.).

2. Identifique la clase o las reglas CSS que afectan a estos elementos.

3. Cree un archivo de hoja de estilo (.css).

4. Incluya la hoja de estilo en una carpeta de la biblioteca del cliente (clientlibs) para su sitio y asegúrese de incluirla en las plantillas y páginas con ui:includeClientLib.

5. Vuelva a definir las clases y reglas CSS que ha identificado (#2) en la hoja de estilo y agregue estilos.

Los estilos personalizados ahora anularán los estilos de marco predeterminados y el componente se procesará con el nuevo aspecto.

Ampliación de Javascript

Para ampliar una implementación de componentes de Javascript, debe:

1. Cree un componente para su aplicación con un jcr:resourceSuperType definido en el valor de jcr:resourceType del componente extendido, por ejemplo, social/forum/components/hbs/forum.
2. Examine el Javascript del componente SCF predeterminado para determinar qué métodos deben registrarse mediante SCF.registerComponent().
3. Copie el Javascript o el inicio del componente extendido desde cero.
4. Amplíe el método.
5. Utilice SCF.registerComponent() para registrar todos los métodos con los valores predeterminados o con los objetos y vistas personalizados.

forum.js: Extensión de muestra del foro - HBS

(function($CQ, _, Backbone, SCF) {
    "use strict";
    var GMForumView = SCF.ForumView.extend({
        viewName: "GMForum",
        showComposer: function(e) {
            SCF.ForumView.prototype.toggleComposer.apply(this);
            var cancel = this.$el.find('.cancel-new-topic');
            cancel.toggle();
        },
        hideComposer: function(e) {
            SCF.ForumView.prototype.toggleComposer.apply(this);
            var cancel = this.$el.find('.cancel-new-topic');
            cancel.toggle();
        }
    });

    SCF.registerComponent('social/forum/components/hbs/post', SCF.Post, SCF.PostView);
    SCF.registerComponent('social/forum/components/hbs/topic', SCF.Topic, SCF.TopicView);
    SCF.registerComponent('social/forum/components/hbs/forum', SCF.Forum, GMForumView );
})($CQ, _, Backbone, SCF);

Etiquetas de script

Las etiquetas de script son una parte inherente del entorno de cliente. Son el pegamento que ayuda a enlazar el marcado generado en el servidor con los modelos y vistas del lado del cliente.

Las etiquetas de script de los scripts SCF no deben eliminarse al superponer o anular componentes. Las etiquetas de script SCF creadas automáticamente para insertar JSON en el HTML se identifican con el atributo data-scf-json=true.

Clientlibs para SCF

El uso de bibliotecas del lado del cliente (clientlibs), proporciona un medio para organizar y optimizar el JavaScript y CSS utilizado para procesar contenido en el cliente.

Los clientlibs para SCF siguen un patrón de nombres muy específico para dos variantes, que varía solamente por la presencia de "autor" en el nombre de la categoría:

Clientes totales

Los clientlibs completos (no autores) incluyen dependencias y son convenientes para incluirlos con ui:includeClientLib.

Estas versiones se encuentran en:

• /etc/clientlibs/social/hbs/<component name>

Por ejemplo:

• Nodo de carpeta de cliente: /etc/clientlibs/social/hbs/forum
• Categorías, propiedad: cq.social.hbs.forum

La guía de componentes de comunidad lista los clientlibs completos requeridos para cada componente SCF.

Clientlibs for Communities Componentsdescribe cómo agregar clientlibs a una página.

Author Clientlibs

Los clientes de la versión de creación se eliminan al mínimo JavaScript necesario para implementar el componente.

Estos clientes no deberían incluirse nunca directamente, sino que están disponibles para ser incorporados a otros clientes, que son hechos a mano para un sitio.

Estas versiones se encuentran en la carpeta de bibliotecas de SCF:

• /libs/social/<feature>/components/hbs/<component name>/clientlibs

Por ejemplo:

• Nodo de carpeta de cliente: /libs/social/forum/hbs/forum/clientlibs
• Categorías, propiedad: cq.social.author.hbs.forum

Nota: aunque los clientlibs de autor nunca incorporan otras bibliotecas, sí que lista sus dependencias. Cuando se incrustan en otras bibliotecas, las dependencias no se extraen automáticamente y también se deben incrustar.

Los clientlibs de creación requeridos se pueden identificar insertando "author" en los clientlibs enumerados para cada componente SCF en la Guía de componentes de comunidad.

Consideraciones de uso

Cada sitio es diferente en la forma en que administra las bibliotecas de cliente. Entre los diversos factores se incluyen:

• Velocidad global: Tal vez el deseo sea que el sitio responda, pero es aceptable que la primera página sea un poco lenta de cargar. Si muchas de las páginas utilizan el mismo JavaScript, los distintos JavaScript se pueden incorporar en una clientlib y se puede hacer referencia a ellos desde la primera página que se va a cargar. El Javascript de esta descarga única permanece en la caché, lo que minimiza la cantidad de datos que descargar para las páginas posteriores.
• Tiempo corto hasta la primera página: Quizás el deseo es que la primera página se cargue rápidamente. En este caso, Javascript se encuentra en varios archivos pequeños para que solo se haga referencia a ellos cuando sea necesario.
• Un equilibrio entre la primera carga de página y las descargas posteriores.