Développer des composants AEM

Les composants AEM servent à stocker, mettre en forme et générer le rendu du contenu diffusé dans vos pages Web.

• Lors de la création de pages, les composants permettent aux auteurs de modifier et de configurer le contenu.

  • Lors de la construction d’un site marchand, les composants peuvent, par exemple, collecter et afficher des informations issues du catalogue.
    Pour plus d’informations, consultez Développement du e-commerce.

  • Lors de la construction d’un site de communauté, les composants peuvent fournir des informations et en collecter auprès des visiteurs.
    Pour plus d’informations, consultez Développement de communautés.

• Sur l’instance de publication, les composants affichent votre contenu, le présentant selon vos besoins aux visiteurs de votre site web.

Exemples de code

Cette page contient la documentation de référence (ou des liens vers la documentation de référence) requise pour développer des composants AEM. Consultez Développement de composants AEM - Exemples de code pour des exemples pratiques.

Structure

La structure de base d’un composant est décrite à la page Composants AEM – Notions de base. Ce document traite à la fois les interfaces utilisateur tactile et classique. Même si vous n’avez pas besoin d’utiliser les paramètres classiques de votre nouveau composant, il peut être utile d’en prendre connaissance lors de l’héritage de composants existants.

Extension des composants et des boîtes de dialogue existants

Selon le composant que vous souhaitez implémenter, il peut être possible d’étendre ou de personnaliser une instance existante, plutôt que de définir et de développer l’ensemble de l’instance. structure à partir de zéro.

Lors de l’extension ou de la personnalisation d’un composant ou d’une boîte de dialogue existant, vous pouvez copier ou répliquer la structure entière ou la structure requise pour la boîte de dialogue avant d’apporter vos modifications.

Extension d’un composant existant

L’extension d’un composant existant peut être réalisée avec Hiérarchie du type de ressource et les mécanismes d'héritage qui s'y rapportent.

Personnalisation d’une boîte de dialogue de composant existante

Il est également possible de remplacer une boîte de dialogue de composant en utilisant le Sling Resource Merger et en définissant la propriété sling:resourceSuperType.

Ainsi, vous avez seulement besoin de redéfinir les modifications à apporter et non pas toute la boîte de dialogue (en utilisant sling:resourceSuperType). Cette méthode est désormais recommandée pour étendre une boîte de dialogue de composant.

Voir Sling Resource Merger pour plus d’informations.

Définition du balisage

Votre composant est rendu dans le langage HTML. Votre composant doit définir les balises HTML nécessaires pour réaliser le rendu du contenu selon les besoins, dans les environnements de création et de publication.

Utilisation du langage de modèle de HTML

Le langage de modèle HTML (HTL) a été introduit avec AEM 6.0 et remplace JSP (JavaServer Pages) en tant que système de modèle côté serveur privilégié et recommandé pour HTML. Pour les développeurs web qui doivent créer des sites web d’entreprise performants, HTL contribue à améliorer l’efficacité de la sécurité et du développement.

Développement de la logique de contenu

Cette logique facultative sélectionne et/ou calcule le contenu dont il faut réaliser le rendu. Il est appelé à partir d’expressions HTL avec le modèle Use-API approprié.

Le mécanisme permettant de séparer la logique de l’aspect aide à définir clairement ce qui est appelé pour un affichage donné. Cela permet également une logique différente pour différentes vues d’une même ressource.

Utilisation de Java

L’Use-API Java HTL permet à un fichier HTL d’accéder aux méthodes d’assistance dans une classe Java personnalisée. Vous pouvez ainsi utiliser du code Java pour implémenter la logique de sélection et de configuration du contenu du composant.

Utilisation de JavaScript

L’Use-API JavaScript HTL permet à un fichier HTL d’accéder au code d’assistance écrit en JavaScript. Cela permet d’utiliser le code JavaScript pour implémenter la logique de sélection et de configuration du contenu du composant.

Utilisation de bibliothèques de HTMLS côté client

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.

Lecture Utilisation de bibliothèques de HTMLS côté client pour plus d’informations.

Configuration du comportement de modification

Vous pouvez configurer le comportement de modification d’un composant, notamment ses attributs tels que les actions disponibles pour le composant, les caractéristiques de l’éditeur local et les écouteurs liés aux événements sur le composant. La configuration est commune aux interfaces utilisateur tactile et classique, avec toutefois 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.

