Pour baliser le contenu et utiliser le framework de balisage AEM, procédez comme suit :
La balise doit exister en tant que nœud du type [cq:Tag](#tags-cq-tag-node-type)
sous le nœud racine de taxonomie.
Le type du nœud de contenu balisé doit inclure le mixin cq:Taggable
.
L’ID de balise est ajouté à la propriété cq:tags
du nœud de contenu et est résolu sur un nœud de type [cq:Tag](#tags-cq-tag-node-type)
.
La déclaration d’une balise est capturée dans le référentiel dans un nœud de type cq:Tag.
.
Une balise peut être constituée d’un simple mot (sky, par exemple) ou représenter une taxonomie hiérarchique (par exemple, fruit/apple, c’est-à-dire la catégorie générique et le fruit).
Les balises sont identifiées par un identifiant unique.
Une balise comprend des méta-informations facultatives, telles qu’un titre, des titres localisés et une description. Le titre doit être affiché dans les interfaces utilisateur au lieu de l’ID de balise, le cas échéant.
Le framework de balisage offre également la possibilité de contraindre les auteurs et les visiteurs du site à n’utiliser que des balises prédéfinies spécifiques.
Le type de nœud est cq:Tag
.
Le nom du nœud est un composant de [TagID](#tagid)
.
Le [TagID](#tagid)
contient toujours un espace de noms.
Propriété jcr:title
facultative (Titre à afficher dans l’interface utilisateur).
propriété jcr:description
facultative
Lorsqu’elle contient des nœuds enfants, la balise est qualifiée de balise conteneur.
Elle est stockée dans le référentiel, sous un chemin de base appelé nœud racine de taxonomie.
Un ID de balise identifie un chemin d’accès qui est résolu sur un nœud de balise dans le référentiel.
En règle générale, l’ID de balise est un identifiant abrégé commençant par l’espace de noms ; il peut également s’agir d’un ID de balise absolu commençant au niveau du nœud racine de taxonomie.
Lorsque le contenu est balisé, la propriété [cq:tags](#tagged-content-cq-tags-property)
est ajoutée, si elle n’existe pas déjà, au nœud de contenu et l’ID de balise est ajouté à la valeur de tableau String de la propriété.
L’ID de balise se compose d’un espace de noms, suivi de l’ID de balise local. Les balises conteneurs contiennent des sous-balises qui représentent un ordre hiérarchique dans la taxonomie. Des sous-balises peuvent être utilisées pour référencer des balises identiques à tout ID de balise local. Par exemple, baliser du contenu avec « fruit » est autorisé, même s’il s’agit d’une balise conteneur avec des sous-balises, comme « fruit/apple » et « fruit/banana ».
Le nœud racine de taxonomie est le chemin d’accès de base pour toutes les balises du référentiel. Le nœud racine de taxonomie ne peut pas être un nœud de type cq :Tag
.
Dans AEM, le chemin d’accès de base est /content/ cq :tags
et le nœud racine est de type cq :Folder
.
Les espaces de noms permettent de regrouper des éléments. Le cas d’utilisation le plus courant consiste à disposer d’un espace de noms par site (Web) (par exemple, public, interne ou sur portail) ou par grande application (par exemple la gestion de contenu Web, ou Assets, Communities), mais les espaces de noms peuvent être utilisés pour d’autres besoins. Les espaces de noms sont utilisés dans l’interface utilisateur pour n’afficher que le sous-ensemble de balises (c’est-à-dire les balises d’un espace de noms donné) applicable au contenu actuel.
L’espace de noms de la balise est le premier niveau de la sous-arborescence de taxonomie, à savoir le nœud situé juste en dessous du nœud racine de taxonomie. Un espace de noms est un nœud de type cq:Tag
dont le parent n’est pas de type cq:Tag
.
Toutes les balises possèdent un espace de noms. Si aucun espace de noms n’est spécifié, la balise est affectée à l’espace de noms par défaut, qui est l’ID de balise (TagID) par default
(le titre est Standard Tags),
ce qui donnera /content/cq:tags/default.
.
Une balise conteneur est un nœud de type cq:Tag
contenant le nombre et le type des nœuds enfants, ce qui permet d’enrichir le modèle de balise avec des métadonnées personnalisées.
En outre, les balises conteneurs (ou super-balises) d’une taxonomie font office de sous-cumul de toutes les sous-balises. Par exemple, le contenu balisé avec « fruit/apple » est considéré comme étant également balisé avec « fruit ». Dès lors, une recherche de contenu balisé simplement avec « fruit » renverra également le contenu balisé avec « fruit/apple ».
Si l’ID de balise contient le signe deux-points (« : »), celui-ci sépare l’espace de noms de la balise ou de la sous-taxonomie, qui sont alors séparés par des barres obliques (« / »). En l’absence de signe deux-points dans l’ID de balise, l’espace de noms par défaut sera utilisé.
L’emplacement standard et unique pour les balises est sous /content/cq:tags.
Les balises qui référencent des chemins d’accès inexistants ou des chemins d’accès qui ne pointent pas vers un nœud cq:Tag sont considérées comme non valides et sont ignorées.
Le tableau ci-dessous présente quelques exemples d’ID de balise, les éléments associés et la manière dont l’ID de balise est résolu sur un chemin d’accès absolu dans le référentiel :
Le tableau ci-dessous présente quelques exemples d’ID de balise, les éléments associés et la manière dont l’ID de balise est résolu sur un chemin d’accès absolu dans le référentiel :
TagID (ID de balise) |
Espace de noms | ID local | Balise(s) conteneur(s) | Balise feuille | Chemin d’accès absolu aux balises du référentiel |
dam:fruit/apple/braeburn | dam | fruit/apple/braeburn | fruit, apple | braeburn | /content/cq:tags/dam/fruit/apple/braeburn |
color/red | par défaut | color/red | couleur | red | /content/cq:tags/default/color/red |
sky | par défaut | sky | (aucune) | sky | /content/cq:tags/default/sky |
dam: | dam | (aucune) | (aucune) | (aucun, l’espace de noms) | /content/cq:tags/dam |
/content/cq:tags/category/car | category | car | car | car | /content/cq:tags/category/car |
Lorsque la balise comprend une chaîne de titre facultative (jcr:title
), il est possible de localiser le titre à afficher en ajoutant la propriété jcr:title.<locale>
.
Pour plus d’informations, voir
Les balises existent sous la forme de nœud dans le répertoire sous le nœud racine de taxonomie. Il est possible d’accorder ou de refuser aux auteurs et aux visiteurs du site le droit de créer des balises dans un espace de noms donné en définissant des listes de contrôle d’accès (ACL) appropriées dans le référentiel.
En outre, refuser les autorisations de lecture sur certains espaces de noms et balises détermine la possibilité d’appliquer des balises à du contenu spécifique.
Une pratique habituelle est la suivante :
Accorder au groupe/rôle tag-administrators
l’accès en écriture à tous les espaces de noms (add/modify sous /content/cq:tags
). Ce groupe est fourni en standard avec AEM.
Accorder aux utilisateurs/auteurs l’accès en lecture à tous les espaces de noms qu’ils doivent être autorisés à lire (presque tous).
Accorder aux utilisateurs/auteurs l’accès en écriture aux espaces de noms dont ils doivent être en mesure de définir librement les balises (add_node sous /content/cq:tags/some_namespace
).
Pour que les développeurs d’application attachent le balisage à un type de contenu, l’enregistrement du nœud (CND) doit inclure le mixin cq:Taggable
ou cq:OwnerTaggable
.
Le mixin cq:OwnerTaggable
, qui hérite de cq:Taggable
, sert à indiquer que le contenu peut être classé par propriétaire/auteur. Dans AEM, il s’agit uniquement d’un attribut du nœud cq:PageContent
. Le mixin cq:OwnerTaggable
n’est pas requis par le cadre de balisage.
Il est recommandé de n’activer les balises que sur le nœud de niveau supérieur d’un élément de contenu agrégé (ou sur son nœud jcr:content). Voici quelques exemples :
Pages (cq:Page
) sur lesquelles le nœud jcr:content
est de type cq:PageContent
ce qui inclut le mixin cq:Taggable
Ressources (cq:Asset
) dans lesquelles le nœud jcr:content/metadata
possède toujours le mixin cq:Taggable
Les définitions de type de nœud existent dans le référentiel sous la forme de fichiers CND. La notation CND est définie dans le cadre de la documentation JCR ici.
Les définitions essentielles relatives aux types de nœud inclus dans AEM sont les suivantes :
[cq:Tag] > mix:title, nt:base
orderable
- * (undefined) multiple
- * (undefined)
+ * (nt:base) = cq:Tag version
[cq:Taggable]
mixin
- cq:tags (string) multiple
[cq:OwnerTaggable] > cq:Taggable
mixin
La propriété cq:tags
est une table de chaînes utilisée pour stocker un ou plusieurs ID de balise lorsque les auteurs ou les visiteurs du site les appliquent au contenu. La propriété n’a de sens que lorsqu’elle est ajoutée à un nœud qui est défini avec le mixin [cq:Taggable](#taggable-content-cq-taggable-mixin)
.
Pour tirer parti de la fonctionnalité de balisage d’AEM, les applications personnalisées ne doivent pas définir de propriétés de balise autres que cq:tags
.
Vous trouverez, ci-après, la description des effets dans le référentiel lors du déplacement ou de la fusion de balises à l’aide de la console de balisage :
Lorsqu’une balise A est déplacée ou fusionnée dans une balise B sous /content/cq:tags
:
cq:movedTo
.cq:backlinks
.cq:movedTo
pointe vers la balise B.
Cette propriété signifie que la balise A a été déplacée ou fusionnée dans la balise B. Le déplacement de la balise B va mettre à jour cette propriété en conséquence. La balise A est donc masquée et elle n’est conservée dans le référentiel que pour résoudre les ID de balise situés dans les nœuds de contenu pointant vers la balise A. Le nettoyeur de mémoire de balise supprime des balises telles que la balise A dès que plus aucun nœud de contenu ne pointe vers elles.
Une valeur spéciale pour la propriété cq:movedTo
est nirvana
: elle est appliquée lorsque la balise est supprimée. Cependant, elle ne peut pas être supprimée du référentiel, car des sous-balises avec une propriété cq:movedTo
doivent être conservées.
La propriété cq:movedTo
n’est ajoutée à la balise déplacée ou fusionnée que si l’une de ces conditions est remplie :
La propriété cq:backlinks
conserve les références dans l’autre sens ; en d’autres termes, elle conserve la liste de toutes les balises qui ont été déplacées vers la balise B ou fusionnées avec celle-ci. Cela est requis essentiellement pour conserver les propriétés cq:movedTo
jusqu’à la date du déplacement, de la fusion ou de la suppression de la balise B ou jusqu’à ce que cette balise soit activée, auquel cas toutes ses balises de lien retour doivent également être activées.
La propriété cq:backlinks
n’est ajoutée à la balise déplacée ou fusionnée que si l’une de ces conditions est remplie :
La lecture d’une propriété cq:tags
d’un nœud de contenu implique la résolution suivante :
S’il n’existe aucune correspondance sous /content/cq:tags
, aucune balise n’est renvoyée.
Si la propriété cq:movedTo
est définie pour la balise, l’ID de balise référencé est suivi.
Cette étape est répétée aussi longtemps que la balise suivie contient la propriété cq:movedTo
.
Si la balise suivie n’est pas associée à une propriété cq:movedTo
, elle est lue.
Pour publier la modification lorsqu’une balise a été déplacée ou fusionnée, le nœud cq:Tag
et tous ses liens retour doivent être répliqués ; cela est exécuté automatiquement lorsque la balise est activée dans la console d’administration des balises.
Les mises à jour ultérieures apportées à la propriété cq:tags
de la page nettoient automatiquement les « anciennes » références. Cette opération est déclenchée, car la résolution d’une balise déplacée via l’API renvoie la balise de destination, fournissant ainsi l’ID de balise de destination.
Le déplacement des balises diffère de la migration des balises.
Les balises Experience Manager 6.4 et ultérieures sont stockées sous /content/cq:tags
, qui étaient auparavant stockées sous /etc/tags
. Cependant, dans les cas où Adobe Experience Manager a été mis à niveau à partir de la version précédente, les balises sont toujours présentes sous l’ancien emplacement /etc/tags
. Dans les systèmes mis à niveau, les balises doivent être migrées sous /content/cq:tags
.
Dans la page Propriétés de page des balises, il est conseillé d’utiliser l’ID de balise (geometrixx-outdoors:activity/biking
) au lieu de coder en dur le chemin d’accès de base de la balise (par exemple, /etc/tags/geometrixx-outdoors/activity/biking
).
Pour répertorier des balises, vous pouvez utiliser com.day.cq.tagging.servlets.TagListServlet
.
Il est conseillé d’utiliser l’API du gestionnaire de balises comme ressource.
Au lancement du composant, l’API TagManager détecte s’il s’agit d’une instance AEM mise à niveau. Dans le système mis à niveau, les balises sont stockées sous /etc/tags
.
L’API TagManager s’exécute ensuite en mode de compatibilité descendante, ce qui signifie que l’API utilise /etc/tags
comme chemin de base. Si ce n’est pas le cas, il utilise le nouvel emplacement /content/cq:tags
.
Mettez à jour l’emplacement des balises.
Après la migration des balises vers le nouvel emplacement, exécutez le script suivant :
import org.apache.sling.api.resource.*
import javax.jcr.*
ResourceResolverFactory resourceResolverFactory = osgi.getService(ResourceResolverFactory.class);
ResourceResolver resolver = resourceResolverFactory.getAdministrativeResourceResolver(null);
Session session = resolver.adaptTo(Session.class);
def queryManager = session.workspace.queryManager;
def statement = "/jcr:root/content/cq:tags//element(*, cq:Tag)[jcr:contains(@cq:movedTo,\'/etc/tags\') or jcr:contains(@cq:backlinks,\'/etc/tags\')]";
def query = queryManager.createQuery(statement, "xpath");
println "query = ${query.statement}\n";
def tags = query.execute().getNodes();
tags.each { node ->
def tagPath = node.path;
println "tag = ${tagPath}";
if(node.hasProperty("cq:movedTo") && node.getProperty("cq:movedTo").getValue().toString().startsWith("/etc/tags"))
{
def movedTo = node.getProperty("cq:movedTo").getValue().toString();
println "cq:movedTo = ${movedTo} \n";
movedTo = movedTo.replace("/etc/tags","/content/cq:tags");
node.setProperty("cq:movedTo",movedTo);
} else if(node.hasProperty("cq:backlinks")){
String[] backLinks = node.getProperty("cq:backlinks").getValues();
int count = 0;
backLinks.each { value ->
if(value.startsWith("/etc/tags")){
println "cq:backlinks = ${value}\n";
backLinks[count] = value.replace("/etc/tags","/content/cq:tags");
}
count++;
}
node.setProperty("cq:backlinks",backLinks);
}
}
session.save();
println "---------------------------------Success-------------------------------------"
Le script récupère toutes les balises qui ont /etc/tags
comme valeur de cq:movedTo/cq:backLinks
. Il effectue ensuite une itération sur l’ensemble des résultats récupérés et résout les valeurs des propriétés cq:movedTo
et cq:backlinks
vers les chemins /content/cq:tags
(dans le cas où /etc/tags
est détecté dans la valeur).
L’interface utilisateur classique n’est pas compatible avec zéro temps d’arrêt et ne prend pas en charge le nouveau chemin d’accès à la base de balises. Si vous souhaitez utiliser l’IU classique, vous devez créer /etc/tags
puis redémarrer le composant cq-tagging
.
Dans le cas d’instances d’AEM mises à niveau prises en charge par l’API TagManager et s’exécutant dans l’interface utilisateur classique :
Une fois que les références à l’ancien chemin d’accès de base des balises /etc/tags
sont remplacées à l’aide de l’ID de balise ou d’un nouvel emplacement de balise /content/cq:tags
, vous pouvez migrer les balises vers le nouvel emplacement /content/cq:tags
dans CRX, puis redémarrer le composant.
Après la migration des balises vers le nouvel emplacement, exécutez le script mentionné ci-dessus.