## 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:

- Welcome XML
- Welcome XHTML
- Help XHTML*
- Help table of contents
- Help topics in context-help

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