Filtres

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.

Attribut de filtre

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>

Elément de filtre

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>

Centre de documentation

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é.

Où puis-je utiliser les filtres ?

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.