bundles/org.eclipse.platform.doc.isv/guide/ua_dynamic_filters.htm - platform/eclipse.platform.common - Git at Google

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
 <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
 <meta http-equiv="Content-Style-Type" content="text/css">
 <link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
 <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
 <title>Filters</title>

 <style type="text/css">
 	.deprecated {
 		color: #444444;
 	}
 	.warning {
 		color: red;
 	}
 	.highlight {
 		color: blue;
 	}
 </style>
 </head>
 <body>

 <h2>Filters</h2>

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

 <p>
 Filters are specified by adding an <code>&lt;enablement&gt;</code> element as a <em>child</em>
 of the element that should conditionally be filtered. The syntax used is
 <a href="../reference/api/org/eclipse/core/expressions/package-summary.html#package_description">
 core expressions</a>, which is the same syntax used to filter menu contributions, etc from the UI.
 </p>

 <h3>System tests</h3>

 <p>
 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:
 </p>

 <table border="1">
    <tr>
       <td>
          <strong>Property</strong>
       </td>
       <td>
          <strong>Meaning</strong>
       </td>
       <td>
          <strong>Possible values</strong>
       </td>
    </tr>
    <tr>
       <td>
          <code>osgi.os</code>
       </td>
       <td>
          operating system
       </td>
       <td>
          <code>win32, win32, linux, macosx, aix, solaris, hpux, qnx</code>
       </td>
    </tr>
    <tr>
       <td>
          <code>osgi.ws</code>
       </td>
       <td>
          windowing system
       </td>
       <td>
          <code>win32, motif, gtk, photon, carbon</code>
       </td>
    </tr>
    <tr>
       <td>
          <code>osgi.arch</code>
       </td>
       <td>
          processor architecture
       </td>
       <td>
          <code>x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc</code>
       </td>
    </tr>
 </table>

 <p>
 Here are a few examples of system tests:
 </p>

 <p>
 <pre>
 &lt;p&gt;
    This paragraph should only be displayed on Windows.
    <span class="highlight">&lt;enablement&gt;
       &lt;systemTest property=&quot;osgi.os&quot; value=&quot;win32&quot;/&gt;
    &lt;/enablement&gt;</span>
 &lt;/p&gt;

 &lt;p&gt;
    This paragraph should *not* be displayed on GTK.
    <span class="highlight">&lt;enablement&gt;
       &lt;not&gt;
          &lt;systemTest property=&quot;osgi.ws&quot; value=&quot;gtk&quot;/&gt;
       &lt;/not&gt;
    &lt;/enablement&gt;</span>
 &lt;/p&gt;

 &lt;p&gt;
    This paragraph should only be displayed on PowerPC Macs.
    <span class="highlight">&lt;enablement&gt;
       &lt;systemTest property=&quot;osgi.os&quot; value=&quot;macosx&quot;/&gt;
       &lt;systemTest property=&quot;osgi.arch&quot; value=&quot;ppc&quot;/&gt;
    &lt;/enablement&gt;</span>
 &lt;/p&gt;
 </pre>
 </p>

 <p>
 <em>Note: When several sub-expressions are listed with no boolean operator, they are
 by default ANDed together. See the complete
 <a href="../reference/api/org/eclipse/core/expressions/package-summary.html#package_description">
 expressions syntax</a> specification for more details.</em>
 </p>

 <h3>Property tests</h3>

 <p>
 In addition to system tests, you can test any property of an available object as long as
 there is a <a href="../reference/extension-points/org_eclipse_core_expressions_propertyTesters.html">
 property tester</a> available for it.
 </p>

 <p>
 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:
 </p>

 <ul>
    <li><code>platform</code> - The underlying platform you're running on</li>
    <li><code>workbench</code> - The UI workbench</li>
 </ul>

 <p>
 You can perform a test on one of these by using the <code>&lt;with&gt;</code> element,
 as shown below:
 </p>

 <p>
 <pre>
 &lt;enablement&gt;
    <span class="highlight">&lt;with variable=&quot;platform&quot;&gt;</span>
       &lt;test property=&quot;<em>x</em>&quot; value=&quot;<em>y</em>&quot;/&gt;
    <span class="highlight">&lt;/with&gt;</span>
 &lt;/enablement&gt;
 </pre>
 </p>

 <p>
 Each property has a namespace, which is a prefix such as <code>org.eclipse.ui</code>
 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:
 </p>

 <table border="1">
    <tr>
       <td>
          <strong>Property</strong>
       </td>
       <td>
          <strong>Object (variable)</strong>
       </td>
       <td>
          <strong>Meaning</strong>
       </td>
    </tr>
    <tr>
       <td>
          <code>org.eclipse.core.runtime.product</code>
       </td>
       <td>
          <code>platform</code>
       </td>
       <td>
          tests if the expected value matches the currently active product's unique id
       </td>
    </tr>
    <tr>
       <td>
          <code>org.eclipse.core.runtime.isBundleInstalled</code>
       </td>
       <td>
          <code>platform</code>
       </td>
       <td>
          tests if the bundle with the symbolic name (e.g. <code>org.eclipse.help</code>)
          specified as a single argument is installed on the platform
       </td>
    </tr>
    <tr>
       <td>
          <code>org.eclipse.ui.isActivityEnabled</code>
       </td>
       <td>
          <code>workbench</code>
       </td>
       <td>
          tests if the activity with the id specified as a single argument exists and
          is currently enabled in the workbench
       </td>
    </tr>
    <tr>
       <td>
          <code>org.eclipse.ui.isCategoryEnabled</code>
       </td>
       <td>
          <code>workbench</code>
       </td>
       <td>
          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
       </td>
    </tr>
 </table>

 <p>
 Here are a few examples using these properties:
 </p>

 <p>
 <pre>
 &lt;p&gt;
    This paragraph should only be displayed when running the Eclipse SDK.
    <span class="highlight">&lt;enablement&gt;
       &lt;with variable=&quot;platform&quot;&gt;
          &lt;test property=&quot;org.eclipse.core.runtime.product&quot; value=&quot;org.eclipse.sdk.ide&quot;/&gt;
       &lt;/with&gt;
    &lt;/enablement&gt;</span>
 &lt;/p&gt;

 &lt;p&gt;
    This paragraph should only be displayed when either the <code>com.myactivity.a</code> or
    <code>com.myactivity.b</code> activity (or both) is enabled in the workbench.
    <span class="highlight">&lt;enablement&gt;
       &lt;with variable=&quot;workbench&quot;&gt;
          &lt;or&gt;
             &lt;test property=&quot;org.eclipse.ui.isActivityEnabled&quot; args=&quot;com.myactivity.a&quot;/&gt;
             &lt;test property=&quot;org.eclipse.ui.isActivityEnabled&quot; args=&quot;com.myactivity.b&quot;/&gt;
          &lt;or&gt;
       &lt;/with&gt;
    &lt;/enablement&gt;</span>
 &lt;/p&gt;

 &lt;p&gt;
    This paragraph should only be displayed when the <code>com.mycategory</code> category
    is enabled and the <code>com.mybundle</code> bundle is not installed.
    <span class="highlight">&lt;enablement&gt;
       &lt;with variable=&quot;workbench&quot;&gt;
          &lt;test property=&quot;org.eclipse.ui.isCategoryEnabled&quot; args=&quot;com.mycategory&quot;/&gt;
       &lt;/with&gt;
       &lt;with variable=&quot;platform&quot;&gt;
          &lt;not&gt;
             &lt;test property=&quot;org.eclipse.core.runtime.isBundleInstalled&quot; args=&quot;com.mybundle&quot;/&gt;
          &lt;/not&gt;
       &lt;/with&gt;
    &lt;/enablement&gt;</span>
 &lt;/p&gt;
 </pre>
 </p>

 <p>
 <em>Note: Make sure you use the <code>value</code> and <code>args</code> attributes for the appropriate
 tests. In general, string properties like product will use <code>value</code> where boolean
 tests (<code>isSomethingTrue</code>) will use <code>args</code>. See the complete
 <a href="../reference/api/org/eclipse/core/expressions/package-summary.html#package_description">
 expressions syntax</a> specification for more details on how to write expressions.</em>
 </p>

 <h3>Defining your own test</h3>

 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
 <a href="../reference/extension-points/org_eclipse_core_expressions_propertyTesters.html">
 property tester</a>.

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

 <h3>Filter attributes/elements <span class="warning">(deprecated)</span></h3>

 <p>
 Prior to the 3.3, filters were specified using <code>filter</code> attributes or elements.
 The use of these filters is now deprecated, and you should use expressions (described
 above) instead.
 </p>

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

 <span class="warning">(deprecated)</span>
 <table class="deprecated" border="1">
    <tr>
       <td>
          <b>Property</b>
       </td>
       <td>
          <b>Meaning</b>
       </td>
       <td>
          <b>Possible Values</b>
       </td>
    </tr>
    <tr>
       <td>
          <code>os</code>
       </td>
       <td>
          operating system
       </td>
       <td>
          <code>win32, win32, linux, macosx, aix, solaris, hpux, qnx</code>
       </td>
    </tr>
    <tr>
       <td>
          <code>ws</code>
       </td>
       <td>
          windowing system
       </td>
       <td>
          <code>win32, motif, gtk, photon, carbon</code>
       </td>
    </tr>
    <tr>
       <td>
          <code>arch</code>
       </td>
       <td>
          processor architecture
       </td>
       <td>
          <code>x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc</code>
       </td>
    </tr>
    <tr>
       <td>
          <code>product</code>
       </td>
       <td>
          eclipse product identifier
       </td>
       <td>
          Any product identifier (e.g., for SDK, <code>org.eclipse.sdk.ide</code>)
       </td>
    </tr>
    <tr>
       <td>
          <code>plugin</code>
       </td>
       <td>
          plug-in presence
       </td>
       <td>
          Any plug-in identifier (e.g. <code>org.eclipse.help</code>)
       </td>
    </tr>
    <tr>
       <td>
          <code>category</code>
       </td>
       <td>
          category of activities
       </td>
       <td>
          Any activity category identifier (e.g. for Team category,
          <code>org.eclipse.categories.teamCategory</code>)
       </td>
    </tr>
    <tr>
       <td>
          <code>activity</code>
       </td>
       <td>
          activity (capability)
       </td>
       <td>
          Any activity identifier (e.g. for CVS Support activity,
          <code>org.eclipse.team.cvs</code>)
       </td>
    </tr>
 </table>

 <p>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 <code>-Dlocation=paris,france</code>
 and filter by that property.</p>

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

 <h3>Filter Attribute <span class="warning">(deprecated)</span></h3>

 <p>The first form is to add a <span class="highlight"><code>filter</code></span> attribute
 to the element. The general form is:</p>

 <pre>
    &lt;element <span class="highlight">filter="[name][operator][value]"</span>&gt;
       Some text.
    &lt;/element&gt;
 </pre>

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

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

 <pre>
    &lt;p filter="os=linux"&gt;
       This message will only appear when viewed on Linux.
    &lt;/p&gt;
 </pre>

 <p>In this second example, the link will only appear when plugin
 <code>com.my.plugin</code> is not installed:</p>

 <pre>
    &lt;a href="..." filter="plugin!=com.my.plugin"&gt;
       Click here to download plugin com.my.plugin.
    &lt;/a&gt;
 </pre>

 <h3>Filter Element <span class="warning">(deprecated)</span></h3>

 <p>The second form is to use a <code>filter</code> element as a <i>child</i> 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:</p>

 <pre>
    &lt;element attribute="value"&gt;
       <span class="highlight"><code>&lt;filter name="[name]" value="[modifier][value]"/&gt;</code></span>
    &lt;/element&gt;
 </pre>

 <p>The <span class="highlight"><code>name</code></span> and <span class="highlight"><code>
 value</code></span> 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 <span class="highlight"><code>modifier</code></span>,
 match is assumed. If it should <i>not</i> match, set the modifier to "<code>!</code>
 "</p>

 <p>Here is the first example shown above in the second form:</p>

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

 <p>And the second example:</p>

 <pre>
    &lt;a href="..."&gt;
       &lt;filter name="plugin" value="!com.my.plugin"/&gt;
       Click here to download plugin com.my.plugin.
    &lt;/a&gt;
 </pre>

 <h3>Infocenter</h3>

 <p>
 Filtering support is turned <strong>off</strong> when running help in
 <a href="ua_help_setup_infocenter.htm">infocenter</a> 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.
 </p>

 <h3>Where can I use filters?</h3>

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

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

 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
	<html>
	<head>
	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2006. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
	<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<meta http-equiv="Content-Style-Type" content="text/css">
	<link rel="STYLESHEET" href="../book.css" charset="ISO-8859-1" type="text/css">
	<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script>
	<title>Filters</title>

	<style type="text/css">
	.deprecated {
	color: #444444;
	}
	.warning {
	color: red;
	}
	.highlight {
	color: blue;
	}
	</style>
	</head>
	<body>

	<h2>Filters</h2>

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

	<p>
	Filters are specified by adding an <code><enablement></code> element as a <em>child</em>
	of the element that should conditionally be filtered. The syntax used is
	<a href="../reference/api/org/eclipse/core/expressions/package-summary.html#package_description">
	core expressions</a>, which is the same syntax used to filter menu contributions, etc from the UI.
	</p>

	<h3>System tests</h3>

	<p>
	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:
	</p>

	<table border="1">
	<tr>
	<td>
	<strong>Property</strong>
	</td>
	<td>
	<strong>Meaning</strong>
	</td>
	<td>
	<strong>Possible values</strong>
	</td>
	</tr>
	<tr>
	<td>
	<code>osgi.os</code>
	</td>
	<td>
	operating system
	</td>
	<td>
	<code>win32, win32, linux, macosx, aix, solaris, hpux, qnx</code>
	</td>
	</tr>
	<tr>
	<td>
	<code>osgi.ws</code>
	</td>
	<td>
	windowing system
	</td>
	<td>
	<code>win32, motif, gtk, photon, carbon</code>
	</td>
	</tr>
	<tr>
	<td>
	<code>osgi.arch</code>
	</td>
	<td>
	processor architecture
	</td>
	<td>
	<code>x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc</code>
	</td>
	</tr>
	</table>

	<p>
	Here are a few examples of system tests:
	</p>

	<p>
	<pre>
	<p>
	This paragraph should only be displayed on Windows.
	<span class="highlight"><enablement>
	<systemTest property="osgi.os" value="win32"/>
	</enablement></span>
	</p>

	<p>
	This paragraph should not be displayed on GTK.
	<span class="highlight"><enablement>
	<not>
	<systemTest property="osgi.ws" value="gtk"/>
	</not>
	</enablement></span>
	</p>

	<p>
	This paragraph should only be displayed on PowerPC Macs.
	<span class="highlight"><enablement>
	<systemTest property="osgi.os" value="macosx"/>
	<systemTest property="osgi.arch" value="ppc"/>
	</enablement></span>
	</p>
	</pre>
	</p>

	<p>
	<em>Note: When several sub-expressions are listed with no boolean operator, they are
	by default ANDed together. See the complete
	<a href="../reference/api/org/eclipse/core/expressions/package-summary.html#package_description">
	expressions syntax</a> specification for more details.</em>
	</p>

	<h3>Property tests</h3>

	<p>
	In addition to system tests, you can test any property of an available object as long as
	there is a <a href="../reference/extension-points/org_eclipse_core_expressions_propertyTesters.html">
	property tester</a> available for it.
	</p>

	<p>
	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:
	</p>

	<ul>
	<li><code>platform</code> - The underlying platform you're running on</li>
	<li><code>workbench</code> - The UI workbench</li>
	</ul>

	<p>
	You can perform a test on one of these by using the <code><with></code> element,
	as shown below:
	</p>

	<p>
	<pre>
	<enablement>
	<span class="highlight"><with variable="platform"></span>
	<test property="<em>x</em>" value="<em>y</em>"/>
	<span class="highlight"></with></span>
	</enablement>
	</pre>
	</p>

	<p>
	Each property has a namespace, which is a prefix such as <code>org.eclipse.ui</code>
	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:
	</p>

	<table border="1">
	<tr>
	<td>
	<strong>Property</strong>
	</td>
	<td>
	<strong>Object (variable)</strong>
	</td>
	<td>
	<strong>Meaning</strong>
	</td>
	</tr>
	<tr>
	<td>
	<code>org.eclipse.core.runtime.product</code>
	</td>
	<td>
	<code>platform</code>
	</td>
	<td>
	tests if the expected value matches the currently active product's unique id
	</td>
	</tr>
	<tr>
	<td>
	<code>org.eclipse.core.runtime.isBundleInstalled</code>
	</td>
	<td>
	<code>platform</code>
	</td>
	<td>
	tests if the bundle with the symbolic name (e.g. <code>org.eclipse.help</code>)
	specified as a single argument is installed on the platform
	</td>
	</tr>
	<tr>
	<td>
	<code>org.eclipse.ui.isActivityEnabled</code>
	</td>
	<td>
	<code>workbench</code>
	</td>
	<td>
	tests if the activity with the id specified as a single argument exists and
	is currently enabled in the workbench
	</td>
	</tr>
	<tr>
	<td>
	<code>org.eclipse.ui.isCategoryEnabled</code>
	</td>
	<td>
	<code>workbench</code>
	</td>
	<td>
	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
	</td>
	</tr>
	</table>

	<p>
	Here are a few examples using these properties:
	</p>

	<p>
	<pre>
	<p>
	This paragraph should only be displayed when running the Eclipse SDK.
	<span class="highlight"><enablement>
	<with variable="platform">
	<test property="org.eclipse.core.runtime.product" value="org.eclipse.sdk.ide"/>
	</with>
	</enablement></span>
	</p>

	<p>
	This paragraph should only be displayed when either the <code>com.myactivity.a</code> or
	<code>com.myactivity.b</code> activity (or both) is enabled in the workbench.
	<span class="highlight"><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></span>
	</p>

	<p>
	This paragraph should only be displayed when the <code>com.mycategory</code> category
	is enabled and the <code>com.mybundle</code> bundle is not installed.
	<span class="highlight"><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></span>
	</p>
	</pre>
	</p>

	<p>
	<em>Note: Make sure you use the <code>value</code> and <code>args</code> attributes for the appropriate
	tests. In general, string properties like product will use <code>value</code> where boolean
	tests (<code>isSomethingTrue</code>) will use <code>args</code>. See the complete
	<a href="../reference/api/org/eclipse/core/expressions/package-summary.html#package_description">
	expressions syntax</a> specification for more details on how to write expressions.</em>
	</p>

	<h3>Defining your own test</h3>

	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
	<a href="../reference/extension-points/org_eclipse_core_expressions_propertyTesters.html">
	property tester</a>.

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

	<h3>Filter attributes/elements <span class="warning">(deprecated)</span></h3>

	<p>
	Prior to the 3.3, filters were specified using <code>filter</code> attributes or elements.
	The use of these filters is now deprecated, and you should use expressions (described
	above) instead.
	</p>

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

	<span class="warning">(deprecated)</span>
	<table class="deprecated" border="1">
	<tr>
	<td>
	<b>Property</b>
	</td>
	<td>
	<b>Meaning</b>
	</td>
	<td>
	<b>Possible Values</b>
	</td>
	</tr>
	<tr>
	<td>
	<code>os</code>
	</td>
	<td>
	operating system
	</td>
	<td>
	<code>win32, win32, linux, macosx, aix, solaris, hpux, qnx</code>
	</td>
	</tr>
	<tr>
	<td>
	<code>ws</code>
	</td>
	<td>
	windowing system
	</td>
	<td>
	<code>win32, motif, gtk, photon, carbon</code>
	</td>
	</tr>
	<tr>
	<td>
	<code>arch</code>
	</td>
	<td>
	processor architecture
	</td>
	<td>
	<code>x86, x86_64, ia64, ia64_32, ppc, PA_RISC, sparc</code>
	</td>
	</tr>
	<tr>
	<td>
	<code>product</code>
	</td>
	<td>
	eclipse product identifier
	</td>
	<td>
	Any product identifier (e.g., for SDK, <code>org.eclipse.sdk.ide</code>)
	</td>
	</tr>
	<tr>
	<td>
	<code>plugin</code>
	</td>
	<td>
	plug-in presence
	</td>
	<td>
	Any plug-in identifier (e.g. <code>org.eclipse.help</code>)
	</td>
	</tr>
	<tr>
	<td>
	<code>category</code>
	</td>
	<td>
	category of activities
	</td>
	<td>
	Any activity category identifier (e.g. for Team category,
	<code>org.eclipse.categories.teamCategory</code>)
	</td>
	</tr>
	<tr>
	<td>
	<code>activity</code>
	</td>
	<td>
	activity (capability)
	</td>
	<td>
	Any activity identifier (e.g. for CVS Support activity,
	<code>org.eclipse.team.cvs</code>)
	</td>
	</tr>
	</table>

	<p>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 <code>-Dlocation=paris,france</code>
	and filter by that property.</p>

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

	<h3>Filter Attribute <span class="warning">(deprecated)</span></h3>

	<p>The first form is to add a <span class="highlight"><code>filter</code></span> attribute
	to the element. The general form is:</p>

	<pre>
	<element <span class="highlight">filter="[name][operator][value]"</span>>
	Some text.
	</element>
	</pre>

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

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

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

	<p>In this second example, the link will only appear when plugin
	<code>com.my.plugin</code> is not installed:</p>

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

	<h3>Filter Element <span class="warning">(deprecated)</span></h3>

	<p>The second form is to use a <code>filter</code> element as a <i>child</i> 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:</p>

	<pre>
	<element attribute="value">
	<span class="highlight"><code><filter name="[name]" value="[modifier][value]"/></code></span>
	</element>
	</pre>

	<p>The <span class="highlight"><code>name</code></span> and <span class="highlight"><code>
	value</code></span> 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 <span class="highlight"><code>modifier</code></span>,
	match is assumed. If it should <i>not</i> match, set the modifier to "<code>!</code>
	"</p>

	<p>Here is the first example shown above in the second form:</p>

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

	<p>And the second example:</p>

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

	<h3>Infocenter</h3>

	<p>
	Filtering support is turned <strong>off</strong> when running help in
	<a href="ua_help_setup_infocenter.htm">infocenter</a> 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.
	</p>

	<h3>Where can I use filters?</h3>

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

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

	</body>
	</html>