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.
Dans l’instance de publication, les composants réalisent le rendu du contenu en le présentant comme vous le souhaitez aux visiteurs et visiteuses de votre site web.
Cette page est la suite du document Composants AEM – Notions de base.
Les composants sous /libs/cq/gui/components/authoring/dialog
s’utilisent uniquement dans l’éditeur (boîtes de dialogue de composants dans l’instance de création). S’ils sont utilisés ailleurs (par exemple dans une boîte de dialogue d’assistant), ils peuvent ne pas se comporter comme prévu.
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.
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.
Selon le composant que vous souhaitez implémenter, il peut être possible d’optimiser ou de personnaliser une instance existante, plutôt que de définir et de développer l’ensemble de la structure à partir de zéro.
Lors de l’optimisation ou de la personnalisation d’un composant existant ou d’une boîte de dialogue existanet, 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.
L’optimisation d’un composant existant peut être réalisée avec la Hiérarchie du type de ressource et les mécanismes d’héritage qui s’y rapportent.
Il est également possible de redéfinir les composants avec une superposition en fonction de la logique du chemin de recherche. Cependant, dans ce cas, Sling Resource Merger n’est pas déclenché et /apps
doit définir le recouvrement en entier.
Le composant de fragment de contenu peut également être personnalisé et optimisé, bien que la structure complète et les relations avec les ressources doivent être prises en compte.
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 optimiser une boîte de dialogue de composant.
Voir Sling Resource Merger pour plus d’informations.
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.
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 et développeuses web qui souhaitent créer des sites eb d’entreprise robustes, le langage HTL permet d’améliorer la sécurité et l’efficacité du développement.
Bien que HTL et JSP puissent être utilisés pour le développement de composants, nous allons illustrer le développement avec HTL sur cette page, car il s’agit du langage de script recommandé pour AEM.
Cette logique facultative sélectionne et/ou calcule le contenu dont il faut réaliser le rendu. Elle est appelée à 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.
L’Use-API Java HTL permet à un fichier HTL d’accéder aux méthodes d’assistance dans une classe Java personnalisée. Cela vous permet d’utiliser le code JavaScript pour implémenter la logique de sélection et de configuration du contenu du composant.
L’Use-API JavaScript HTL permet à un fichier HTL d’accéder au code d’assistance écrit en JavaScript. Vous pouvez ainsi utiliser du code JavaScript pour implémenter la logique de sélection et de configuration du contenu du composant.
Les sites web modernes reposent largement sur un traitement côté client piloté par un 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 Dossiers de bibliothèques côté client, qui vous permet de stocker votre code côté client dans le référentiel, de l’organiser en catégories 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.
Consultez Utilisation de bibliothèques HTML côté client pour plus d’informations.
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.
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.
Dans l’IU tactile, seules les valeurs EDIT
et PREVIEW
sont utilisées pour le cookie Mode Gestion de contenu Web.
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).
Coral UI et Granite UI définissent l’aspect moderne d’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. Si nécessaire, vous pouvez étendre cette sélection et créer votre propre widget.
Pour plus d’informations, consultez :
IU Coral
IU Granite
En raison de la nature des composants de l’IU Granite (et des différences avec les widgets ExtJS), il existe des différences entre la façon dont les composants interagissent avec l’IU tactile et l’IU classique.
Les boîtes de dialogue pour 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
;
utilisent le framework de l’interface utilisateur Granite ;
contiennent une structure de nœud décrivant les champs contenus dans la boîte de dialogue.
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, car 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
Si un composant ne possède pas de boîte de dialogue définie pour l’IU tactile, la boîte de dialogue de l’IU classique est utilisée comme solution de secours à l’intérieur d’une couche de compatibilité. Pour personnaliser ce type de boîte de dialogue, vous devez personnaliser la boîte de dialogue de l’IU classique. Consultez Composants AEM pour l’IU classique.
Voir :
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éation d’un composant de champ d’IU Granite.
Pour plus d’informations sur l’interface utilisateur Granite, voir Documentation de l’interface utilisateur 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. Pour créer un champ de formulaire, vous devez créer un type de ressource, ce qui é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).
Cela diffère de l’IU classique où les widgets sont représentés par des nœuds cq:Widgets
, chacun avec un xtype
particulier pour établir la relation avec le widget ExtJS correspondant. Du point de vue de la mise en œuvre, ces widgets sont rendus côté client par le framework ExtJS.
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.
Si vous souhaitez définir le style et le comportement de votre composant, vous pouvez créer une bibliothèque cliente qui définit vos CSS/LESS et JS personnalisés.
Pour que votre bibliothèque cliente soit chargée uniquement pour votre boîte de dialogue de composant (c’est-à-dire qu’elle ne sera pas chargée pour un autre composant), vous devez définir la propriété . extraClientlibs
de votre boîte de dialogue au nom de catégorie de la bibliothèque cliente que vous avez créée. Ceci est conseillé si votre bibliothèque cliente est assez grande et/ou si votre champ est spécifique à cette boîte de dialogue et ne sera pas nécessaire dans d’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. Faites-le 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, reportez-vous à :
cqgems/customizingfield/components/colorpicker/clientlibs
Selon vos besoins, vous pouvez effectuer l’une des opérations suivantes :
sling:resourceSuperType
)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"]
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 des listeners dans la structure de contenu.
Pour injecter une logique dans votre champ, vous devez :
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, reportez-vous à :
cqgems/customizingfield/components/clientlibs/customizingfield
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 de listener JS (ou tout autre code tout court) 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.
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.
Pour marquer un champ donné comme obligatoire, définissez la propriété suivante sur le nœud de contenu de votre champ :
required
Boolean
Pour consulter un exemple, reportez-vous à :
/libs/foundation/components/page/cq:dialog/content/items/tabs/items/basic/items/column/items/title/items/title
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-valdiation
documentation de Granite pour plus de détails.
Pour consulter des exemples, voir :
cqgems/customizingfield/components/clientlibs/customizingfield/js/validations.js
/libs/cq/gui/components/authoring/dialog/clientlibs/dialog/js/validations.js
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 :
cq:design_dialog
nt:unstructured
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 possèdent tous deux un éditeur intégré.
Un éditeur intégré n’est pas nécessaire/déterminant pour chaque type de composant.
Voir Extension de la création de pages - Ajout d’un nouvel éditeur intégré pour plus d’informations.
Le Barre d’outils de composant permet aux utilisateurs 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.
Si votre nouveau composant fait référence au contenu d’autres pages, vous pouvez déterminer si vous souhaitez qu’il affecte les sections Contenu emprunté et Contenu prêté du rail de références.
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 entrée dans la définition, en spécifiant votre composant, ainsi que la propriété à vérifier. Par exemple :
/apps/<*your-Project*>/components/reference@parentPath
Lorsque vous utilisez AEM, plusieurs méthodes permettent de gérer les paramètres de configuration de ces services. Voir Configuration d’OSGi pour plus d’informations et les pratiques recommandées.
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 :
components
sur le système de paragraphe d’un modèle.AEM offre la possibilité de configurer un système de paragraphes sur votre page afin qu’une instance de votre nouveau composant soit automatiquement créée lorsqu’un utilisateur ou une utilisatrice 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 ressource-à-composant requise, peuvent être configurés :
Sous la définition de paragraphe de votre conception de page. Par exemple :
/etc/designs/<myApp>/page/par
Créez un nœud :
cq:authoring
nt:unstructured
Dans ce cas, créez un noeud destiné à contenir tous les mappages ressource-composant :
assetToComponentMapping
nt:unstructured
Pour chaque mappage actif à composant, créez un nœud :
nt:unstructured
Chacun possédant les propriétés suivantes :
assetGroup
:
String
media
assetMimetype
:
String
image/*
droptarget
:
String
image
resourceType
:
String
foundation/components/image
type
:
String
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.
La création automatique d’instances de composant est désormais facile à configurer dans l’interface utilisateur lors de l’utilisation de composants de base et de modèles modifiables. Consultez Création de modèles de page pour plus d’informations sur la définition des composants automatiquement associés à des types de média donnés.
L’extension AEM Brackets fournit un workflow fluide pour modifier les composants AEM et les bibliothèques clientes. Elle se base sur l’éditeur de code Brackets.
L’extension :
Brackets est le mécanisme recommandé pour créer des composants. Il remplace la fonctionnalité CRXDE Lite - Créer un composant, qui a été conçue pour l’interface utilisateur 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
Les composants :
cq:listener
code qui utilise des fonctions spécifiques à l’IU classiquecq:listener
qui utilise des fonctions spécifiques à l’IU classique.Boîtes de dialogue
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’interface utilisateur classique et l’interface utilisateur tactile pendant la période de migration (scénario habituel), vous devez implémenter un système de basculement 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
}
En tant que développeur ou développeuse, vous aimez accéder facilement à la documentation d’un composant afin de pouvoir comprendre rapidement :
Pour cette raison, il est facile de rendre tout markdown de documentation existant disponible dans le composant lui-même.
Placez un fichier README.md
dans la structure du composant. Ce markdown s’affiche dans la console du composant.
Le MarkDown pris en charge est le même que pour les fragments de contenu.