Créer un composant personnalisé custom-component

Téléchargez le point de départ de ce tutoriel via Git :

$ git clone git@github.com:adobe/aem-guides-wknd-spa.git
$ cd aem-guides-wknd-spa
$ git checkout Angular/custom-component-start

Déployez la base de code sur une instance AEM locale à l’aide de Maven :

$ mvn clean install -PautoInstallSinglePackage

Si vous utilisez AEM 6.x ajoutez le profil classic :

$ mvn clean install -PautoInstallSinglePackage -Pclassic

Installez le package terminé pour le site de référence WKND classique. Les images fournies par le site de référence WKND sont réutilisées dans la SPA WKND. Le package peut être installé à l’aide du Gestionnaire de packages d’AEM.

Ouvrez le dossier ui.apps dans l’IDE de votre choix.

Accédez à ui.apps/src/main/content/jcr_root/apps/wknd-spa-angular/components et créez un dossier appelé custom-component.

Créez un fichier appelé .content.xml sous le dossier custom-component. Remplissez custom-component/.content.xml avec les éléments suivants :

<?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:primaryType="cq:Component"
    jcr:title="Custom Component"
    componentGroup="WKND SPA Angular - Content"/>

jcr:primaryType="cq:Component" : identifie que ce nœud est un composant AEM.

jcr:title est la valeur affichée pour les auteurs et autrices de contenu et le componentGroup détermine le regroupement des composants dans l’interface utilisateur de création.

Sous le dossier custom-component, créez un autre dossier appelé _cq_dialog.

Sous le dossier _cq_dialog, créez un fichier appelé .content.xml et remplissez-le avec les éléments suivants :

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:granite="http://www.adobe.com/jcr/granite/1.0" xmlns:cq="http://www.day.com/jcr/cq/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0" xmlns:nt="http://www.jcp.org/jcr/nt/1.0"
    jcr:primaryType="nt:unstructured"
    jcr:title="Custom Component"
    sling:resourceType="cq/gui/components/authoring/dialog">
    <content
        jcr:primaryType="nt:unstructured"
        sling:resourceType="granite/ui/components/coral/foundation/container">
        <items jcr:primaryType="nt:unstructured">
            <tabs
                jcr:primaryType="nt:unstructured"
                sling:resourceType="granite/ui/components/coral/foundation/tabs"
                maximized="{Boolean}true">
                <items jcr:primaryType="nt:unstructured">
                    <properties
                        jcr:primaryType="nt:unstructured"
                        jcr:title="Properties"
                        sling:resourceType="granite/ui/components/coral/foundation/container"
                        margin="{Boolean}true">
                        <items jcr:primaryType="nt:unstructured">
                            <columns
                                jcr:primaryType="nt:unstructured"
                                sling:resourceType="granite/ui/components/coral/foundation/fixedcolumns"
                                margin="{Boolean}true">
                                <items jcr:primaryType="nt:unstructured">
                                    <column
                                        jcr:primaryType="nt:unstructured"
                                        sling:resourceType="granite/ui/components/coral/foundation/container">
                                        <items jcr:primaryType="nt:unstructured">
                                            <message
                                                jcr:primaryType="nt:unstructured"
                                                sling:resourceType="granite/ui/components/coral/foundation/form/textfield"
                                                fieldDescription="The text to display on the component."
                                                fieldLabel="Message"
                                                name="./message"/>
                                        </items>
                                    </column>
                                </items>
                            </columns>
                        </items>
                    </properties>
                </items>
            </tabs>
        </items>
    </content>
</jcr:root>

Le fichier XML ci-dessus génère une boîte de dialogue simple pour le Custom Component. La partie essentielle du fichier est le nœud interne <message>. Cette boîte de dialogue contient un simple textfield nommé Message et conserve la valeur du champ de texte dans une propriété nommée message.

Un modèle Sling est ensuite créé pour exposer la valeur de la propriété message via le modèle JSON.

Avec un composant d’AEM traditionnel, un script HTL est généralement requis. Étant donné que la SPA effectue le rendu du composant, aucun script HTL n’est nécessaire.

Dans l’IDE de votre choix, ouvrez le module core. CustomComponent.java et CustomComponentImpl.java ont déjà été créés et bouchés dans le cadre du code de démarrage de projet.

Ouvrez le CustomComponent.java d’interface Java™ dans core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/CustomComponent.java :

Il s’agit de l’interface Java™ implémentée par le modèle Sling.

Mettez à jour CustomComponent.java pour qu’il étende l’interface du ComponentExporter :

package com.adobe.aem.guides.wknd.spa.angular.core.models;
import com.adobe.cq.export.json.ComponentExporter;

public interface CustomComponent extends ComponentExporter {

    public String getMessage();

}

L’implémentation de l’interface du ComponentExporter est obligatoire pour que le modèle Sling soit automatiquement récupéré par l’API du modèle JSON.

