Desarrollo de un componente personalizado para AEM Screens

En el siguiente tutorial se explican los pasos para crear un componente personalizado para AEM Screens. AEM Screens reutiliza muchos patrones de diseño y tecnologías existentes de otros productos AEM. El tutorial resalta las diferencias y las consideraciones especiales al desarrollar para AEM Screens.

Información general

Este tutorial está dirigido a los desarrolladores que son nuevos en AEM Screens. En este tutorial, se ha creado un sencillo componente "Hello World" para un canal de secuencia en AEM Screens. Un cuadro de diálogo permite a los autores actualizar el texto mostrado.

overviewhellow

Requisitos previos

Para completar este tutorial, es necesario lo siguiente:

Paquete de funciones de pantallas más recientes de AEM 6.5 o AEM 6.3 +
Reproductor de AEM Screens
Entorno de desarrollo local

Los pasos del tutorial y las capturas de pantalla se realizan mediante CRXDE-Lite. También se pueden utilizar IDE para completar el tutorial. Puede encontrar más información sobre el uso de un IDE para desarrollar con AEM aquí.

Configuración del proyecto

El código fuente de un proyecto de Screens suele gestionarse como un proyecto Maven de varios módulos. Para acelerar el tutorial, se generó un proyecto previamente utilizando el AEM Arquetipo de proyecto 13. Puede encontrar más detalles sobre la creación de un proyecto con el arquetipo del proyecto Maven AEM aquí.

Descargue e instale los siguientes paquetes con administrador de paquetes CRX:

Obtener archivo

Obtener archivo
Si trabaja con Eclipse u otro IDE, descargue el siguiente paquete de origen. Implemente el proyecto en una instancia de AEM local mediante el comando Maven:

mvn -PautoInstallPackage clean install

Inicio HelloWorld SRC Screens We.Retail Run Project

Obtener archivo
En Administrador de paquetes de CRX compruebe que están instalados los dos paquetes siguientes:
1. screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip
2. screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip
Screens We.Retail Ejecute los paquetes Ui.Apps y Ui.Content instalados mediante el administrador de paquetes CRX
El paquete screens-weretail-run.ui.apps instala código debajo de /apps/weretail-run.

Este paquete contiene el código responsable de procesar los componentes personalizados del proyecto. Este paquete incluye código de componente y cualquier JavaScript o CSS necesario. Este paquete también incluye screen-weretail-run.core-0.0.1-SNAPSHOT.jar, que contiene cualquier código Java que necesite el proyecto.

NOTA

En este tutorial no se escribe ningún código Java. Si se necesita una lógica empresarial más compleja, se puede crear e implementar Java back-end mediante el paquete Core Java.

Representación del código ui.apps en el CRXDE Lite

El componente helloworld actualmente es sólo un marcador de posición. Durante el tutorial, se agregará la funcionalidad que permite a un autor actualizar el mensaje que muestra el componente.
El paquete screens-weretail-run.ui.content instala código debajo de:
- /conf/we-retail-run
- /content/dam/we-retail-run
- /content/screens/we-retail-run
Este paquete contiene el contenido inicial y la estructura de configuración necesarias para el proyecto. /conf/we-retail-run contiene todas las configuraciones para el proyecto de ejecución We.Retail. /content/dam/we-retail-run incluye el inicio de recursos digitales para el proyecto. /content/screens/we-retail-run contiene la estructura de contenido Pantallas. El contenido debajo de todas estas rutas se actualiza principalmente en AEM. Para fomentar la coherencia entre entornos (local, Dev, Stage, Prod), a menudo se guarda una estructura de contenido base en el control de código fuente.
Vaya al proyecto AEM Screens > Ejecución de We.Retail:

En el menú Inicio de AEM > Haga clic en el icono Pantallas. Verifique que se pueda ver el proyecto de ejecución We.Retail.

Crear el componente Hello World

El componente Hello World es un componente sencillo que permite al usuario introducir un mensaje para que se muestre en la pantalla. El componente se basa en la Plantilla de componentes de AEM Screens: https://github.com/Adobe-Marketing-Cloud/aem-screens-component-template.

AEM Screens tiene algunas restricciones interesantes que no son necesariamente ciertas para los componentes de sitios WCM tradicionales.

La mayoría de los componentes de Pantallas necesitan ejecutarse a pantalla completa en los dispositivos de señalización digital destinatario
La mayoría de los componentes de Pantallas deben poder incrustarse en los canales de secuencias para generar proyecciones de diapositivas
La creación debe permitir la edición de componentes individuales en un canal de secuencia, de modo que la representación en pantalla completa no está en cuestión

