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