Show Menu
TEMAS×

Desarrollo de componentes de AEM

Los componentes de AEM se utilizan para mantener, dar formato y procesar el contenido disponible en las páginas web.
  • Al crear páginas , los componentes permiten a los autores editar y configurar el contenido.
    • Al construir un sitio de comercio , los componentes pueden, por ejemplo, recopilar y procesar información del catálogo. See Developing eCommerce for more information.
    • Al construir un sitio de Comunidades , los componentes pueden proporcionar información a sus visitantes y recopilarla. See Developing Communities for more information.
  • En la instancia de publicación, los componentes representan el contenido, presentándolo como se requiere a los visitantes del sitio web.
Esta página es una continuación de documento AEM Components - The Basics .
Los siguientes componentes /libs/cq/gui/components/authoring/dialog están pensados para utilizarse solo en el Editor (cuadros de diálogo de componentes en Creación). Si se utilizan en otro lugar (por ejemplo, en un cuadro de diálogo de asistente), es posible que no se comporten del modo esperado.

Ejemplos de código

Esta página proporciona la documentación de referencia (o vínculos a la documentación de referencia) necesaria para desarrollar nuevos componentes para AEM. Consulte Desarrollo de componentes de AEM: ejemplos de código para ver algunos ejemplos prácticos.

Estructura

La estructura básica de un componente se describe en la página Componentes de AEM: Conceptos básicos . Ese documento abarca tanto las IU táctiles como las clásicas. Aunque no necesite usar la configuración clásica en el nuevo componente, puede ser de ayuda que los conozca al heredar de componentes existentes.

Ampliación de los componentes y cuadros de diálogo existentes

Según el componente que desee implementar, puede que sea posible ampliar o personalizar una instancia existente, en lugar de definir y desarrollar toda la estructura desde cero.
Al ampliar o personalizar un componente o cuadro de diálogo existente, puede copiar o replicar toda la estructura o la estructura necesaria para el cuadro de diálogo antes de realizar los cambios.

Ampliación de un componente existente

La ampliación de un componente existente se puede lograr con la jerarquía de tipo de recurso y los mecanismos de herencia relacionados.
Los componentes también se pueden redefinir con una superposición basada en la lógica de ruta de búsqueda. Sin embargo, en este caso, la fusión de recursos Sling no se activará y /apps debe definir la superposición completa.
El componente de fragmento de contenido también se puede personalizar y ampliar, aunque se debe tener en cuenta la estructura completa y las relaciones con Recursos.

Personalización de un cuadro de diálogo de componente existente

También es posible anular un cuadro de diálogo de componente mediante la fusión de recursos de Sling y la definición de la propiedad sling:resourceSuperType .
Esto significa que solo necesita redefinir las diferencias necesarias, en lugar de redefinir todo el cuadro de diálogo (mediante sling:resourceSuperType ). Ahora se recomienda utilizar este método para ampliar un cuadro de diálogo de componentes
Consulte la Fusión de recursos de Sling para obtener más detalles.

Definición de la marca

El componente se procesará con HTML . El componente debe definir el HTML necesario para tomar el contenido necesario y, a continuación, procesarlo según sea necesario, tanto en el entorno de creación como en el de publicación.

Uso del lenguaje de plantilla HTML

The HTML Templating Language (HTL) , introduced with AEM 6.0, takes the place of JSP (JavaServer Pages) as the preferred and recommended server-side template system for HTML. Para los desarrolladores web que necesitan crear sitios web empresariales sólidos, HTL ayuda a lograr una mayor seguridad y eficiencia de desarrollo.
Aunque tanto HTL como JSP pueden utilizarse para desarrollar componentes, ilustraremos el desarrollo con HTL en esta página, ya que es el lenguaje de secuencias de comandos recomendado para AEM.

Desarrollo de la lógica de contenido

Esta lógica opcional selecciona o calcula el contenido que se va a representar. Se invoca desde expresiones HTL con el patrón de uso-API adecuado.
El mecanismo para separar la lógica de la apariencia ayuda a aclarar lo que se necesita para una vista determinada. También permite una lógica diferente para diferentes vistas del mismo recurso.

Uso de Java

La Use-API de HTL Java permite que un archivo HTL acceda a los métodos de ayuda en una clase Java personalizada. Esto le permite utilizar código Java para implementar la lógica de selección y configuración del contenido del componente.

Uso de JavaScript

La Use-API de JavaScript de HTL permite que un archivo HTL acceda al código de ayuda escrito en JavaScript . Esto le permite utilizar código JavaScript para implementar la lógica de selección y configuración del contenido del componente.

Uso de bibliotecas HTML del lado del cliente