En CRXDE-Lite http://localhost:4502/crx/de/index.jsp (o IDE de su elección) navegue a /apps/weretail-run/components/content/helloworld.

Añada las siguientes propiedades al componente helloworld:
```
    jcr:title="Hello World"
    sling:resourceSuperType="foundation/components/parbase"
    componentGroup="We.Retail Run - Content"
```
Propiedades para /apps/weretail-run/components/content/helloworld

El componente helloworld extiende el componente foundation/components/parbase para que pueda utilizarse correctamente dentro de un canal de secuencia.
Cree un archivo bajo /apps/weretail-run/components/content/helloworld con el nombre helloworld.html.

Rellene el archivo con lo siguiente:
```



<sly data-sly-test.production="${wcmmode.preview || wcmmode.disabled}" data-sly-include="production.html" />


<sly data-sly-test="${!production}" data-sly-include="edit.html" />
```
Los componentes de pantalla requieren dos representaciones diferentes según el modo de creación que se esté utilizando:
1. Producción: Previsualización o modo de publicación (wcmmode=disabled)
2. Editar: se utiliza para todos los demás modos de creación, es decir, edición, diseño, andamiaje, desarrollador…
helloworld.htmlactúa como conmutador, comprobando qué modo de creación está activo actualmente y redirigiéndose a otro script HTL. Una convención común que utilizan los componentes de pantallas es tener una secuencia de comandos edit.html para el modo de edición y una secuencia de comandos production.html para el modo de producción.
Cree un archivo bajo /apps/weretail-run/components/content/helloworld con el nombre production.html.

Rellene el archivo con lo siguiente:
```


<div data-duration="${properties.duration}" class="cmp-hello-world">
 <h1 class="cmp-hello-world__message">${properties.message}</h1>
</div>
```
Arriba está el marcado de producción para el componente Hello World. Se incluye un atributo data-duration, ya que el componente se utiliza en un canal de secuencia. El canal de secuencias utiliza el atributo data-duration para saber durante cuánto tiempo se va a mostrar un elemento de secuencia.

El componente procesa una etiqueta div y una etiqueta h1 con texto. ${properties.message} es una parte de la secuencia de comandos HTML que mostrará el contenido de una propiedad JCR denominada message. Posteriormente se crea un cuadro de diálogo que permite al usuario introducir un valor para el texto de la propiedad message.

Tenga en cuenta también que la notación BEM (Modificador de elemento de bloque) se utiliza con el componente. BEM es una convención de codificación CSS que facilita la creación de componentes reutilizables. BEM es la notación utilizada por Componentes principales de AEM. Puede encontrar más información en: https://getbem.com/
Cree un archivo bajo /apps/weretail-run/components/content/helloworld con el nombre edit.html.

Rellene el archivo con lo siguiente:
```



<div
 data-sly-test.message="${properties.message}"
 class="aem-Screens-editWrapper cmp-hello-world">
 <p class="cmp-hello-world__message">${message}</p>
</div>


<div data-sly-test="${!message}"
     class="aem-Screens-editWrapper cq-placeholder cmp-hello-world"
     data-emptytext="${'Hello World' @ i18n, locale=request.locale}">
</div>
```
Arriba está el marcador de edición para el componente Hello World. El primer bloque muestra una versión de edición del componente si se ha rellenado el mensaje de diálogo.

El segundo bloque se procesa si no se ha introducido ningún mensaje de cuadro de diálogo. Los cq-placeholder y data-emptytext representan la etiqueta Hello World como marcador de posición en ese caso. La cadena de la etiqueta se puede internacionalizar con i18n para admitir la creación en varias configuraciones regionales.
Copiar cuadro de diálogo de imagen de pantalla que se usará para el componente Hola a todos.

Es más fácil inicio desde un cuadro de diálogo existente y luego realizar modificaciones.
1. Copie el cuadro de diálogo de: /libs/screens/core/components/content/image/cq:dialog
2. Pegue el cuadro de diálogo debajo de /apps/weretail-run/components/content/helloworld

Actualice el cuadro de diálogo Hola mundo para incluir una ficha para el mensaje.

