Show Menu
SUJETS×

Personnalisation des composants principaux CIF AEM

Le projet aem-cif-guides-venia CIF Venia est une base de code de référence pour l'utilisation des composants principaux CIF. Dans ce didacticiel, vous allez étendre davantage le composant Product Teaser pour afficher un attribut personnalisé du Magento. Vous en apprendrez davantage sur l'intégration de GraphQL entre AEM et Magento et les crochets d'extension fournis par les composants principaux du FIC.
Utilisez l'archétype du projet AEM lors du démarrage de votre propre implémentation commerciale.

Ce que vous allez construire

La marque Venia a récemment commencé à fabriquer certains produits à l'aide de matériaux durables et l'entreprise aimerait présenter un badge écologique dans le cadre du produit Teaser. Un nouvel attribut personnalisé sera créé en 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 produit Teaser pour les produits spécifiés.

Conditions préalables

Un environnement de développement local est nécessaire pour compléter ce tutoriel. Cela inclut une instance en cours d’exécution d’AEM qui est configurée et connectée à une instance de Magento. Examinez les exigences et les étapes de la configuration d’un développement local avec AEM comme SDK Cloud Service. Pour suivre complètement le didacticiel, vous aurez besoin d'autorisations pour ajouter des attributs à un produit en Magento.
Vous aurez également besoin d'un IDE GraphQL tel que GraphiQL ou d'une extension de navigateur pour exécuter les exemples de code et les didacticiels. Si vous installez une extension de navigateur, assurez-vous qu’elle permet de définir des en-têtes de requête. Sur Google Chrome, Altair GraphQL Client est une extension qui peut faire le travail.

Cloner le projet Venia

Nous clonerons le projet aem-cif-guides-venia Venia, puis nous remplacerons les styles par défaut.
N'hésitez pas à utiliser un projet existant (basé sur l'archétype de projet AEM avec CIF inclus) et ignorez 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 -PautoInstallPackage,cloud
    
    
  3. ajoutez les configurations OSGi nécessaires pour connecter votre instance AEM à une instance de Magento ou ajoutez les configurations au projet nouvellement créé.
  4. A ce stade, vous devez 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 la vitrine utilise actuellement le thème Venia. En développant le menu principal de la vitrine, vous devriez voir différentes catégories, indiquant que le Magento de connexion fonctionne.

Auteur du produit Teaser

Le composant Teaser du produit sera étendu tout au long de ce tutoriel. Dans un premier temps, ajoutez une nouvelle instance de Product Teaser à la Page d'accueil pour comprendre la fonctionnalité 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 Produit Teaser dans le conteneur de mise en page principal de la page.
  3. Développez le panneau latéral (s’il n’est pas déjà activé) et basculez la liste déroulante de recherche de ressources sur Produits . Ceci devrait afficher une liste de produits disponibles à partir d’une instance de Magento connectée. Sélectionnez un produit et faites-le glisser sur le composant Produit Teaser de la page.
    Remarque : 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 le prix du produit sont des attributs par défaut affichés.

ajouter un attribut personnalisé dans le Magento

Les produits et les données de produit affichées dans AEM sont stockés dans le Magento. Ajoutez ensuite un nouvel attribut pour Eco Friendly dans l’attribut de produit défini à l’aide de l’interface utilisateur du Magento.
Avez-vous déjà 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 de Magento.
  2. Accédez à Catalogue > Produits .
  3. Mettez à jour le filtre de recherche pour trouver le produit ​configurable utilisé lors de son ajout au composant Teaser dans l’exercice précédent. Ouvrez le produit en mode d’édition.
  4. Dans la vue de produits, cliquez sur Ajouter attribut > Créer un attribut .
  5. Remplissez le formulaire Nouvel attribut avec les valeurs suivantes (laissez les paramètres par défaut pour les autres valeurs).
    Jeu de champs
    Libellé du champ
    Valeur
    Propriétés d’attribut
    Étiquette d'attribut
    Éco convivial
    Propriétés d’attribut
    Type d’entrée du catalogue
    Oui/Non
    Propriétés d’attribut avancées
    Code d’attribut
    eco_friendly
    Click Save Attribute when finished.
  6. Faites défiler la page jusqu’au bas du produit et développez l’en-tête Attributs . Vous devriez voir le nouveau champ écologique . Bascule sur Oui .
    Enregistrez les modifications apportées au produit.
    Pour plus d’informations sur la gestion des attributs de produit, consultez le guide d’utilisation du Magento.
  7. Accédez à System > Tools > Cache Management . Comme une mise à jour a été effectuée sur le schéma de données, nous devons invalider certains types de cache dans le Magento.
  8. Cochez la case en regard de Configuration et envoyez le type de cache pour Actualiser.
    Pour plus d’informations sur la gestion du cache, consultez le guide d’utilisation du Magento.

Utiliser un IDE GraphQL pour vérifier l'attribut

