Personnaliser la couche de données du client Adobe avec les composants AEM

Découvrez comment personnaliser la couche de données du client Adobe avec le contenu des composants d'AEM personnalisés. Découvrez comment utiliser les API fournies par AEM Core Components pour étendre et personnaliser la couche de données.

Ce que vous allez créer

Signature de la couche de données

Dans ce didacticiel, vous allez explorer diverses options pour étendre la couche de données du client Adobe en mettant à jour le composant Signature WKND. Il s’agit d’un composant personnalisé et les leçons apprises dans ce didacticiel peuvent être appliquées à d’autres composants personnalisés.

Objectifs

  1. Injecter des données de composant dans la couche de données en étendant un modèle Sling et un composant HTL
  2. Utiliser les utilitaires de couche de données du composant principal pour réduire les efforts
  3. Utiliser les attributs de données du composant principal pour se connecter aux événements de couche de données existants

Conditions préalables

Un environnement de développement local est nécessaire pour compléter ce tutoriel. Les captures d’écran et la vidéo sont capturées à l’aide de l’AEM en tant que SDK Cloud Service s’exécutant sur un macOS. Sauf indication contraire, les commandes et le code sont indépendants du système d'exploitation local.

Vous découvrez AEM as a Cloud Service ? Consultez le guide suivant pour configurer un environnement de développement local à l’aide de l’AEM en tant que SDK Cloud Service.

Nouveau à AEM 6.5 ? Consultez le guide suivant pour la configuration d'un environnement de développement local.

Téléchargement et déploiement du site de référence WKND

Ce didacticiel étend le composant Signature du site de référence WKND. Cloner et installer la base de code WKND sur votre environnement local.

  1. Début d’une instance locale de démarrage rapide author de l’AEM s’exécutant à http://localhost:4502.

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

    $ git clone git@github.com:adobe/aem-guides-wknd.git
    
  3. Déployez la base de code WKND sur une instance locale d’AEM :

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

    Si vous utilisez AEM 6.5 et le dernier Service Pack, ajoutez le profil classic à la commande Maven :

    mvn clean install -PautoInstallSinglePackage -Pclassic

  4. Ouvrez une nouvelle fenêtre de navigateur et connectez-vous à AEM. Ouvrez une page Magazine comme suit : http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

    Composant signature sur la page

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

  5. Ouvrez vos outils de développement et saisissez la commande suivante dans la console :

    window.adobeDataLayer.getState();
    

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

    Réponse de la couche de données d'Adobe

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

Mettre à jour le modèle Sling de signature

Pour injecter des données sur le composant dans la couche de données, nous devons d’abord mettre à jour le modèle Sling du composant. Ensuite, mettez à jour l’interface Java de la signature et l’implémentation du modèle Sling pour ajouter une nouvelle méthode getData(). Cette méthode contiendra les propriétés que nous voulons injecter dans la couche de données.

  1. Dans l'IDE de votre choix, ouvrez le projet aem-guides-wknd. Accédez au module core.

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

    Interface Java de signature

  3. Ajoutez une nouvelle méthode à l’interface :

    public interface Byline {
        ...
        /***
         * Return data about the Byline Component to populate the data layer
         * @return String
         */
        String getData();
    }
    
  4. Ouvrez le fichier BylineImpl.java dans core/src/main/java/com/adobe/aem/guides/wknd/core/models/impl/BylineImpl.java.

    Il s’agit de l’implémentation de l’interface Byline et elle est implémentée en tant que modèle Sling.

  5. Ajoutez les instructions d'importation 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 seront utilisées pour sérialiser les données à exposer en tant que JSON. Le ComponentUtils des composants principaux AEM sera utilisé pour vérifier si la couche de données est activée.

  6. Ajoutez la méthode getData() non implémentée sur 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, un nouveau HashMap est utilisé pour capturer les propriétés que nous voulons exposer en tant que JSON. Notez que des méthodes existantes telles que getName() et getOccupations() sont utilisées. @type représente le type de ressource unique du composant, ce qui permet à un client d'identifier facilement des événements et/ou des déclencheurs en fonction du type de composant.

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

  7. 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
    

Mettre à jour la signature HTL

Ensuite, mettez à jour Byline HTL. HTL (HTML Template Language) est le modèle utilisé pour générer le code HTML du composant.

Un attribut de données spécial data-cmp-data-layer sur chaque composant AEM est utilisé pour exposer sa couche de données. Le code JavaScript fourni par AEM Core Components recherche cet attribut de données, dont la valeur sera renseignée avec la chaîne JSON renvoyée par la méthode getData() du modèle Sling de signature, et injecte les valeurs dans la couche Données du client de l’Adobe.

  1. Dans l'IDE, ouvrez le projet aem-guides-wknd. Accédez au module ui.apps.

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

    Signature HTML

  3. 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}"byline correspond au modèle Sling mis à jour précédemment. .data est la notation standard pour l’appel d’une méthode Java Getter dans HTL de l’exercice getData() précédent.

  4. Ouvrez une fenêtre de 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
    
  5. Revenez au navigateur et rouvrez la page avec un composant Signature : http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

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

    Signature de la couche de données

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

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

    window.adobeDataLayer.getState();
    
  8. Accédez sous la réponse sous component pour trouver l'instance du composant byline ajoutée à la couche de données :

    Partie de signature de la couche de données

    Vous devriez voir une entrée 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"
    

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

Ajouter un Événement de clic

