Crear un componente personalizado

Obtenga información sobre cómo crear un componente personalizado para utilizarlo con el AEM SPA Editor. Aprenda a desarrollar cuadros de diálogo de autor y modelos de Sling para ampliar el modelo JSON y rellenar un componente personalizado.

Objetivo

  1. Comprenda el papel de los modelos Sling en la manipulación de la API del modelo JSON proporcionada por AEM.
  2. Obtenga información sobre cómo crear cuadros de diálogo de componentes de AEM.
  3. Aprenda a crear un custom AEM componente compatible con el marco del editor de SPA.

Qué va a generar

El objetivo de los capítulos anteriores era elaborar SPA componentes y asignarlos a existente AEM componentes principales. Este capítulo se centra en cómo crear y ampliar new AEM componentes y manipule el modelo JSON servido por AEM.

Una sencilla Custom Component ilustra los pasos necesarios para crear un componente de AEM nuevo.

Mensaje mostrado en Todas las mayúsculas

Requisitos previos

Revise las herramientas e instrucciones necesarias para configurar un entorno de desarrollo local.

Obtención del código

  1. Descargue el punto de partida para este tutorial mediante Git:

    $ git clone git@github.com:adobe/aem-guides-wknd-spa.git
    $ cd aem-guides-wknd-spa
    $ git checkout Angular/custom-component-start
    
  2. Implemente el código base en una instancia de AEM local mediante Maven:

    $ mvn clean install -PautoInstallSinglePackage
    

    Si usa AEM 6.x añada la variable classic perfil:

    $ mvn clean install -PautoInstallSinglePackage -Pclassic
    
  3. Instale el paquete terminado para el Sitio de referencia WKND. Las imágenes proporcionadas por Sitio de referencia WKND se reutilizan en la SPA WKND. El paquete se puede instalar mediante Administrador de paquetes AEM.

    Package Manager instalar wknd.all

Siempre puede ver el código terminado en GitHub o extraer el código localmente cambiando a la rama Angular/custom-component-solution.

Definir el componente AEM

Un componente AEM se define como un nodo y propiedades. En el proyecto, estos nodos y propiedades se representan como archivos XML en la variable ui.apps módulo. A continuación, cree el componente AEM en la ui.apps módulo.

  1. Abra el ui.apps en el IDE de su elección.

  2. Vaya a ui.apps/src/main/content/jcr_root/apps/wknd-spa-angular/components y crear una carpeta con el nombre custom-component.

  3. Crear un archivo con el nombre .content.xml debajo del custom-component carpeta. Rellene el custom-component/.content.xml con lo siguiente:

    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
        jcr:primaryType="cq:Component"
        jcr:title="Custom Component"
        componentGroup="WKND SPA Angular - Content"/>
    

    Crear definición de componente personalizado

    jcr:primaryType="cq:Component" : identifica que este nodo es un componente AEM.

    jcr:title es el valor que se muestra a los autores de contenido y la variable componentGroup determina la agrupación de componentes en la IU de creación.

  4. Debajo de la variable custom-component carpeta, cree otra carpeta denominada _cq_dialog.

  5. Debajo de la variable _cq_dialog carpeta crear un archivo con el nombre .content.xml y rellénelo de la siguiente manera:

    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:granite="http://www.adobe.com/jcr/granite/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
        jcr:primaryType="nt:unstructured"
        jcr:title="Custom Component"
        sling:resourceType="cq/gui/components/authoring/dialog">
        <content
            jcr:primaryType="nt:unstructured"
            sling:resourceType="granite/ui/components/coral/foundation/container">
            <items jcr:primaryType="nt:unstructured">
                <tabs
                    jcr:primaryType="nt:unstructured"
                    sling:resourceType="granite/ui/components/coral/foundation/tabs"
                    maximized="{Boolean}true">
                    <items jcr:primaryType="nt:unstructured">
                        <properties
                            jcr:primaryType="nt:unstructured"
                            jcr:title="Properties"
                            sling:resourceType="granite/ui/components/coral/foundation/container"
                            margin="{Boolean}true">
                            <items jcr:primaryType="nt:unstructured">
                                <columns
                                    jcr:primaryType="nt:unstructured"
                                    sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns"
                                    margin="{Boolean}true">
                                    <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="The text to display on the component."
                                                    fieldLabel="Message"
                                                    name="./message"/>
                                            </items>
                                        </column>
                                    </items>
                                </columns>
                            </items>
                        </properties>
                    </items>
                </tabs>
            </items>
        </content>
    </jcr:root>
    

    Definición de componente personalizado

    El archivo XML anterior genera un cuadro de diálogo sencillo para la variable Custom Component. La parte crítica del archivo es el <message> nodo . Este cuadro de diálogo contiene textfield named Message y conservan el valor del campo de texto en una propiedad denominada message.

    Se crea un modelo de Sling junto a para exponer el valor de la variable message a través del modelo JSON.

    NOTA

    Puede ver mucho más ejemplos de cuadros de diálogo consultando las definiciones de los componentes principales. También puede ver campos de formulario adicionales, como select, textarea, pathfield, disponible debajo de /libs/granite/ui/components/coral/foundation/form en CRXDE-Lite.

    Con un componente AEM tradicional, una HTL normalmente se requiere una secuencia de comandos. Dado que la SPA procesa el componente, no se necesita ningún script HTL.

