Mappage des composants pour AEM Sites

L’article aborde les différents aspects du mappage des composants pour les sites AEM (à l’aide du mappage des composants composites).

Règles de mappage des composants

Utilisez un tableau JSON de règles (votre componentmapping.json) pour convertir HTML en composants. Veillez à ce que les règles soient aussi simples, explicites et spécifiques que possible.

Cibler l’élément HTML et sa classe

Lors de la définition des éléments ci-dessus, assurez-vous des points suivants :

Utilisez attributeMap pour enregistrer les propriétés sur le nœud JCR

Ajoutez des entrées à attributeMap pour définir des propriétés sur le nœud de sortie. Chaque entrée génère des attrs[to] = value.
Modèles courants :

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

Vous trouverez ci-dessous un exemple d’HTML au format JSON pour un élément d’image.

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

Normalisation des chemins via une entrée dédiée

Si vous souhaitez normaliser (rendre absolues) les valeurs, déclarez les clés d’attribut qui doivent être normalisées en utilisant :

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

Veillez à tenir compte des points importants suivants :

Extraire des valeurs HTML avant de diviser en composants

Utilisez from pour spécifier comment lire une valeur à partir de l’élément avant que le document ne soit divisé en composants distincts :

Exemples :

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

Exemple complet minimal dans 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" }
    ]
  }
]

Définissez l’élément et la classe à cibler, utilisez attributeMap pour définir les propriétés du nœud, ajoutez une entrée de path-attributes pour normaliser les chemins d’accès et sélectionnez le from approprié pour les valeurs que vous souhaitez extraire. L’heroimage utilisé ci-dessus est un composant d’un site we-retail.

Remarque : il est important de discuter du texte enrichi par défaut et d’identifier les éléments pour lesquels il est utilisé.

Créer un composant personnalisé

Découvrez comment créer un composant de tableau personnalisé qui affiche des images dans ses cellules. Cette approche garantit une conception propre et réutilisable pour le contenu dynamique. Il couvre ce que vous allez créer, ses raisons d’efficacité, les principales conditions préalables, la conception de haut niveau, etc.

Ce que vous allez créer

Composant de tableau personnalisé qui accepte le contenu du tableau HTML et qui remplace chaque <img> qu’il contient par la sortie du composant Image principal AEM. Vous pouvez ainsi réutiliser les fonctionnalités de Core Image (images réactives, gestion des alternatives, accessibilité) tout en gardant un contrôle total sur les balises de votre tableau.
Grâce à cette approche, vous pouvez créer d’autres composants personnalisés pour votre site web AEM (à l’aide du mappage des composants composites).

Pourquoi cette approche

Prérequis

Conception de haut niveau.

Votre tableau est généré une seule fois, contenant déjà le balisage de l’image principale. Aucune manipulation DOM côté client n’est nécessaire.

Structure des dossiers et fichiers de clé (dans ce référentiel)

Étapes de mise en œuvre

Définissez le composant Tableau (nœud de composant)

Créez le composant sous apps/guides-components/components/table. Si vous n’en avez pas encore, ajoutez une .content.xml minimale comme ci-dessous pour l’enregistrer dans le panneau latéral.

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

Indique à AEM qu’il s’agit d’un composant que les auteurs peuvent ajouter aux pages.

Rendu avec HTL et inclusion des styles

Utilisez un modèle Sling et générez les HTML traitées. Incluez votre catégorie de bibliothèque cliente pour 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>

Le modèle renvoie un HTML complet avec une image principale déjà rendue, donc HTL l’imprime simplement.

Ajouter le modèle Sling pour traiter HTML et effectuer le rendu de l’image principale

Le modèle lit les champs de la boîte de dialogue, analyse le tableau HTML, recherche chaque <img> et le remplace par Core Image HTML via un service.

Voici quelques-uns des savoir-faire importants pour 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 */ }
}

Cela centralise la logique sur le serveur et réutilise le comportement de l’image principale.

Rendu d’image principale via un service (inclusion côté serveur)

ImageComponentRenderer effectue le rendu du composant Image principal et capture la sortie. 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
  }
}

Vous pouvez ainsi déposer l’image principale où vous en avez besoin, et pas seulement en tant que composant enfant.

Bibliothèques clientes

Créez une bibliothèque cliente pour les petits styles ou les futurs JS. Le HTL ci-dessus charge la catégorie guides-components.table .

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

Cela permet de conserver la modularité et la visibilité des styles/scripts.

Champs de boîte de dialogue (entrées Auteur)

Ajoutez une boîte de dialogue avec au moins les propriétés suivantes :

Ils mappent 1:1 aux propriétés du modèle Sling et contrôlent le rendu.

Autoriser le composant sur les modèles

Dans l’éditeur de modèles, modifiez la stratégie du conteneur de mises en page > Composants autorisés > activez votre composant Tableau sous Guides - Personnalisés.

Les auteurs ne peuvent pas ajouter de composants tant que les politiques ne les autorisent pas.

Conseils de création

Contraintes

Référence rapide (implémentation)

Ce modèle montre comment composer un composant personnalisé avec un composant principal côté serveur, en conservant vos balises tout en réutilisant la logique Core.