Personnaliser la couche de données client Adobe avec les composants AEM customize-data-layer

Démarrez une instance locale de démarrage rapide de création d’AEM exécutée à l’adresse http://localhost:4502.

Ouvrez une fenêtre de terminal et clonez la base de code WKND à l’aide de Git :

$ git clone git@github.com:adobe/aem-guides-wknd.git

Déployez la base de code WKND sur une instance locale d’AEM :

$ cd aem-guides-wknd
$ mvn clean install -PautoInstallSinglePackage

Ouvrez une nouvelle fenêtre de navigateur et connectez-vous à AEM. Ouvrez une page de Magazine, comme par exemple : http://localhost:4502/content/wknd/fr/magazine/guide-la-skateparks.html.

Vous devriez voir un exemple du composant de signature qui a été ajouté à la page dans le cadre d’un fragment d’expérience. Vous pouvez afficher le fragment d’expérience à l’adresse http://localhost:4502/editor.html/content/experience-fragments/wknd/language-masters/fr/contributors/stacey-roswells/byline.html.

Ouvrez vos outils de développement et saisissez la commande suivante dans la Console  :

window.adobeDataLayer.getState();

Pour afficher l’état actuel de la couche de données sur un site AEM, examinez la réponse. Vous devriez voir des informations sur la page et les composants individuels.

Notez que le composant de signature n’est pas répertorié dans la couche de données.

Ouvrez le projet aem-guides-wknd dans l’IDE de votre choix. Accédez au module core.

Ouvrez le fichier Byline.java dans core/src/main/java/com/adobe/aem/guides/wknd/core/models/Byline.java.

Ajoutez la méthode ci-dessous à l’interface :

public interface Byline {
    ...
    /***
     * Return data about the Byline Component to populate the data layer
     * @return String
     */
    String getData();
}

Ouvrez le fichier BylineImpl.java dans core/src/main/java/com/adobe/aem/guides/wknd/core/models/impl/BylineImpl.java. Il s’agit de la mise en œuvre de l’interface Byline. Elle est implémentée en tant que modèle Sling.

Ajoutez les instructions d’import suivantes au début du fichier :

import java.util.HashMap;
import java.util.Map;
import org.apache.sling.api.resource.Resource;
import com.fasterxml.jackson.core.JsonProcessingException;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.adobe.cq.wcm.core.components.util.ComponentUtils;

Les API fasterxml.jackson sont utilisées pour sérialiser les données à exposer au format JSON. Les ComponentUtils des composants principaux d’AEM sont utilisés pour vérifier si la couche de données est activée.

Ajoutez la méthode non implémentée getData() à BylineImple.java :

public class BylineImpl implements Byline {
    ...
    @Override
    public String getData() {
        Resource bylineResource = this.request.getResource();
        // Use ComponentUtils to verify if the DataLayer is enabled
        if (ComponentUtils.isDataLayerEnabled(bylineResource)) {

            //Create a map of properties we want to expose
            Map<String, Object> bylineProperties = new HashMap<String,Object>();
            bylineProperties.put("@type", bylineResource.getResourceType());
            bylineProperties.put("name", this.getName());
            bylineProperties.put("occupation", this.getOccupations());
            bylineProperties.put("fileReference", image.getFileReference());

            //Use AEM Core Component utils to get a unique identifier for the Byline component (in case multiple are on the page)
            String bylineComponentID = ComponentUtils.getId(bylineResource, this.currentPage, this.componentContext);

            // Return the bylineProperties as a JSON String with a key of the bylineResource's ID
            try {
                return String.format("{\"%s\":%s}",
                    bylineComponentID,
                    // Use the ObjectMapper to serialize the bylineProperties to a JSON string
                    new ObjectMapper().writeValueAsString(bylineProperties));
            } catch (JsonProcessingException e) {

                LOGGER.error("Unable to generate dataLayer JSON string", e);
            }

        }
        // return null if the Data Layer is not enabled
        return null;
    }
}

Dans la méthode ci-dessus, une nouvelle HashMap est utilisée pour capturer les propriétés à exposer au format JSON. Notez que les méthodes existantes comme getName() et getOccupations() sont utilisées. Le @type représente le type de ressource unique du composant. Il permet à un client ou une cliente d’identifier facilement des événements et/ou des déclencheurs en fonction du type de composant.

Le ObjectMapper est utilisé pour sérialiser les propriétés et renvoyer une chaîne JSON. Cette chaîne JSON peut ensuite être injectée dans la couche de données.

Ouvrez une fenêtre de terminal. Créez et déployez uniquement le module core avec vos compétences Maven :

