Développer des composants AEM (IU classique) developing-aem-components-classic-ui

CAUTION
AEM 6.4 a atteint la fin de la prise en charge étendue et cette documentation n’est plus mise à jour. Pour plus d’informations, voir notre période de support technique. Rechercher les versions prises en charge here.

L’IU classique utilise ExtJS pour créer des widgets qui donnent une apparence aux composants. En raison de la nature de ces widgets, il existe des différences entre la manière dont les composants interagissent avec l’IU classique et la IU tactile.

NOTE
De nombreux aspects du développement de composants sont communs aux deux interfaces utilisateur, vous êtes donc invité à lire la page Principes de base des composants AEM avant d’utiliser cette page qui traite des particularités de l’IU classique.
NOTE
Les langages HTL (HTML Template Language) et JSP peuvent tous deux être utilisés pour développer des composants pour l’IU classique. Cependant, cette page illustre le développement avec JSP. Cela est simplement dû au fait que JSP est traditionnellement utilisé dans l’IU classique.
HTL est désormais le langage de script recommandé pour AEM. Pour comparer les deux méthodes, reportez-vous aux sections HTL et Développement de composants AEM.

Structure structure

La structure de base d’un composant est traitée à la page Principes de base des composants AEM qui s’applique aux interfaces utilisateur classique et tactile. Même si vous n’avez pas besoin d’utiliser les paramètres de l’interface utilisateur tactile dans votre nouveau composant, il peut être utile de les connaître lors de l’héritage de composants existants.

Scripts JSP jsp-scripts

Les scripts ou servlets JSP peuvent être utilisés pour effectuer le rendu des composants. Selon les règles de traitement des requêtes de Sling, le nom du script par défaut est :

<*componentname*>.jsp

global.jsp global-jsp

Le fichier de script JSP global.jsp est utilisé pour fournir un accès rapide à des objets spécifiques (accéder à du contenu, par exemple) à n’importe quel fichier de script JSP utilisé pour le rendu d’un composant.

Par conséquent, global.jsp doit être inclus dans chaque script JSP de rendu de composant dans lequel un ou plusieurs des objets fournis dans global.jsp sont utilisés.

L’emplacement du fichier global.jsp par défaut est le suivant :

/libs/foundation/global.jsp

NOTE
Le chemin d’accès /libs/wcm/global.jsp, qui était utilisé par les versions CQ 5.3 et antérieures, est désormais obsolète.

Fonction de global.jsp, des API utilisées et des bibliothèques de balises function-of-global-jsp-used-apis-and-taglibs

Vous trouverez, ci-dessous, les objets les plus importants fournis à partir du fichier global.jsp par défaut :

Résumé :

  • <cq:defineObjects />

    • slingRequest – Objet Requête enveloppé (SlingHttpServletRequest)
    • slingResponse – Objet Réponse enveloppé (SlingHttpServletResponse)
    • resource – Objet Ressource Sling (slingRequest.getResource();)
    • resourceResolver – Objet Résolveur de ressources Sling (slingRequest.getResoucreResolver();)
    • currentNode– Nœud JCR résolu pour la requête
    • log – Enregistreur par défaut ().
    • sling – Assistant de script Sling
    • properties – Propriétés de la ressource gérée (resource.adaptTo(ValueMap.class);)
    • pageProperties – Propriétés de la page de la ressource gérée
    • pageManager – Gestionnaire de pages permettant d’accéder aux pages de contenu AEM (resourceResolver.adaptTo(PageManager.class);)
    • component – Objet du composant AEM en cours
    • designer – Objet Designer permettant de récupérer des informations de conception (resourceResolver.adaptTo(Designer.class);)
    • currentDesign – Conception de la ressource gérée
    • currentStyle – Style de la ressource gérée

Accès au contenu accessing-content

