Personnalisation des composants principaux AEM CIF

Le projet CIF Venia est une base de code de référence pour l’utilisation des composants principaux CIF. Dans ce tutoriel, vous allez étendre davantage le composant Teaser de produit pour afficher un attribut personnalisé de Magento. Vous allez également en apprendre davantage sur l’intégration de GraphQL entre AEM et Magento, et les hooks d’extension fournis par les composants principaux CIF.

CONSEIL

Utilisez l’archétype de projet AEM pour démarrer votre propre implémentation commerciale.

Ce que vous allez créer

La marque Venia a récemment commencé à fabriquer des produits à l’aide de matériaux durables et l’entreprise aimerait faire apparaître un badge Écologique dans son teaser de produit. Un nouvel attribut personnalisé sera créé dans Magento pour indiquer si un produit utilise le matériau Écologique. Cet attribut personnalisé sera ensuite ajouté dans le cadre de la requête GraphQL et affiché sur le teaser des produits spécifiés.

Mise en œuvre finale du badge Écologique

Prérequis

Un environnement de développement local est nécessaire pour suivre ce tutoriel. Cela inclut une instance AEM en cours d’exécution configurée et connectée à une instance Magento. Examinez les exigences et les étapes de configuration d’un développement local avec AEM. Pour suivre entièrement le tutoriel, vous avez besoin d’autorisations de façon à ajouter des attributs à un produit dans Magento.

Vous avez également besoin d’un IDE GraphQL tel que GraphiQL ou d’une extension de navigateur pour exécuter les exemples de code et les tutoriels. Si vous installez une extension de navigateur, assurez-vous que celle-ci permet de définir des en-têtes de requête. Dans Google Chrome, Altair GraphQL Client est une extension pouvant réaliser cette tâche.

Clonage du projet Venia

Nous allons cloner le projet Venia puis remplacer les styles par défaut.

REMARQUE

N’hésitez pas à utiliser un projet existant (basé sur l’archétype de projet AEM avec CIF inclus) et à ignorer cette section.

  1. Exécutez la commande git suivante pour cloner le projet :

    $ git clone git@github.com:adobe/aem-cif-guides-venia.git
    
  2. Créez et déployez le projet sur une instance locale d’AEM :

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  3. Ajoutez les configurations OSGi nécessaires pour connecter votre instance AEM à une instance Magento ou ajoutez les configurations au projet nouvellement créé.

  4. À ce stade, vous devriez disposer d’une version fonctionnelle d’une vitrine connectée à une instance de Magento. Accédez à la page US > Home à l’adresse suivante : http://localhost:4502/editor.html/content/venia/us/en.html.

    Vous devriez voir que le storefront utilise actuellement le thème Venia. En développant le menu principal du storefront, vous devriez voir différentes catégories, indiquant que la connexion à Magento fonctionne.

    Storefont configuré avec le thème Venia

Création du teaser de produit

Le composant Teaser de produit va être étendu tout au long de ce tutoriel. Dans un premier temps, ajoutez une nouvelle instance du teaser de produit à la page d’accueil pour comprendre les fonctionnalités de base.

  1. Accédez à la page d’accueil du site : http://localhost:4502/editor.html/content/acme/us/en.html

  2. Insérez un nouveau composant Teaser de produit dans le conteneur de disposition principal de la page.

    Insérer un teaser de produit

  3. Développez le panneau latéral (s’il n’est pas déjà activé) et faites basculer la liste déroulante de recherche de ressources sur Produits. Cela devrait afficher la liste de produits disponibles à partir d’une instance Magento connectée. Sélectionnez un produit puis faites-le glisser et déposez-le sur le composant Teaser de produit de la page.

    Faire glisser et déposer le teaser de produit

    REMARQUE

    Sachez que vous pouvez également configurer le produit affiché en configurant le composant à l’aide de la boîte de dialogue (en cliquant sur l’icône de clé à molette).

  4. Vous devriez maintenant voir un produit affiché par le teaser de produit. Le nom du produit et son prix sont des attributs par défaut qui sont affichés.

    Teaser de produit – style par défaut

Ajout d’un attribut personnalisé dans Magento

Les produits et les données de produit affichés dans AEM sont stockés dans Magento. Ajoutez ensuite un nouvel attribut pour Écologique dans le cadre de l’attribut de produit défini avec l’interface utilisateur de Magento.

CONSEIL