La couche de données du client Adobe est pilotée par événement et l'un des événements les plus courants pour déclencher une action est le événement cmp:click. Les composants AEM Core facilitent l’enregistrement de votre composant à l’aide de l’élément de données : data-cmp-clickable.

Les éléments cliquables sont généralement un bouton CTA ou un lien de navigation. Malheureusement, le composant Byline n'en a pas, mais nous l'enregistrerons de toute façon car cela peut être courant pour d'autres composants personnalisés.

  1. Ouvrez le module ui.apps dans votre IDE.

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

  3. Mettez à jour byline.html pour inclure l'attribut data-cmp-clickable dans l'élément name de la signature :

      <h2 class="cmp-byline__name" 
    +    data-cmp-clickable="${byline.data ? true : false}">
         ${byline.name}
      </h2>
    
  4. 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
    
  5. 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 console de développement. Voir Utilisation de la couche de données du client Adobe avec les composants principaux AEM pour une vidéo sur la façon de procéder.

  6. Ouvrez les outils de développement du navigateur et saisissez la méthode 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 Byline.

  7. Saisissez la méthode suivante dans la Console :

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

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

    ATTENTION

    Il sera important de ne pas actualiser le navigateur tout au long de cet exercice, sinon le code JavaScript de la console sera perdu.

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

    Composant de signature cliqué

    Vous devriez voir le message de la console Byline Clicked! et le nom de la signature.

    Le é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. Un excellent exemple est le composant de carrousel, qui déclenche un événement cmp:show chaque fois qu'une diapositive est basculée. Voir le code source pour plus de détails.

Utiliser l'utilitaire DataLayerBuilder

Lorsque le modèle Sling était mis à jour plus tôt dans le chapitre, nous avons choisi de créer la chaîne JSON en utilisant HashMap et en définissant manuellement chacune des propriétés. Cette méthode fonctionne bien pour les petits composants ponctuels, mais pour les composants qui étendent les composants principaux de l'AEM, cela peut entraîner beaucoup de code supplémentaire.

Il existe une classe d'utilitaires DataLayerBuilder pour effectuer la majeure partie de la charge lourde. Cela permet aux implémentations d’étendre uniquement les propriétés qu’elles souhaitent. Mettons à jour le modèle Sling pour utiliser le DataLayerBuilder.

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

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

  3. 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 AEM Core Components. Il génère une chaîne JSON, tout comme dans l’exemple précédent, mais effectue également beaucoup de travail supplémentaire.

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

  5. Ajoutez les instructions d'importation suivantes :

    import com.adobe.cq.wcm.core.components.models.datalayer.ComponentData;
    import com.adobe.cq.wcm.core.components.models.datalayer.builder.DataLayerBuilder;
    
  6. Remplacez la méthode getData() par la méthode 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 Image Core pour afficher une image représentant l’auteur. Dans le fragment de code ci-dessus, DataLayerBuilder est utilisé pour étendre la couche de données du composant Image. Ceci préremplit l’objet JSON avec toutes les données relatives à l’image utilisée. Il exécute également certaines des fonctions de routine telles que la définition de @type et de l'identifiant unique du composant. Notez que la méthode est vraiment petite !

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

  7. 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
    
  8. Revenez à l'IDE et ouvrez le fichier byline.html sous ui.apps

  9. Mettez à jour le fichier HTL pour utiliser byline.data.json pour 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}"
    

    Souvenez-vous que nous renvoyons maintenant un objet de type ComponentData. Cet objet comprend une méthode getter getJson() qui est utilisée pour remplir l'attribut data-cmp-data-layer.

  10. Ouvrez une fenêtre de 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
    
  11. Revenez au navigateur et rouvrez la page en ajoutant le composant Signature : http://localhost:4502/content/wknd/us/en/magazine/guide-la-skateparks.html.

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

    window.adobeDataLayer.getState();
    
  13. Accédez sous la réponse sous component pour trouver l'instance du composant byline :

    Signature de la couche de données mise à jour

    Vous devriez voir une entrée 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 désormais un objet image dans l'entrée de composant byline. Cette section contient beaucoup plus d’informations sur la ressource dans la gestion des actifs numériques. Notez également que les attributs @type et l'identifiant unique (dans ce cas byline-136073cfcb) ont été automatiquement renseignés, ainsi que les attributs repo:modifyDate qui indiquent la date de modification du composant.

Exemples supplémentaires

  1. Un autre exemple d'extension de la couche de données peut être affiché en examinant le composant ImageList dans la base de code WKND :

    • ImageList.java - Interface Java dans le core module.
    • ImageListImpl.java - Modèle Sling dans le core module.
    • image-list.html - Modèle HTML dans le ui.apps module.
    REMARQUE

    Il est un peu plus difficile d’inclure des propriétés personnalisées telles que occupation lors de l’utilisation de DataLayerBuilder. Cependant, si vous étendez un composant principal qui comprend une image ou une page, l’utilitaire économise beaucoup de temps.

    REMARQUE

    Si vous créez une couche de données avancée pour les objets réutilisés tout au long d’une implémentation, il est recommandé d’extraire les éléments de couche de données dans leurs propres objets Java spécifiques à la couche de données. Par exemple, les composants de base du commerce ont ajouté des interfaces pour ProductData et CategoryData car elles peuvent être utilisées sur de nombreux composants dans une implémentation du commerce. Consultez le code dans le repo aem-cif-core-components pour plus de détails.

Félicitations!

Vous venez d'explorer quelques façons d'étendre et de personnaliser la couche de données du client Adobe avec les composants AEM !

Ressources supplémentaires

Sur cette page