Il existe trois méthodes pour accéder au contenu dans AEM WCM :

  • Par le biais de l’objet de propriétés introduit dans global.jsp :

    L’objet de propriétés est une instance d’une ValueMap (voir API Sling) et contient toutes les propriétés de la ressource active.

    Exemple : String pageTitle = properties.get("jcr:title", "no title"); utilisé dans le script de rendu d’un composant de page.

    Exemple : String paragraphTitle = properties.get("jcr:title", "no title"); utilisé dans le script de rendu d’un composant de paragraphe standard.

  • Par le biais de l’objet currentPage introduit dans global.jsp :

    L’objet currentPage est une instance d’une page (voir API AEM). La classe de page fournit plusieurs méthodes d’accès au contenu.

    Exemple : String pageTitle = currentPage.getTitle();

  • Par le biais de l’objet currentNode introduit dans global.jsp :

    L’objet currentNode est une instance d’un nœud (voir API JCR). Les propriétés d’un nœud sont accessibles via la méthode getProperty().

    Exemple : String pageTitle = currentNode.getProperty("jcr:title");

Bibliothèques de balises JSP jsp-tag-libraries

Les bibliothèques de balises CQ et Sling vous donnent accès à des fonctions spécifiques à utiliser dans le script JSP de vos modèles et composants.

Pour plus d’informations, consultez le document Bibliothèques de balises.

Utilisation de bibliothèques de HTMLS côté client using-client-side-html-libraries

Les sites web modernes reposent principalement sur un traitement côté client piloté par du code JavaScript et CSS complexe. Organiser et optimiser la diffusion de ce code est une opération qui peut se révéler complexe.

Pour résoudre ce problème, AEM fournit des dossiers de bibliothèques côté client qui permettent de stocker le code côté client dans le référentiel, de le classer par catégorie et de définir quand et comment chaque catégorie de code doit être diffusée au client. Le système de bibliothèque côté client se charge alors de la génération des liens appropriés dans la page Web finale pour charger le code correct.

Pour plus d’informations, consultez le document Utilisation de bibliothèques HTML côté client.

Boîte de dialogue dialog

Votre composant aura besoin d’une boîte de dialogue pour que les auteurs puissent ajouter et configurer le contenu.

Pour plus d’informations, consultez Composants AEM – Principes de base.

Configuration du comportement de modification configuring-the-edit-behavior

Vous pouvez configurer le comportement de modification d’un composant. Cela inclut les attributs tels que les actions disponibles pour le composant, les caractéristiques de l’éditeur statique et les écouteurs liés aux événements sur le composant. La configuration est commune aux IU tactile et classique, bien qu’avec certaines différences spécifiques.

La configuration du comportement de modification d’un composant s’effectue en ajoutant un nœud cq:editConfig de type cq:EditConfig sous le nœud de composant (de type cq:Component), ainsi qu’en ajoutant des nœuds enfants et des propriétés spécifiques.

Utilisation et extension de widgets ExtJS using-and-extending-extjs-widgets

Pour plus d’informations, consultez Utilisation et extension de widgets ExtJS.

Utilisation de xtypes pour les widgets ExtJS using-xtypes-for-extjs-widgets

Voir Utilisation de xtypes pour plus d’informations.

Développement de nouveaux composants developing-new-components

Cette section décrit comment créer vos propres composants et les ajouter au système de paragraphes.

Pour commencer rapidement, une méthode consiste à copier un élément existant, puis à effectuer les modifications de votre choix.

Un exemple de développement d’un composant est décrit en détail dans la section Extension du composant Texte et image - Exemple.

Développement d’un nouveau composant (adaptation d’un composant existant) develop-a-new-component-adapt-existing-component

