Componentes AEM: conceptos básicos

Cuando comience a desarrollar nuevos componentes, debe comprender los conceptos básicos de su estructura y configuración.

Este proceso implica leer la teoría y observar la amplia gama de implementaciones de componentes en una instancia de AEM estándar. Este último enfoque se complica ligeramente por el hecho de que, aunque AEM ha cambiado a una nueva interfaz de usuario estándar, moderna y con capacidad táctil, sigue siendo compatible con la IU clásica.

Información general

Esta sección trata los conceptos y problemas clave como una introducción a los detalles necesarios para desarrollar sus propios componentes.

Planificación

Antes de empezar a configurar o codificar realmente su componente, debe preguntar:

• ¿Qué necesita exactamente el nuevo componente para hacer?
  • Una especificación clara ayuda en todas las etapas de desarrollo, pruebas y entrega. Los detalles pueden cambiar con el tiempo, pero la especificación se puede actualizar (aunque también se deben documentar los cambios).
• ¿Necesita crear el componente desde cero o puede heredar los conceptos básicos de un componente existente?
  • No hay necesidad de reinventar la rueda.
  • AEM proporciona varios mecanismos que le permiten heredar y ampliar detalles de otra definición de componente, entre los que se incluyen la anulación, superposición y la fusión de recursos de Sling.
• ¿Necesitará lógica el componente para seleccionar o manipular el contenido?
  • La lógica debe mantenerse separada de la capa de la interfaz de usuario. HTL está diseñado para ayudar a garantizar que esto suceda.
• ¿Necesitará su componente el formato CSS?
  • El formato CSS debe mantenerse separado de las definiciones de componentes. Defina convenciones para asignar nombres a los elementos HTML de modo que pueda modificarlos a través de archivos CSS externos.
• ¿Qué aspectos de seguridad debo tener en cuenta?
  • Consulte Lista de comprobación de seguridad: prácticas recomendadas de desarrollo para obtener más información.

IU táctil frente a IU clásica

Antes de comenzar una conversación seria sobre el desarrollo de componentes, debe saber qué IU utilizarán sus autores:

• IU táctil
  La interfaz de usuario estándar se basa en la experiencia de usuario unificada de Adobe Marketing Cloud, que utiliza las tecnologías subyacentes de la IU de Coral y la IU de Granite.
• Interfaz
  UIUser clásica basada en la tecnología ExtJS obsoleta con AEM 6.4.

Consulte Interfaz de interfaz de usuario de Recommendations para clientes para obtener más información.

Se pueden implementar componentes para admitir la IU táctil, la IU clásica o ambas. Al consultar una instancia estándar, también verá los componentes integrados que se diseñaron originalmente para la IU clásica, la IU táctil o ambas.

Por este motivo, en esta página trataremos los aspectos básicos de ambos y cómo reconocerlos.

Lógica de contenido y marcado de renderización

Se recomienda mantener el código responsable del marcado y el procesamiento separado del código que controla la lógica utilizada para seleccionar el contenido del componente.

Esta filosofía es compatible con HTL, un lenguaje de plantilla limitado a propósito para garantizar que se utilice un lenguaje de programación real para definir la lógica empresarial subyacente. Esta lógica (opcional) se invoca desde HTL con un comando específico. Este mecanismo resalta el código que se llama para una vista determinada y, si es necesario, permite una lógica específica para diferentes vistas del mismo componente.

HTL frente a JSP

HTL es un lenguaje de plantilla HTML introducido con AEM 6.0.

La discusión sobre si usar HTL o JSP (páginas de servidor Java) al desarrollar sus propios componentes debería ser sencilla, ya que HTL es ahora el lenguaje de secuencias de comandos recomendado para AEM.

