Un conkeyref est un attribut servant à référencer du contenu par le bais d’une clé plutôt qu’en référençant directement le contenu d’un élément. Comme décrit dans le cours Introduction à la réutilisation dans DITA, un conref est utilisé de la façon suivante :
<ul conref="canard_domestique_dépot.dita#domestique_dépot/matériaux_nidation"> <li/> </ul>
Le conref vient référencer le contenu de l’élément <ul> depuis la rubrique dépôt contenant tout le contenu réutilisable en lien avec les canards domestiques.
Si la rubrique contenant le conref doit être réutilisable, alors pointer directement vers le fichier codé sera un problème. Pour référencer une rubrique réutilisable dans une carte DITA qui traite des canards sauvages, le conref doit pointer vers une autre rubrique dépôt telle que canard_sauvage_depot.dita.
Plutôt que de coder en dur un chemin vers un fichier, vous pouvez utiliser un conref qui pointe plutôt vers une clé.
La première étape pour utiliser un conkeyref est de créer une rubrique dita (canard_domestiques_rubrique.dita) qui contient un élément réutilisable (qui a donc un attribut id) :
<ul id="matériaux_nidation"> <li>sciure</li> <li>copeaux</li> <li>sable</li> ... </ul>
Dans la carte qui référencera la rubrique où sera utilisé le conkeyref, définir une clé pointant vers la rubrique dépôt :
<keydef keys="canard_depot" href="canard_domestique_depot.dita"/>
Le premier exemple de cette rubrique présente un élément <ul> avec un conref. Remplacez l’attribut conref par un conkeyref. En valeur, ajouter le nom de la clé suivi d’un slash (« / ») et de l’id l’élément référencé :
<ul conkeyref="canard_depot/matériaux_nidation"> <li/> </ul>
Note: Quand vous utilisez un conkeyref, vous n’avez pas besoin de spécifier l’id de la rubrique contenant l’élément référencé.
Quand la rubrique contenant le conkeyref est transformée, la clé canard_depot est remplacée par sa définition qui est canard_domestique_depot.dita.
Vous pouvez réutiliser la rubrique contenant le conkeyref dans une autre carte DITA, mais vous devrez peut-être importer du contenu depuis un fichier qui est spécifique à cette carte. Pour se faire, ajouter un élément <keydef> à votre nouvelle carte pour définir la clé qui va pointer vers le bon fichier. Dans l’exemple suivant, la clé canard_dépot de la nouvelle carte (qui traite des canards sauvages) pointe vers canard_sauvage_depot.dita :
<keydef keys="canard_depot" href="canard_sauvage_depot.dita"/>
Le fichier canard_sauvage_depot.dita possède un élément <ul> différent. Cependant, il faut que son attribut id possède la même valeur :
<ul id="matériaux_nidation"> <li>fougères</li> <li>brindilles</li> <li>de l'herbe</li> ... </ul>
Quand cette nouvelle clé sera utilisée dans la carte sur les canards sauvages, la liste des matériaux de nidation pour les canards sauvages sera utilisée.
Enfin, notez que toutes les règles qui s’appliquent aux conrefs s’appliquent également aux conkeyref :
- L’élément référençant doit être du même type que celui de l’élément référencé.
- L’élément référençant doit être valide. Par exemple, un élément <ul> doit contenir au moins un élément <li>.
Contributors
- Simon Bate
- Jake Campbell
- Gretyl Kinsey
- Decarnelle Rémi (traducteur)