Avant de passer au code AEM, il est utile d'explorer GraphQL Magento à l'aide d'un IDE GraphQL. L'intégration du Magento avec l'AEM se fait 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 de base CIF.
Ensuite, utilisez un IDE GraphQL pour vérifier que l' eco_friendly attribut a été ajouté au jeu d'attributs du produit. Les captures d'écran de ce didacticiel 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 produits suivante où YOUR_SKU correspond au SKU ​du produit utilisé lors de l’exercice précédent :
      {
        products(
        filter: { sku: { eq: "YOUR_SKU" } }
        ) {
            items {
            name
            sku
            eco_friendly
            }
        }
    }
    
    
  3. Exécutez la requête et obtenez une réponse comme celle-ci :
    {
    "data": {
        "products": {
            "items": [
                {
                "name": "Valeria Two-Layer Tank",
                "sku": "VT11",
                "eco_friendly": 1
                }
            ]
            }
        }
    }
    
    
    Notez que la valeur de Yes est un entier de 1 . Cela sera utile lorsque nous écrirons la requête GraphQL dans Java.
    Une documentation plus détaillée sur Magento GraphQL est disponible ici .

Mettre à jour le modèle Sling pour le produit Teaser

Ensuite, nous étendrons la logique métier de Product Teaser en implémentant un modèle Sling. Les modèles Sling sont des "POJO" pilotés par les annotations (objets Java standard) qui implémentent toute logique métier nécessaire au composant. Les modèles Sling sont utilisés conjointement avec les scripts HTL dans le cadre du composant. Nous suivrons le modèle de délégation pour les modèles Sling afin que nous puissions simplement étendre certaines parties du modèle existant de Teaser produit.
Les modèles Sling sont implémentés en tant que Java et se trouvent dans le module principal 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 development-tools.html#microsoft-visual-studio-code Visual Studio Code.
  1. Dans votre IDE, naviguez sous le module principal pour : core/src/main/java/com/venia/core/models/commerce/MyProductTeaser.java .
    MyProductTeaser.java est une interface Java qui étend l’interface CIF ProductTeaser .
    Une nouvelle méthode a déjà été ajoutée pour afficher un badge si le produit est considéré comme "nouveau" isShowBadge() .
  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 Non .
  3. Ensuite, inspectez le MyProductTeaserImpl.java à core/src/main/java/com/venia/core/models/commerce/MyProductTeaserImpl.java .
    Le modèle de délégation pour les 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 ou modifier, nous pouvons simplement renvoyer la valeur ProductTeaser renvoyée. 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 AEM CIF Core Components est celui AbstractProductRetriever qui permet d'accéder à des attributs de produits spécifiques. inspect à la initModel() méthode :
    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’ @PostConstruct annotation 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 extendProductQueryWith méthode pour récupérer l'attribut supplémentaire created_at . Cet attribut est ensuite utilisé dans le cadre de la isShowBadge() méthode.
  5. Mettez à jour la requête GraphQL pour inclure l’ eco_friendly attribut 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 ->
                 productRetriever.extendProductQueryWith(p -> p
                    .createdAt()
                    .addCustomSimpleField(ECO_FRIENDLY_ATTRIBUTE)
                );
            );
        }
    }
    
    
    ajouter à la extendProductQueryWith méthode est un moyen puissant de s'assurer que d'autres attributs de produit sont disponibles pour le reste du modèle. Elle permet également de réduire le nombre de requêtes exécutées.
    Dans le code ci-dessus, les addCustomSimpleField est utilisé pour récupérer l’ eco_friendly attribut. Ceci illustre comment vous pouvez requête pour les attributs personnalisés qui font partie du schéma du Magento.
    La createdAt() méthode a en fait été implémentée dans le cadre de l'interface ProductInterface.java du produit. La plupart des attributs de schéma les plus courants ont été implémentés, utilisez donc uniquement la addCustomSimpleField pour les attributs réellement personnalisés.
  6. ajoutez une journalisation pour aider à déboguer le 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. Ensuite, implémentez la isEcoFriendly() méthode :
    @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 getAsInteger() méthode est utilisée pour obtenir la valeur de l' eco_friendly attribut. Selon les requêtes GraphQL que nous avons exécutées précédemment, nous savons que la valeur attendue lorsque l’ eco_friendly attribut est défini sur " Yes " est en fait un entier de 1 .
    Maintenant que le modèle Sling a été mis à jour, l’annotation de composant doit être mise à jour pour afficher un indicateur d’ éco-compatible basé sur le modèle Sling.

Personnalisation de l'annotation du produit Teaser

