Filters

If certain sections of your document should only appear within a specific context, you can use filtering markup to specify criteria that must be met in order for the section of the document to appear. If the criteria are not met, that section of the document will not be visible to the user. Filters can be specified on any XML element as long as the markup will still be valid after processing. If an element is filtered, all elements and text contained under that element will also be filtered.

The table below contains a complete list of all the filter properties and their possible values.

Property Meaning Possible Values
os operating system win32, win32, linux, macosx, aix, solaris, hpux, qnx
ws windowing system win32, motif, gtk, photon, carbon
arch processor architecture x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc
product eclipse product identifier Any product identifier (e.g., for SDK, org.eclipse.sdk.ide)
plugin plug-in presence Any plug-in identifier (e.g. org.eclipse.help)
category category of activities Any activity category identifier (e.g. for Team category, org.eclipse.categories.teamCategory)
activity activity (capability) Any activity identifier (e.g. for CVS Support activity, org.eclipse.team.cvs)

If the name does not match any pre-defined property, the help system will use the JVM's system property of that name. For example, you can pass in any user-defined property at launch, such as -Dlocation=paris,france and filter by that property.

There are two ways to specify filters on an element; using attributes, or elements.

Filter Attribute

The first form is to add a filter attribute to the element. The general form is:

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

The name is the name of the property by which to filter, for example, os for operating system. The operator is either = to denote a match (exact match, case sensitive), or != to denote does not match. The value is what the property should (or shouldn't) match. For example, for os, one of the possible values is win32 (Windows). A complete list of filter properties and their values is available in a table below.

The example below shows how to display a paragraph of text in an XHTML document when running on Linux only.

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

In this second example, the link will only appear when plugin com.my.plugin is not installed:

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

Filter Element

The second form is to use a filter element as a child of the element you wish to filter. This form is slightly longer than the attribute form, but it is more powerful because you can specify any number of filters on an element. The general form is:

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

The name and value here are the same as with the attribute. However, since they are separated, we need another way to specify whether or not it should match. By default, if you do not provide a modifier, match is assumed. If it should not match, set the modifier to "! "

Here is the first example shown above in the second form:

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

And the second example:

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

Infocenter

Filtering support is turned off when running help in infocenter mode, causing all content, including filtered content, to be visible. If you intent to host your documentation in both workbench and infocenter modes, you should use filters in a way that makes sense even if filtering is turned off.

Where can I use filters?

Filtering can be used in the following types of documents:

* Note: There are a few extra steps required to enable dynamic content in your XHTML documents.

In any case, you must not place filters on any element where removing that element would result in invalid XML. For example, you should not place a filter on the html element in XHTML, because without that element it is no longer valid XHTML.