Tanto HTL como JSP pueden utilizarse para desarrollar componentes tanto para la IU clásica como para la táctil. Aunque puede haber una tendencia a suponer que HTL solo es para la IU táctil y JSP para la IU clásica, se trata de una idea errónea y más debido al tiempo. La IU táctil y HTL se incorporaron a AEM durante aproximadamente el mismo periodo. Dado que HTL es ahora el idioma recomendado, se utiliza para componentes nuevos, que tienden a ser para la IU táctil.

Desarrollo de sus propios componentes

Para crear sus propios componentes para la IU adecuada, consulte (después de leer esta página):

• Componentes AEM para la IU táctil
• Componentes AEM para la IU clásica

Una forma rápida de empezar es copiar un componente existente y luego realizar los cambios que desee. Para aprender a crear sus propios componentes y añadirlos al sistema de párrafos, consulte:

• Desarrollo de componentes (centrado en la IU táctil)

Mover componentes a la instancia de publicación

Los componentes que representan el contenido deben implementarse en la misma instancia de AEM que el contenido. Por lo tanto, todos los componentes que se utilizan para crear y procesar páginas en la instancia de autor deben implementarse en la instancia de publicación. Cuando se implementan, los componentes están disponibles para procesar páginas activadas.

Utilice las siguientes herramientas para mover los componentes a la instancia de publicación:

• Utilice Package Manager para añadir los componentes a un paquete y moverlos a otra instancia de AEM.
• Utilice la herramienta Activar replicación de árbol para replicar los componentes.

Componentes que se deben tener en cuenta desde el inicio

• Página:

  • AEM tiene el componente page ( cq:Page).
  • Es un tipo específico de recurso que es importante para la administración de contenido.
    • Una página corresponde a una página web que contiene contenido para su sitio web.

• Sistemas de párrafos:

  • El sistema de párrafos es una parte fundamental de un sitio web, ya que gestiona una lista de párrafos. Se utiliza para contener y estructurar los componentes individuales que contienen el contenido real.
  • Puede crear, mover, copiar y eliminar párrafos en el sistema de párrafos.
  • También puede seleccionar los componentes que estarán disponibles para su uso en un sistema de párrafos específico.
  • Hay varios sistemas de párrafos disponibles en una instancia estándar (por ejemplo parsys, [responsivegrid](/docs/experience-manager-65/sites-authoring/responsive-layout.html?lang=es)).

Estructura

La estructura de un componente AEM es potente y flexible, y las principales consideraciones son:

• Tipo de medio
• Definición de componentes
• Propiedades y nodos secundarios de un componente
• Cuadros de diálogo
• Cuadros de diálogo de diseño
• Disponibilidad de componentes
• Componentes y el contenido que crean

Tipo de medio

Un elemento clave de la estructura es el tipo de recurso.

• La estructura de contenido declara sus intenciones.
• El tipo de recurso los implementa.

Esta es una abstracción que ayuda a garantizar que, incluso cuando la apariencia cambie con el tiempo, la intención se mantenga en el tiempo.

Definición de componente

Conceptos básicos de componentes

La definición de un componente se puede desglosar de la siguiente manera:

• AEM componentes se basan en Sling.

• AEM componentes se encuentran (normalmente) en:

  • HTL: /libs/wcm/foundation/components
  • JSP: /libs/foundation/components

• Los componentes específicos del proyecto/sitio se encuentran (generalmente) en:

  • /apps/<myApp>/components

• AEM componentes estándar se definen como cq:Component y tienen los elementos clave:

  • propiedades de jcr:

    Una lista de las propiedades de jcr; son variables y algunas pueden ser opcionales a través de la estructura básica de un nodo de componente, sus propiedades y subnodos están definidos por la definición cq:Component

  • Medios:

    Definen los elementos estáticos utilizados por el componente.

  • Secuencias de comandos:

  Se utilizan para implementar el comportamiento de la instancia resultante del componente.

• Nodo raíz:

  • <mycomponent> (cq:Component) - Nodo de jerarquía del componente.