$ cd aem-guides-wknd/core
$ mvn clean install -PautoInstallBundle

Ouvrez le projet aem-guides-wknd dans l’IDE. Accédez au module ui.apps.

Ouvrez le fichier byline.html dans ui.apps/src/main/content/jcr_root/apps/wknd/components/byline/byline.html.

Mettez à jour byline.html pour inclure l’attribut data-cmp-data-layer :

  <div data-sly-use.byline="com.adobe.aem.guides.wknd.core.models.Byline"
    data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html"
    data-sly-test.hasContent="${!byline.empty}"
+   data-cmp-data-layer="${byline.data}"
    class="cmp-byline">
    ...

La valeur de data-cmp-data-layer a été définie sur "${byline.data}" où byline est le modèle Sling mis à jour précédemment. .data est la notation standard pour appeler une méthode Java™ Getter en HTL de la méthode getData() mise en œuvre dans l’exercice précédent.

Ouvrez une fenêtre de terminal. Créez et déployez uniquement le module ui.apps avec vos compétences Maven :

$ cd aem-guides-wknd/ui.apps
$ mvn clean install -PautoInstallPackage

Revenez au navigateur et rouvrez la page avec un composant de signature : http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

Ouvrez les outils de développement et examinez la source HTML de la page pour le composant de signature :

Vous devriez constater que la data-cmp-data-layer a été renseignée avec la chaîne JSON du modèle Sling.

Ouvrez les outils de développement du navigateur et saisissez la commande suivante dans la console  :

window.adobeDataLayer.getState();

Naviguez sous la réponse sous component pour voir que l’instance du composant byline a été ajoutée à la couche de données :

Une entrée doit s’afficher comme suit :

byline-136073cfcb:
    @type: "wknd/components/byline"
    fileReference: "/content/dam/wknd/en/contributors/stacey-roswells.jpg"
    name: "Stacey Roswells"
    occupation: (3) ["Artist", "Photographer", "Traveler"]
    parentId: "page-30d989b3f8"

Notez que les propriétés exposées sont les mêmes que celles ajoutées dans la HashMap du modèle Sling.

Ouvrez le module ui.apps dans votre IDE.

Ouvrez le fichier byline.html dans ui.apps/src/main/content/jcr_root/apps/wknd/components/byline/byline.html.

Mettez à jour byline.html pour inclure l’attribut data-cmp-clickable dans l’élément nom du composant Signature :

  <h2 class="cmp-byline__name"
+    data-cmp-clickable="${byline.data ? true : false}">
     ${byline.name}
  </h2>

Ouvrez un nouveau terminal. Créez et déployez uniquement le module ui.apps en utilisant vos compétences Maven :

$ cd aem-guides-wknd/ui.apps
$ mvn clean install -PautoInstallPackage

Revenez au navigateur et rouvrez la page en ajoutant le composant Signature : http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

Pour tester notre événement, nous allons ajouter manuellement du code JavaScript à l’aide de la Developer Console. Consultez Utilisation de la couche de données client Adobe avec les composants principaux AEM pour une vidéo sur la façon de procéder.

Ouvrez les outils de développement du navigateur et saisissez la commande suivante dans la console  :

function bylineClickHandler(event) {
    var dataObject = window.adobeDataLayer.getState(event.eventInfo.path);
    if (dataObject != null && dataObject['@type'] === 'wknd/components/byline') {
        console.log("Byline Clicked!");
        console.log("Byline name: " + dataObject['name']);
    }
}

Cette méthode simple doit gérer le clic sur le nom du composant Signature.

Saisissez la méthode suivante dans la console  :

window.adobeDataLayer.push(function (dl) {
     dl.addEventListener("cmp:click", bylineClickHandler);
});

La méthode ci-dessus envoie un écouteur d’événement sur la couche de données pour écouter l’événement cmp:click et appelle le bylineClickHandler.

Dans le navigateur, avec la console ouverte, cliquez sur le nom de l’auteur ou de l’autrice dans le composant Signature :

Le message Byline Clicked! devrait s’afficher dans la console ainsi que le nom de la Signature.

L’événement cmp:click est le plus facile à relier. Pour les composants plus complexes et pour suivre d’autres comportements, il est possible d’ajouter du code JavaScript personnalisé pour ajouter et enregistrer de nouveaux événements. Le composant du carrousel est un excellent exemple, qui déclenche un événement cmp:show chaque fois qu’une diapositive est activée ou désactivée. Consultez le code source pour plus d’informations.

Revenez à l’IDE et accédez au module core.

Ouvrez le fichier Byline.java dans core/src/main/java/com/adobe/aem/guides/wknd/core/models/Byline.java.

