Mappatura dei componenti per AEM Sites

L’articolo tratta i vari aspetti della mappatura dei componenti per i siti AEM (utilizzando la mappatura dei componenti compositi).

Regole di mappatura dei componenti

Utilizza un array JSON di regole (il tuo componentmapping.json) per convertire HTML in componenti. Usa regole il più possibile semplici, esplicite e specifiche.

Eseguire il targeting dell’elemento HTML e della relativa classe

Durante la definizione degli elementi di cui sopra, assicurati quanto segue:

Utilizza attributeMap per salvare le proprietà sul nodo JCR

Aggiungere voci a attributeMap per impostare le proprietà nel nodo di output. Ogni voce produce attrs[to] = value.
Pattern comuni:

// 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" }

Di seguito è riportato un esempio da HTML a JSON per un elemento immagine.

<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"
      }
    ]
  }

Normalizzare i percorsi tramite una voce dedicata

Per normalizzare (rendere assoluti) i valori, dichiarare quali chiavi di attributo devono essere normalizzate utilizzando:

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

Assicurati di occuparti dei seguenti punti importanti:

Estrarre i valori HTML prima di suddividerli in componenti

Utilizzare from per specificare come leggere un valore dall'elemento prima che il documento venga suddiviso in componenti separati:

Esempi:

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

Esempio end-to-end minimo in 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" }
    ]
  }
]

Definisci l'elemento e la classe di destinazione, utilizza attributeMap per impostare le proprietà del nodo, aggiungi una voce path-attributes per normalizzare i percorsi e scegli il from destro per i valori che desideri estrarre. heroimage utilizzato in precedenza è un componente in un sito we-retail.

Nota: è importante discutere il testo RTF predefinito e identificare gli elementi per i quali viene utilizzato.

Creare un componente personalizzato

Scopri come creare un componente tabella personalizzato che visualizzi le immagini all’interno delle celle. Questo approccio garantisce un design pulito e riutilizzabile per i contenuti dinamici. Copre ciò che verrà creato, il motivo per cui è efficace, i prerequisiti chiave, il design di alto livello e altro ancora.

Cosa verrà creato

Componente tabella personalizzato che accetta il contenuto della tabella HTML e sostituisce ogni <img> al suo interno con l’output del componente Immagine core di AEM. Questo consente di riutilizzare le funzioni dell’immagine core (immagini reattive, gestione delle opzioni Alt, accessibilità) mantenendo al contempo il controllo completo sul markup della tabella.
Utilizzando questo approccio, puoi creare altri componenti personalizzati per il sito web di AEM (utilizzando la mappatura dei componenti compositi).

Perché questo approccio

Prerequisiti

Design di alto livello

La tabella viene generata una sola volta e contiene già il markup Immagine core. Non è necessaria alcuna manipolazione DOM lato client.

Struttura delle cartelle e file chiave (in questo archivio)

Passaggi di implementazione

Definire il componente Tabella (nodo componente)

Crea il componente in apps/guides-components/components/table. Se non ne hai già uno, aggiungi un minimo di .content.xml come di seguito per registrarlo nel pannello laterale.

<?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 ad AEM che si tratta di un componente disponibile per gli autori per l’aggiunta alle pagine.

Esegui rendering con HTL e includi stili

Utilizza un modello Sling e genera il HTML elaborato. Includi la categoria clientlib per 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>

Il modello restituisce HTML completo con l’immagine core già renderizzata, quindi HTL lo stampa e basta.

Aggiungi il modello Sling per elaborare HTML ed eseguire il rendering dell'immagine core

Il modello legge i campi della finestra di dialogo, analizza la tabella HTML, trova ogni <img> e lo sostituisce con Core Image HTML tramite un servizio.

Di seguito sono riportate alcune delle conoscenze importanti per 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 */ }
}

Questo centralizza la logica sul server e riutilizza il comportamento Immagine core.

Esegui rendering dell'immagine di base tramite un servizio (server-side include)

ImageComponentRenderer esegue il rendering del componente immagine core e acquisisce l'output. 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
  }
}

Questo ti consente di rilasciare l'immagine principale ovunque ti serva, non solo come componente secondario.

Librerie client

Crea una libreria client per piccoli stili o JS futuri. L'HTL riportato sopra carica la categoria guides-components.table.

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

In questo modo gli stili e gli script sono sempre modulari e individuabili.

Campi finestra di dialogo (input autore)

Aggiungi una finestra di dialogo con almeno le seguenti proprietà:

Questi mappano 1:1 alle proprietà del modello Sling e controllano il rendering.

Consenti il componente nei modelli

Nell'Editor modelli, modifica il criterio Contenitore di layout > Componenti consentiti > abilita il componente Tabella in Guide - Personalizzato.

Gli autori non possono aggiungere componenti finché i criteri non lo consentono.

Suggerimenti per l’authoring

Vincoli

Riferimento rapido (implementazione)

Questo modello mostra come comporre un componente personalizzato con un componente core lato server, mantenendo il markup durante il riutilizzo della logica core.