Creación del modelo Sling

Los modelos Sling son "POJO" Java™ impulsados por anotaciones (objetos Java™ antiguos comunes) que facilitan la asignación de datos de las variables JCR a Java™. Modelos de Sling normalmente funcionan para encapsular una lógica empresarial compleja del lado del servidor para AEM componentes.

En el contexto del Editor de SPA, los modelos de Sling exponen el contenido de un componente a través del modelo JSON a través de una función que utiliza el Exportador de modelo Sling.

  1. En el IDE de su elección, abra el core módulo. CustomComponent.java y CustomComponentImpl.java ya se han creado y rellenado como parte del código de inicio de capítulo.

    NOTA

    Si utiliza Visual Studio Code IDE, puede ser útil instalar extensiones para Java™.

  2. Abra la interfaz de Java™ CustomComponent.java at core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/CustomComponent.java:

    Interfaz CustomComponent.java

    Esta es la interfaz de Java™ implementada por el modelo Sling.

  3. Actualizar CustomComponent.java para que se extienda el ComponentExporter interfaz:

    package com.adobe.aem.guides.wknd.spa.angular.core.models;
    import com.adobe.cq.export.json.ComponentExporter;
    
    public interface CustomComponent extends ComponentExporter {
    
        public String getMessage();
    
    }
    

    Implementación de ComponentExporter es un requisito para que la API del modelo JSON recopile automáticamente el modelo Sling.

    La variable CustomComponent la interfaz incluye un único método de captador getMessage(). Este es el método que expone el valor del cuadro de diálogo de autor a través del modelo JSON. Solo métodos get con parámetros vacíos () se exportan en el modelo JSON.

  4. Apertura CustomComponentImpl.java at core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/impl/CustomComponentImpl.java.

    Esta es la implementación de la variable CustomComponent interfaz. La variable @Model la anotación identifica la clase Java™ como modelo de Sling. La variable @Exporter la anotación permite serializar y exportar la clase Java™ a través del exportador del modelo Sling.

  5. Actualizar la variable estática RESOURCE_TYPE para señalar al componente AEM wknd-spa-angular/components/custom-component creada en el ejercicio anterior.

    static final String RESOURCE_TYPE = "wknd-spa-angular/components/custom-component";
    

    El tipo de recurso del componente es el que enlaza el modelo Sling al componente AEM y, en última instancia, se asigna al componente Angular.

  6. Agregue la variable getExportedType() para CustomComponentImpl para devolver el tipo de recurso de componente:

    @Override
    public String getExportedType() {
        return CustomComponentImpl.RESOURCE_TYPE;
    }
    

    Este método es necesario al implementar la variable ComponentExporter y expone el tipo de recurso que permite la asignación al componente de Angular.

  7. Actualice el getMessage() método para devolver el valor de la variable message propiedad que persiste en el cuadro de diálogo de autor. Utilice la variable @ValueMap la anotación está asignada al valor JCR message a una variable de Java™:

    import org.apache.commons.lang3.StringUtils;
    ...
    
    @ValueMapValue
    private String message;
    
    @Override
    public String getMessage() {
        return StringUtils.isNotBlank(message) ? message.toUpperCase() : null;
    }
    

    Se agrega algo de "lógica empresarial" adicional para devolver el valor del mensaje en mayúsculas. Esto nos permite ver la diferencia entre el valor sin procesar almacenado por el cuadro de diálogo de creación y el valor expuesto por el modelo Sling.