Los sitios web modernos dependen en gran medida del procesamiento del lado del cliente impulsado por código CSS y JavaScript complejo. Organizar y optimizar el servicio de este código puede ser un problema complicado.
Para ayudarle a solucionar este problema, AEM proporciona carpetas de biblioteca del lado del cliente, que le permiten almacenar el código del lado del cliente en el repositorio, organizarlo en categorías y definir cuándo y cómo se debe proporcionar cada categoría de código al cliente. El sistema de biblioteca del cliente se encarga de producir los vínculos correctos en la página web final para cargar el código correcto.
Lea Uso de bibliotecas HTML del lado del cliente para obtener más información.

Configuración del comportamiento de edición

Puede configurar el comportamiento de edición de un componente, incluyendo atributos como acciones disponibles para el componente, características del editor in-situ y los oyentes relacionados con eventos en el componente. La configuración es común a la IU táctil y a la clásica, aunque con ciertas diferencias específicas.
El comportamiento de edición de un componente se configura agregando un cq:editConfig nodo de tipo cq:EditConfig debajo del nodo del componente (de tipo cq:Component ) y agregando propiedades y nodos secundarios específicos.

Configuración del comportamiento de la Previsualización

La cookie de modo WCMMode.html WCM se establece al cambiar al modo de Previsualización aunque la página no se actualice.
Para los componentes con una representación sensible al modo WCM, deben definirse para actualizarse específicamente y, a continuación, basarse en el valor de la cookie.
En la IU táctil solo se utilizan los valores EDIT y PREVIEW para la cookie de modo WCMMode.html WCM.

Creación y configuración de un cuadro de diálogo

Los cuadros de diálogo se utilizan para permitir que el autor interactúe con el componente. El uso de un cuadro de diálogo permite a los autores y/o administradores editar contenido, configurar el componente o definir parámetros de diseño (mediante un cuadro de diálogo de diseño)

IU de Coral y Granite

La interfaz de usuario de Coral y la interfaz de usuario de Granite definen el aspecto moderno de AEM.
La interfaz de usuario de Granite proporciona una amplia gama de componentes básicos (widgets) necesarios para crear el cuadro de diálogo en el entorno de creación. Cuando sea necesario, puede ampliar esta selección y crear su propia utilidad .
Para obtener más información sobre el desarrollo de componentes mediante tipos de recursos de Coral y Granite, consulte: Generación de componentes de Experience Manager mediante tipos de recursos de Coral/Granite.
Para obtener más información, consulte:
Debido a la naturaleza de los componentes de la interfaz de usuario Granite (y a las diferencias con los widgets ExtJS), hay algunas diferencias entre la forma en que los componentes interactúan con la interfaz de usuario táctil y la IU Desarrollo de componentes de AEM (IU clásica) clásica.

Creating a New Dialog

Cuadros de diálogo para la IU táctil:
  • se denominan cq:dialog .
  • se definen como un nt:unstructured nodo con el conjunto de sling:resourceType propiedades.
  • se encuentran bajo su cq:Component nodo y junto a su definición de componente.
  • se procesan en el servidor (como componentes Sling), según la estructura de contenido y la sling:resourceType propiedad.
  • utilice la interfaz de usuario Granite.
  • contiene una estructura de nodos que describe los campos del cuadro de diálogo.
    • estos nodos están nt:unstructured con la sling:resourceType propiedad requerida.
Una estructura de nodos de ejemplo puede ser:
newComponent (cq:Component)
  cq:dialog (nt:unstructured)
    content
      layout
      items
        column
          items
            file
            description

La personalización de un cuadro de diálogo es similar al desarrollo de un componente, ya que el cuadro de diálogo es un componente (es decir, el marcado procesado por un script de componente junto con el comportamiento o estilo proporcionado por una biblioteca de cliente).
Para ver ejemplos, consulte:
  • /libs/foundation/components/text/cq:dialog
  • /libs/foundation/components/download/cq:dialog
Si un componente no tiene ningún cuadro de diálogo definido para la IU táctil, el cuadro de diálogo de la IU clásica se utiliza como alternativa dentro de una capa de compatibilidad. Para personalizar este cuadro de diálogo, debe personalizar el cuadro de diálogo de IU clásica. Consulte Componentes de AEM para la IU clásica.

Personalización de los campos del cuadro de diálogo

Consulte:

Creating a New Field