Vous disposez déjà d’un attribut Oui/Non personnalisé dans votre jeu d’attributs de produit ? N’hésitez pas à l’utiliser et à ignorer cette section.

  1. Connectez-vous à votre instance Magento.

  2. Accédez à Catalog > Products.

  3. Mettez à jour le filtre de recherche pour rechercher le Configurable product (Produit configurable) utilisé lors de son ajout au composant Teaser dans l’exercice précédent. Ouvrez le produit en mode édition.

    Rechercher un produit Valeria

  4. Dans le mode Produits, cliquez sur Add Attribute (Ajouter un attribut) > Create New Attribute (Créer un attribut).

  5. Remplissez le formulaire New Attribute (Nouvel attribut) avec les valeurs suivantes (conservez les paramètres par défaut des autres valeurs).

    Jeu de champs Libellé du champ Valeur
    Propriétés d’attribut Attribute Label Écologique
    Propriétés d’attribut Catalog Input Type Oui/Non
    Propriétés d’attribut avancées Attribute Code eco_friendly

    Formulaire de nouvel attribut

    Lorsque vous avez terminé, cliquez sur Save Attribute (Enregistrer l’attribut).

  6. Faites défiler la page jusqu’au bas du produit et développez l’en-tête Attributes. Le nouveau champ Écologique devrait apparaître. Redéfinissez le bouton bascule sur Yes.

    Redéfinir le bouton bascule sur Yes

    Cliquez sur Save pour enregistrer les modifications apportées au produit.

    CONSEIL

    Pour plus d’informations sur la gestion des attributs de produit, consultez le guide de l’utilisateur de Magento.

  7. Accédez à System > Tools > Cache Management. Une mise à jour ayant été apportée au schéma de données, certains des types de cache doivent être invalidés dans Magento.

  8. Cochez la case Configuration et envoyez le type de cache pour Actualiser.

    Actualise le type de cache de configuration

    CONSEIL

Utilisation d’un IDE GraphQL pour vérifier l’attribut

Avant de passer au code AEM, il est utile d’explorer le point d’entrée Magento GraphQL à l’aide d’un IDE GraphQL. L’intégration de Magento avec AEM s’effectue principalement par le biais d’une série de requêtes GraphQL. Comprendre et modifier les requêtes GraphQL est l’un des principaux moyens d’étendre les composants principaux CIF.

Ensuite, utilisez un IDE GraphQL pour vérifier que l’attribut eco_friendly a été ajouté au jeu d’attributs du produit. Les captures d’écran de ce tutoriel utilisent le client Altair GraphQL.

  1. Ouvrez l’IDE GraphQL et entrez l’URL http://<magento-server>/graphql dans la barre d’URL de votre IDE ou extension.

  2. Ajoutez la requête de produit suivante, YOUR_SKU correspondant au SKU du produit utilisé dans l’exercice précédent :

      {
        products(
        filter: { sku: { eq: "YOUR_SKU" } }
        ) {
            items {
            name
            sku
            eco_friendly
            }
        }
    }
    
  3. Exécutez la requête ; vous devriez obtenir une réponse semblable à la suivante :

    {
      "data": {
        "products": {
          "items": [
            {
              "name": "Valeria Two-Layer Tank",
              "sku": "VT11",
              "eco_friendly": 1
            }
          ]
        }
      }
    }
    

    Exemple de réponse GraphQL

    Notez que la valeur Oui est égale au nombre entier 1. Cela sera utile pour écrire la requête GraphQL dans Java.

    CONSEIL

    Une documentation plus détaillée sur Magento GraphQL est disponible ici.

Mise à jour du modèle Sling du teaser de produit

Nous allons ensuite étendre la logique métier du teaser de produit en mettant en œuvre un modèle Sling. Les modèles Sling sont des objets POJO (Plain Old Java Object) pilotés par les annotations et mettant en œuvre la logique métier nécessaire au composant. Ils sont utilisés conjointement avec les scripts HTL dans le cadre du composant. Nous allons suivre le motif de délégation des modèles Sling afin de pouvoir simplement étendre des parties du modèle de teaser de produit existant.

Les modèles Sling sont implémentés sous forme de code Java et se trouvent dans le module core du projet généré.

