Asignación de componentes para AEM Sites

El artículo habla sobre los distintos aspectos de la asignación de componentes para sitios de AEM (mediante la asignación de componentes compuestos).

Reglas de asignación de componentes

Utilice una matriz de reglas JSON (su componentmapping.json) para convertir HTML en componentes. Mantenga las reglas tan simples, explícitas y específicas como sea posible.

Oriente el elemento HTML y su clase

Al definir los elementos anteriores, asegúrese de lo siguiente:

Utilice attributeMap para guardar las propiedades en el nodo JCR

Agregue entradas a attributeMap para establecer propiedades en el nodo de salida. Cada entrada genera attrs[to] = value.
Patrones comunes:

// copy an attribute
{ "attribute": "src", "to": "image-src" }
// read content or tag name
{ "from": "textContent", "to": "jcr:title" }
{ "from": "outerHTML",  "to": "text" }
{ "from": "innerHTML",  "to": "text" }
{ "from": "name",       "to": "type" }  // the tag name, e.g., "h2"
// constant value
{ "value": true, "to": "textIsRich" }

A continuación se muestra un ejemplo de HTML a JSON para un elemento de imagen.

<img src="/content/dam/aemg-docs/tragopan.svg" class="cmp-image__image" itemprop="contentUrl" data-cmp-hook-image="image" alt="">

{
    "name": "img",
    "resourceType": "core/wcm/components/image/v2/image",
    "attributeMap": [
      {
        "from": "src",
        "to": "fileReference"
      },
      {
        "value": ["fileReference"],
        "to": "path-attributes"
      }
    ]
  }

Normalizar rutas mediante una entrada dedicada

Si desea normalizar valores (convertir en absolutos), declare qué claves de atributo deben normalizarse utilizando:

{
  "value": ["text"],
  "to": "path-attributes"
}

Asegúrese de tener en cuenta los siguientes puntos importantes:

Extraer valores de HTML antes de dividirlos en componentes

Use from para especificar cómo leer un valor del elemento antes de que el documento se divida en componentes independientes:

Ejemplos:

{ "from": "textContent", "to": "jcr:title" }
{ "from": "outerHTML",  "to": "text" }
{ "from": "innerHTML",  "to": "snippet" }
{ "from": "src",        "to": "image#src" }

Ejemplo mínimo de extremo a extremo en componentmapping.json

[
  {
    "name": "h1, h2",
    "class": "topic-title",
    "resourceType": "core/wcm/components/title/v2/title",
    "attributeMap": [
      { "from": "textContent", "to": "text" },
      { "from": "name",        "to": "type" }
    ]
  },
  {
    "name": "img",
    "class": "hero",
    "resourceType": "weretail/components/content/heroimage",
    "attributeMap": [
      { "from": "src", "to": "image#src" },
      { "value": ["image#src"], "to": "path-attributes" }
    ]
  },
  {
    "name": "#element",
    "resourceType": "core/wcm/components/text/v2/text",
    "attributeMap": [
      { "from": "outerHTML", "to": "text" },
      { "value": true,        "to": "textIsRich" }
    ]
  }
]

Defina el elemento y la clase a los que se va a dirigir, use attributeMap para establecer las propiedades del nodo, agregue una entrada path-attributes para normalizar las rutas y elija el from correcto para los valores que desee extraer. El(la) heroimage utilizado(a) arriba es un componente en un sitio we-retail.

Nota: Es importante analizar el texto enriquecido predeterminado e identificar los elementos para los que se utiliza.

Crear un componente personalizado

Aprenda a crear un componente de tabla personalizado que muestre imágenes dentro de sus celdas. Este enfoque garantiza un diseño limpio y reutilizable para el contenido dinámico. Abarca lo que va a crear, por qué es eficaz, los requisitos previos clave, el diseño de alto nivel, etc.

Lo que va a generar

Componente de tabla personalizado que acepta contenido de tabla de HTML y reemplaza cada <img> dentro de él con la salida del componente de imagen principal de AEM. Esto le permite reutilizar las funciones de la imagen principal (imágenes adaptables, control alternativo, accesibilidad) mientras mantiene un control total sobre el marcado de la tabla.
Con este método, puede crear otros componentes personalizados para su sitio web de AEM (mediante la asignación de componentes compuestos).

Por qué este enfoque

Requisitos previos

Diseño de alto nivel

La tabla se genera una vez, y ya contiene el marcado de la imagen principal. No es necesaria ninguna manipulación DOM del lado del cliente.