Las utilidades de la interfaz de usuario táctil se implementan como componentes de la interfaz de usuario de Granite.
Para crear una nueva utilidad para utilizarla en un cuadro de diálogo de componentes para la IU táctil, es necesario crear un nuevo componente de campo de la interfaz de usuario de Granite.
Para obtener más información sobre la interfaz de usuario de Granite, consulte la documentación de la interfaz de usuario de Granite.
Si considera el cuadro de diálogo como un contenedor sencillo para un elemento de formulario, también puede ver el contenido principal del cuadro de diálogo como campos de formulario. La creación de un nuevo campo de formulario requiere la creación de un tipo de recurso; esto equivale a crear un componente nuevo. Para ayudarle en esa tarea, la interfaz de usuario de Granite oferta un componente de campo genérico del que heredar (mediante sling:resourceSuperType ):
/libs/granite/ui/components/coral/foundation/form/field
Más específicamente, la interfaz de usuario de Granite proporciona una serie de componentes de campo que se pueden utilizar en los diálogos (o, más generalmente, en formularios ).
Esto difiere de la IU clásica, en la que los widgets se representan mediante cq:Widgets nodos, cada uno con un xtype objeto concreto de establecer la relación con el widget ExtJS correspondiente. Desde el punto de vista de la implementación, estos widgets se procesaron en el lado del cliente mediante el marco de trabajo de ExtJS.
Una vez creado el tipo de recurso, puede crear una instancia del campo agregando un nuevo nodo en el cuadro de diálogo, con la propiedad sling:resourceType que hace referencia al tipo de recurso que acaba de introducir.

Creación de una biblioteca de clientes para estilo y comportamiento

Si desea definir el estilo y el comportamiento de su componente, puede crear una biblioteca de cliente dedicada que defina su CSS/LESS y JS personalizados.
Para que la biblioteca de cliente se cargue únicamente para el cuadro de diálogo de componentes (es decir, no se cargará para otro componente), debe establecer la propiedad extraClientlibs * del cuadro de diálogo en el nombre de categoría de la biblioteca de cliente que acaba de crear. Esto es aconsejable si la biblioteca del cliente es bastante grande y/o si el campo es específico de ese cuadro de diálogo y no será necesario en otros cuadros de diálogo.
Para que la biblioteca de cliente se cargue en todos los cuadros de diálogo, establezca la propiedad de categoría de la biblioteca de cliente en cq.authoring.dialog . Es el nombre de la categoría de la biblioteca del cliente que se incluye de forma predeterminada al procesar todos los cuadros de diálogo. Desea hacerlo si la biblioteca de cliente es pequeña o si el campo es genérico y puede reutilizarse en otros cuadros de diálogo.
Para ver un ejemplo, consulte:
  • cqgems/customizingfield/components/colorpicker/clientlibs
    • proporcionado por la muestra de código

Ampliación (heredado) de un campo

Según sus necesidades, puede:
  • Extender un campo de la interfaz de usuario de Granite determinado por herencia de componentes ( sling:resourceSuperType )
  • Extender un widget determinado desde la biblioteca de utilidades subyacente (en el caso de la interfaz de usuario de Granite, es Coral UI), siguiendo la API de la biblioteca de utilidades (herencia de JS/CSS)

Acceso a los campos del cuadro de diálogo

También puede utilizar las condiciones de procesamiento ( rendercondition ) para controlar quién tiene acceso a fichas o campos específicos en el cuadro de diálogo; por ejemplo:
+ mybutton
  - sling:resourceType = granite/ui/components/coral/foundation/button
  + rendercondition
    - sling:resourceType = myapp/components/renderconditions/group
    - groups = ["administrators"]

Gestión de Eventos de campo

El método de gestión de eventos en campos de diálogo ahora se realiza con oyentes en una biblioteca cliente personalizada. Esto supone un cambio con respecto al método anterior de tener oyentes en la estructura de contenido.

Oyentes en una biblioteca de clientes personalizada

Para insertar lógica en el campo, debe:
  1. Marque el campo con una clase CSS determinada (el gancho ).
  2. Defina, en la biblioteca de cliente, un detector JS conectado al nombre de la clase CSS (esto garantiza que la lógica personalizada solo se alcance en el campo y no afecta a otros campos del mismo tipo).
Para lograrlo, debe conocer la biblioteca de utilidades subyacente con la que desea interactuar. Consulte la documentación de la interfaz de usuario de Coral para identificar a qué evento desea reaccionar. Esto es muy similar al proceso que tenía que realizar con ExtJS en el pasado: busque la página de documentación de una utilidad determinada y, a continuación, compruebe los detalles de su API de evento.
Para ver un ejemplo, consulte:
  • cqgems/customizingfield/components/clientlibs/customizingfield
    • proporcionado por la muestra de código

Oyentes en la estructura de contenido

