Quand une rubrique utilise un conref, elle vient « importer » du contenu depuis une rubrique référencée vers une rubrique référençante. Cependant, il existe des situations où vous aurez besoin d’insérer un élément dans un emplacement arbitraire au sein d’une rubrique réutilisable.
Par exemple, vous avez peut-être une rubrique qui est pratique dans la majorité des cas. Cependant, il existe un cas (un produit, un client) où vous avez besoin d’ajouter un paragraphe supplémentaire à votre rubrique réutilisable. Une première solution serait d’ajouter ce paragraphe puis de l’inclure ou l’exclure à l’aide du traitement conditionnel. Mais comment faire si vous n’avez pas les droits d’édition sur la rubrique ? Ou bien que votre rubrique est conservée dans une zone publique d’accès (comme GitHub) et ne voulez pas que vos modifications soient visibles de tous ?
Le conref push (ou conaction), soit la technique de réutilisation en poussant le contenu, sert à « pousser » le contenu d’une rubrique (source) vers une carte dita dans une autre rubrique (cible).
L’attribut conaction rend possible possible la poussée d’un contenu de trois façons :
- Le contenu est inséré avant un élément spécifique
- Le contenu remplace un élément spécifique
- Le contenu est inséré après un élément spécifique
De la même façon que le conref, les éléments référencés et référençants doivent être du même type.
-
Assurez-vous que l’élément référencé, soit l’élément qui sera poussé vers la cible, possède un attribut id.
<p id="installation_intro">Ce chapitre décrit comment installer et configure la base de données canard sur Windows et Macintosh.</p>
-
Créez une rubrique contenant l’élément qui sera poussé.
La rubrique doit contenir tous les éléments nécessaires afin de rendre l’élément poussé valide. Par exemple, si vous devez pousser un élément <li>, la rubrique doit contenir les éléments <body>, <ul> et <li>.
Le contenu et les attributs de l’élément poussé sont abordés plus loin dans la leçon.
-
Ajoutez un élément <topicref> à votre carte qui va référencer la rubrique contenant l’élément poussé.
<topicref href="c_conrefpush_sources.dita" processing-role="resource-only"/>
Notez que cet élément <topicref> doit avoir l’attribut processing-role couplé à la valeur « resource-only », car son contenu ne doit pas apparaître dans une publication générée à partir de la carte.
Les sections suivantes décrivent comment utiliser l’attribut conaction pour remplacer un élément, ou insérer un élément avant ou après un autre. Tous les exemples utilisent cette rubrique comme exemple :
<concept id="c_installation"> <title>Installer la Base de données Canard</title> <conbody> <p id="installation_intro">Pour installer la Base de données Canard sur Windows ou Macintosh, veuillez suivre ces instructions.</p> <p>Si vous en avez besoin, à n'importe quelle étape de l'installation, veuillez contacter notre plateforme d'appel disponible 24 heures sur 24.</p> </conbody> </concept>
Une publication générée à partir de cette rubrique sans aucun conref ressemblerait à ceci :
Note: Les fichiers DITA montrés dans ces exemples peuvent être consultés dans le dossier exemples_reutilisation_avance.zip examples_réutilisation_avancé. Le fichier cible est c_conaction_cible.dita. Le fichier source est c_conaction_sources.dita.
Remplacer l’élément cible
Pour remplacer un élément dans la rubrique cible, utilisez l’attribut conref pour identifier l’élément à remplacer, et ajoutez l’attribut conaction avec la valeur « pushreplace » :
<concept id="c_conrefp_source"> <title>Sources conaction</title> <conbody> <p conref="c_conaction_cible.dita#c_installation/installation_intro" conaction="pushreplace"> Pour installer la Base de données Canard sur Windows, veuillez suivre ces instructions</p> </conbody> </concept>
Une publication générée à partir de cette rubrique ressemblerait à ceci :
Insérer un élément avant l’élément cible
- Le premier élément utilise l’attribut conaction avec la valeur « pushbefore » et contient le contenu qui sera poussé
- Le second élément ne contient aucun élément mais utilise les attributs conref (pour identifier l’élément cible) et l’attribut conaction avec la valeur « mark »
Voici un exemple :
<concept id="c_conrefp_source"> <title>Sources conaction</title> <conbody> <p conaction="pushbefore"> Assurez d'avoir rempli toutes les étapes de la pré-configuration. </p> <p conref="c_conaction_cible.dita#c_installation/installation_intro" conaction="mark"/> </conbody> </concept>
Une publication générée à partir de cette rubrique sans aucun conref ressemblerait à ceci :
Insérer un élément avant l’élément cible
Pour insérer un élément avant l’élément cible, utilisez deux éléments du même type que la cible, mais cette fois-ci, l’élément avec les attributs conref et conaction avec la valeur « mark » doivent venir avant l’élement avec l’attribut conaction et la valeur « pushafter » :
<concept id="c_conrefp_source"> <title>Sources conaction</title> <conbody> <p conref="c_conaction_cible.dita#c_installation/installation_intro" conaction="mark"/> <p conaction="pushafter">Pour installer le logiciel sur Ubuntu, veuillez consulter la section prévue à cet effet. </p> </conbody> </concept>
Une publication générée à partir de cette rubrique sans aucun conref ressemblerait à ceci :
Voici encore deux notes sur le mécanisme de poussée de contenu (conaction) :
-
Vous ne pouvez pas utiliser l’attribut conrefend avec conaction
-
Vous pouvez utiliser l’attribut conkeyref pour indiquer la cible du conaction
Contributors
- Simon Bate
- Jake Campbell
- Gretyl Kinsey
- Decarnelle Rémi (traducteur)