• Propiedades vitales:

  • jcr:title - Título del componente; por ejemplo, se utiliza como etiqueta cuando el componente se enumera en el navegador de componentes o en la barra de tareas.

  • jcr:description - Descripción del componente; se puede utilizar como indicio de pase de ratón en el navegador de componentes o la barra de tareas.

  • IU clásica:

    • icon.png - Icono para este componente.
    • thumbnail.png - Imagen mostrada si este componente aparece en la lista dentro del sistema de párrafos.

  • IU táctil

    • Consulte la sección Icono de componente en la interfaz de usuario táctil para obtener más información.

• Nodos secundarios vitales:

  • cq:editConfig (cq:EditConfig) : Define las propiedades de edición del componente y permite que el componente aparezca en el navegador de componentes o en la barra de tareas.

    Nota: si el componente tiene un cuadro de diálogo, aparecerá automáticamente en el explorador de componentes o en la barra de tareas, aunque cq:editConfig no exista.

  • cq:childEditConfig (cq:EditConfig) - Controla los aspectos de la interfaz de usuario del autor para los componentes secundarios que no definen los suyos propios cq:editConfig.

  • IU táctil:

    • cq:dialog ( nt:unstructured) - Cuadro de diálogo para este componente. Define la interfaz que permite al usuario configurar el componente o editar contenido.
    • cq:design_dialog ( nt:unstructured) - Edición de diseño para este componente

  • IU clásica:

    • dialog ( cq:Dialog) - Cuadro de diálogo para este componente. Define la interfaz que permite al usuario configurar el componente o editar contenido.
    • design_dialog ( cq:Dialog) - Edición de diseño para este componente.

Icono de componente en la interfaz de usuario táctil

El icono o la abreviatura del componente se definen mediante las propiedades JCR del componente cuando el desarrollador crea el componente. Estas propiedades se evalúan en el siguiente orden y se utiliza la primera propiedad válida encontrada.

1. cq:icon : propiedad de cadena que señala a un icono estándar en la biblioteca de Coral UI para mostrarlo en el navegador de componentes
   • Utilice el valor del atributo HTML del icono Coral.
2. abbreviation - Propiedad de cadena para personalizar la abreviatura del nombre del componente en el navegador de componentes
   • La abreviatura debe limitarse a dos caracteres.
   • Si se proporciona una cadena vacía, la abreviatura se genera a partir de los dos primeros caracteres de la propiedad jcr:title.
     • Por ejemplo, "Im" para "Image"
     • El título localizado se utilizará para crear la abreviatura.
   • La abreviación solo se traduce si el componente tiene una propiedad abbreviation_commentI18n, que luego se utiliza como indicio de traducción.
3. cq:icon.png o cq:icon.svg - Icono para este componente, que se muestra en el navegador de componentes
   • 20 x 20 píxeles es el tamaño de los iconos de los componentes estándar.
     • Los iconos más grandes se reducirán de tamaño (lado del cliente).
   • El color recomendado es rgb(112, 112, 112) > #707070
   • El fondo de los iconos de componente estándar es transparente.
   • Solo se admiten archivos .png y .svg.
   • Si se importa desde el sistema de archivos a través del complemento Eclipse, los nombres de archivo deben omitirse como _cq_icon.png o _cq_icon.svg, por ejemplo.
   • .png toma precedente .svg si ambos están presentes

Si no se encuentra ninguna de las propiedades anteriores ( cq:icon, abbreviation, cq:icon.png o cq:icon.svg) en el componente:

• El sistema buscará las mismas propiedades en los supercomponentes que siguen a la propiedad sling:resourceSuperType.
• Si no se encuentra nada o una abreviatura vacía en el nivel de supercomponente, el sistema creará la abreviatura a partir de las primeras letras de la propiedad jcr:title del componente actual.

Para cancelar la herencia de los iconos de los supercomponentes, si se configura una propiedad vacía abbreviation en el componente, se volverá al comportamiento predeterminado.

La Consola de componentes muestra cómo se define el icono de un componente en particular.