Utilisez l’IDE de votre choix pour importer le projet Venia. Les captures d’écran utilisées proviennent de l’IDE Visual Studio Code.

  1. Dans votre IDE, naviguez jusqu’au module core vers : core/src/main/java/com/venia/core/models/commerce/MyProductTeaser.java.

    Core location IDE

    MyProductTeaser.java est une interface Java qui étend l’interface 🔗 ProductTeaser CIF.

    Une nouvelle méthode nommée isShowBadge() a déjà été ajoutée pour afficher un badge si le produit est considéré comme « Nouveau ».

  2. Ajoutez une nouvelle méthode, isEcoFriendly(), à l’interface :

    @ProviderType
    public interface MyProductTeaser extends ProductTeaser {
        // Extend the existing interface with the additional properties which you
        // want to expose to the HTL template.
        public Boolean isShowBadge();
    
        public Boolean isEcoFriendly();
    }
    

    Il s’agit d’une nouvelle méthode que nous allons introduire pour encapsuler la logique afin d’indiquer si l’attribut eco_friendly du produit est défini sur Oui ou sur Non.

  3. Ensuite, inspectez MyProductTeaserImpl.java à l’emplacement core/src/main/java/com/venia/core/models/commerce/MyProductTeaserImpl.java.

    Le motif de délégation des modèles Sling permet à MyProductTeaserImpl de référencer le modèle ProductTeaser via la propriété sling:resourceSuperType :

    @Self
    @Via(type = ResourceSuperType.class)
    private ProductTeaser productTeaser;
    

    Pour toutes les méthodes que nous ne voulons pas remplacer ni modifier, nous pouvons simplement renvoyer la valeur renvoyée par le ProductTeaser. Par exemple :

    @Override
    public String getImage() {
        return productTeaser.getImage();
    }
    

    Cela réduit la quantité de code Java qu’une implémentation doit écrire.

  4. L’un des points d’extension supplémentaires fournis par les composants principaux AEM CIF est le point AbstractProductRetriever, qui permet d’accéder à des attributs de produits spécifiques. Inspectez la méthode initModel() :

    import javax.annotation.PostConstruct;
    ...
    @Model(adaptables = SlingHttpServletRequest.class, adapters = MyProductTeaser.class, resourceType = MyProductTeaserImpl.RESOURCE_TYPE)
    public class MyProductTeaserImpl implements MyProductTeaser {
        ...
        private AbstractProductRetriever productRetriever;
    
        /* add this method to intialize the proudctRetriever */
        @PostConstruct
        public void initModel() {
            productRetriever = productTeaser.getProductRetriever();
    
            if (productRetriever != null) {
                productRetriever.extendProductQueryWith(p -> p.createdAt());
            }
    
        }
    ...
    

    L’annotation @PostConstruct garantit que cette méthode est appelée dès que le modèle Sling est initialisé.

    Notez que la requête GraphQL du produit a déjà été étendue à l’aide de la méthode extendProductQueryWith pour récupérer l’attribut created_at supplémentaire. Cet attribut est ensuite utilisé dans le cadre de la méthode isShowBadge().

  5. Mettez la requête GraphQL à jour pour inclure l’attribut eco_friendly dans la requête partielle :

    //MyProductTeaserImpl.java
    
    private static final String ECO_FRIENDLY_ATTRIBUTE = "eco_friendly";
    
    @PostConstruct
    public void initModel() {
        productRetriever = productTeaser.getProductRetriever();
    
        if (productRetriever != null) {
            productRetriever.extendProductQueryWith(p -> p
                .createdAt()
                .addCustomSimpleField(ECO_FRIENDLY_ATTRIBUTE)
            );
        }
    }
    

    Ajouter à la méthode extendProductQueryWith est un moyen performant de s’assurer que d’autres attributs de produit sont disponibles pour le reste du modèle. Cela permet également de réduire le nombre de requêtes exécutées.

    Dans le code ci-dessus, addCustomSimpleField est utilisé pour récupérer l’attribut eco_friendly . Cela illustre la manière d’exécuter une requête pour des attributs personnalisés faisant partie du schéma Magento.

    REMARQUE

    La méthode createdAt() a en fait été implémentée dans le cadre de l’interface du produit. La plupart des attributs de schéma courants ayant été implémentés, n’utilisez que addCustomSimpleField pour les attributs réellement personnalisés.

  6. Ajoutez un journal pour faciliter le débogage du code Java :

    import org.slf4j.Logger;
    import org.slf4j.LoggerFactory;
    ...
    @Model(adaptables = SlingHttpServletRequest.class, adapters = MyProductTeaser.class, resourceType = MyProductTeaserImpl.RESOURCE_TYPE)
    public class MyProductTeaserImpl implements MyProductTeaser {
    
    private static final Logger LOGGER = LoggerFactory.getLogger(MyProductTeaserImpl.class);
    
  7. Implémentez ensuite la méthode isEcoFriendly() :

    @Override
    public Boolean isEcoFriendly() {
    
        Integer ecoFriendlyValue;
        try {
            ecoFriendlyValue = productRetriever.fetchProduct().getAsInteger(ECO_FRIENDLY_ATTRIBUTE);
            if(ecoFriendlyValue != null && ecoFriendlyValue.equals(Integer.valueOf(1))) {
                LOGGER.info("*** Product is Eco Friendly**");
                return true;
            }
        } catch (SchemaViolationError e) {
            LOGGER.error("Error retrieving eco friendly attribute");
        }
        LOGGER.info("*** Product is not Eco Friendly**");
        return false;
    }
    

    Dans la méthode ci-dessus, productRetriever est utilisé pour récupérer le produit et la méthode getAsInteger() est utilisée pour obtenir la valeur de l’attribut eco_friendly . Selon les requêtes GraphQL que nous avons exécutées précédemment, nous savons que la valeur attendue lorsque l’attribut eco_friendly est défini sur Oui est égale au nombre entier 1.

    Maintenant que le modèle Sling a été mis à jour, le balisage de composant doit être mis à jour pour afficher un indicateur Écologique basé sur le modèle Sling.

Personnalisation du balisage du teaser de produit

Une extension courante des composants AEM consiste à modifier le balisage généré par le composant. Il faut pour cela remplacer le script HTL utilisé par le composant afin d’effectuer le rendu de son balisage. HTL (HTML Template Language) est un langage de modèle léger que les composants AEM utilisent pour générer dynamiquement des balises en fonction du contenu créé, ce qui permet de réutiliser les composants. Le teaser de produit, par exemple, peut être réutilisé plusieurs fois pour afficher différents produits.

Dans notre cas, nous voulons générer une bannière au-dessus du teaser pour indiquer que le produit est « écologique » en fonction d’un attribut personnalisé. Le modèle de conception permettant de personnaliser le balisage d’un composant est standard pour tous les composants AEM, et pas uniquement les composants principaux AEM CIF.

REMARQUE

Si vous personnalisez un composant à l’aide des sélecteurs de catégorie et de produit CIF tels que ce teaser de produit ou le composant de page CIF, veillez à inclure la bibliothèque cliente cif.shell.picker requise pour les boîtes de dialogue du composant. Voir Utilisation du sélecteur de catégorie et de produit CIF pour plus d’informations.

  1. Dans l’IDE, accédez au module ui.apps et développez-le, puis développez la hiérarchie de dossiers comme suit : ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser et inspectez le fichier .content.xml.

    Module ui.apps du teaser de produit

    <?xml version="1.0" encoding="UTF-8"?>
    <jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
        jcr:description="Product Teaser Component"
        jcr:primaryType="cq:Component"
        jcr:title="Product Teaser"
        sling:resourceSuperType="core/cif/components/commerce/productteaser/v1/productteaser"
        componentGroup="Venia - Commerce"/>
    

    Ci-dessus figure la définition du composant Teaser de produit de notre projet. Notez la propriété sling:resourceSuperType="core/cif/components/commerce/productteaser/v1/productteaser". Il s’agit d’un exemple de création d’un composant proxy. Au lieu de copier et de coller tous les scripts HTL du composant Teaser de produit à partir des composants principaux AEM CIF, nous pouvons utiliser sling:resourceSuperType pour hériter de toutes les fonctionnalités.

  2. Ouvrez le fichier productteaser.html. Il s’agit d’une copie du fichier productteaser.html du teaser de produit CIF.

    <!--/* productteaser.html */-->
    <sly
      data-sly-use.product="com.venia.core.models.commerce.MyProductTeaser"
      data-sly-use.templates="core/wcm/components/commons/v1/templates.html"
      data-sly-use.actionsTpl="actions.html"
      data-sly-test.isConfigured="${properties.selection}"
      data-sly-test.hasProduct="${product.url}"
    ></sly>
    

    Notez que le modèle Sling de MyProductTeaser est utilisé et affecté à la variable product.

  3. Modifiez productteaser.html pour effectuer un appel à la méthode isEcoFriendly implémentée lors de l’exercice précédent :

    ...
    <div
      data-sly-test="${isConfigured && hasProduct}"
      class="item__root"
      data-cmp-is="productteaser"
      data-virtual="${product.virtualProduct}"
    >
      <div data-sly-test="${product.showBadge}" class="item__badge">
        <span>${properties.text || 'New'}</span>
      </div>
      <!--/* Insert call to Eco Friendly here */-->
      <div data-sly-test="${product.ecoFriendly}" class="item__eco">
        <span>Eco Friendly</span>
      </div>
      ...
    </div>
    

    Lors de l’appel d’une méthode de modèle Sling dans HTL, les parties get et is de la méthode sont ignorées et la première lettre est une minuscule. isShowBadge() devient donc .showBadge, et isEcoFriendly devient .ecoFriendly. La valeur booléenne renvoyée par .isEcoFriendly() détermine si <span>Eco Friendly</span> est affiché.

    Vous trouverez ici plus d’informations sur data-sly-test et d’autres instructions de bloc HTL.

  4. Enregistrez les modifications et déployez les mises à jour dans AEM à l’aide de vos compétences Maven, à partir d’un terminal de ligne de commande :

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  5. Ouvrez une nouvelle fenêtre de navigateur et accédez à AEM et à la Console OSGi > État > Modèles Sling : http://localhost:4502/system/console/status-slingmodels

  6. Recherchez MyProductTeaserImpl ; une ligne semblable à la suivante devrait apparaître :

    com.venia.core.models.commerce.MyProductTeaserImpl - venia/components/commerce/productteaser
    

    Cette ligne indique que le modèle Sling a été correctement déployé et mappé sur le composant approprié.

  7. Actualisez la page d’accueil Venia à l’adresse http://localhost:4502/editor.html/content/venia/us/en.html où le teaser de produit a été ajouté.

    Message Écologique affiché

    Si l’attribut eco_friendly du produit est défini sur Oui, le texte « Écologique » devrait s’afficher sur la page. Essayez de passer à d’autres produits pour observer le changement de comportement.

  8. Ouvrez ensuite le fichier error.log d’AEM pour voir les instructions de journal que nous avons ajoutées. Le fichier error.log est situé dans <AEM SDK Install Location>/crx-quickstart/logs/error.log.

    Dans les journaux AEM, recherchez les instructions de journal ajoutées dans le modèle Sling :

    2020-08-28 12:57:03.114 INFO [com.venia.core.models.commerce.MyProductTeaserImpl] *** Product is Eco Friendly**
    ...
    2020-08-28 13:01:00.271 INFO [com.venia.core.models.commerce.MyProductTeaserImpl] *** Product is not Eco Friendly**
    ...
    
    ATTENTION

    Vous pouvez également voir des arborescences des appels si l’attribut eco_friendly ne fait pas partie du jeu d’attributs du produit utilisé dans le teaser.

Ajout de styles au badge Écologique

À ce stade, la logique indiquant à quel moment afficher le badge Écologique fonctionne, mais le texte brut pourrait profiter de certains styles. Ajoutez ensuite une icône et des styles au module ui.frontend pour terminer l’implémentation.

  1. Téléchargez le fichier eco_friendly.svg. Ce fichier sera utilisé comme badge Écologique.

  2. Revenez à l’IDE et accédez au dossier ui.frontend.

  3. Ajoutez le fichier eco_friendly.svg dans le dossier ui.frontend/src/main/resources/images :

    Fichier SVG Écologique ajouté

  4. Ouvrez le fichier productteaser.scss dans ui.frontend/src/main/styles/commerce/_productteaser.scss.

  5. Ajoutez les règles Sass suivantes dans la classe .productteaser :

    .productteaser {
        ...
        .item__eco {
            width: 60px;
            height: 60px;
            left: 0px;
            overflow: hidden;
            position: absolute;
            padding: 5px;
    
        span {
            display: block;
            position: absolute;
            width: 45px;
            height: 45px;
            text-indent: -9999px;
            background: no-repeat center center url('../resources/images/eco_friendly.svg');
            }
        }
    ...
    }
    
    REMARQUE

    Voir Affectation d’un style aux composants principaux CIF pour en savoir plus sur les workflows front-end.

  6. Enregistrez les modifications et déployez les mises à jour dans AEM à l’aide de vos compétences Maven, à partir d’un terminal de ligne de commande :

    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallSinglePackage,cloud
    
  7. Actualisez la page d’accueil Venia à l’adresse http://localhost:4502/editor.html/content/venia/us/en.html où le teaser de produit a été ajouté.

    Mise en œuvre finale du badge Écologique

Félicitations

Vous venez de personnaliser votre premier composant AEM CIF ! Téléchargez ici les fichiers de solution terminés.

Défi bonus

Examinez les fonctionnalités du badge New qui a déjà été mis en oeuvre dans le teaser de produit. Essayez d’ajouter une case à cocher supplémentaire afin que les auteurs puissent déterminer à quel moment le badge Écologique doit s’afficher. Vous devez mettre à jour la boîte de dialogue du composant à l’adresse ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser/_cq_dialog/.content.xml.

Défi lié à la mise en œuvre du badge Nouveau

Ressources supplémentaires

Sur cette page