Actualice el cuadro de diálogo para que coincida con lo siguiente. La estructura de nodos JCR del cuadro de diálogo final se presenta a continuación en XML:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="https://sling.apache.org/jcr/sling/1.0" xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
    jcr:primaryType="nt:unstructured"
    jcr:title="Hello World"
    sling:resourceType="cq/gui/components/authoring/dialog">
    <content
        jcr:primaryType="nt:unstructured"
        sling:resourceType="granite/ui/components/coral/foundation/tabs"
        size="L">
        <items jcr:primaryType="nt:unstructured">
            <message
                jcr:primaryType="nt:unstructured"
                jcr:title="Message"
                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
                <items jcr:primaryType="nt:unstructured">
                    <column
                        jcr:primaryType="nt:unstructured"
                        sling:resourceType="granite/ui/components/coral/foundation/container">
                        <items jcr:primaryType="nt:unstructured">
                            <message
                                jcr:primaryType="nt:unstructured"
                                sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
                                fieldDescription="Message for component to display"
                                fieldLabel="Message"
                                name="./message"/>
                        </items>
                    </column>
                </items>
            </message>
            <sequence
                jcr:primaryType="nt:unstructured"
                jcr:title="Sequence"
                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns">
                <items jcr:primaryType="nt:unstructured">
                    <column
                        jcr:primaryType="nt:unstructured"
                        sling:resourceType="granite/ui/components/coral/foundation/container">
                        <items jcr:primaryType="nt:unstructured">
                            <duration
                                jcr:primaryType="nt:unstructured"
                                sling:resourceType="granite/ui/components/coral/foundation/form/numberfield"
                                defaultValue=""
                                fieldDescription="Amount of time the image will be shown in the sequence, in milliseconds"
                                fieldLabel="Duration (ms)"
                                min="0"
                                name="./duration"/>
                        </items>
                    </column>
                </items>
            </sequence>
        </items>
    </content>
</jcr:root>

El campo de texto del mensaje se guardará en una propiedad denominada message y que el campo de número de la duración se guardará en una propiedad denominada duration. HTL hace referencia a estas dos propiedades en /apps/weretail-run/components/content/helloworld/production.html como ${properties.message} y ${properties.duration}.

Hola Mundo: cuadro de diálogo completado

Crear bibliotecas del lado del cliente

Las bibliotecas del lado del cliente proporcionan un mecanismo para organizar y administrar los archivos CSS y JavaScript necesarios para una implementación AEM.

Los componentes de AEM Screens se procesan de forma distinta en el modo de edición frente al modo de Previsualización/producción. Se crearán dos bibliotecas cliente, una para el modo de edición y otra para la Previsualización/producción.

Cree una carpeta para las bibliotecas del lado del cliente para el componente Hello World.

Debajo de /apps/weretail-run/components/content/helloworldcree una nueva carpeta con el nombre clientlibs.
Debajo de la carpeta clientlibs, cree un nuevo nodo denominado shared de tipo cq:ClientLibraryFolder.
Añada las siguientes propiedades en la biblioteca de cliente compartida:
- allowProxy | Booleano | true
- categories| Cadena[] | cq.screens.components
Propiedades para /apps/weretail-run/components/content/helloworld/clientlibs/shared

La propiedad categorías es una cadena que identifica la biblioteca del cliente. La categoría cq.screen.components se utiliza tanto en el modo de edición como en el modo de Previsualización/producción. Por lo tanto, cualquier CSS/JS definido en la clientlib compartida se carga en todos los modos.

Se recomienda no exponer nunca ninguna ruta directamente a /apps en un entorno de producción. La propiedad allowProxy garantiza que se haga referencia a CSS de la biblioteca del cliente y a JS mediante un prefijo of/etc.clientlibs.
Cree un archivo con el nombre css.txt debajo de la carpeta compartida.

Rellene el archivo con lo siguiente:
```
#base=css

styles.less
```
Cree una carpeta con el nombre css debajo de la carpeta shared. Añada un archivo denominado style.less debajo de la carpeta css. La estructura de las bibliotecas cliente ahora debería tener este aspecto:

En lugar de escribir CSS directamente, este tutorial utiliza MENOS. LESSes un precompilador de CSS popular que admite variables, mezclas y funciones de CSS. AEM bibliotecas cliente admiten de forma nativa la compilación LESS. Se pueden utilizar sass u otros precompiladores, pero es necesario compilarlos fuera de AEM.

Rellene /apps/weretail-run/components/content/helloworld/clientlibs/shared/css/styles.less con lo siguiente:

/**
    Shared Styles
   /apps/weretail-run/components/content/helloworld/clientlibs/shared/css/styles.less

**/

.cmp-hello-world {
    background-color: #fff;

 &__message {
  color: #000;
  font-family: Helvetica;
  text-align:center;
 }
}

Copie y pegue la carpeta de la biblioteca de cliente shared para crear una nueva biblioteca de cliente denominada production.

Copiar la biblioteca del cliente compartido para crear una nueva biblioteca del cliente de producción
Actualice la propiedad categories de la clientlibrary de producción para que sea cq.screens.components.production.

Esto garantiza que los estilos solo se carguen en el modo Previsualización/Producción.

Propiedades para /apps/weretail-run/components/content/helloworld/clientlibs/production

Rellene /apps/weretail-run/components/content/helloworld/clientlibs/production/css/styles.less con lo siguiente:

/**
    Production Styles
   /apps/weretail-run/components/content/helloworld/clientlibs/production/css/styles.less

**/
.cmp-hello-world {

    height: 100%;
    width: 100%;
    position: fixed;

 &__message {

  position: relative;
  font-size: 5rem;
  top:25%;
 }
}

Los estilos anteriores mostrarán el mensaje centrado en medio de la pantalla, pero solo en modo de producción.

Una tercera categoría clientlibrary: cq.screens.components.edit se puede utilizar para agregar estilos específicos de sólo edición al componente.

Categoría de Clientlib	Uso
`cq.screens.components`	Estilos y secuencias de comandos que se comparten entre los modos de edición y producción
`cq.screens.components.edit`	Estilos y secuencias de comandos que solo se utilizan en el modo de edición
`cq.screens.components.production`	Estilos y secuencias de comandos que solo se utilizan en el modo de producción

Crear una página de diseño

AEM Screens utiliza plantillas de página estáticas y configuraciones de diseño para los cambios globales. Las configuraciones de diseño se utilizan frecuentemente para configurar los componentes permitidos para Parsys en un canal. Se recomienda almacenar estas configuraciones de una forma específica para la aplicación.

Debajo se crea una página de diseño de ejecución We.Retail que almacenará todas las configuraciones específicas del proyecto de ejecución We.Retail.

En CRXDE-Lite http://localhost:4502/crx/de/index.jsp#/apps/settings/wcm/designs vaya a /apps/settings/wcm/designs
Cree un nuevo nodo debajo de la carpeta de diseños, denominado we-retail-run con un tipo de cq:Page.
Debajo de la página we-retail-run, agregue otro nodo denominado jcr:content de tipo nt:unstructured. Añada las siguientes propiedades en el nodo jcr:content:

Nombre Tipo Value

jcr:title Cadena Ejecución de We.Retail

sling:resourceType Cadena wcm/core/components/designer

cq:doctype Cadena html_5

Página de diseño en /apps/settings/wcm/designs/we-retail-run

Nombre	Tipo	Value
jcr:title	Cadena	Ejecución de We.Retail
sling:resourceType	Cadena	wcm/core/components/designer
cq:doctype	Cadena	html_5

Crear un Canal de secuencia

El componente Hello World está pensado para utilizarse en un Canal de secuencia. Para probar el componente, se crea un nuevo Canal de secuencia.

En el menú Inicio de AEM, vaya a Pantallas > We.Retail Ru n > y seleccione Canales.
Haga clic en el botón Crear
1. Elija Crear entidad
En el asistente Crear:
Paso de plantilla: elija Canal de secuencia
1. Paso de propiedades
- Ficha básica > Título = Canal inactivo
- Ficha canal > marcar Hacer canal en línea
Abra las propiedades de página del Canal Inactivo. Actualice el campo Diseño para que señale a /apps/settings/wcm/designs/we-retail-run,la página de diseño creada en la sección anterior.

Configuración de diseño que apunta a /apps/settings/wcm/designs/we-retail-run
Edite el Canal de inactividad recién creado para abrirlo.
Cambiar el modo de página al modo Diseño
1. Haga clic en el icono de la llave inglesa en Parsys para configurar los componentes permitidos
2. Seleccione el grupo Pantallas y el grupo Ejecución de We.Retail - Contenido.
Cambie el modo de página a Editar. El componente Hello World ahora se puede agregar a la página y combinarse con otros componentes de canal de secuencia.
En CRXDE-Lite http://localhost:4502/crx/de/index.jsp#/apps/settings/wcm/designs/we-retail-run/jcr%3Acontent/sequencechannel/par navegue a /apps/settings/wcm/designs/we-retail-run/jcr:content/sequencechannel/par. Observe que la propiedad components ahora incluye group:Screens, group:We.Retail Run - Content.