Modifiez la méthode getData() pour renvoyer un type de ComponentData.

import com.adobe.cq.wcm.core.components.models.datalayer.ComponentData;
...
public interface Byline {
    ...
    /***
     * Return data about the Byline Component to populate the data layer
     * @return ComponentData
     */
    ComponentData getData();
}

ComponentData est un objet fourni par les composants principaux d’AEM. Il génère une chaîne JSON, tout comme dans l’exemple précédent, mais exécute également beaucoup de travail supplémentaire.

Ouvrez le fichier BylineImpl.java dans core/src/main/java/com/adobe/aem/guides/wknd/core/models/impl/BylineImpl.java.

Ajoutez les instructions d’import suivantes :

import com.adobe.cq.wcm.core.components.models.datalayer.ComponentData;
import com.adobe.cq.wcm.core.components.models.datalayer.builder.DataLayerBuilder;

Remplacez la méthode getData() par la suivante :

@Override
public ComponentData getData() {
    Resource bylineResource = this.request.getResource();
    // Use ComponentUtils to verify if the DataLayer is enabled
    if (ComponentUtils.isDataLayerEnabled(bylineResource)) {

        return DataLayerBuilder.extending(getImage().getData()).asImageComponent()
            .withTitle(this::getName)
            .build();

    }
    // return null if the Data Layer is not enabled
    return null;
}

Le composant Signature réutilise des parties du composant principal Image pour afficher une image représentant l’auteur ou l’autrice. Dans l’extrait de code ci-dessus, le DataLayerBuilder est utilisé pour étendre la couche de données du composant Image. Cela préremplit l’objet JSON avec toutes les données sur l’image utilisée. Il remplit également certaines fonctions de routine, comme la définition du @type et l’identifiant unique du composant. Notez que la méthode est petite.

La seule propriété étend le withTitle qui est remplacé par la valeur de getName().

Ouvrez une fenêtre de terminal. Créez et déployez uniquement le module core en utilisant vos compétences Maven :

$ cd aem-guides-wknd/core
$ mvn clean install -PautoInstallBundle

Revenez à l’IDE et ouvrez le fichier byline.html sous ui.apps.

Mettez à jour le HTL pour utiliser byline.data.json afin de renseigner l’attribut data-cmp-data-layer :

  <div data-sly-use.byline="com.adobe.aem.guides.wknd.core.models.Byline"
    data-sly-use.placeholderTemplate="core/wcm/components/commons/v1/templates.html"
    data-sly-test.hasContent="${!byline.empty}"
-   data-cmp-data-layer="${byline.data}"
+   data-cmp-data-layer="${byline.data.json}"

Rappelez-vous que nous renvoyons maintenant un objet de type ComponentData. Cet objet comprend une méthode Getter getJson() et est utilisé pour renseigner l’attribut data-cmp-data-layer.

Ouvrez une fenêtre de terminal. Créez et déployez uniquement le module ui.apps avec vos compétences Maven :

$ cd aem-guides-wknd/ui.apps
$ mvn clean install -PautoInstallPackage

Revenez au navigateur et rouvrez la page avec le composant de signature ajouté : http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

Ouvrez les outils de développement du navigateur et saisissez la commande suivante dans la console  :

window.adobeDataLayer.getState();

Naviguez sous la réponse sous component pour trouver l’instance du composant byline :

Une entrée doit s’afficher comme suit :

byline-136073cfcb:
    @type: "wknd/components/byline"
    dc:title: "Stacey Roswells"
    image:
        @type: "image/jpeg"
        repo:id: "142658f8-4029-4299-9cd6-51afd52345c0"
        repo:modifyDate: "2019-10-25T23:49:51Z"
        repo:path: "/content/dam/wknd/en/contributors/stacey-roswells.jpg"
        xdm:tags: []
    parentId: "page-30d989b3f8"
    repo:modifyDate: "2019-10-18T20:17:24Z"

Observez qu’il existe maintenant un objet image dans l’entrée du composant byline. Il y a beaucoup plus d’informations sur la ressource dans la gestion des ressources numériques. Notez également que le @type et l’ID unique (dans ce cas, byline-136073cfcb) ont été automatiquement renseignés et l’élément repo:modifyDate qui indique quand le composant a été modifié.

Vous pouvez également consulter un autre exemple d’extension de la couche de données en examinant le composant ImageList dans la base de code WKND :

• ImageList.java : interface Java dans le module core.
• ImageListImpl.java : modèle Sling dans le module core.
• image-list.html : modèle HTL dans le module ui.apps.