Actualizar el componente Angular

El código de Angular para el componente personalizado ya se ha creado. A continuación, realice algunas actualizaciones para asignar el componente de Angular al componente de AEM.

  1. En el ui.frontend abra el archivo ui.frontend/src/app/components/custom/custom.component.ts

  2. Observe el @Input() message: string; línea. Se espera que el valor en mayúsculas transformado se asigne a esta variable.

  3. Importe el MapTo del SDK de JS del Editor SPA de AEM y utilícelo para asignarlo al componente AEM:

    + import {MapTo} from '@adobe/cq-angular-editable-components';
    
     ...
     export class CustomComponent implements OnInit {
         ...
     }
    
    + MapTo('wknd-spa-angular/components/custom-component')(CustomComponent, CustomEditConfig);
    
  4. Apertura cutom.component.html y observe que el valor de {{message}} se muestra en el lado de un <h2> etiqueta.

  5. Apertura custom.component.css y agregue la siguiente regla:

    :host-context {
        display: block;
    }
    

    Para que el marcador de posición del Editor de AEM se muestre correctamente cuando el componente está vacío, la variable :host-context u otro <div> necesita configurarse como display: block;.

  6. Implemente las actualizaciones en un entorno de AEM local desde la raíz del directorio del proyecto, con sus habilidades con Maven:

    $ cd aem-guides-wknd-spa
    $ mvn clean install -PautoInstallSinglePackage
    

Actualizar la directiva de plantilla

A continuación, vaya a AEM para comprobar las actualizaciones y permitir que Custom Component para agregarlo al SPA.

  1. Verifique el registro del nuevo modelo Sling navegando hasta http://localhost:4502/system/console/status-slingmodels.

    com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl - wknd-spa-angular/components/custom-component
    
    com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl exports 'wknd-spa-angular/components/custom-component' with selector 'model' and extension '[Ljava.lang.String;@6fb4a693' with exporter 'jackson'
    

    Debería ver las dos líneas anteriores que indican la variable CustomComponentImpl está asociado con la variable wknd-spa-angular/components/custom-component y que está registrado a través del Sling Model Exporter.

  2. Vaya a la plantilla de página SPA en http://localhost:4502/editor.html/conf/wknd-spa-angular/settings/wcm/templates/spa-page-template/structure.html.

  3. Actualice la política del contenedor de diseño para agregar el nuevo Custom Component como componente permitido:

    Actualizar directiva de contenedor de diseño

    Guarde los cambios en la directiva y observe la Custom Component como componente permitido:

    Componente personalizado como componente permitido

Creación del componente personalizado

A continuación, cree el Custom Component uso del AEM SPA Editor.

  1. Vaya a http://localhost:4502/editor.html/content/wknd-spa-angular/us/en/home.html.

  2. En Edit , añada la variable Custom Component a Layout Container:

    Insertar nuevo componente

  3. Abra el cuadro de diálogo del componente e introduzca un mensaje que contenga letras minúsculas.

    Configurar el componente personalizado

    Este es el cuadro de diálogo que se creó en función del archivo XML anteriormente en el capítulo.

  4. Guarde los cambios. Observe que el mensaje mostrado está en mayúsculas.

    Mensaje mostrado en Todas las mayúsculas

  5. Para ver el modelo JSON, vaya a http://localhost:4502/content/wknd-spa-angular/us/en.model.json. Buscar wknd-spa-angular/components/custom-component:

    "custom_component_208183317": {
        "message": "HELLO WORLD",
        ":type": "wknd-spa-angular/components/custom-component"
    }
    

    Observe que el valor JSON se establece en todas las mayúsculas basándose en la lógica añadida al modelo Sling.

Felicitaciones!

Felicitaciones, ha aprendido a crear un componente de AEM personalizado y a cómo funcionan los modelos y diálogos de Sling con el modelo JSON.

Siempre puede ver el código terminado en GitHub o extraer el código localmente cambiando a la rama Angular/custom-component-solution.

Siguientes pasos

Ampliar un componente principal - Obtenga información sobre cómo ampliar un componente principal existente para utilizarlo con el AEM SPA Editor. Comprender cómo añadir propiedades y contenido a un componente existente es una técnica eficaz para expandir las capacidades de una implementación AEM Editor SPA.

En esta página