Configuration du comportement de prévisualisation

Le cookie Mode Gestion de contenu Web est défini lors du passage en mode Aperçu même lorsque la page n’est pas rafraîchie.

Pour les composants dont le rendu est sensible au Mode Gestion de contenu Web, ils doivent être définis de manière à s’actualiser eux-mêmes, puis s’appuyer sur la valeur du cookie.

Création et configuration d’une boîte de dialogue

Les boîtes de dialogue permettent à l’auteur d’interagir avec le composant. L’utilisation d’une boîte de dialogue permet aux auteurs et aux administrateurs de modifier le contenu, de configurer le composant ou de définir les paramètres de conception (dans une Boîte de dialogue de conception).

IU Coral et IU Granite

IU Coral et IU Granite définir l'aspect moderne de l'AEM.

L’IU Granite offre un vaste éventail de composants de base (widgets) nécessaires pour créer une boîte de dialogue dans l’environnement de création. Au besoin, vous pouvez étendre cette sélection et créer votre propre widget.

Pour plus d’informations, voir :

• IU Coral

  • Fournit une interface utilisateur uniforme dans toutes les solutions cloud.
  • Concepts de l’IU tactile AEM - IU Coral
  • Guide de l’IU Coral

• IU Granite

  • Fournit le balisage de l’IU Coral encapsulé dans les composants Sling pour la création de consoles d’interface utilisateur et de boîtes de dialogue.
  • Concepts de l’IU tactile AEM - IU Granite
  • Documentation relative à l’interface utilisateur Granite

Création d’une boîte de dialogue

Boîtes de dialogue de l’interface utilisateur tactile :

• sont nommées cq:dialog ;

• sont définies sous forme de nœud nt:unstructured avec le jeu de propriétés sling:resourceType ;

• sont situées sous leur nœud cq:Component et à côté de leur définition de composant ;

• sont rendues côté serveur (en tant que composants Sling), en fonction de la structure de leur contenu et de la propriété sling:resourceType ;

• utilisez la structure de l’interface utilisateur Granite.

• contiennent une structure de noeud décrivant les champs de la boîte de dialogue.

  • Ces nœuds sont nt:unstructured avec la propriété sling:resourceType obligatoire.

Un exemple de structure de nœud pourrait être :

newComponent (cq:Component)
  cq:dialog (nt:unstructured)
    content
      layout
      items
        column
          items
            file
            description

La personnalisation d’une boîte de dialogue est similaire au développement d’un composant dans la mesure où la boîte de dialogue est elle-même un composant (c’est-à-dire un balisage rendu par un script de composant avec le comportement/style fourni par une bibliothèque cliente).

Pour consulter des exemples, voir :

• /libs/foundation/components/text/cq:dialog
• /libs/foundation/components/download/cq:dialog

Personnalisation des champs de boîte de dialogue

Création d’un champ

Les widgets de l’IU tactile sont implémentés en tant que composants de l’IU Granite.

Pour créer un widget à utiliser dans une boîte de dialogue de composant pour l’interface utilisateur tactile, vous devez : créer un composant de champ d’IU Granite ;.

Si vous configurez votre boîte de dialogue comme un conteneur simple pour un élément de formulaire, vous pouvez également voir le contenu principal du contenu de la boîte de dialogue sous la forme de champs de formulaire. La création d’un champ de formulaire nécessite la création d’un type de ressource. Cela équivaut à créer un composant. Pour vous aider dans cette tâche, l’IU Granite propose un composant de champ générique duquel hériter (en utilisant sling:resourceSuperType) :

/libs/granite/ui/components/coral/foundation/form/field

Plus précisément, l’IU Granite offre divers composants de champ qui conviennent pour une utilisation dans des boîtes de dialogue (ou, de manière plus générale, dans des formulaires).

Une fois que vous avez créé votre type de ressource, vous pouvez instancier le champ en ajoutant un nouveau nœud dans la boîte de dialogue, avec la propriété sling:resourceType faisant référence au type de ressource que vous venez d’introduire.

Création d’une bibliothèque cliente pour le style et le comportement

Si vous souhaitez définir le style et le comportement de votre composant, vous pouvez créer un bibliothèque cliente qui définit vos CSS/LESS et JS personnalisés.

