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.
El objetivo de los capítulos anteriores era desarrollar componentes SPA y asignarlos a componentes principales existentes AEM. Este capítulo se centrará en cómo crear y ampliar nuevos componentes de AEM y manipular el modelo JSON servido por AEM.
Un Custom Component
sencillo ilustra los pasos necesarios para crear un componente de AEM nuevo.
Revise las herramientas e instrucciones necesarias para configurar un entorno de desarrollo local.
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
Implemente el código base en una instancia de AEM local mediante Maven:
$ mvn clean install -PautoInstallSinglePackage
Si utiliza AEM 6.x, añada el perfil classic
:
$ mvn clean install -PautoInstallSinglePackage -Pclassic
Instale el paquete terminado para el sitio de referencia tradicional WKND. Las imágenes proporcionadas por WKND reference site se reutilizarán en la SPA WKND. El paquete se puede instalar utilizando AEM Package Manager.
Siempre puede ver el código terminado en GitHub o extraer el código localmente cambiando a la rama Angular/custom-component-solution
.
Un componente AEM se define como un nodo y propiedades. En el proyecto, estos nodos y propiedades se representan como archivos XML en el módulo ui.apps
. A continuación, cree el componente AEM en el módulo ui.apps
.
Puede resultar útil realizar un repaso rápido sobre los conceptos básicos de los componentes de AEM.
En el IDE de su elección, abra la carpeta ui.apps
.
Vaya a ui.apps/src/main/content/jcr_root/apps/wknd-spa-angular/components
y cree una nueva carpeta denominada custom-component
.
Cree un nuevo archivo con el nombre .content.xml
debajo de la carpeta custom-component
. Rellene 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"/>
jcr:primaryType="cq:Component"
: identifica que este nodo será un componente AEM.
jcr:title
es el valor que se muestra a los autores de contenido y componentGroup
determina la agrupación de componentes en la interfaz de usuario de creación.
Debajo de la carpeta custom-component
, cree otra carpeta denominada _cq_dialog
.
Debajo de la carpeta _cq_dialog
cree un nuevo archivo llamado .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>
El archivo XML anterior genera un cuadro de diálogo muy sencillo para Custom Component
. La parte crítica del archivo es el nodo <message>
interno. Este cuadro de diálogo contendrá un textfield
sencillo denominado Message
y persistirá el valor del campo de texto en una propiedad denominada message
.
Se creará un modelo de Sling junto a para exponer el valor de la propiedad message
a través del modelo JSON.
Puede ver muchos 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
, disponibles debajo de /libs/granite/ui/components/coral/foundation/form
en CRXDE-Lite.
Con un componente de AEM tradicional, normalmente se requiere un script HTL. Dado que el SPA procesará el componente, no se necesita ningún script HTL.
Los modelos Sling son objetos Java Java "POJO" (objetos Java antiguos comunes) impulsados por anotaciones que facilitan la asignación de datos de JCR a variables Java. Sling funciona de forma modesta 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 del modelo de Sling.
En el IDE de su elección, abra el módulo core
. CustomComponent.java
y ya se CustomComponentImpl.java
han creado y se han combinado como parte del código de inicio de capítulo.
Si utiliza Visual Studio Code IDE, puede resultar útil instalar extensiones para Java.
Abra la interfaz de Java CustomComponent.java
en core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/CustomComponent.java
:
Esta es la interfaz de Java que implementará el modelo Sling.
Actualice CustomComponent.java
para que amplíe la interfaz ComponentExporter
:
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();
}
La implementación de la interfaz ComponentExporter
es un requisito para que la API del modelo JSON recopile automáticamente el modelo Sling.
La interfaz CustomComponent
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. En el modelo JSON solo se exportan los métodos de captador con parámetros vacíos ()
.
Abra CustomComponentImpl.java
en core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/impl/CustomComponentImpl.java
.
Esta es la implementación de la interfaz CustomComponent
. La anotación @Model
identifica la clase Java como modelo de Sling. La anotación @Exporter
permite serializar y exportar la clase Java a través del Exportador del modelo Sling.
Actualice la variable estática RESOURCE_TYPE
para que apunte al componente de AEM wknd-spa-angular/components/custom-component
creado en el ejercicio anterior.
static final String RESOURCE_TYPE = "wknd-spa-angular/components/custom-component";
El tipo de recurso del componente es lo que enlazará el modelo de Sling con el componente AEM y, finalmente, se asignará al componente de Angular.
Agregue el método getExportedType()
a la clase 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 interfaz ComponentExporter
y expone el tipo de recurso que permite la asignación al componente de Angular.
Actualice el método getMessage()
para devolver el valor de la propiedad message
que persiste en el cuadro de diálogo de autor. Utilice la anotación @ValueMap
para asignar el valor JCR message
a una variable 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 permitirá 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.
Puede ver el CustomComponentImpl.java terminado aquí.
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.
En el módulo ui.frontend
abra el archivo ui.frontend/src/app/components/custom/custom.component.ts
Observe la línea @Input() message: string;
. Se espera que el valor en mayúsculas transformado se asigne a esta variable.
Importe el objeto 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);
Abra cutom.component.html
y observe que el valor de {{message}}
se mostrará en un lado de la etiqueta <h2>
.
Abra 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, es necesario establecer :host-context
u otro <div>
en display: block;
.
Implemente todas 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
A continuación, vaya a AEM para comprobar las actualizaciones y permitir que el Custom Component
se añada al SPA.
Compruebe el registro del nuevo modelo Sling navegando a 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 que CustomComponentImpl
está asociado con el componente wknd-spa-angular/components/custom-component
y que está registrado a través del Exportador del modelo Sling.
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.
Actualice la política del contenedor de diseño para agregar el nuevo Custom Component
como componente permitido:
Guarde los cambios en la directiva y observe el Custom Component
como un componente permitido:
A continuación, cree el Custom Component
con el AEM SPA Editor.
Vaya a http://localhost:4502/editor.html/content/wknd-spa-angular/us/en/home.html.
En el modo Edit
, agregue Custom Component
a Layout Container
:
Abra el cuadro de diálogo del componente e introduzca un mensaje que contenga letras minúsculas.
Este es el cuadro de diálogo que se creó en función del archivo XML anteriormente en el capítulo.
Guarde los cambios. Observe que el mensaje mostrado está en mayúsculas.
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, 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
.
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.