Filtry

Jeśli niektóre sekcje dokumentu powinny być wyświetlane wyłącznie w określonym kontekście, istnieje możliwość skorzystania ze znaczników filtrowania. Pozwalają one na określenie kryteriów, które muszą zostać spełnione w celu wyświetlenia danej sekcji dokumentu. Jeśli kryteria nie zostaną spełnione, sekcja pozostanie niewidoczna dla użytkownika. Filtry można określać w odniesieniu do dowolnego elementu języka XML, o ile po przetworzeniu nie spowoduje to wystąpienia błędów w języku znaczników. Odfiltrowanie elementu powoduje także pominięcie wszystkich elementów oraz fragmentów tekstu znajdujących się poniżej niego.

W poniższej tabeli znajduje się pełny wykaz wszystkich właściwości filtrów oraz ich możliwych wartości.

Właściwość Znaczenie Możliwe wartości
os System operacyjny win32, win32, linux, macosx, aix, solaris, hpux, qnx
ws System okienkowy win32, motif, gtk, photon, carbon
arch Architektura procesora x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc
product Identyfikator produktu Eclipse Dowolny identyfikator produktu (np. org.eclipse.sdk.ide w przypadku pakietu SDK)
plugin Wtyczka Dowolny identyfikator wtyczki (np. org.eclipse.help)
category Kategoria czynności Dowolny identyfikator kategorii czynności (np. org.eclipse.categories.teamCategory w przypadku kategorii zespołu)
activity Czynność (funkcja) Dowolny identyfikator czynności (np. org.eclipse.team.cvs w przypadku czynności wsparcia w systemie CVS)

Jeśli podana nazwa nie odpowiada żadnej uprzednio zdefiniowanej właściwości, w systemie wykorzystywana jest właściwość maszyny JVM o podanej nazwie. Podczas uruchamiania można na przykład przekazać dowolną właściwość zdefiniowaną przez użytkownika, taką jak -Dlocation=Warszawa,Polska, a następnie przeprowadzić filtrowanie według tej właściwości.

Filtry dotyczące poszczególnych elementów można określić na dwa sposoby, tj. za pomocą atrybutów lub za pomocą elementów.

Atrybut filtru

Pierwszym sposobem jest dodanie atrybutu filter. Zasadniczo kod ma następującą postać:

   <element filter="[nazwa][operator][wartość]">
      Tekst...
   </element>

Parametr name oznacza nazwę właściwości, według której ma się odbywać filtrowanie, na przykład os (system operacyjny). Parametr operator może mieć wartość =, co oznacza zgodność (pełna zgodność, z rozróżnianiem wielkości liter), lub !=, co oznacza brak zgodności. Parametr value oznacza wartość, z którą powinna (lub nie powinna) być zgodna dana właściwość. Na przykład w przypadku parametru os jedną z dostępnych wartości jest win32 (system Windows). Pełny wykaz właściwości filtrów i ich wartości znajduje się w poniższej tabeli.

Na poniższym przykładzie przedstawiono, w jaki sposób można wyświetlać akapit tekstu w dokumencie XHTML wyłącznie w systemie Linux.

   <p filter="os=linux">
      Ten komunikat jest wyświetlany wyłącznie w systemie Linux.
</p>

Na kolejnym przykładzie przedstawiono odsyłacz, który jest wyświetlany wyłącznie w przypadku, gdy nie zainstalowano wtyczki com.nazwa_wtyczki.

   <a href="..." filter="plugin!=com.nazwa_wtyczki">
      Kliknij tutaj, aby pobrać wtyczkę com.nazwa_wtyczki.
   </a>

Element filtru

Druga metoda polega na skorzystaniu z elementu filter jako elementu potomnego elementu, którego ma dotyczyć filtrowanie. W tym przypadku kod jest nieco dłuższy niż przy korzystaniu z atrybutu, ale rozwiązanie to stwarza większe możliwości, pozwalając na określenie dowolnej liczby filtrów w odniesieniu do elementu. Zasadniczo kod ma następującą postać:

   <element attribute="value">
      <filter name="[nazwa]" value="[modyfikator][wartość]"/>
   </element>

Parametry name i value są takie same, jak w przypadku atrybutu. Są one jednak oddzielone, w związku z czym ich zgodność należy stwierdzić inną metodą. Domyślnie zakłada się, że jeśli nie zostanie podany parametr modifier, występuje zgodność. Jeśli oczekiwany jest brak zgodności, modyfikator powinien mieć wartość "!".

Poniżej przedstawiono, w jaki sposób można uzyskać funkcjonalność opisaną na pierwszym przykładzie przy zastosowaniu drugiej metody.

   <p>
      <filter name="os" value="linux"/>
      Ten komunikat jest wyświetlany wyłącznie w systemie Linux.
</p>

Drugi przykład:

   <a href="...">
      <filter name="plugin" value="!com.nazwa_wtyczki"/>
      Kliknij tutaj, aby pobrać wtyczkę com.nazwa_wtyczki.
   </a>

Centrum informacyjne

Obsługa filtrowania jest wyłączona, jeśli system pomocy działa w trybie Centrum informacyjnego. W związku z tym widoczna jest cała treść (w tym treść objęta filtrowaniem). Jeśli dokumentacja ma być udostępniana zarówno w trybie środowiska roboczego, jak i w trybie Centrum informacyjnego, filtry należy stosować w taki sposób, aby tekst był spójny także w przypadku wyłączenia filtrowania.

Gdzie można stosować filtry?

Filtrowanie można stosować w dokumentach następującego typu:

*Uwaga: Uaktywnienie treści dynamicznej w dokumentach XHTML wymaga wykonania kilku dodatkowych czynności.

W żadnym przypadku nie wolno umieszczać filtrów w elementach, których usunięcie spowodowałoby powstanie niepoprawnego pliku XML. Filtrów nie należy na przykład umieszczać w elementach html w kodzie XHTML, ponieważ bez tych elementów pliki XHTML są traktowane jako błędne.