Suodattimet

Jos asiakirjan tiettyjen osioiden tulee näkyä vain tietyssä tilanteessa, käyttämällä suodatinmerkintöjä voit määrittää ehdot, joiden tulee täyttyä, jotta asiakirjan osio näytettäisiin. Jos ehdot eivät täyty, asiakirjan kyseistä osiota ei näytetä käyttäjälle. Suodattimia voi määrittää mille tahansa XML-elementille, jos merkinnät ovat käsittelyn jälkeen yhä kelvolliset. Jos elementti suodatetaan, myös kaikki kyseisen elementin sisältämät elementit ja teksti suodatetaan.

Seuraavassa taulukossa on luettelo kaikista suodattimen ominaisuuksista ja niiden mahdollisista arvoista.

Ominaisuus Merkitys Mahdolliset arvot
os käyttöjärjestelmä win32, win32, linux, macosx, aix, solaris, hpux, qnx
ws ikkunointijärjestelmä win32, motif, gtk, photon, carbon
arch suoritinarkkitehtuuri x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc
product eclipse-tuotteen tunniste Mikä tahansa tuotteen tunniste (esim. org.eclipse.sdk.ide tuotteelle SDK)
plugin lisäosan olemassaolo Mikä tahansa lisäosan tunniste (esim. org.eclipse.help)
category tapahtumaluokka Mikä tahansa tapahtumaluokan tunniste (esim. org.eclipse.categories.teamCategory Team-luokalle)
activity tapahtuma (toiminto) Mikä tahansa tapahtuman tunniste (esim. org.eclipse.team.cvs CVS-tukitapahtumalle)

Jos nimi ei vastaa mitään ennalta määritettyä ominaisuutta, ohjejärjestelmä käyttää kyseisennimistä JVM-näennäiskoneen järjestelmäominaisuutta. Voit esimerkiksi välittää minkä tahansa käyttäjän määrittämän ominaisuuden, kuten -Dlocation=paris,france-ominaisuuden aloituksen yhteydessä ja tehdä suodatuksen tämän ominaisuuden perusteella.

Elementille voi määrittää suodattimia kahdella tapaa: käyttämällä määritteitä tai elementtejä.

Suodatinmäärite

Ensimmäisessä tavassa lisätään filter-määrite elementtiin. Yleinen muoto on:

   <element filter="[name][operator][value]">
      Some text.
   </element>

Kohta name on suodatusperusteena käytettävän ominaisuuden nimi, esimerkiksi os, jos suodatus tehdään käyttöjärjestelmän perusteella. Kohta operator on joko =, mikä merkitsee vastinetta (tarkka vastine, kirjainkoko on merkitsevä), tai !=, mikä merkitsee, että vastinetta ei ole. Kohdassa value on arvo, jota ominaisuuden tulee (tai jota sen ei tule) vastata. Esimerkiksi ominaisuuden os yksi mahdollinen arvo on win32 (Windows). Luettelo kaikista suodattimen ominaisuuksista ja niiden arvoista on saatavilla edellä olevassa taulukossa.

Seuraava esimerkki näyttää, kuinka XHTML-asiakirjassa näytetään tietty tekstikappale vain, kun käyttöjärjestelmänä on Linux.

   <p filter="os=linux">
      This message will only appear when viewed on Linux.
   </p>

Seuraavassa esimerkissä linkki näkyy vain, jos lisäosaa com.my.plugin ei ole asennettu:

   <a href="..." filter="plugin!=com.my.plugin">
      Click here to download plugin com.my.plugin.
   </a>

Suodatinelementti

Toisessa tavassa käytetään filter-elementtiä suodatettavan elementin alielementtinä. Tämä tapa on hieman pidempi kuin suodatus määritteen avulla, mutta se on myös tehokkaampi, sillä voit määrittää elementille halutun määrän suodattimia. Yleinen muoto on:

   <element attribute="value">
      <filter name="[name]" value="[modifier][value]"/>
   </element>

Kohdat name ja value ovat tässä samat kuin suodatinmääritteen yhteydessä. Ne on kuitenkin määritetty erikseen, joten se, tuleeko niiden vastata toisiaan, on määritettävä toisella tavalla. Oletusarvoisesti, jos kohtaa modifier ei määritetä, oletetaan, että vastineen tulee löytyä. Jos vastinetta ei tule olla, määritä kohtaan modifier "! "

Tässä on aiemmin esitelty ensimmäinen esimerkki toisella tavalla:

   <p>
      <filter name="os" value="linux"/>
      This message will only appear when viewed on Linux.
   </p>

Toinen esimerkki toisella tavalla:

   <a href="...">
      <filter name="plugin" value="!com.my.plugin"/>
      Click here to download plugin com.my.plugin.
   </a>

Info Center

Suodatuksen tuki on pois käytöstä, kun ohjetta käytetään Info Center -tilassa, jolloin kaikki sisältö, myös suodatettu sisältö, on näkyvissä. Jos aiot sijoittaa ohjeet sekä työympäristöön että Info Center -tilaan, käytä suodattimia tavalla, josta on hyötyä myös silloin, kun suodatus ei ole käytössä.

Missä yhteydessä voin käyttää suodattimia?

Suodatusta voi käyttää seuraavissa asiakirjalajeissa:

* Huomautus: XHTML-asiakirjoissa dynaamisen sisällön käyttöönotto edellyttää vain vähän ylimääräisiä vaiheita.

Missään tapauksessa suodattimia ei tule sijoittaa sellaisiin elementteihin, joissa kyseisen elementin poisto johtaisi virheellisiin XML-merkintöihin. Esimerkiksi XHTML-asiakirjan html-elementtiin ei tule sijoittaa suodatinta, koska ilman kyseistä elementtiä XHTML-merkinnät eivät ole enää kelvollisia.