Lorsque vous commencez à développer de nouveaux composants, vous devez comprendre les bases de leur structure et de leur configuration.
Ce processus implique de lire la théorie et d’étudier le vaste éventail d’implémentations de composants possibles dans une instance AEM standard. Cette dernière approche est légèrement compliquée dans la mesure où AEM prend toujours en charge l’IU classique même s’il offre désormais une nouvelle IU tactile, moderne et standard.
Cette section décrit les concepts et les problèmes majeurs et sert d’introduction aux informations dont vous avez besoin pour développer vos propres composants.
Avant de commencer à configurer ou coder votre composant, vous devez vous poser la question suivante :
Avant toute considération sérieuse sur le développement de composants, vous devez savoir quelle IU vos auteurs vont utiliser :
Voir Recommandations d’IU destinées aux clients pour plus de détails.
Les composants peuvent être implémentés de manière à prendre en charge l’IU tactile, l’IU classique ou les deux. Si vous étudiez une instance standard, vous pouvez également remarquer la présence de composants prêts à l’emploi qui ont été conçus à l’origine pour l’IU classique ou l’IU tactile, ou les deux.
Pour cette raison, nous allons aborder dans cette page les notions de base des deux interfaces et expliquer comment les reconnaître.
Adobe recommande d’utiliser l’interface utilisateur tactile pour bénéficier des dernières technologies. Les Outils de modernisation d’AEM peuvent faciliter la migration.
Il est recommandé de garder le code responsable du balisage et du rendu distinct de celui qui contrôle la logique utilisée pour sélectionner le contenu du composant.
Cette approche est compatible avec HTL, un langage de modèle intentionnellement limité pour s’assurer qu’un vrai langage de programmation est utilisé afin de définir la logique métier sous-jacente. Cette logique (facultative) est appelée à partir de HTL avec une commande spécifique. Ce mécanisme met en évidence le code appelé pour une vue donnée et, si nécessaire, autorise une logique spécifique pour différentes vues du même composant.
HTL est un langage de modèle HTML introduit avec AEM 6.0.
Le choix entre l’utilisation de HTL ou de JSP (Java Server Pages) lors du développement de vos propres composants devrait être simple à faire dans la mesure où HTL est aujourd’hui le langage de script recommandé pour AEM.
HTL et JSP peuvent être utilisés pour développer des composants de l’IU classique et de l’IU tactile. Bien que la tendance laisse à supposer que HTL est réservé à l’IU tactile et JSP à l’IU classique, c’est une idée reçue que l’on attribue à une synchronisation fortuite. L’IU tactile et HTL ont été intégrés à AEM à peu près en même temps. Puisque HTL est aujourd’hui le langage recommandé, il est utilisé pour les nouveaux composants, qui sont plus souvent développés pour l’IU tactile.
Les exceptions sont les champs de formulaire de base de l’IU Granite (utilisés dans les boîtes de dialogue). Ceux-ci nécessitent toujours l’utilisation de JSP.
Pour créer vos propres composants à utiliser dans une IU donnée, voir (après avoir lu la présente page) :
Pour commencer rapidement, une méthode consiste à copier un élément existant, puis à effectuer les modifications de votre choix. Pour apprendre à créer vos propres composants et les ajouter au système de paragraphes, voir :
Les composants de rendu de contenu doivent être déployés sur la même instance AEM que le contenu. Par conséquent, tous les composants utilisés pour la création et le rendu des pages sur l’instance d’auteur doivent être déployés sur l’instance de publication. Une fois déployés, les composants sont disponibles pour le rendu des pages activées.
Utilisez les outils suivants pour déplacer vos composants vers l’instance de publication :
Ces mécanismes servent également à transférer votre composant entre d’autres instances, par exemple de l’instance de développement vers celle de test.
Page :
cq:Page
).Systèmes de paragraphes :
parsys
, [responsivegrid](/docs/experience-manager-65/sites-authoring/responsive-layout.md)
).La structure d’un composant AEM est puissante et flexible. Les principales considérations sont les suivantes :
Le type de ressource est un élément clé de la structure.
Ceci est une abstraction qui permet de s’assurer que même lorsque l’aspect change au fil du temps, l’intention reste la durée.
La définition d’un composant peut être décomposée comme suit :
Les composants AEM sont basés sur Sling.
Les composants AEM sont (généralement) stockés sous :
/libs/wcm/foundation/components
/libs/foundation/components
Les composants spécifiques au projet/site sont (généralement) situés sous :
/apps/<myApp>/components
Les composants standard d’AEM sont définis comme cq:Component
et possèdent les éléments clés suivants :
Propriétés jcr :
Liste de propriétés jcr. Celles-ci sont variables et certaines peuvent être facultatives si la structure de base d’un nœud de composant, ses propriétés et ses sous-nœuds sont définis par la définition cq:Component
.
Ressources :
Elles définissent les éléments statiques utilisés par le composant.
Scripts :
Utilisés pour implémenter le comportement de l’instance résultante du composant.
Nœud racine :
<mycomponent> (cq:Component)
– Nœud de hiérarchie du composant.Propriétés vitales :
jcr:title
- Titre du composant. Par exemple utilisé comme libellé lorsque le composant est répertorié dans le navigateur de composants ou le sidekick.
jcr:description
- Description du composant. Peut être utilisé comme indicateur de survol de la souris dans le navigateur de composants ou le sidekick.
Interface utilisateur classique :
icon.png
- Icône du composant.thumbnail.png
- Vignette affichée si le composant est listé dans le système de paragraphe.IU tactile
Nœuds enfants essentiels :
cq:editConfig (cq:EditConfig)
- Définit les propriétés de modification du composant et permet au composant d’apparaître dans le navigateur de composants ou le sidekick.
Remarque : si le composant possède une boîte de dialogue, elle apparaît automatiquement dans le navigateur de composants ou le sidekick, même si le cq:editConfig n’existe pas.
cq:childEditConfig (cq:EditConfig)
– Contrôle les aspects de l’IU de création pour les composants enfants qui ne définissent pas leur propre cq:editConfig
.
Interface utilisateur optimisée pour les écrans tactiles :
cq:dialog
(nt:unstructured
) - Boîte de dialogue pour ce composant. Définit l’interface permettant à l’utilisateur de configurer le composant et/ou de modifier le contenu.cq:design_dialog
(nt:unstructured
) - Modification de la conception du composant.Interface utilisateur classique :
dialog
(cq:Dialog
) - Boîte de dialogue pour ce composant. Définit l’interface permettant à l’utilisateur de configurer le composant et/ou de modifier le contenu.design_dialog
(cq:Dialog
) - Modification de la conception du composant.L’icône ou l’abréviation du composant est définie via les propriétés JCR du composant lorsque le composant est créé par le développeur. Ces propriétés sont évaluées dans l’ordre suivant, la première propriété valide trouvée étant utilisée.
cq:icon
– Propriété de chaîne pointant vers une icône standard dans la bibliothèque de l’IU Coral à afficher dans le navigateur de composants
abbreviation
– Propriété de chaîne servant à personnaliser l’abréviation du nom du composant dans le navigateur de composants
jcr:title
.
abbreviation_commentI18n
, qui est ensuite utilisée comme indice de traduction.cq:icon.png
ou cq:icon.svg
– Icône du composant, affichée dans le navigateur de composants
.png
et .svg
sont pris en charge._cq_icon.png
ou _cq_icon.svg
, par exemple..png
est prioritaire sur .svg
si les deux sont présentsSi aucune des propriétés ci-dessus (cq:icon.png
, cq:icon
, abbreviation
ou cq:icon.svg
) n’existe pour le composant :
sling:resourceSuperType
.jcr:title
du composant actif.Pour annuler l’héritage des icônes à partir de super-composants, la définition d’une propriété abbreviation
vide sur le composant rétablit le comportement par défaut.
La console des composants affiche la façon dont est définie l’icône d’un composant particulier.
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "https://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
<svg version="1.1" id="Layer_1" xmlns="https://www.w3.org/2000/svg" xmlns:xlink="https://www.w3.org/1999/xlink" x="0px" y="0px"
width="20px" height="20px" viewBox="0 0 20 20" enable-background="new 0 0 20 20" xml:space="preserve">
<ellipse cx="5" cy="5" rx="3" ry="3" fill="#707070"/>
<ellipse cx="15" cy="5" rx="4" ry="4" fill="#707070"/>
<ellipse cx="5" cy="15" rx="5" ry="5" fill="#707070"/>
<ellipse cx="15" cy="15" rx="4" ry="4" fill="#707070"/>
</svg>
La plupart des nœuds/propriétés nécessaires pour définir un composant sont communs aux deux interfaces utilisateur, les différences restant indépendantes pour que votre composant puisse fonctionner dans les deux environnements.
Un composant est un nœud de type cq:Component
et possède les propriétés et les nœuds enfants suivants :
Nom |
Type |
Description |
cq:Component |
Composant actif. Un composant possède le type de nœud cq:Component . |
|
componentGroup |
String |
Groupe sous lequel le composant peut être sélectionné dans le navigateur de composants (IU tactile) ou le sidekick (IU classique). Une valeur .hidden est utilisée pour les composants qui ne sont pas sélectionnables dans l’IU, tels que les systèmes de paragraphes réels. |
cq:isContainer |
Boolean |
Indique si le composant est un composant de type « container » qui peut donc contenir d’autres composants, tels qu’un système de paragraphes. |
cq:dialog |
nt:unstructured |
Définition de la boîte de dialogue de modification pour l’IU tactile. |
dialog |
cq:Dialog |
Définition de la boîte de dialogue de modification pour l’IU classique. |
cq:design_dialog |
nt:unstructured |
Définition de la boîte de dialogue de conception pour l’IU tactile. |
design_dialog |
cq:Dialog |
Définition de la boîte de dialogue de conception pour l’IU classique. |
dialogPath |
String |
Chemin d’accès à une boîte de dialogue permettant de prendre en charge un cas où le composant n’aurait pas de nœud de boîte de dialogue. |
cq:cellName |
String |
Si elle est définie, cette propriété sert d’ID de cellule. Pour plus d’informations, reportez-vous à l’article de la base de connaissances sur la création d’ID de cellule de conception. |
cq:childEditConfig |
cq:EditConfig |
Lorsque le composant est de type « container », par exemple un système de paragraphes, cela engendre la modification de la configuration des nœuds enfants. |
cq:editConfig |
cq:EditConfig |
Modifier la configuration du composant. |
cq:htmlTag |
nt:unstructured |
Renvoie des attributs de balise supplémentaires ajoutés à la balise html environnante. Active l’ajout d’attributs aux divs générés automatiquement. |
cq:noDecoration |
Boolean |
Si la valeur est true, le composant n’est pas rendu avec les classes div et css générées automatiquement. |
cq:template |
nt:unstructured |
S’il est détecté, ce nœud est utilisé comme modèle de contenu lorsque le composant est ajouté depuis le navigateur de composants ou le sidekick. |
cq:templatePath |
String |
Chemin d’accès à un nœud à utiliser comme modèle de contenu lorsque le composant est ajouté depuis le navigateur de composants ou le sidekick. Doit être un chemin absolu, non relatif au nœud du composant. Sauf si vous souhaitez réutiliser du contenu déjà disponible ailleurs, cela n’est pas obligatoire, et cq:template est suffisant (voir ci-dessous). |
jcr:created |
Date |
Date de création du composant. |
jcr:description |
String |
Description du composant. |
jcr:title |
String |
Titre du composant. |
sling:resourceSuperType |
String |
Lorsqu’il est défini, le composant hérite de ce composant. |
virtual |
sling:Folder |
Permet la création de composants virtuels. Pour voir un exemple, consultez le composant contact à l’adresse :/libs/foundation/components/profile/form/contact |
<breadcrumb.jsp> |
nt:file |
Fichier de script. |
icon.png |
nt:file |
L’icône du composant apparaît à côté du titre dans le sidekick. |
thumbnail.png |
nt:file |
Vignette facultative affichée lorsque le composant est déplacé depuis le sidekick. |
Si nous nous intéressons au composant Text (l’une ou l’autre des versions), nous pouvons voir ces éléments :
HTL (/libs/wcm/foundation/components/text
)
JSP (/libs/foundation/components/text
)
Les propriétés d’intérêt particulier sont les suivantes :
jcr:title
- Titre du composant. Il peut être utilisé pour identifier le composant, par exemple. Il est visible dans la liste du navigateur de composants dans le navigateur ou le sidekick.jcr:description
- Description du composant. Peut être utilisée comme indice de survol de la souris dans la liste des composants du sidekick.sling:resourceSuperType
- Indique le chemin de l’héritage lors de l’extension d’un composant (en remplaçant une définition).Les nœuds d’enfant d’un intérêt particulier sont les suivants :
cq:editConfig
(cq:EditConfig
) - Contrôle les aspects visuels. Par exemple, il peut définir l’apparence d’une barre ou d’un widget, ou peut ajouter des contrôles personnalisés.cq:childEditConfig
(cq:EditConfig
) - Contrôle les aspects visuels des composants enfants qui n’ont pas leurs propres définitions.cq:dialog
(nt:unstructured
) - Définit la boîte de dialogue de modification du contenu de ce composant.cq:design_dialog
(nt:unstructured
) - Spécifie les options de modification de conception pour le composant.dialog
(cq:Dialog
) - Définit la boîte de dialogue de modification du contenu du composant (spécifique à l’IU classique).design_dialog
(cq:Dialog
) - Spécifie les options de modification de conception pour le composant.icon.png
- Fichier graphique à utiliser comme icône pour le composant dans le sidekickthumbnail.png
- Fichier graphique à utiliser comme miniature pour le composant en le faisant glisser depuis le sidekickLes boîtes de dialogue constituent un élément majeur de votre composant car elles fournissent une interface permettant aux auteurs de configurer et de commenter ce composant.
En fonction de la complexité du composant, la boîte de dialogue peut nécessiter un ou plusieurs onglets pour s’assurer qu’elle soit de petite taille et pour trier les champs de saisie.
Les définitions de boîte de dialogue sont spécifiques à l’IU :
Interface utilisateur optimisée pour les écrans tactiles
cq:dialog
(nt:unstructured
) :
sling:resourceType
, comme structure de contenu Sling standard ;helpPath
pour définir la ressource d’aide contextuelle (chemin absolu ou relatif) accessible lorsque l’icône d’aide (l’icône ? ) est sélectionnée.
helpPath
n’est spécifié, l’URL par défaut (page de présentation de la documentation) est affichée.Dans la boîte de dialogue, chaque champ est défini :
Interface utilisateur classique
dialog
(cq:Dialog
) :
xtype
qui fait référence à ExtJS ;helpPath
pour définir la ressource d’aide contextuelle (chemin absolu ou relatif) accessible lorsque le bouton Aide est sélectionné.
helpPath
n’est spécifié, l’URL par défaut (page de présentation de la documentation) est affichée.Dans la boîte de dialogue, chaque champ est défini :
Dans une boîte de dialogue classique :
cq:Dialog
qui fournira un seul onglet (comme dans le composant text). Si vous avez besoin de plusieurs onglets, comme dans le composant textimage, la boîte de dialogue peut être définie comme cq:TabPanel
.cq:WidgetCollection
(items
) sert de base pour les champs de saisie (cq:Widget
) ou d’autres onglets (cq:Widget
). Cette hiérarchie peut être étendue.Les boîtes de dialogue de conception sont très similaires aux boîtes de dialogue utilisées pour modifier et configurer le contenu, mais elles fournissent une interface permettant aux auteurs de configurer et de fournir des détails de conception pour ce composant.
Les boîtes de dialogue de conception sont disponibles en mode Conception, bien qu’elles ne soient pas nécessaires pour tous les composants. Par exemple, les composants Title et Image ont tous deux des boîtes de dialogue de conception, alors que le composant Text n’en a pas.
La boîte de dialogue de conception pour le système de paragraphe (par exemple parsys) est un cas particulier. Elle permet à l’utilisateur de définir d’autres composants spécifiques à rendre sélectionnables (depuis le navigateur de composants ou le sidekick) sur la page.
Une fois qu’un composant a été défini, il doit être disponible pour utilisation. Pour rendre un composant sélectionnable dans un système de paragraphes, vous pouvez :
ouvrir le mode Conception pour une page et activer le composant requis ;
ajouter le(s) composant(s) requis à la propriété components
de votre définition de modèle sous :
/etc/designs/<*yourProject*>/jcr:content/<*yourTemplate*>/par
Pour obtenir un exemple, reportez-vous à :
/etc/designs/geometrixx/jcr:content/contentpage/par
Si nous créons et configurons une instance du composant Titre sur la page : <content-path>/Prototype.html
Interface utilisateur optimisée pour les écrans tactiles
Interface utilisateur classique
Ensuite, nous pouvons voir la structure du contenu créé dans le référentiel :
En particulier, si vous vous intéressez au texte actuel d’un composant Titre :
la définition (pour les deux interfaces utilisateur) possède la propriété name
= ./jcr:title
/libs/foundation/components/title/cq:dialog/content/items/column/items/title
/libs/foundation/components/title/dialog/items/title
dans le contenu, ceci génère la propriété jcr:title
qui stocke le contenu de l’auteur.
Les propriétés définies dépendent des définitions individuelles. Bien qu’elles puissent être plus complexes que dans les exemples ci-dessus, elles suivent toujours les mêmes principes simples.
Les composants d’AEM sont soumis à trois hiérarchies différentes :
Hiérarchie du type de ressource
Elle est utilisée pour étendre des composants à l’aide de la propriété sling:resourceSuperType
. Cela permet au composant d’hériter d’attributs. Par exemple, un composant Text hérite de divers attributs du composant standard.
Hiérarchie des conteneurs
Cette option permet de renseigner les paramètres de configuration du composant enfant. Elle est généralement utilisée dans un scénario parsys.
Par exemple, les paramètres de configuration des boutons de la barre de modification, la disposition de jeux de contrôles (barres de modification, survol), la disposition des boîtes de dialogue (ancrée, flottante) peuvent être définis sur le composant parent.
Les paramètres de configuration (liés à la fonctionnalité de modification) dans cq:editConfig
et cq:childEditConfig
sont propagés.
Hiérarchie d’inclusion
Paramètre imposé lors de l’exécution par la séquence d’inclusions.
Cette hiérarchie est utilisée par le concepteur, qui à son tour sert de base pour divers aspects de conception du rendu, notamment les informations de disposition, les informations css, les composants disponibles dans un parsys, etc.
Cette section explique comment 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 local et les écouteurs liés aux événements sur le composant.
La configuration est commune à l’IU tactile et à l’IU classique, à l’exception de certaines différences.
Le comportement de modification d’un composant est configuré en ajoutant un nœud cq:editConfig
de type cq:EditConfig
en dessous du nœud de composant (de type cq:Component
) et en ajoutant des propriétés spécifiques et des nœuds enfants. Les propriétés et les nœuds enfants suivants sont disponibles :
Propriétés du nœud cq:editConfig
:
cq:actions
(String array
) : définit les actions pouvant être effectuées sur le composant.
cq:layout
(String
) : définit la façon dont le composant est modifié dans l’IU classique.
cq:dialogMode
(String
) : définit le mode d’ouverture de la boîte de dialogue des composants dans l’IU classique.
cq:emptyText
(String
) : définit le texte qui est affiché quand aucun contenu visuel n’est présent.
cq:inherit
(Boolean
) : définit si les valeurs manquantes sont héritées du composant.
dialogLayout
(chaîne) : définit le mode d’ouverture de la boîte de dialogue.
cq:dropTargets
(type de nœud nt:unstructured
) : définit une liste de cibles de dépôt pouvant accepter une ressource déposée à partir de l’outil de recherche de contenu.
cq:actionConfigs
(type de nœud nt:unstructured
) : définit une liste de nouvelles actions ajoutées à la liste cq:actions.
cq:formParameters
(type de nœud nt:unstructured
) : définit des paramètres supplémentaires qui sont ajoutés au formulaire de la boîte de dialogue.
cq:inplaceEditing
(type de nœud cq:InplaceEditingConfig
) : définit une configuration de modification en place pour le composant.
cq:listeners
(type de nœud cq:EditListenersConfig
) : définit ce qui se passe avant ou après une action sur le composant.
Dans cette page, un nœud (propriétés et nœuds enfants) est représenté au format XML, comme indiqué dans l’exemple suivant.
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[edit]"
cq:dialogMode="floating"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig">
<cq:listeners
jcr:primaryType="cq:EditListenersConfig"
afteredit="REFRESH_PAGE"/>
</jcr:root>
Il existe de nombreuses configurations dans le référentiel. Vous pouvez facilement rechercher des propriétés spécifiques ou des nœuds enfants :
Pour rechercher une propriété du nœud cq:editConfig
, par exemple cq:actions
, vous pouvez utiliser l’outil de requête dans CRXDE Lite et faire une recherche avec la chaîne de requête XPath suivante :
//element(cq:editConfig, cq:EditConfig)[@cq:actions]
Pour rechercher un nœud enfant de cq:editConfig
, par exemple, vous pouvez rechercher cq:dropTargets
, qui est de type cq:DropTargetConfig
, vous pouvez utiliser l’outil de requête dans CRXDE Lite et faire une recherche avec la chaîne de requête XPath suivante :
//element(cq:dropTargets, cq:DropTargetConfig)
Les composants doivent toujours générer du code HTML visible par l’auteur, même si le composant ne comporte aucun contenu, sans quoi il pourrait disparaître visuellement de l’interface de l’éditeur, ce qui le rend techniquement présent, mais invisible sur la page et dans l’éditeur. Dans ce cas, les auteurs ne pourraient pas sélectionner ce composant vide ni interagir avec lui.
Pour cette raison, les composants doivent générer un espace réservé tant qu’ils n’affichent pas de sortie visible lorsque la page est rendue dans l’éditeur de page (lorsque le WCM est en mode edit
ou preview
).
L’annotation HTML type d’un espace réservé est la suivante :
<div class="cq-placeholder" data-emptytext="Component Name"></div>
Le script HTL type pour effectuer le rendu du code HTML d’espace réservé ci-dessus est le suivant :
<div class="cq-placeholder" data-emptytext="${component.properties.jcr:title}"
data-sly-test="${(wcmmode.edit || wcmmode.preview) && isEmpty}"></div>
Dans l’exemple précédent, isEmpty
est une variable vraie uniquement lorsque le composant n’a aucun contenu et est invisible pour l’auteur.
Pour éviter la répétition, Adobe recommande que les implémenteurs des composants utilisent un modèle HTL pour ces espaces réservés, comme celui fourni par les composants principaux.
L’utilisation du modèle dans le lien précédent se fait ensuite grâce à la ligne HTL suivante :
<sly data-sly-use.template="core/wcm/components/commons/v1/templates.html"
data-sly-call="${template.placeholder @ isEmpty=!model.text}"></sly>
Dans l’exemple précédent, model.text
est la variable qui est vraie uniquement lorsque le contenu comporte du contenu et est visible.
Vous trouverez un exemple d’utilisation de ce modèle dans les composants principaux, tels que dans le composant Titre.
La propriété cq:actions
(String array
) définit une ou plusieurs actions pouvant être exécutées sur le composant. Les valeurs suivantes sont configurables :
Valeur de la propriété | Description |
text:<some text> |
Affiche la valeur de texte statique. <some text> Visible uniquement dans l’IU classique. L’IU tactile n’affiche pas les actions dans un menu contextuel, donc ceci n’est pas applicable. |
- | Ajoute un espacement. Visible uniquement dans l’IU classique. L’IU tactile n’affiche pas les actions dans un menu contextuel, donc ceci n’est pas applicable. |
edit |
Ajoute un bouton pour modifier le composant. |
editannotate |
Ajoute un bouton permettant de modifier le composant et d’autoriser les annotations. |
delete |
Ajoute un bouton pour supprimer le composant. |
insert |
Ajoute un bouton permettant d’insérer un nouveau composant avant le composant actif. |
copymove |
Ajoute un bouton pour copier et couper le composant. |
La configuration suivante ajoute un bouton de modification, un espacement, ainsi qu’un bouton de suppression et d’insertion à la barre de modification du composant :
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[edit,-,delete,insert]"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig"/>
La configuration suivante ajoute le texte « Configurations héritées du framework de base » à la barre de modification des composants :
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[text:Inherited Configurations from Base Framework]"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig"/>
La propriété cq:layout
(String
) définit la façon dont le composant peut être modifié dans l’IU classique. Les valeurs suivantes sont disponibles :
Valeur de la propriété | Description |
rollover |
Valeur par défaut. La modification de composant est accessible par survol de la souris, via des clics et/ou un menu contextuel. Pour une utilisation avancée, notez que l’objet côté client correspondant est : CQ.wcm.EditRollover |
editbar |
L’édition du composant est accessible par le biais d’une barre d’outils. Pour une utilisation avancée, notez que l’objet côté client correspondant est : CQ.wcm.EditBar |
auto |
Le choix est laissé au code côté client. |
Les concepts de survol et de modification ne sont pas applicables dans l’IU tactile.
La configuration suivante ajoute un bouton de modification à la barre de modification du composant :
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[edit]"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig">
</jcr:root>
Le composant peut être lié à une boîte de dialogue de modification. La propriété cq:dialogMode
(String
) définit le mode d’ouverture de la boîte de dialogue du composant dans l’IU classique. Les valeurs suivantes sont disponibles :
Valeur de la propriété | Description |
floating |
La boîte de dialogue est flottante. |
inline |
(valeur par défaut). La boîte de dialogue est ancrée sur le composant. |
auto |
Si la largeur du composant est inférieure à celle du côté client CQ.themes.wcm.EditBase.INLINE_MINIMUM_WIDTH , la boîte de dialogue est flottante, sinon elle est insérée. |
Dans l’IU tactile, les boîtes de dialogue flottent toujours en mode bureau et s’ouvrent automatiquement en mode plein écran sur mobile.
La configuration suivante définit une barre de modification avec un bouton de modification et une boîte de dialogue flottante :
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0"
cq:actions="[edit]"
cq:dialogMode="floating"
cq:layout="editbar"
jcr:primaryType="cq:EditConfig">
</jcr:root>
La propriété cq:emptyText
(String
) définit le texte qui est affiché quand aucun contenu visuel n’est présent. Cet attribut est défini, par défaut, sur : Drag components or assets here
.
La propriété cq:inherit
(boolean
) définit si les valeurs manquantes sont héritées du composant. Cet attribut est défini, par défaut, sur false
.
La propriété dialogLayout
définit la façon dont une boîte de dialogue doit s’ouvrir par défaut.
fullscreen
ouvre la boîte de dialogue en plein écran.Le nœud cq:dropTargets
(type de nœud nt:unstructured
) définit une liste de cibles de dépôt pouvant accepter une ressource déplacée à partir de l’outil de recherche de contenu. Il sert de collection de nœuds de type cq:DropTargetConfig
.
Les cibles de dépôt multiples sont uniquement disponibles dans l’IU classique.
Dans l’IU tactile, seule la première cible est utilisée.
Chaque nœud enfant de type cq:DropTargetConfig
définit une cible de dépôt dans le composant. Le nom du nœud est important car il doit être utilisé dans JSP, comme suit, pour générer le nom de classe CSS affecté à l’élément DOM qui est la cible de dépôt réelle :
<drop target css class> = <drag and drop prefix> +
<node name of the drop target in the edit configuration>
Le <drag and drop prefix>
est défini par la propriété Java :
com.day.cq.wcm.api.components.DropTarget.CSS_CLASS_PREFIX
.
Par exemple, le nom de la classe est défini comme suit dans le JSP du composant Télécharger (/libs/foundation/components/download/download.jsp
) où file
correspond au nom de nœud de la cible de dépôt dans la configuration de modification du composant Télécharger :
String ddClassName = DropTarget.CSS_CLASS_PREFIX + "file";
Le nœud de type cq:DropTargetConfig
doit posséder les propriétés suivantes :
Nom de la propriété | Valeur de la propriété |
accept |
Expression régulière appliquée au type MIME de la ressource pour valider si le dépôt est autorisé. |
groups |
Tableau de groupes cibles de dépôt. Chaque groupe doit correspondre au type de groupe défini dans l’extension du Content Finder et associé aux ressources. |
propertyName |
Nom de la propriété qui sera mise à jour après un dépôt valide. |
La configuration suivante est issue du composant Télécharger. Elle active n’importe quelle ressource (le type mime peut être n’importe quelle chaîne) à partir du groupe media
à déposer à partir de l’outil de recherche de contenu dans le composant. Après le dépôt, la propriété de composant fileReference
est mise à jour :
<cq:dropTargets jcr:primaryType="nt:unstructured">
<file
jcr:primaryType="cq:DropTargetConfig"
accept="[.*]"
groups="[media]"
propertyName="./fileReference"/>
</cq:dropTargets>
Le nœud cq:actionConfigs
(type de nœud nt:unstructured
) définit une liste de nouvelles actions ajoutées à la liste définie par la propriété cq:actions
. Chaque nœud enfant de cq:actionConfigs
définit une nouvelle action en définissant un widget.
L’exemple de configuration suivant définit un nouveau bouton (avec un séparateur pour l’IU classique) :
un séparateur, défini par le xtype tbseparator
;
un bouton nommé Gérer les commentaires qui exécute la fonction de gestionnaire CQ_collab_forum_openCollabAdmin()
.
<jcr:root xmlns:cq="https://www.day.com/jcr/cq/1.0" xmlns:jcr="https://www.jcp.org/jcr/1.0" xmlns:nt="https://www.jcp.org/jcr/nt/1.0"
cq:actions="[EDIT,COPYMOVE,DELETE,INSERT]"
jcr:primaryType="cq:EditConfig">
<cq:actionConfigs jcr:primaryType="nt:unstructured">
<separator0
jcr:primaryType="nt:unstructured"
xtype="tbseparator"/>
<manage
jcr:primaryType="nt:unstructured"
handler="function(){CQ_collab_forum_openCollabAdmin();}"
text="Manage comments"/>
</cq:actionConfigs>
</jcr:root>
Consultez Ajout d’une nouvelle action à une barre d’outils de composants à titre d’exemple pour l’IU tactile.
Le nœud cq:formParameters
(type de nœud nt:unstructured
) définit des paramètres supplémentaires qui sont ajoutés au formulaire de la boîte de dialogue. Chaque propriété est mappée à un paramètre de formulaire.
La configuration suivante ajoute un paramètre appelé name
, défini avec la valeur photos/primary
dans le formulaire de boîte de dialogue :
<cq:formParameters
jcr:primaryType="nt:unstructured"
name="photos/primary"/>
Le nœud cq:inplaceEditing
(type de nœud cq:InplaceEditingConfig
) définit une configuration de modification en place pour le composant. Il peut posséder les propriétés suivantes :
Nom de la propriété | Valeur de la propriété |
active |
(boolean ) True pour activer la modification locale du composant. |
configPath |
(String ) Chemin d’accès à l’éditeur de configuration. La configuration peut être spécifiée par un nœud de configuration. |
editorType |
(
|
La configuration suivante active la modification locale du composant et définit plaintext
comme type d’éditeur :
<cq:inplaceEditing
jcr:primaryType="cq:InplaceEditingConfig"
active="{Boolean}true"
editorType="plaintext"/>
Le nœud cq:listeners
(type de nœud cq:EditListenersConfig
) définit ce qui se passe avant ou après une action sur le composant. Le tableau suivant définit ses propriétés possibles.
Nom de la propriété | Valeur de la propriété |
Valeur par défaut (IU classique uniquement) |
beforedelete |
Le gestionnaire est déclenché avant la suppression du composant. |
|
beforeedit |
Le gestionnaire est déclenché avant la modification du composant. | |
beforecopy |
Le gestionnaire est déclenché avant la copie du composant. | |
beforemove |
Le gestionnaire est déclenché avant le déplacement du composant. | |
beforeinsert |
Le gestionnaire est déclenché avant l’insertion du composant. Valide uniquement pour l’IU tactile. |
|
beforechildinsert |
Le gestionnaire est déclenché avant l’insertion du composant dans un autre composant (conteneurs uniquement). | |
afterdelete |
Le gestionnaire est déclenché après la suppression du composant. | REFRESH_SELF |
afteredit |
Le gestionnaire est déclenché après la modification du composant. | REFRESH_SELF |
aftercopy |
Le gestionnaire est déclenché après la copie du composant. | REFRESH_SELF |
afterinsert |
Le gestionnaire est déclenché après l’insertion du composant. | REFRESH_INSERTED |
aftermove |
Le gestionnaire est déclenché après le déplacement du composant. | REFRESH_SELFMOVED |
afterchildinsert |
Le gestionnaire est déclenché après l’insertion du composant dans un autre composant (conteneurs uniquement). |
Les gestionnaires REFRESH_INSERTED
et REFRESH_SELFMOVED
sont uniquement disponibles dans l’IU classique.
Les valeurs par défaut des écouteurs ne sont définies que dans l’IU classique.
Dans le cas des composants imbriqués, certaines restrictions existent sur les actions définies en tant que propriétés sur le nœud cq:listeners
:
REFRESH_PAGE
: >
aftermove
aftercopy
Le gestionnaire d’événements peut être mis en œuvre avec une implémentation personnalisée. Par exemple (où project.customerAction
est une méthode statique) :
afteredit = "project.customerAction"
L’exemple suivant est équivalent à la configuration REFRESH_INSERTED
:
afterinsert="function(path, definition) { this.refreshCreated(path, definition); }"
En ce qui concerne l’IU classique, pour voir quels paramètres peuvent être utilisés dans les gestionnaires, reportez-vous aux sections des événements before<action>
> et after<action>
> de la documentation sur les widgets CQ.wcm.EditBar
et CQ.wcm.EditRollover
.
Avec la configuration suivante, la page est actualisée après la suppression, la modification, l’insertion ou le déplacement du composant :
<cq:listeners
jcr:primaryType="cq:EditListenersConfig"
afterdelete="REFRESH_PAGE"
afteredit="REFRESH_PAGE"
afterinsert="REFRESH_PAGE"
afterMove="REFRESH_PAGE"/>