Ejemplo de icono SVG

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "https://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="https://www.w3.org/2000/svg" xmlns:xlink="https://www.w3.org/1999/xlink" x="0px" y="0px"
     width="20px" height="20px" viewBox="0 0 20 20" enable-background="new 0 0 20 20" xml:space="preserve">
    <ellipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/>
    <ellipse cx="15" cy="5" rx="4" ry="4" fill="#707070"/>
    <ellipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/>
    <ellipse cx="15" cy="15" rx="4" ry="4" fill="#707070"/>
</svg>

Propiedades y nodos secundarios de un componente

Muchos de los nodos o propiedades necesarios para definir un componente son comunes a ambas IU, con diferencias que permanecen independientes para que el componente pueda funcionar en ambos entornos.

Un componente es un nodo de tipo cq:Component y tiene las siguientes propiedades y nodos secundarios:

Si miramos el componente Texto (cualquiera de las versiones), podemos ver estos elementos:

• HTL ( /libs/wcm/foundation/components/text)

  

• JSP ( /libs/foundation/components/text)

  

Entre las propiedades de particular interés se incluyen:

• jcr:title - título del componente; esto se puede utilizar para identificar el componente; por ejemplo, aparece en la lista de componentes dentro del navegador de componentes o la barra de tareas
• jcr:description - descripción del componente; se puede utilizar como sugerencia de pase de ratón en la lista de componentes de la barra de tareas
• sling:resourceSuperType: esto indica la ruta de herencia al ampliar un componente (anulando una definición)

Los nodos secundarios de interés particular incluyen:

• cq:editConfig ( cq:EditConfig) - controla los aspectos visuales; por ejemplo, puede definir el aspecto de una barra o un widget, o agregar controles personalizados
• cq:childEditConfig ( cq:EditConfig) : controla los aspectos visuales de los componentes secundarios que no tienen sus propias definiciones
• IU táctil:
  • cq:dialog ( nt:unstructured): define el cuadro de diálogo para editar el contenido de este componente
  • cq:design_dialog ( nt:unstructured): especifica las opciones de edición de diseño de este componente
• IU clásica:
  • dialog ( cq:Dialog): define el cuadro de diálogo para editar el contenido de este componente (específico de la IU clásica)
  • design_dialog ( cq:Dialog): especifica las opciones de edición de diseño de este componente
  • icon.png - archivo gráfico que se utilizará como icono para el componente en la barra de tareas
  • thumbnail.png - archivo gráfico que se utilizará como miniatura del componente mientras lo arrastra desde la barra de tareas

Cuadros de diálogo

Los cuadros de diálogo son un elemento clave de su componente, ya que proporcionan una interfaz para que los autores configuren y proporcionen entradas para ese componente.

Dependiendo de la complejidad del componente, su cuadro de diálogo puede necesitar una o más fichas - para mantener el cuadro de diálogo corto y ordenar los campos de entrada.

Las definiciones de cuadro de diálogo son específicas de la IU:

• IU táctil

  • cq:dialog ( nt:unstructured) nodes:
    • definir el cuadro de diálogo para editar el contenido de este componente
    • específico de la IU táctil
    • se definen mediante los componentes de la interfaz de usuario de Granite
    • tienen una propiedad sling:resourceType como estructura de contenido estándar de Sling
    • puede tener una propiedad helpPath para definir el recurso de ayuda contextual (ruta absoluta o relativa) al que se accede cuando se muestra el icono Ayuda (el icono ? ).
      • Para los componentes listos para usar , a menudo hace referencia a una página de la documentación.
      • Si no se especifica helpPath, se muestra la dirección URL predeterminada (página de información general de la documentación).

  

  Dentro del cuadro de diálogo, se definen los campos individuales:

  