Afin que la bibliothèque cliente soit chargée uniquement pour votre boîte de dialogue de composant (c’est-à-dire qu’elle ne soit pas chargée pour un autre composant), vous devez définir la propriété extraClientlibs de la boîte de dialogue sur le nom de catégorie de la bibliothèque cliente que vous venez de créer. Ceci est conseillé si votre bibliothèque cliente est assez volumineuse ou si votre champ est spécifique à cette boîte de dialogue et n’est pas nécessaire dans les autres boîtes de dialogue.

Afin que la bibliothèque cliente soit chargée pour toutes les boîtes de dialogue, définissez la propriété Catégorie de votre bibliothèque cliente sur cq.authoring.dialog. Il s’agit du nom de la catégorie de la bibliothèque cliente qui est incluse par défaut lors du rendu de toutes les boîtes de dialogue. Vous souhaitez le faire si votre bibliothèque cliente est petite et/ou si votre champ est générique et peut être réutilisé dans d’autres boîtes de dialogue.

Pour consulter un exemple, voir :

• cqgems/customizingfield/components/colorpicker/clientlibs

  • fournie par l’exemple de code

Extension (héritage d’un champ)

Selon vos besoins, vous pouvez effectuer l’une des opérations suivantes :

• Étendre un champ de l’IU Granite par héritage de composant (sling:resourceSuperType)
• Étendez un widget donné à partir de la bibliothèque de widgets sous-jacente (dans le cas de l’IU Granite, il s’agit de l’IU Coral), en suivant l’API de bibliothèque de widgets (héritage JS/CSS).

Accès aux champs de boîte de dialogue

Vous pouvez également utiliser les conditions de rendu (rendercondition) pour contrôler qui a accès à des onglets/champs spécifiques dans votre boîte de dialogue. Par exemple :

+ mybutton
  - sling:resourceType = granite/ui/components/coral/foundation/button
  + rendercondition
    - sling:resourceType = myapp/components/renderconditions/group
    - groups = ["administrators"]

Gestion des événements de champ

La méthode de gestion des événements dans les champs de boîte de dialogue est désormais appliquée avec les écouteurs d’une bibliothèque cliente personnalisée. Il s’agit d’un changement par rapport à l’ancienne méthode de écouteurs dans la structure de contenu.

Écouteurs dans une bibliothèque cliente personnalisée

Pour injecter une logique dans votre champ, vous devez :

1. Faites marquer votre champ avec une classe CSS donnée (le hook).
2. Définissez, dans votre bibliothèque cliente, un écouteur JS connecté à ce nom de classe CSS (cela garantit que votre logique personnalisée est limitée à votre champ uniquement et n’affecte pas les autres champs du même type).

Pour ce faire, vous devez connaître la bibliothèque de widgets sous-jacente avec laquelle vous souhaitez interagir. Consultez la documentation relative à l’IU Coral pour identifier l’événement auquel vous voulez réagir. Cette opération est très similaire au processus que vous deviez effectuer avec ExtJS dans le passé : recherchez la page de documentation d’un widget donné, puis vérifiez les détails de son API d’événement.

Pour consulter un exemple, voir :

• cqgems/customizingfield/components/clientlibs/customizingfield

  • fournie par l’exemple de code

Écouteurs dans la structure de contenu

Dans l’IU classique avec ExtJS, il était habituel de trouver des écouteurs pour un widget donné dans la structure de contenu. L’obtention de la même valeur dans l’interface utilisateur tactile est différente, car le code d’écouteur JS (ou tout autre code du tout) n’est plus défini dans le contenu.

La structure du contenu décrit la structure sémantique ; elle ne devrait (doit) pas impliquer la nature du widget sous-jacent. En l’absence de code JS dans la structure du contenu, vous pouvez modifier les détails d’implémentation sans avoir à modifier la structure du contenu. En d’autres termes, vous pouvez modifier la bibliothèque de widgets sans avoir à toucher la structure de contenu.

Détection de la disponibilité de la boîte de dialogue

Si vous utilisez un script JavaScript personnalisé qui doit être exécuté uniquement lorsque la boîte de dialogue est disponible et prête, vous devez écouter l’événement dialog-ready.

Ce événement est déclenché chaque fois que la boîte de dialogue se charge (ou se recharge) et est prête à l’emploi, soit chaque fois qu’une modification (création ou mise à jour) a lieu dans le DOM de la boîte de dialogue.

dialog-ready peut être utilisé pour associer du code personnalisé JavaScript qui effectue des personnalisations dans les champs d’une boîte de dialogue ou pour des tâches similaires.