Estructura de carpetas y archivos de claves (en este repositorio)

Pasos de la implementación

Defina el componente Tabla (nodo de componente)

Cree el componente en apps/guides-components/components/table. Si todavía no tiene uno, agregue un mínimo de .content.xml como el que se muestra a continuación para registrarlo en el panel lateral.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0"
          xmlns:jcr="http://www.jcp.org/jcr/1.0"
          jcr:primaryType="cq:Component"
          jcr:title="Table"
          componentGroup="Guides - Custom"/>

Indica a AEM que este es un componente disponible para que los autores lo agreguen a las páginas.

Procesar con HTL e incluir estilos

Utilice un modelo Sling y envíe el HTML procesado. Incluya la categoría clientlib para CSS/JS.

<sly data-sly-use.model="com.adobe.guides.aem.components.core.models.TableModel"
     data-sly-use.clientLib="/libs/granite/sightly/templates/clientlib.html">
</sly>
<sly data-sly-call="${clientLib.css @ categories='guides-components.table'}"></sly>
<sly data-sly-test="${wcmmode.edit && !model.hasContent}">
  <div class="cq-placeholder" data-emptytext="${component.title}"></div>
</sly>
<div data-sly-test="${model.hasContent}"
     class="gu-table-wrapper ${model.enableResponsive ? 'gu-table--responsive' : ''} gu-table--style-${model.tableStyle}"
     id="${model.componentId}">
  ${model.processedTableHtml @ context='unsafe'}
</div>

El modelo devuelve HTML completo con la imagen principal ya representada, por lo que HTL solo la imprime.

Agregar el modelo Sling para procesar HTML y procesar la imagen principal

El modelo lee campos de diálogo, analiza la tabla de HTML, encuentra cada <img> y lo reemplaza por Core Image HTML a través de un servicio.

A continuación se indican algunos de los conocimientos importantes de TableModel:

@Model(adaptables = {Resource.class, SlingHttpServletRequest.class},
       defaultInjectionStrategy = DefaultInjectionStrategy.OPTIONAL)
public class TableModel {
  @ValueMapValue private String tableHtml;
  @ValueMapValue private boolean enableResponsive;
  @ValueMapValue private String tableStyle;
  @OSGiService private ImageComponentRenderer imageRenderer;
  // ...
  @PostConstruct
  protected void init() {
    // parse HTML, for each <img> build image props (fileReference, alt, title)
    // call imageRenderer.renderImageComponent(...)
    // replace <img> with returned Core Image HTML
  }
  public String getProcessedTableHtml() { /* return final HTML */ }
}

Esto centraliza la lógica en el servidor y reutiliza el comportamiento de la imagen principal.

Procesar imagen principal mediante un servicio (incluido en el servidor)

ImageComponentRenderer procesa el componente de imagen principal y captura el resultado. It

@Component(service = ImageComponentRenderer.class)
public class ImageComponentRenderer {
  private static final String IMAGE_RESOURCE_TYPE = "core/wcm/components/image/v2/image";
  public String renderImageComponent(Resource base, Map<String,Object> props,
                                     SlingHttpServletRequest req, SlingHttpServletResponse resp) {
    // create wrapped resource with IMAGE_RESOURCE_TYPE and props
    // dispatcher.include(...) with a response wrapper to capture HTML
    // return captured HTML
  }
}

Esto le permite colocar imagen principal donde la necesite, no solo como componente secundario.

Bibliotecas de cliente

Cree una clientlib para estilos pequeños o JS futuros. El HTL anterior carga la categoría guides-components.table.

clientlibs/css.txt
  #base=css
  table.css
clientlibs/js.txt
  #base=js
  table.js

Esto mantiene los estilos/scripts modulares y reconocibles.

Campos de diálogo (entradas del autor)

Añada un cuadro de diálogo con al menos estas propiedades:

Estos asignan 1:1 a las propiedades y controlan la representación del modelo Sling.

Permitir el componente en las plantillas

En el Editor de plantillas, edite la directiva Contenedor de diseños > Componentes permitidos > Habilite el componente Tabla en Guías - Personalizadas.

Los autores no pueden agregar componentes hasta que las directivas lo permitan.

Sugerencias de creación

Restricciones

Referencia rápida (implementación)

Este patrón muestra cómo componer un componente personalizado con un componente principal del lado del servidor, conservando el marcado y reutilizando la lógica principal.