• IU clásica

  • dialog ( cq:Dialog) nodes
    • definir el cuadro de diálogo para editar el contenido de este componente
    • específico para la IU clásica
    • se definen con las utilidades de ExtJS
    • tienen una propiedad xtype, que hace referencia a ExtJS
    • puede tener una propiedad helpPath para definir el recurso de ayuda contextual (ruta absoluta o relativa) al que se accede cuando se selecciona el botón Ayuda.
      • Para los componentes listos para usar , a menudo hace referencia a una página de la documentación.
      • Si no se especifica helpPath, se muestra la dirección URL predeterminada (página de información general de la documentación).

  

  Dentro del cuadro de diálogo, se definen los campos individuales:

  

  Dentro de un cuadro de diálogo clásico:

  • puede crear el cuadro de diálogo como cq:Dialog, que proporcionará una sola pestaña, como en el componente de texto, o si necesita varias pestañas, como con el componente de textimage, el cuadro de diálogo se puede definir como cq:TabPanel.
  • se utiliza un cq:WidgetCollection ( items) para proporcionar una base para los campos de entrada ( cq:Widget) o para otras pestañas ( cq:Widget). Esta jerarquía se puede ampliar.

Diálogo de diseño

Los cuadros de diálogo de diseño son muy similares a los cuadros de diálogo utilizados para editar y configurar contenido, pero proporcionan la interfaz para que los autores configuren y proporcionen detalles de diseño para ese componente.

Los cuadros de diálogo de diseño están disponibles en el modo de diseño, aunque no son necesarios para todos los componentes, por ejemplo, ​​Título e ​​Imágenes, ambos tienen cuadros de diálogo de diseño, mientras que el texto no lo ​​hace.

El cuadro de diálogo de diseño para el sistema de párrafos (por ejemplo, parsys) es un caso especial, ya que permite al usuario seleccionar otros componentes específicos (desde el navegador de componentes o la barra de tareas) en la página.

Adición del componente al sistema de párrafos

Una vez definido un componente, debe estar disponible para su uso. Para que un componente esté disponible para su uso en un sistema de párrafos, puede:

1. Abra Design Mode para una página y habilite el componente requerido.

2. Agregue los componentes necesarios a la propiedad components de la definición de la plantilla en:

   /etc/designs/<*yourProject*>/jcr:content/<*yourTemplate*>/par

   Por ejemplo, consulte:

   /etc/designs/geometrixx/jcr:content/contentpage/par

   

Componentes y el contenido que crean

Si creamos y configuramos una instancia del componente Title en la página: <content-path>/Prototype.html

• IU táctil

  

• IU clásica

  

A continuación, podemos ver la estructura del contenido creado dentro del repositorio:

En particular, si observa el texto real de un Título:

• la definición (para ambas IU) tiene la propiedad name= ./jcr:title

  • /libs/foundation/components/title/cq:dialog/content/items/column/items/title
  • /libs/foundation/components/title/dialog/items/title

• dentro del contenido, esto genera la propiedad jcr:title que contiene el contenido del autor.

Las propiedades definidas dependen de las definiciones individuales. Aunque pueden ser más complejos que arriba, siguen los mismos principios básicos.

Jerarquía y herencia de componentes

Los componentes dentro de AEM están sujetos a tres jerarquías diferentes:

• Jerarquía de tipo de recurso

  Se utiliza para ampliar componentes con la propiedad sling:resourceSuperType. Esto permite que el componente herede. Por ejemplo, un componente de texto heredará varios atributos del componente estándar.

  • scripts (resueltos por Sling)
  • cuadros de diálogo
  • descripciones (incluidas imágenes en miniatura, iconos, etc.)

• Jerarquía de contenedores

  Se utiliza para rellenar los ajustes de configuración en el componente secundario y se utiliza más comúnmente en un escenario de parsys.

  Por ejemplo, los ajustes de configuración de los botones de la barra de edición, el diseño del conjunto de controles (barras de edición, desplazamiento) y el diseño del cuadro de diálogo (en línea, flotante) se pueden definir en el componente principal y propagarse a los componentes secundarios.

  Los ajustes de configuración (relacionados con la funcionalidad de edición) en cq:editConfig y cq:childEditConfig se propagan.