Validation de champ

Champ obligatoire

Pour marquer un champ donné comme obligatoire, définissez la propriété suivante sur le noeud de contenu de votre champ :

• Nom : required
• Type : Boolean

Pour consulter un exemple, voir :

/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title

Validation de champ (IU Granite)

La validation du champ dans l’IU Granite et les composants de l’IU Granite (équivalent aux widgets) est effectuée à l’aide de l’API foundation-validation. Consultez la foundation-valdiationdocumentation de Granite pour plus de détails.

Pour consulter des exemples, voir :

• cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js

  • fourni par l’exemple de code

• /libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js

Création et configuration d’une boîte de dialogue Conception

La boîte de dialogue Conception est utilisée lorsqu’un composant possède des détails de conception modifiables en mode Conception.

La définition est très similaire à celle d’une boîte de dialogue servant à modifier le contenu, à la différence qu’elle est définie comme un nœud :

• Nom du nœud : cq:design_dialog
• Type : nt:unstructured

Création et configuration d’un éditeur statique

Un éditeur local permet à l’utilisateur de modifier le contenu directement dans le flux de paragraphe, sans avoir besoin d’ouvrir une boîte de dialogue. Par exemple, les composants Texte et Titre standard disposent tous deux d’un éditeur statique.

Un éditeur statique n’est pas nécessaire/significatif pour chaque type de composant.

Voir Extension de la création de pages - Ajout d’un nouvel éditeur statique pour plus d’informations.

Personnalisation de la barre d’outils de composant

Le Barre d’outils de composant permet à l’utilisateur d’accéder à un éventail d’actions pour le composant, telles que la modification, la configuration, la copie et la suppression.

Voir Extension de la création de page - Ajouter une nouvelle action à une barre d’outils de composant pour plus d’informations.

Configuration d’un composant pour le rail de références (emprunté/prêté)

Si votre nouveau composant fait référence au contenu d’autres pages, vous pouvez déterminer si vous souhaitez qu’il affecte la variable Contenu emprunté et Contenu prêté des sections Références Rail.

AEM prêt à l’emploi ne vérifie que le composant Référence. Pour ajouter votre composant, vous devez configurer le bundle OSGi Configuration de référence du contenu de création de gestion de contenu Web.

Créez une nouvelle entrée dans la définition, en spécifiant votre composant, avec la propriété à vérifier. Par exemple :

/apps/<*your-Project*>/components/reference@parentPath

Activation et ajout de votre composant au système de paragraphes

Une fois le composant développé, il doit être activé pour être utilisé dans un système de paragraphes approprié, de sorte qu’il puisse être utilisé sur les pages requises.

Pour ce faire, procédez comme suit :

• using Mode de conception lors de la modification d’une page spécifique.
• en définissant la propriété components sur le système de paragraphe d’un modèle.

Configuration d’un système de paragraphes pour que le glissement d’une ressource crée une instance de composant

AEM offre la possibilité de configurer un système de paragraphes sur votre page afin que une instance de votre nouveau composant est automatiquement créée lorsqu’un utilisateur fait glisser une ressource (appropriée) sur une instance de cette page. (au lieu d’avoir toujours à faire glisser un composant vide sur la page).

Ce comportement et la relation actif-à-composant requise peuvent être configurés :

1. Sous la définition de paragraphe de votre conception de page. Par exemple :

   • /etc/designs/<myApp>/page/par

   Créez un nœud :

   • Nom : cq:authoring
   • Type : nt:unstructured

2. Sous cela, créez un nouveau nœud qui contiendra tous les mappages actif à composant :

   • Nom : assetToComponentMapping
   • Type : nt:unstructured