Pour développer de nouveaux composants pour AEM en fonction du composant existant, vous pouvez copier le composant, créer un fichier JavaScript pour le nouveau composant et le stocker dans un emplacement accessible à AEM (voir également Personnalisation des composants et autres éléments) :

  1. À l’aide de CRXDE Lite, créez un dossier de composants dans :

    / apps/<myProject>/components/<myComponent>

    Recréez la structure de noeud comme dans libs, puis copiez la définition d’un composant existant, tel que le composant Texte . Par exemple, pour personnaliser le composant Texte, copiez :

    • de /libs/foundation/components/text
    • vers /apps/myProject/components/text
  2. Modifiez le jcr:title en tenant compte de son nouveau nom.

  3. Ouvrez le nouveau dossier de composants et apportez les modifications nécessaires. Supprimez également toutes les informations superflues contenues dans le dossier.

    Vous pouvez apporter des modifications telles que :

    • ajout d’un nouveau champ dans la boîte de dialogue

      • cq:dialog : boîte de dialogue pour l’interface utilisateur tactile
      • dialog : boîte de dialogue pour l’interface utilisateur classique
    • Remplacer le fichier .jsp (lui donner le nom du nouveau composant) ou

    • Retravailler complètement le composant, si vous le souhaitez

    Par exemple, si vous prenez une copie du composant Texte standard, vous pouvez ajouter un champ supplémentaire à la boîte de dialogue, puis mettre à jour le fichier .jsp pour traiter l’entrée qui y est effectuée.

    note note
    NOTE
    Un composant pour :
    • l’interface utilisateur tactile utilise des composants Granite ;
    • L’interface utilisateur classique utilise Widgets ExtJS
    note note
    NOTE
    Une boîte de dialogue définie pour l’IU classique fonctionnera dans l’IU tactile.
    Une boîte de dialogue définie pour l’IU tactile ne fonctionnera pas dans l’IU classique.
    En fonction de l’instance et de l’environnement de création, vous pouvez définir les deux types de boîte de dialogue pour votre composant.
  4. L’un des nœuds suivants doit être présent et correctement initialisé pour que le nouveau composant puisse s’afficher :

    • cq:dialog : boîte de dialogue pour l’interface utilisateur tactile
    • dialog : boîte de dialogue pour l’interface utilisateur classique
    • cq:editConfig : comportement des composants dans l’environnement de modification (glisser-déposer, par exemple)
    • design_dialog : boîte de dialogue pour le mode Création (interface utilisateur classique uniquement)
  5. Activez le nouveau composant dans votre système de paragraphes en effectuant l’une des opérations suivantes :

    • Utilisez CRXDE Lite pour ajouter la valeur <path-to-component> (par exemple : /apps/geometrixx/components/myComponent) à la propriété Composants du nœud /etc/designs/geometrixx/jcr:content/contentpage/par.
    • suivez les instructions de la section Ajout de nouveaux composants aux systèmes de paragraphes
  6. Dans AEM WCM, ouvrez une page de votre site web et insérez un nouveau paragraphe du type que vous venez de créer pour vous assurer que le composant fonctionne correctement.

NOTE
Pour afficher des statistiques de durée pour le chargement d’une page, vous pouvez utiliser la combinaison de touches Ctrl+Maj+U, avec ?debugClientLibs=true défini dans l’URL.

Ajout d’un nouveau composant au système de paragraphes (mode de conception) adding-a-new-component-to-the-paragraph-system-design-mode

Une fois le composant développé, vous l’ajoutez au système de paragraphes, ce qui permet aux auteurs de sélectionner et d’utiliser le composant lors de la modification d’une page.

  1. Accédez à une page de votre environnement de création qui utilise le système de paragraphes ; par exemple, <contentPath>/Test.html.

  2. Pour basculer vers le mode Création, effectuez l’une des opérations suivantes :

    • Ajoutez ?wcmmode=design à la fin de l’URL et accédez-y à nouveau. Par exemple :

      <contextPath>/ Test.html?wcmmode=design

    • clic sur Conception dans le sidekick

    Vous êtes désormais en mode de conception et pouvez modifier le système de paragraphes.

  3. Cliquez sur Modifier.

    Une liste des composants appartenant au système de paragraphes s’affiche. Votre nouveau composant est également répertorié.

    Les composants peuvent être activés (ou désactivés) pour déterminer lesquels sont proposés à l’auteur lors de la modification d’une page.

  4. Activez votre composant, puis revenez au mode d’édition normal pour confirmer qu’il est disponible.

Extension du composant Texte et image - Exemple extending-the-text-and-image-component-an-example

Cette section fournit un exemple d’extension du composant standard Texte et Image, largement utilisé, avec une fonctionnalité de placement d’image configurable.

L’extension au composant texte et image permet aux éditeurs d’utiliser toutes les fonctionnalités existantes du composant et d’avoir une option supplémentaire pour spécifier l’emplacement de l’image :

  • Sur le côté gauche du texte (comportement actuel et nouvelle valeur par défaut)
  • Ainsi que sur le côté droit

Après avoir étendu ce composant, vous pouvez configurer le placement d’image par le biais de la boîte de dialogue du composant.