En la IU clásica con ExtJS, era habitual tener oyentes para una utilidad determinada en la estructura de contenido. Lograr lo mismo en la IU táctil es diferente ya que el código de escucha de JS (o cualquier código) ya no se define en el contenido.
La estructura de contenido describe la estructura semántica; no debe implicar la naturaleza del widget subyacente. Al no tener el código JS en la estructura de contenido, puede cambiar los detalles de implementación sin tener que cambiar la estructura de contenido. En otras palabras, puede cambiar la biblioteca de utilidades sin necesidad de tocar la estructura de contenido.

Validación de campos

Campo obligatorio

Para marcar un campo determinado como obligatorio, establezca la siguiente propiedad en el nodo de contenido del campo:
  • Nombre: required
  • Tipo: Boolean
Para ver un ejemplo, consulte:
/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title

Validación de campos (IU granítica)

La validación de campos en la interfaz de usuario de Granite y los componentes de la interfaz de usuario de Granite (equivalentes a widgets) se realiza mediante la foundation-validation API. Consulte la documentación de
Para ver ejemplos, consulte:
  • cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js
    • proporcionado por la muestra de código
  • /libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js

Creación y configuración de un cuadro de diálogo de diseño

El cuadro de diálogo Diseño se muestra cuando un componente tiene detalles de diseño que se pueden editar en el modo Configurar componentes en modo Diseño Diseño.
La definición es muy similar a la de un cuadro de diálogo utilizado para editar contenido , con la diferencia de que se define como nodo:
  • Node name: cq:design_dialog
  • Tipo: nt:unstructured

Creación y configuración de un editor en contexto

Un editor in-situ permite al usuario editar contenido directamente en el flujo de párrafos, sin necesidad de abrir un cuadro de diálogo. Por ejemplo, los componentes estándar Texto y Título tienen un editor in situ.
Un editor in situ no es necesario ni significativo para cada tipo de componente.
Consulte Ampliación de la creación de páginas: Añadir nuevo editor de entrada para obtener más información.

Personalización de la barra de herramientas del componente

La barra de herramientas de componentes proporciona al usuario acceso a una serie de acciones para el componente, como editar, configurar, copiar y eliminar.

Configuración de un componente para el carril de referencias (prestado/alquilado)

Si el nuevo componente hace referencia a contenido de otras páginas, puede considerar si desea que afecte a las secciones Contenido ​prestado y Contenido de Cuartos de referencias del raíl.
AEM incorporado solo comprueba el componente Referencia. Para agregar el componente, debe configurar la configuración de referencia de contenido de creación WCM del paquete OSGi.
Cree una nueva entrada en la definición, especificando el componente, junto con la propiedad que se va a comprobar. Por ejemplo:
/apps/<*your-Project*>/components/reference@parentPath
When working with AEM there are several methods of managing the configuration settings for such services. See Configuring OSGi for more details and the recommended practices.

Habilitar y Añadir el componente en el sistema de párrafos

Una vez desarrollado el componente, debe habilitarse para su uso en un sistema de párrafos adecuado, de modo que pueda utilizarse en las páginas requeridas.
Esto se puede realizar mediante:

Configuring a Paragraph System so that Dragging an Asset Creates a Component Instance

