Filter

Falls bestimmte Abschnitte eines Dokuments nur in einem bestimmten Kontext angezeigt werden sollen, können Sie mit der Markup-Formatierung für die Filterung Bedingungen angeben, die erfüllt sein müssen, damit der Abschnitt des Dokuments angezeigt wird. Falls die Bedingungen nicht erfüllt werden, ist der entsprechende Abschnitt des Dokuments für den Benutzer nicht sichtbar. Filter können für jedes beliebige XML-Element angegeben werden, sofern die Markup-Formatierung nach der Verarbeitung noch gültig ist. Falls ein Element gefiltert wird, werden alle Elemente und auch der gesamte Text unter diesem Element gefiltert.

Die folgende Tabelle enthält eine vollständige Liste aller Filtereigenschaften und ihrer möglichen Werte.

Eigenschaft Bedeutung Gültige Werte
os Betriebssystem win32, win32, linux, macosx, aix, solaris, hpux, qnx
ws Fenstertechnik win32, motif, gtk, photon, carbon
arch Prozessorarchitektur x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc
product Eclipse-Produkt-ID Jede beliebige Produkt-ID (z. B. org.eclipse.sdk.ide für SDK)
plugin Plug-in-Vorkommen Jede beliebige Plug-in-ID (z. B. org.eclipse.help)
category Kategorie der Aktivitäten Jede beliebige Aktivitätenkategorie-ID (z. B. org.eclipse.categories.teamCategory für die Kategorie "Team")
activity Aktivität (Funktionalität) Jede beliebige Aktivitäten-ID (z. B. org.eclipse.team.cvs für Aktivität der CVS-Unterstützung)

Falls der Name nicht mit einer der vordefinierten Eigenschaften übereinstimmt, verwendet die Hilfefunktion die JVM-Systemeigenschaft dieses Namens. Sie können beispielsweise beim Startvorgang jede beliebige benutzerdefinierte Eigenschaft (z. B. -Dlocation=paris,france) übergeben und eine Filterung nach dieser Eigenschaft vornehmen.

Für die Angabe von Filtern für ein Element haben Sie zwei Möglichkeiten, nämlich entweder die Verwendung von Attributen oder die Verwendung von Elementen.

Attribut "filter"

Die erste Möglichkeit besteht darin, ein Attribut filter zum Element hinzuzufügen. Das allgemeine Format lautet:

   <element filter="[name][operator][wert]">
      Beliebiger Text.
   </element>

Der Wert für name gibt den Namen der Eigenschaft an, nach der die Filterung erfolgen soll, beispielsweise os für das Betriebssystem. Die Variable operator steht entweder für =, um eine Übereinstimmung (exakte Übereinstimmung, Groß-/Kleinschreibung muss beachtet werden) anzugeben, oder für !=, um keine Übereinstimmung anzugeben. Die Variable wert steht für den Wert, mit dem die Eigenschaft übereinstimmen (bzw. nicht übereinstimmen) soll. Einer der gültigen Werte für os ist beispielsweise win32 (Windows). Eine vollständige Liste der Filtereigenschaften und ihrer Werte ist in einer folgenden Tabelle enthalten.

Das folgende Beispiel zeigt, wie ein Textabschnitt in einem XHTML-Dokument ausschließlich bei der Ausführung unter Linux angezeigt wird:

   <p filter="os=linux">
      Diese Nachricht wird nur beim Anzeigen unter Linux ausgegeben.
   </p>

Im zweiten Beispiel wird der Link nur dann angezeigt, wenn das Plug-in com.my.plugin nicht installiert ist:

   <a href="..." filter="plugin!=com.my.plugin">
      Klicken Sie hier, um das Plug-in 'com.my.plugin' herunterzuladen.
   </a>

Element "filter"

Die zweite Möglichkeit besteht in der Verwendung eines Elements filter als untergeordnetes Element desjenigen Elements, das Sie filtern wollen. Dieses Format ist etwas länger als das Format mit der Verwendung des Attributs, bietet jedoch ein größeres Leistungsspektrum, weil Sie für ein Element beliebig viele Filter angeben können. Das allgemeine Format lautet:

   <element attribute="wert">
      <filter name="[name]" value="[änderungswert][wert]"/>
   </element>

Die Variablen name und wert haben hier dieselbe Bedeutung wie bei der Verwendung des Attributs. Da sie separat angegeben werden, muss jedoch auf andere Weise angegeben werden, ob eine Übereinstimmung vorliegen soll oder nicht. Falls Sie keine Angabe für die Variable änderungswert machen, wird standardmäßig von einer Übereinstimmung ausgegangen. Wenn Sie keine Übereinstimmung wünschen, setzen Sie den Änderungswert auf ! "

Hier sehen Sie das erste Beispiel im zweiten Format:

   <p>
      <filter name="os" value="linux"/>
      Diese Nachricht wird nur beim Anzeigen unter Linux ausgegeben.
   </p>

Hier das zweite Beispiel:

   <a href="...">
      <filter name="plugin" value="!com.my.plugin"/>
      Klicken Sie hier, um das Plug-in 'com.my.plugin' herunterzuladen.
   </a>

Infocenter

Die Unterstützung der Filterung ist inaktiviert, wenn die Hilfefunktion im Modus für das Infocenter ausgeführt wird, weshalb in diesem Fall der gesamte Inhalt (auch der gefilterte Inhalt) sichtbar ist. Falls Sie Ihre Dokumentation sowohl im Modus für die Workbench als auch im Modus für das Infocenter bereitstellen wollen, sollten Sie Filter verwenden, die auch dann sinnvoll sind, wenn die Filterung inaktiviert ist.

Einsatzmöglichkeiten für Filter

Filter können bei den folgenden Dokumenttypen verwendet werden:

* Hinweis: Zur Aktivierung von dynamischem Inhalt in XHTML-Dokumenten sind einige zusätzliche Schritte erforderlich.

Sie dürfen auf keinen Fall Filter für Elemente setzen, bei denen das Entfernen des Elements zu einer ungültigen XML-Datei führen würde. Beispielsweise sollten Sie in XHTML keinen Filter für das Element html definieren, da die XHTML-Datei ohne dieses Element nicht mehr gültig ist.