3. Pour chaque mappage actif à composant, créez un nœud :

   • Nom : text ; il est recommandé que le nom indique l’actif et le type de composant associé, par exemple, « image ».
   • Type : nt:unstructured

   Chacun possédant les propriétés suivantes :

   • assetGroup :

     • Type : String
     • Valeur : groupe auquel l’actif associé appartient, par exemple, media

   • assetMimetype :

     • Type : String
     • Valeur : type mime de l’actif associé, par exemple image/*

   • droptarget :

     • Type : String
     • Valeur : cible de dépôt, par exemple, image

   • resourceType :

     • Type : String
     • Valeur : ressource de composant associée, par exemple, foundation/components/image

   • type :

     • Type : String
     • Valeur : type, par exemple, Images

Pour voir des exemples, reportez-vous à :

• /etc/designs/geometrixx/jcr:content/page/par/cq:authoring
• /etc/designs/geometrixx-outdoors/jcr:content/page/par/cq:authoring
• /etc/designs/geometrixx-media/jcr:content/article/article-content-par/cq:authoring

CODE SUR GITHUB

Vous pouvez trouver le code de cette page sur GitHub.

• Ouvrez le projet aem-project-archetype sur GitHub.
• Téléchargez le projet sous la forme d’un fichier ZIP.

Utilisation de l’extension AEM Brackets

L’extension AEM Brackets fournit un workflow fluide pour modifier les composants AEM et les bibliothèques clientes. Elle est basée sur la variable Brackets éditeur de code.

L’extension :

• Facilite la synchronisation (aucun Maven ou File Vault requis) pour améliorer le rendement des développeurs et permet également aux développeurs de front-end ayant des connaissances limitées en matière d’AEM de participer à des projets.
• Fournit une prise en charge d’HTL, le langage de modèle conçu pour simplifier le développement des composants et renforcer la sécurité.

Migration à partir d’un composant classique

Lors de la migration d’un composant de l’IU classique vers un composant pouvant être utilisé avec l’IU tactile (exclusivement ou conjointement), les problèmes suivants doivent être anticipés :

• HTL

  • L’utilisation d’HTL n’est pas obligatoire, mais si le composant doit être mis à jour, c’est l’occasion idéale pour envisager une migration de JSP vers HTL.

• Les composants :

  • migrent le code cq:listener qui utilise des fonctions spécifiques à l’IU classique ;
  • Plugin RTE. Pour plus d’informations, consultez Configuration de l’éditeur de texte enrichi ;
  • migrent le code cq:listener qui utilise des fonctions spécifiques à l’IU classique.

• Boîtes de dialogue

  • Créez une boîte de dialogue à utiliser dans l’interface utilisateur tactile. Pour des raisons de compatibilité, l’IU tactile peut utiliser la définition d’une boîte de dialogue d’IU classique, si aucune boîte de dialogue n’a été définie pour l’IU tactile.
  • Les Outils de modernisation d’AEM sont fournis pour vous aider à étendre les composants existants.
  • Le mappage d’ExtJS aux composants de l’IU Granite fournit une présentation pratique des xtypes ExtJS et des types de nœud avec les types de ressources équivalents dans l’IU Granite.
  • Personnalisation des champs, pour plus d’informations, consultez la session AEM Gems sur Personnalisation des champs de boîte de dialogue.
  • Migration des types vers Validation de l’IU Granite
  • Utilisation des écouteurs JS, pour plus d’informations, voir Gestion des événements de champ et la session AEM Gems sur Personnalisation des champs de boîte de dialogue.

Migration du code cq:listener

Si vous migrez un projet conçu pour l’IU classique, le code cq:listener (et les bibliothèques clientes associées aux composants) peut utiliser des fonctions spécifiques à l’IU classique (telles que CQ.wcm.*). Pour la migration, vous devez mettre à jour ce code en utilisant les objets/fonctions équivalents dans l’IU tactile.

Si votre projet est complètement migré vers l’interface utilisateur tactile, vous devez remplacer ce code pour utiliser les objets et fonctions appropriés à l’interface utilisateur tactile.

Cependant, si votre projet doit prendre en charge à la fois l’IU classique et l’IU tactile pendant la période de migration (scénario habituel), vous devez mettre en oeuvre un commutateur pour différencier le code distinct référençant les objets appropriés.

Ce mécanisme de basculement peut être implémenté comme suit :

if (Granite.author) {
    // touch UI
} else {
    // classic UI
}

Documentation de votre composant

En tant que développeur, vous souhaitez un accès facile à la documentation des composants afin de pouvoir rapidement comprendre :

• sa description ;
• son utilisation prévue ;
• Structure et propriétés du contenu
• API exposées et points d’extension
• Et ainsi de suite

Pour cette raison, il est facile de rendre tout balisage de documentation existant disponible dans le composant lui-même.

Placez un README.md dans la structure du composant. Cette balise s’affiche dans la variable console de composants.

Le MarkDown pris en charge est le même que pour les fragments de contenu.

Ressources Business.Adobe.com

Multichannel Communication Cms Cloud Mobile Forms Responsive Forms Document Generation Web Content Management