Les techniques suivantes sont décrites dans cet exercice :

  • Copie d’un noeud de composant existant et modification de ses métadonnées
  • Modification de la boîte de dialogue du composant, y compris l’héritage des widgets des boîtes de dialogue parentes
  • Modification du script du composant pour mettre en oeuvre la nouvelle fonctionnalité
NOTE
Cet exemple concerne l’IU classique.
NOTE
Cet exemple est basé sur l’échantillon de contenu Geometrixx. Celui-ci n’est plus fourni avec AEM et a été remplacé par We.Retail. Pour savoir comment télécharger et installer Geometrixx, consultez le document Implémentation de référence We.Retail.

Extension du composant textimage existant extending-the-existing-textimage-component

Pour créer le composant, nous allons nous baser sur le composant textimage standard et le modifier. Nous allons stocker le nouveau composant dans l’exemple d’application de gestion de contenu Web Geometrixx AEM.

  1. Copiez le composant textimage standard depuis /libs/foundation/components/textimage dans le dossier de composants Geometrixx, /apps/geometrixx/components, en utilisant textimage comme nom de nœud cible. (Pour copier le composant, accédez à son emplacement, cliquez avec le bouton droit de la souris, sélectionnez Copier, puis accédez au répertoire cible.)

    chlimage_1-59

  2. Pour que cet exemple reste simple, accédez au composant que vous avez copié et supprimez tous les sous-nœuds du nouveau nœud textimage, à l’exception de ceux mentionnés ci-dessous :

    • définition de boîte de dialogue : textimage/dialog
    • script de composant : textimage/textimage.jsp
    • nœud de configuration d’édition (autorisant le déplacement de ressources par glisser-déposer) : textimage/cq:editConfig
    note note
    NOTE
    La définition de la boîte de dialogue dépend de l’interface utilisateur :
    • Interface utilisateur optimisée pour les écrans tactiles : textimage/cq:dialog
    • Interface utilisateur classique : textimage/dialog
  3. Modifiez les métadonnées du composant :

    • Nom du composant

      • Définissez jcr:description sur Text Image Component (Extended).
      • Définissez jcr:title sur Text Image (Extended).
    • Groupe où le composant est répertorié dans le sidekick (laisser tel quel)

      • Conservez la définition de componentGroup sur General.
    • Composant parent pour le nouveau composant (le composant textimage standard)

      • Définissez sling:resourceSuperType sur foundation/components/textimage.

    Après cette étape, le nœud de composant ressemble à ceci :

    chlimage_1-60

  4. Modifiez la propriété sling:resourceType du nœud de configuration d’édition de l’image (propriété : textimage/cq:editConfig/cq:dropTargets/image/parameters/sling:resourceType) sur geometrixx/components/textimage..

    De cette manière, lorsqu’une image est déposée sur le composant de la page, la propriété sling:resourceType du composant textimage étendu est définie sur geometrixx/components/textimage..

  5. Modifiez la boîte de dialogue du composant pour inclure la nouvelle option. Le nouveau composant hérite des parties de la boîte de dialogue qui sont identiques à celles de l’original. Le seul ajout que nous faisons est d'étendre la variable Avancé , ajout d’un Position de l’image liste déroulante, avec options Left et Right:

    • Laissez les propriétés textimage/dialog telles quelles.

    Notez que textimage/dialog/items comporte quatre sous-nœuds, tab1 à tab4, qui représentent les quatre onglets de la boîte de dialogue textimage.

    • Pour les deux premiers onglets (tab1 et tab2) :

      • Modifiez xtype en cqinclude (pour hériter du composant standard).
      • Ajoutez une propriété path avec les valeurs /libs/foundation/components/textimage/dialog/items/tab1.infinity.json et /libs/foundation/components/textimage/dialog/items/tab2.infinity.json, respectivement.
      • Supprimez toutes les autres propriétés ou sous-noeuds.
    • Pour tab3 :

      • Ne modifiez pas les propriétés et les sous-noeuds.

      • Ajoutez une nouvelle définition de champ à tab3/items, la position du nœud de type cq:Widget.

      • Définissez les propriétés suivantes (du type String) pour le nouveau nœud tab3/items/position :

        • name: ./imagePosition
        • xtype: selection
        • fieldLabel: Image Position
        • type: select
      • Ajoutez un sous-nœud position/options de type cq:WidgetCollection pour représenter les deux options de positionnement d’images. En dessous, créez deux nœuds, o1 et o2, de type nt:unstructured.

      • Pour le nœud position/options/o1, définissez les propriétés : text sur Left et value sur left.

      • Pour le nœud position/options/o2, définissez les propriétés : text sur Right et value sur right.

    • Supprimez tab4.

    La position de l’image est conservée dans le contenu en tant que propriété imagePosition du nœud représentant le paragraphe textimage. Après avoir suivi ces étapes, la boîte de dialogue du composant ressemble à ceci :

    chlimage_1-61

  6. Étendez le script du composant, textimage.jsp, avec une gestion supplémentaire du nouveau paramètre :

    code language-xml
    Image image = new Image(resource, "image");
    
    if (image.hasContent() || WCMMode.fromRequest(request) == WCMMode.EDIT) {
         image.loadStyleData(currentStyle);
    

    Nous allons remplacer le fragment de code %><div class="image"><% par le nouveau code qui génère un style personnalisé pour cette balise.

    code language-xml
    // todo: add new CSS class for the 'right image' instead of using
    // the style attribute
    String style="";
         if (properties.get("imagePosition", "left").equals("right")) {
              style = "style=\"float:right\"";
         }
         %><div <%= style %> class="image"><%
    
  7. Enregistrez le composant dans le référentiel. Le composant est prêt à être testé.

Vérification du nouveau composant checking-the-new-component

Une fois le composant développé, vous pouvez l’ajouter au système de paragraphes, ce qui permet aux auteurs de sélectionner et d’utiliser le composant lors de la modification d’une page. Ces étapes vous permettent de tester le composant.

  1. Ouvrez une page en Geometrixx, par exemple en anglais/société.
  2. Passez en mode de conception en cliquant sur Conception dans le sidekick.
  3. Modifiez la conception du système de paragraphes en cliquant sur Modifier dans le système de paragraphes au milieu de la page. Une liste des composants, qui peuvent être placés dans le système de paragraphes, s’affiche. Elle doit inclure votre nouveau composant, Texte Image (Étendu) . Activez-le pour le système de paragraphes en le sélectionnant et en cliquant sur OK .
  4. Revenez au mode d’édition.
  5. Ajoutez le paragraphe Image texte (étendue) au système de paragraphes, initialisez le texte et l’image avec un exemple de contenu. Enregistrez les modifications.
  6. Ouvrez la boîte de dialogue du paragraphe de texte et d’image, définissez la position de l’image dans l’onglet Avancé sur Droite , puis cliquez sur OK pour enregistrer les modifications.
  7. Le rendu du paragraphe est effectué avec l’image à droite.
  8. Le composant est maintenant prêt à l’emploi.

Le composant stocke son contenu dans un paragraphe sur la page Société.

Désactivation de la fonctionnalité de téléchargement du composant Image disable-upload-capability-of-the-image-component

Pour désactiver cette fonctionnalité, nous allons utiliser le composant image standard et le modifier. Nous allons stocker le nouveau composant dans l’exemple d’application Geometrixx.

  1. Copiez le composant image standard depuis /libs/foundation/components/image dans le dossier de composants Geometrixx, /apps/geometrixx/components, en utilisant « image » comme nom de nœud cible.

    chlimage_1-62

  2. Modifiez les métadonnées du composant :

    • Définissez jcr:title sur Image (Extended).
  3. Accédez à /apps/geometrixx/components/image/dialog/items/image.

  4. Ajouter une nouvelle propriété :

    • Nom  : allowUpload
    • Type  : String
    • Valeur  : false

    chlimage_1-63

  5. Cliquez sur Enregistrer tout. Le composant est prêt à être testé.

  6. Ouvrez une page en Geometrixx, par exemple en anglais/société.

  7. Passez en mode de conception et activez Image (étendu).

  8. Revenez au mode d’édition et ajoutez-le au système de paragraphes. Sur les images suivantes, vous pouvez voir les différences entre le composant d’image d’origine et celui que vous venez de créer.

    Composant image d’origine :

    chlimage_1-64

    Votre nouveau composant image :

    chlimage_1-65

  9. Le composant est maintenant prêt à l’emploi.

recommendation-more-help
2315f3f5-cb4a-4530-9999-30c8319c520e