• Incluir jerarquía

  Esto se impone en tiempo de ejecución por la secuencia de inclusiones.

  Esta jerarquía la utiliza el Diseñador, que a su vez actúa como base para varios aspectos de diseño de la renderización; incluyendo información de diseño, información css, los componentes disponibles en un parsys, entre otros.

Editar comportamiento

En esta sección se explica cómo configurar el comportamiento de edición de un componente. Esto incluye atributos como acciones disponibles para el componente, características del editor in situ y 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 añadiendo un nodo cq:editConfig de tipo cq:EditConfig debajo del nodo del componente (de tipo cq:Component) y añadiendo propiedades específicas y nodos secundarios. Están disponibles las siguientes propiedades y nodos secundarios:

• cq:editConfig propiedades de nodo:

  • cq:actions ( String array): define las acciones que se pueden realizar en el componente.

  • cq:layout ( String): : define cómo se edita el componente en la IU clásica.

  • cq:dialogMode ( String): define cómo se abre el cuadro de diálogo del componente en la IU clásica

    • En la IU táctil, los cuadros de diálogo siempre flotan en modo de escritorio y se abren automáticamente como pantalla completa en dispositivos móviles.

  • cq:emptyText ( String): define el texto que se muestra cuando no hay contenido visual presente.

  • cq:inherit ( Boolean): define si los valores que faltan se heredan del componente del que se hereda.

  • dialogLayout (Cadena): define cómo se debe abrir el cuadro de diálogo.

• cq:editConfig nodos secundarios:

  • cq:dropTargets (tipo de nodo nt:unstructured): define una lista de destinos de colocación que pueden aceptar una colocación de un recurso del buscador de contenido

    • Los objetivos de colocación múltiple solo están disponibles en la IU clásica.
    • En la IU táctil se permite un solo destino de colocación.

  • cq:actionConfigs (tipo de nodo nt:unstructured): define una lista de nuevas acciones que se anexan a la lista cq:actions.

  • cq:formParameters (tipo de nodo nt:unstructured): define parámetros adicionales que se agregan al formulario de diálogo.

  • cq:inplaceEditing (tipo de nodo cq:InplaceEditingConfig): define una configuración de edición in situ para el componente.

  • cq:listeners (tipo de nodo cq:EditListenersConfig): define lo que sucede antes o después de que se produzca una acción en el componente.

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afteredit="REFRESH_PAGE"/>
</jcr:root>

Hay muchas configuraciones existentes en el repositorio. Puede buscar fácilmente propiedades específicas o nodos secundarios:

• Para buscar una propiedad del nodo cq:editConfig, p. ej. cq:actions, puede utilizar la herramienta Consulta en CRXDE Lite y buscar con la siguiente cadena de consulta XPath:

  //element(cq:editConfig, cq:EditConfig)[@cq:actions]

• Para buscar un nodo secundario de cq:editConfig, por ejemplo, puede buscar cq:dropTargets, que es de tipo cq:DropTargetConfig; puede utilizar la herramienta Consulta en CRXDE Lite y buscar con la siguiente cadena de consulta XPath:

  //element(cq:dropTargets, cq:DropTargetConfig)

Marcadores de posición de componente

Los componentes siempre deben representar algún HTML que sea visible para el autor, incluso cuando el componente no tenga contenido. De lo contrario, podría desaparecer visualmente de la interfaz del editor, haciendo que esté técnicamente presente pero invisible en la página y en el editor. En tal caso, los autores no podrán seleccionar ni interactuar con el componente vacío.

Por este motivo, los componentes deben representar un marcador de posición siempre que no muestren ningún resultado visible cuando la página se procese en el editor de páginas (cuando el modo WCM sea edit o preview).
El marcado HTML típico de un marcador de posición es el siguiente:

<div class="cq-placeholder" data-emptytext="Component Name"></div>