Une extension courante des composants AEM consiste à modifier l’annotation générée par le composant. Pour ce faire, il doit remplacer le script overview.html HTL utilisé par le composant pour effectuer le rendu de son balisage. HTML Template Language (HTL) est un langage de modèle léger que AEM composants utilisent pour générer dynamiquement des balises en fonction du contenu créé, ce qui permet de réutiliser les composants. Le produit Teaser, par exemple, peut être réutilisé plusieurs fois pour afficher différents produits.
Dans notre cas, nous voulons rendre une bannière au-dessus du teaser pour indiquer que le produit est "écologique" basé sur un attribut personnalisé. Le modèle de conception permettant de personnaliser l’annotation d’un composant est en fait standard pour tous les composants AEM, et pas seulement pour les composants CIF Core AEM.
  1. Dans l'IDE, naviguez et développez le ui.apps module et développez la hiérarchie de dossiers pour : ui.apps/src/main/content/jcr_root/apps/venia/components/commerce/productteaser et inspecter le .content.xml dossier.
    <?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, la définition de composant pour le composant Teaser du produit dans 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 using.html#create-proxy-components Proxy. Au lieu de copier et de coller tous les scripts HTML de Product Teaser à partir des composants principaux CIF AEM, nous pouvons utiliser le sling:resourceSuperType pour hériter de toutes les fonctionnalités.
  2. Open the file productteaser.html . Il s'agit d'une copie du productteaser.html fichier du CIF Product Teaser.
    <!--/* 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}">
    
    
    Notez que le modèle Sling pour MyProductTeaser est utilisé et affecté à la product variable.
  3. Modifiez productteaser.html pour effectuer un appel à la isEcoFriendly méthode 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>
    ...
    
    
    Lors de l’appel d’une méthode de modèle Sling dans HTL, la get partie et la partie is de la méthode sont ignorées et la première lettre est lue. Alors isShowBadge() devient .showBadge et isEcoFriendly devient .ecoFriendly . Basé sur la valeur booléenne renvoyée par .isEcoFriendly() détermine si la <span>Eco Friendly</span> variable est affichée.
    Vous trouverez ici data-sly-test plus d'informations sur les instructions de blocage HTL et d'autres.
  4. Enregistrez les modifications et déployez les mises à jour pour AEM à l’aide de vos compétences Maven, à partir d’un terminal de ligne de commande :
    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallPackage,cloud
    
    
  5. Ouvrez une nouvelle fenêtre de navigateur et accédez à AEM et à la console ​OSGi > Status > Sling Models : http://localhost:4502/system/console/status-slingmodels
  6. Recherchez MyProductTeaserImpl et vous devriez voir une ligne comme celle-ci :
    com.venia.core.models.commerce.MyProductTeaserImpl - venia/components/commerce/productteaser
    
    
    Ceci indique que le modèle Sling a été correctement déployé et mappé au composant approprié.
  7. Actualisez la Page d'accueil ​Venia à l’adresse http://localhost:4502/editor.html/content/venia/us/en.html où le produit Teaser a été ajouté.
    Si l’attribut eco_friendly du produit est défini sur Oui , le texte "Eco Friendly" doit s’afficher sur la page. Essayez de passer à d'autres produits pour voir le changement de comportement.
  8. Ouvrez ensuite l'AEM error.log pour voir les instructions du journal que nous avons ajoutées. Le error.log est situé à <AEM SDK Install Location>/crx-quickstart/logs/error.log .
    Recherchez les journaux d'AEM pour afficher 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**
    ...
    
    
    Vous pouvez également voir des traces de pile si le produit utilisé dans le teaser n'a pas l' eco_friendly attribut dans son jeu d'attributs.

Styles d’Ajoute pour le badge Eco Friendly

A ce stade, la logique pour quand afficher le badge Eco Friendly fonctionne, mais le texte brut pourrait utiliser certains styles. Ajoutez ensuite une icône et des styles au ui.frontend module pour terminer l’implémentation.
  1. Téléchargez le fichier eco_friendly.svg . Il sera utilisé comme badge écologique .
  2. Revenez à l'IDE et accédez au ui.frontend dossier.
  3. ajoutez le eco_friendly.svg fichier dans le ui.frontend/src/main/resources/images dossier :
  4. Open the file productteaser.scss at ui.frontend/src/main/styles/commerce/_productteaser.scss .
  5. ajoutez les règles Sass suivantes dans la .productteaser classe :
    .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'); 
            }
        }
    ...
    }
    
    
    Consultez Styling CIF Core Components pour en savoir plus sur les workflows frontaux.
  6. Enregistrez les modifications et déployez les mises à jour pour AEM à l’aide de vos compétences Maven, à partir d’un terminal de ligne de commande :
    $ cd aem-cif-guides-venia/
    $ mvn clean install -PautoInstallPackage,cloud
    
    
  7. Actualisez la Page d'accueil ​Venia à l’adresse http://localhost:4502/editor.html/content/venia/us/en.html où le produit Teaser a été ajouté.

Congratulations

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

Bonus Challenge

Examinez les fonctionnalités du nouveau badge qui a déjà été mis en oeuvre dans le produit Teaser. Essayez d’ajouter une case supplémentaire pour les auteurs afin de contrôler quand 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 .