Eclipse Plug-in Developer Guide (Galileo)

Eclipse Plug-in Developer Guide
Previous Page	Home	Next Page

Platform Plug-in Developer Guide Programmer's Guide User assistance support Dynamic content

Filters

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.

System tests

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:

Property	Meaning	Possible values
`osgi.os`	operating system	`win32, win32, linux, macosx, aix, solaris, hpux, qnx`
`osgi.ws`	windowing system	`win32, motif, gtk, photon, carbon`
`osgi.arch`	processor architecture	`x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc`

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.

Property tests

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 <with> element, 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 org.eclipse.ui 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:

Property	Object (variable)	Meaning
`org.eclipse.core.runtime.product`	`platform`	tests if the expected value matches the currently active product's unique id
`org.eclipse.core.runtime.isBundleInstalled`	`platform`	tests if the bundle with the symbolic name (e.g. `org.eclipse.help`) specified as a single argument is installed on the platform
`org.eclipse.ui.isActivityEnabled`	`workbench`	tests if the activity with the id specified as a single argument exists and is currently enabled in the workbench
`org.eclipse.ui.isCategoryEnabled`	`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.a or
   com.myactivity.b activity (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.mycategory category
   is enabled and the com.mybundle bundle 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 value and args attributes for the appropriate tests. In general, string properties like product will use value where boolean tests (isSomethingTrue) will use args. See the complete expressions syntax specification for more details on how to write expressions.

Defining your own test

The core expressions framework allows you define your own test that can test on any arbitrary property of any object that is accessible through the variables defined for the context you're in. You do this by defining a property tester.

Note: The variables platform and workbench resolve to the org.eclipse.core.runtime.Platform Class object (we use the class object for "static" tests) and the singleton org.eclipse.ui.IWorkbench instance, respectively. Your property tester must declare one of these two classes for its type.

Using Filters in Table of Contents (TOC) Files

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>

Filter attributes/elements (deprecated)

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 above) instead.

The table below contains a complete list of all the filter properties and their possible values for use with filter elements and attributes.

(deprecated)

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 (deprecated)

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 (deprecated)

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