Configuración de diseño en /apps/settings/wcm/designs/we-retail-run

Plantilla para controladores personalizados

Si el componente personalizado utiliza recursos externos como recursos (imágenes, vídeos, fuentes, iconos, etc.), representaciones de recursos específicas o bibliotecas del lado del cliente (css, js, etc.), estos recursos no se agregan automáticamente a la configuración sin conexión, ya que solo empaquetamos el código HTML de forma predeterminada.

Con el fin de permitirle personalizar y optimizar los recursos exactos que se descargan en el reproductor, se oferta un mecanismo de extensión para los componentes personalizados para exponer sus dependencias a la lógica de almacenamiento en caché sin conexión en Pantallas.

La sección siguiente muestra la plantilla para los controladores de recursos sin conexión personalizados y los requisitos mínimos de pom.xml para ese proyecto específico.

package …;

import javax.annotation.Nonnull;

import org.apache.felix.scr.annotations.Component;
import org.apache.felix.scr.annotations.Reference;
import org.apache.felix.scr.annotations.Service;
import org.apache.sling.api.resource.Resource;
import org.apache.sling.api.resource.ResourceUtil;
import org.apache.sling.api.resource.ValueMap;

import com.adobe.cq.screens.visitor.OfflineResourceHandler;

@Service(value = OfflineResourceHandler.class)
@Component(immediate = true)
public class MyCustomHandler extends AbstractResourceHandler {

 @Reference
 private …; // OSGi services injection

 /**
  * The resource types that are handled by the handler.
  * @return the handled resource types
  */
 @Nonnull
 @Override
 public String[] getSupportedResourceTypes() {
     return new String[] { … };
 }

 /**
  * Accept the provided resource, visit and traverse it as needed.
  * @param resource The resource to accept
  */
 @Override
 public void accept(@Nonnull Resource resource) {
     ValueMap properties = ResourceUtil.getValueMap(resource);
     
     /* You can directly add explicit paths for offline caching using the `visit`
        method of the visitor. */
     
     // retrieve a custom property from the component
     String myCustomRenditionUrl = properties.get("myCustomRenditionUrl", String.class);
     // adding that exact asset/rendition/path to the offline manifest
     this.visitor.visit(myCustomRenditionUrl);
     
     
     /* You can delegate handling for dependent resources so they are also added to
        the offline cache using the `accept` method of the visitor. */
     
     // retrieve a referenced dependent resource
     String referencedResourcePath = properties.get("myOtherResource", String.class);
     ResourceResolver resolver = resource.getResourceResolver();
     Resource referencedResource = resolver.getResource(referencedResourcePath);
     // let the handler for that resource handle it
     if (referencedResource != null) {
         this.visitor.accept(referencedResource);
     }
   }
}

El siguiente código proporciona los requisitos mínimos de pom.xml para ese proyecto específico:

   <dependencies>
        …
        <!-- Felix annotations -->
        <dependency>
            <groupId>org.apache.felix</groupId>
            <artifactId>org.apache.felix.scr.annotations</artifactId>
            <version>1.9.0</version>
            <scope>provided</scope>
        </dependency>

        <!-- Screens core bundle with OfflineResourceHandler/AbstractResourceHandler -->
        <dependency>
            <groupId>com.adobe.cq.screens</groupId>
            <artifactId>com.adobe.cq.screens</artifactId>
            <version>1.5.90</version>
            <scope>provided</scope>
        </dependency>
        …
      </dependencies>

Colocando todo

El siguiente vídeo muestra el componente terminado y cómo se puede agregar a un canal de secuencia. A continuación, el Canal se agrega a la pantalla Ubicación y, finalmente, se asigna a un reproductor de Pantallas.

Código finalizado

A continuación se muestra el código terminado del tutorial. Los screens-weretail-run.ui.apps-0.0.1-SNAPSHOT.zip y screens-weretail-run.ui.content-0.0.1-SNAPSHOT.zip son los paquetes de AEM compilados. El SRC-screen-weretail-run-0.0.1.zip es el código fuente no compilado que se puede implementar con Maven.

Obtener archivo

Recursos en adobe.com

Multichannel Communication Ecommerce Integrations Auto Form Fill Managed Cloud Digital Rights Management Digital Signage