Si certaines sections de votre document doivent apparaître uniquement dans un contexte précis, vous pouvez utiliser le marquage de filtrage pour indiquer les critères devant être réunis pour que la section du document apparaisse. Si les critères ne sont pas réunis, la section du document ne sera pas visible pour l'utilisateur. Des filtres peuvent être indiqués sur n'importe quel élément XML à condition que le marquage reste valide à l'issue du traitement. Si un élément est filtré, tous les éléments ainsi que le texte contenu sous cet élément seront également filtrés.
Le tableau ci-dessous contient une liste complète de toutes les propriétés de filtre et leurs valeurs possibles.
Propriété | Signification | Valeurs possibles |
os
|
système d'exploitation |
win32, win32, linux, macosx, aix, solaris, hpux, qnx
|
ws
|
système de fenêtrage |
win32, motif, gtk, photon, carbon
|
arch
|
architecture du processeur |
x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc
|
produit
|
identificateur du produit eclipse |
Tous les identificateurs de produit (par ex., pour SDK, org.eclipse.sdk.ide )
|
plugin
|
présence du plug-in |
Tout identificateur de plug-in (par ex. : org.eclipse.help )
|
catégorie
|
catégorie d'activités |
Tout identificateur de catégorie d'activité (par ex. pour la catégorie Equipe,
org.eclipse.categories.teamCategory )
|
activité
|
activité (fonction) |
Tout identificateur d'activité (par ex. pour l'activité Support CVS,
org.eclipse.team.cvs )
|
Si le nom ne correspond à aucune propriété prédéfinie, le système d'aide utilisera la propriété système de la JVM de ce nom. Par exemple, vous pouvez transmettre n'importe quelle propriété définie par l'utilisateur au démarrage, comme -Dlocation=paris,france
et appliquer un filtre selon cette propriété.
Il existe deux manières d'indiquer des filtres sur un élément : à l'aide d'attributs ou d'éléments.
Le premier format consiste à ajouter un attribut de filtre
à l'élément. Le format général est le suivant :
<element filter="[nom][opérateur][valeur]"> Du texte. </element>
Le nom
correspond au nom de la propriété selon laquelle appliquer un filtre, par exemple : os
pour système d'exploitation. L'opérateur
désigne soit =
pour indiquer une occurrence (occurrence exacte, dépendant maj/min), soit !=
pour indiquer ne correspond pas. La valeur
est la valeur que doit ou (ne doit pas) prendre la propriété. Par exemple, pour os
, l'une des valeurs possibles est win32
(Windows). Une liste complète des propriétés de filtre accompagnées de leurs valeurs est disponible dans un tableau ci-dessous.
L'exemple ci-dessous indique comment afficher un paragraphe de texte dans un document XHTML sous Linux uniquement.
<p filter="os=linux"> Ce message apparaîtra seulement sous Linux. </p>
Dans ce second exemple, le lien n'apparaîtra que si le plug-in
com.my.plugin
n'est pas installé :
<a href="..." filter="plugin!=com.my.plugin"> Cliquez ici pour télécharger le plug-in com.my.plugin. </a>
La seconde méthode consiste à utiliser un élément filter
en tant qu'enfant de l'élément à filtrer. Cette méthode est légèrement plus longue qu'avec un attribut, mais est plus efficace car vous pouvez indiquer un nombre indéfini de filtres sur un élément. Le format général est le suivant :
<element attribute="value">
<filter name="[nom]" value="[modificateur][valeur]"/>
</element>
Les éléments nom
et
valeur
sont identiques à ceux utilisés avec l'attribut. Toutefois, comme ils sont séparés, nous devons trouver une autre manière d'indiquer s'ils doivent ou non correspondre. Par défaut, si vous n'indiquez pas de modificateur
, on suppose une correspondance. S'il ne doit pas correspondre, affectez la valeur "!
au modificateur
"
Voici le premier exemple illustré précédemment dans la seconde méthode :
<p> <filter name="os" value="linux"/> Ce message apparaîtra seulement sous Linux. </p>
Et le second exemple :
<a href="..."> <filter name="plugin" value="!com.my.plugin"/> Cliquez ici pour télécharger le plug-in com.my.plugin. </a>
La prise en charge du filtrage est désactivée lorsque vous exécutez l'aide en mode centre de documentation, rendant ainsi visible tout contenu, y compris le contenu filtré. Si vous envisagez d'héberger votre documentation à la fois en mode plan de travail et centre de documentation, vous devez utiliser les filtres de manière cohérente même si le filtrage est désactivé.
Les filtres peuvent être utilisés dans les types de document suivants :
* Remarque : Il existe un petit nombre d'étapes supplémentaires nécessaires pour activer le contenu dynamique dans vos documents XHTML.
Dans tous les cas, vous ne devez pas appliquer de filtres sur un élément si la suppression de cet élément entraîne du code XML non valide. Par exemple, vous ne devez pas appliquer un filtre sur l'élément html
dans un document XHTML, car sans cet élément, le document XHTML n'est plus valide.