L’interface CustomComponent comprend une méthode getter unique getMessage(). Il s’agit de la méthode qui expose la valeur de la boîte de dialogue de création par le biais du modèle JSON. Seules les méthodes getter avec des paramètres vides () sont exportées dans le modèle JSON.

Ouvrez le CustomComponentImpl.java dans core/src/main/java/com/adobe/aem/guides/wknd/spa/angular/core/models/impl/CustomComponentImpl.java.

Il s’agit de l’implémentation de l’interface du CustomComponent. L’annotation @Model identifie la classe Java™ en tant que modèle Sling. L’annotation @Exporter permet à la classe Java™ d’être sérialisée et exportée via l’exporteur de modèle Sling.

Mettez à jour la variable statique RESOURCE_TYPE pour pointer vers le composant AEM wknd-spa-angular/components/custom-component créé dans l’exercice précédent.

static final String RESOURCE_TYPE = "wknd-spa-angular/components/custom-component";

Le type de ressource du composant est ce qui lie le modèle Sling au composant AEM et qui le mappe finalement au composant Angular.

Ajoutez la méthode getExportedType() à la classe CustomComponentImpl pour renvoyer le type de ressource du composant :

@Override
public String getExportedType() {
    return CustomComponentImpl.RESOURCE_TYPE;
}

Cette méthode est requise lors de l’implémentation de l’interface du ComponentExporter et expose le type de ressource qui permet le mappage au composant Angular.

Mettez à jour la méthode getMessage() pour renvoyer la valeur de la propriété message conservée par la boîte de dialogue de création. Utilisez l’annotation @ValueMap pour mapper la valeur JCR message à une variable Java™ :

import org.apache.commons.lang3.StringUtils;
...

@ValueMapValue
private String message;

@Override
public String getMessage() {
    return StringUtils.isNotBlank(message) ? message.toUpperCase() : null;
}

Une « logique commerciale » supplémentaire est ajoutée pour renvoyer la valeur du message en majuscules. Cela nous permet de voir la différence entre la valeur brute stockée par la boîte de dialogue de création et la valeur exposée par le modèle Sling.

Dans le module ui.frontend, ouvrez le fichier ui.frontend/src/app/components/custom/custom.component.ts.

Observez la ligne @Input() message: string;. La valeur transformée en majuscules est normalement mappée à cette variable.

Importez l’objet MapTo à partir du SDK JS de l’éditeur de SPA d’AEM et utilisez-le pour mapper au composant AEM :

+ import {MapTo} from '@adobe/cq-angular-editable-components';

 ...
 export class CustomComponent implements OnInit {
     ...
 }

+ MapTo('wknd-spa-angular/components/custom-component')(CustomComponent, CustomEditConfig);

Ouvrez cutom.component.html et observez que la valeur de {{message}} s’affiche à côté d’une balise <h2>.

Ouvrez custom.component.css et ajoutez la règle suivante :

:host-context {
    display: block;
}

Pour que l’espace réservé de l’éditeur AEM s’affiche correctement lorsque le composant est vide, le :host-context ou un autre <div> doit être défini sur display: block;.

Déployez les mises à jour dans un environnement AEM local à partir de la racine du répertoire du projet, en utilisant vos compétences Maven :

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

Vérifiez l’enregistrement du nouveau modèle Sling en accédant à http://localhost:4502/system/console/status-slingmodels.

com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl - wknd-spa-angular/components/custom-component

com.adobe.aem.guides.wknd.spa.angular.core.models.impl.CustomComponentImpl exports 'wknd-spa-angular/components/custom-component' with selector 'model' and extension '[Ljava.lang.String;@6fb4a693' with exporter 'jackson'

Vous devriez voir les deux lignes ci-dessus qui indiquent que le CustomComponentImpl est associé au composant wknd-spa-angular/components/custom-component et qu’il est enregistré via l’exporteur de modèle Sling.

Accédez au modèle de page SPA à l’adresse http://localhost:4502/editor.html/conf/wknd-spa-angular/settings/wcm/templates/spa-page-template/structure.html.

Mettez à jour la stratégie du conteneur de disposition pour ajouter le nouveau Custom Component en tant que composant autorisé :

Enregistrez les modifications apportées à la stratégie et observez le composant Custom Component en tant que composant autorisé :

Accédez à http://localhost:4502/editor.html/content/wknd-spa-angular/us/en/home.html.

Dans le mode Edit, ajoutez le Custom Component au Layout Container :

Ouvrez la boîte de dialogue du composant et saisissez un message contenant des lettres minuscules.

Il s’agit de la boîte de dialogue qui a été créée à partir du fichier XML plus tôt dans le chapitre.

Enregistrez les modifications. Notez que le message affiché est en majuscules.

Affichez le modèle JSON en accédant à http://localhost:4502/content/wknd-spa-angular/us/en.model.json. Recherchez wknd-spa-angular/components/custom-component :

"custom_component_208183317": {
    "message": "HELLO WORLD",
    ":type": "wknd-spa-angular/components/custom-component"
}

Notez que la valeur JSON est définie en majuscules en fonction de la logique ajoutée au modèle Sling.