If some sections of a document (e.g. a list item in a XHTML help topic) should only be displayed to the user if certain conditions are met, you can specify an enablement expression declaring the criteria that must be met in order to display the element.
Filters are specified by adding an
<enablement> element as a child
of the element that should conditionally be filtered. The syntax used is
core expressions, which is the same syntax used to filter menu contributions, etc from the UI.
Expressions check criteria by performing tests. One type of test is a system test, which tests a system property against an expected value. Some common system properties to test by are listed below:
Here are a few examples of system tests:
<p> This paragraph should only be displayed on Windows. <enablement> <systemTest property="osgi.os" value="win32"/> </enablement> </p> <p> This paragraph should *not* be displayed on GTK. <enablement> <not> <systemTest property="osgi.ws" value="gtk"/> </not> </enablement> </p> <p> This paragraph should only be displayed on PowerPC Macs. <enablement> <systemTest property="osgi.os" value="macosx"/> <systemTest property="osgi.arch" value="ppc"/> </enablement> </p>
Note: When several sub-expressions are listed with no boolean operator, they are by default ANDed together. See the complete expressions syntax specification for more details.
In addition to system tests, you can test any property of an available object as long as there is a property tester available for it.
Tests always perform their test on a property of some object, and each object has different properties you can test. User assistance provides two variables that are used to select the object to test on:
platform- The underlying platform you're running on
workbench- The UI workbench
You can perform a test on one of these by using the
as shown below:
<enablement> <with variable="platform"> <test property="x" value="y"/> </with> </enablement>
Each property has a namespace, which is a prefix such as
that is used to minimize the chances of duplicate properties being defined by two
components. The table below shows some common properties you can test by:
||tests if the expected value matches the currently active product's unique id|
tests if the bundle with the symbolic name (e.g.
||tests if the activity with the id specified as a single argument exists and is currently enabled in the workbench|
||tests if the category of activities with the id specified as a single argument exists and is currently enabled in the workbench. A category is enabled if all its activities are enabled|
Here are a few examples using these properties:
<p> This paragraph should only be displayed when running the Eclipse SDK. <enablement> <with variable="platform"> <test property="org.eclipse.core.runtime.product" value="org.eclipse.sdk.ide"/> </with> </enablement> </p> <p> This paragraph should only be displayed when either the
com.myactivity.bactivity (or both) is enabled in the workbench. <enablement> <with variable="workbench"> <or> <test property="org.eclipse.ui.isActivityEnabled" args="com.myactivity.a"/> <test property="org.eclipse.ui.isActivityEnabled" args="com.myactivity.b"/> <or> </with> </enablement> </p> <p> This paragraph should only be displayed when the
com.mycategorycategory is enabled and the
com.mybundlebundle is not installed. <enablement> <with variable="workbench"> <test property="org.eclipse.ui.isCategoryEnabled" args="com.mycategory"/> </with> <with variable="platform"> <not> <test property="org.eclipse.core.runtime.isBundleInstalled" args="com.mybundle"/> </not> </with> </enablement> </p>
Note: Make sure you use the
args attributes for the appropriate
tests. In general, string properties like product will use
value where boolean
isSomethingTrue) will use
args. See the complete
expressions syntax specification for more details on how to write expressions.
Note: The variables
workbench resolve to the
org.eclipse.core.runtime.Platform Class object (we use the class object for
"static" tests) and the singleton
respectively. Your property tester must declare one of these two classes for its type.
Filters can be used in Table of Contents files to filter out content that does not apply to the current installation. The example below is a topic which is only included in the TOC if plugin x.y.z is running.
<topic href="html/subtopic.html" label="This topic is shown only if plugin x,y.z is running"> <enablement> <with variable="platform"> <test property="org.eclipse.core.runtime.isBundleInstalled" args="x.y.z"/> </with> </enablement> </topic>
Prior to the 3.3, filters were specified using
filter attributes or elements.
The use of these filters is now deprecated, and you should use expressions (described
The table below contains a complete list of all the filter properties and their possible values for use with filter elements and attributes.(deprecated)
||eclipse product identifier||
Any product identifier (e.g., for SDK,
Any plug-in identifier (e.g.
||category of activities||
Any activity category identifier (e.g. for Team category,
Any activity identifier (e.g. for CVS Support activity,
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
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
to the element. The general form is:
<element filter="[name][operator][value]"> Some text. </element>
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
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:
<filter name="[name]" value="[modifier][value]"/></element>
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
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 by default when running help in
information center mode, causing all content,
including filtered content, to be visible. If you intend to host your
documentation in both workbench and information center modes, you should use filters in
a way that makes sense even if filtering is turned off. If you wish to turn on filtering
in an information center set the customization preference
filterInfocenter to true,
see help system customization.
Filtering can be used in any XML-based user assistance document, such as help XHTML topics, help table of contents, welcome pages, cheat sheets, etc. You cannot use filtering in HTML 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