AEM oferta la posibilidad de configurar un sistema de párrafos en la página para que una instancia del nuevo componente se cree automáticamente cuando un usuario arrastra un recurso (adecuado) a una instancia de esa página (en lugar de arrastrar siempre un componente vacío a la página).
Se puede configurar este comportamiento y la relación entre los recursos y los componentes necesaria:
  1. Bajo la definición de párrafo del diseño de página. Por ejemplo:
    • /etc/designs/<myApp>/page/par
    Crear un nuevo nodo:
    • Nombre: cq:authoring
    • Tipo: nt:unstructured
  2. En este campo, cree un nuevo nodo para albergar todas las asignaciones de recursos a componentes:
    • Nombre: assetToComponentMapping
    • Tipo: nt:unstructured
  3. Para cada asignación de recursos a componentes, cree un nodo:
    • Nombre: texto; se recomienda que el nombre indique el recurso y el tipo de componente relacionado; por ejemplo, image
    • Tipo: nt:unstructured
    Cada una con las siguientes propiedades:
    • assetGroup :
      • Tipo: String
      • Valor: el grupo al que pertenece el activo relacionado; por ejemplo, media
    • assetMimetype :
      • Tipo: String
      • Valor: el tipo MIME del activo correspondiente; por ejemplo image/*
    • droptarget :
      • Tipo: String
      • Valor: el destinatario de caída; por ejemplo, image
    • resourceType :
      • Tipo: String
      • Valor: el recurso de componente relacionado; por ejemplo, foundation/components/image
    • type :
      • Tipo: String
      • Valor: el tipo, por ejemplo, Images
Para ver ejemplos, consulte:
  • /etc/designs/geometrixx/jcr:content/page/par/cq:authoring
  • /etc/designs/geometrixx-outdoors/jcr:content/page/par/cq:authoring
  • /etc/designs/geometrixx-media/jcr:content/article/article-content-par/cq:authoring
CÓDIGO DE GITHUB
Puede encontrar el código de esta página en GitHub
La creación automática de instancias de componentes ahora se puede configurar fácilmente en la interfaz de usuario al utilizar componentes principales y plantillas editables. Consulte Creación de plantillas de página para obtener más información sobre cómo definir qué componentes se asocian automáticamente a determinados tipos de medios.

Uso de la extensión de corchetes AEM

La extensión AEM Bracks proporciona un flujo de trabajo sencillo para editar componentes de AEM y bibliotecas de clientes. Se basa en el editor de código Corchetes .
La extensión:
  • Facilita la sincronización (no se requiere Maven ni File Vault) para ayudar a aumentar la eficacia del desarrollador y también ayuda a los desarrolladores de front-end con conocimientos limitados de AEM a participar en los proyectos.
  • Proporciona cierta compatibilidad con HTL , el lenguaje de plantilla diseñado para simplificar el desarrollo de componentes y aumentar la seguridad.
Los corchetes son el mecanismo recomendado para crear componentes. Sustituye a la funcionalidad CRXDE Lite - Crear componente, diseñada para la IU clásica.

Migración desde un componente clásico

Al migrar un componente diseñado para su uso con la IU clásica a un componente que se pueda utilizar con la IU táctil (exclusiva o conjuntamente), se deben tener en cuenta los siguientes problemas:
  • HTL
    • El uso de HTL no es obligatorio, pero si su componente necesita actualizarse, entonces es el momento ideal para considerar la migración de JSP a HTL .
  • Componentes
    • Migrar código que utiliza funciones específicas de la IU clásica
    • RTE, para obtener más información, consulte Configuración del editor de texto enriquecido.
    • Migrar que utiliza funciones específicas de la IU clásica
  • Cuadros de diálogo
    • Deberá crear un nuevo cuadro de diálogo para utilizarlo en la IU táctil. Sin embargo, por motivos de compatibilidad, la IU táctil puede utilizar la definición de un cuadro de diálogo de IU clásica cuando no se ha definido ningún cuadro de diálogo para la IU táctil.
    • La herramienta de conversión de cuadro de diálogo se proporciona para ayudarle a ampliar los componentes existentes.
    • La asignación de ExtJS a los componentes de la interfaz de usuario de Granite proporciona una visión general práctica de los xtypes y tipos de nodo de ExtJS con sus tipos de recursos de la interfaz de usuario de Granite equivalentes.
    • Personalización de campos, para obtener más información, consulte la sesión de AEM Gems sobre la personalización de campos de cuadro de diálogo.
    • Migración de tipos a la validación Granite UI
    • Con los oyentes JS, para obtener más información, consulte Gestión de Eventos de campo y la sesión de AEM Gems sobre la personalización de campos de cuadro de diálogo.

Migración de código cq:listener

Si está migrando un proyecto diseñado para la IU clásica, el cq:listener código (y los clientes relacionados con componentes) pueden utilizar funciones específicas de la IU clásica (como CQ.wcm.* ). Para la migración, debe actualizar dicho código con los objetos o funciones equivalentes de la IU táctil.
Si el proyecto se está migrando completamente a la IU táctil, debe reemplazar dicho código para utilizar los objetos y funciones relevantes para la IU táctil.
Sin embargo, si el proyecto debe ocuparse tanto de la IU clásica como de la táctil durante el período de migración (el escenario habitual), deberá implementar un conmutador para diferenciar el código independiente que hace referencia a los objetos correspondientes.
Este mecanismo de cambio se puede implementar de la siguiente manera:
if (Granite.author) {
    // touch UI
} else {
    // classic UI
}

Documentar el componente

Como desarrollador, desea acceder fácilmente a la documentación de componentes para que pueda comprender rápidamente:
  • Descripción
  • Uso previsto
  • Estructura y propiedades del contenido
  • API y puntos de extensión expuestos
  • Etc.
Por este motivo, es bastante fácil hacer que cualquier marca de documentación existente que tenga disponible dentro del propio componente.
Todo lo que necesita es colocar un README.md archivo en la estructura de componentes. Esta marca se mostrará en la consola de componentes.
La marca admitida es la misma que la de los fragmentos de contenido.