El script HTL típico que procesa el marcador de posición HTML anterior es el siguiente:

<div class="cq-placeholder" data-emptytext="${component.properties.jcr:title}"
     data-sly-test="${(wcmmode.edit || wcmmode.preview) && isEmpty}"></div>

En el ejemplo anterior, isEmpty es una variable que solo es verdadera cuando el componente no tiene contenido y es invisible para el autor.

Para evitar la repetición, Adobe recomienda que los implementadores de componentes utilicen una plantilla HTL para estos marcadores de posición, como la proporcionada por los componentes principales.

El uso de la plantilla en el vínculo anterior se realiza con la siguiente línea de HTL:

<sly data-sly-use.template="core/wcm/components/commons/v1/templates.html"
     data-sly-call="${template.placeholder @ isEmpty=!model.text}"></sly>

En el ejemplo anterior, model.text es la variable que solo tiene el valor "True" cuando el contenido tiene contenido y es visible.

Se puede ver un ejemplo de uso de esta plantilla en los componentes principales, como en el componente Título.

Configuración con propiedades cq:EditConfig

cq:actions

La propiedad cq:actions ( String array) define una o varias acciones que se pueden realizar en el componente. Los siguientes valores están disponibles para su configuración:

La configuración siguiente añade un botón de edición, un separador, una eliminación y un botón de inserción a la barra de edición de componentes:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit,-,delete,insert]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

La siguiente configuración agrega el texto "Configuraciones heredadas de la estructura base" a la barra de edición de componentes:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[text:Inherited Configurations from Base Framework]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig"/>

cq:layout (solo IU clásica)

La propiedad cq:layout ( String) define cómo se puede editar el componente en la IU clásica. Los valores disponibles son los siguientes:

La configuración siguiente añade un botón de edición a la barra de edición de componentes:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:dialogMode (solo IU clásica)

El componente se puede vincular a un cuadro de diálogo de edición. La propiedad cq:dialogMode ( String) define cómo se abrirá el cuadro de diálogo del componente en la IU clásica. Los valores disponibles son los siguientes:

La configuración siguiente define una barra de edición con un botón de edición y un cuadro de diálogo flotante:

<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
    cq:actions="[edit]"
    cq:dialogMode="floating"
    cq:layout="editbar"
    jcr:primaryType="cq:EditConfig">
</jcr:root>

cq:emptyText

La propiedad cq:emptyText ( String) define el texto que se muestra cuando no hay contenido visual presente. El valor predeterminado es: Drag components or assets here.

cq:inherit

La propiedad cq:inherit ( boolean) define si los valores que faltan se heredan del componente del que se hereda. Su valor predeterminado es false.

dialogLayout

La propiedad dialogLayout define cómo se debe abrir un cuadro de diálogo de forma predeterminada.

• Un valor de fullscreen abre el cuadro de diálogo en pantalla completa.
• Un valor vacío o ausencia de la propiedad toman el valor predeterminado de abrir el cuadro de diálogo normalmente.
• Tenga en cuenta que el usuario siempre puede alternar el modo de pantalla completa dentro del cuadro de diálogo.
• No se aplica a la IU clásica.

Configuración con nodos secundarios cq:EditConfig

cq:dropTargets

El nodo cq:dropTargets (tipo de nodo nt:unstructured) define una lista de destinos de colocación que pueden aceptar una colocación de un recurso arrastrado desde el buscador de contenido. Sirve como una colección de nodos de tipo cq:DropTargetConfig.

Cada nodo secundario de tipo cq:DropTargetConfig define un destino de colocación en el componente. El nombre del nodo es importante porque debe usarse en el JSP, como se indica a continuación, para generar el nombre de clase CSS asignado al elemento DOM que es el destino de colocación efectivo:

<drop target css class> = <drag and drop prefix> +
 <node name of the drop target in the edit configuration>

La <drag and drop prefix> está definida por la propiedad Java:

com.day.cq.wcm.api.components.DropTarget.CSS_CLASS_PREFIX.

Por ejemplo, el nombre de clase se define de la siguiente manera en el JSP del componente de descarga
( /libs/foundation/components/download/download.jsp), donde file es el nombre del nodo del destino de colocación en la configuración de edición del componente Descargar:

String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";

El nodo de tipo cq:DropTargetConfig debe tener las siguientes propiedades:

La siguiente configuración se toma del componente Descargar. Permite que cualquier recurso (el tipo mime puede ser cualquier cadena) del grupo media se coloque desde el buscador de contenido en el componente. Tras la colocación, se actualiza la propiedad fileReference del componente:

    <cq:dropTargets jcr:primaryType="nt:unstructured">
        <file
            jcr:primaryType="cq:DropTargetConfig"
            accept="[.*]"
            groups="[media]"
            propertyName="./fileReference"/>
    </cq:dropTargets>

cq:actionConfigs (solo IU clásica)

El nodo cq:actionConfigs (tipo de nodo nt:unstructured) define una lista de nuevas acciones que se adjuntan a la lista definida por la propiedad cq:actions. Cada nodo secundario de cq:actionConfigs define una nueva acción definiendo un widget.

La siguiente configuración de ejemplo define un nuevo botón (con un separador para la IU clásica):

• un separador, definido por xtype tbseparator;

  • Solo lo utiliza la IU clásica.
  • La IU táctil ignora esta definición, ya que se ignoran los xtype (y los separadores no son necesarios, ya que la barra de herramientas de acciones se construye de forma diferente en la IU táctil).

• un botón llamado Administrar comentarios que ejecuta la función de controlador CQ_collab_forum_openCollabAdmin().

<jcr:root 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"
    cq:actions="[EDIT,COPYMOVE,DELETE,INSERT]"
    jcr:primaryType="cq:EditConfig">
    <cq:actionConfigs jcr:primaryType="nt:unstructured">
        <separator0
            jcr:primaryType="nt:unstructured"
            xtype="tbseparator"/>
        <manage
            jcr:primaryType="nt:unstructured"
            handler="function(){CQ_collab_forum_openCollabAdmin();}"
            text="Manage comments"/>
    </cq:actionConfigs>
</jcr:root>

cq:formParameters

El nodo cq:formParameters (tipo de nodo nt:unstructured) define parámetros adicionales que se agregan al formulario de diálogo. Cada propiedad está asignada a un parámetro de formulario.

La siguiente configuración agrega un parámetro llamado name, configurado con el valor photos/primary al formulario de diálogo:

    <cq:formParameters
        jcr:primaryType="nt:unstructured"
        name="photos/primary"/>

cq:inplaceEditing

El nodo cq:inplaceEditing (tipo de nodo cq:InplaceEditingConfig) define una configuración de edición in situ para el componente. Puede tener las siguientes propiedades:

La siguiente configuración habilita la edición in situ del componente y define plaintext como el tipo de editor:

    <cq:inplaceEditing
        jcr:primaryType="cq:InplaceEditingConfig"
        active="{Boolean}true"
        editorType="plaintext"/>

cq:listeners

El nodo cq:listeners (tipo de nodo cq:EditListenersConfig) define lo que sucede antes o después de una acción en el componente. La tabla siguiente define sus posibles propiedades.

El controlador de eventos se puede implementar con una implementación personalizada. Por ejemplo (donde project.customerAction es un método estático):

afteredit = "project.customerAction"

El siguiente ejemplo equivale a la configuración REFRESH_INSERTED:

afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"

Con la siguiente configuración, la página se actualiza después de que el componente se haya eliminado, editado, insertado o movido:

    <cq:listeners
        jcr:primaryType="cq:EditListenersConfig"
        afterdelete="REFRESH_PAGE"
        afteredit="REFRESH_PAGE"
        afterinsert="REFRESH_PAGE"
        afterMove="REFRESH_PAGE"/>