Adding criteria to help content

This page will explain how to activate criteria. To enable criteria you need define which criteria are associated with each topic and also set preferences which tell the help system to show criteria. The association between criteria and topics can be either in a toc file or using a criteria provider class.

What are criteria?

Some topics of the plug-in might only be of interest to certain users, for example a topic may be specific to the linux platform. The document writer can define a criterion "platform" with values such as "linux", "windows" etc applied to different topics. The user can then filter the documentation to show only documents applicable to a specific platform.

How to define criteria in a table of contents file

When defining a table of contents file criteria information can be appended according to these steps:

Add criteria tag as children to the topic.
Use id to define 'name' and 'value' attribute of the criteria element

For example:

 <toc href="tochref">
      <criteria  name="platform"  value="AIX"/>
      <criteria  name="platform"  value="Windows"/>
      <topic label="label1" href="href1">
          <criteria  name="platform" value="Windows"/>
      </topic>
      <topic label="label2" href="href2">
          <criteria name="platform" value="AIX"/>
      </topic>
 </toc>

Some rules to follow when adding criteria:

The criteria name is case insensitive but the criteria value is case sensitive.
It is important to ensure that parent topics contain all of the criteria of any of their children, the parent and child will not show in the table of contents if filtered using criteria which only the child satisfies.
Any criterion with an empty value is invalid and will be ignored.
Multiple comma separated values can be specified in a single <criteria> element, for example <criteria name="Platform" value="AIX,Linux"/>. The name attribute takes a single value.

How to define criteria using a criteria provider

As an alternative to defining criteria in a table of contents file the extension point org.eclipse.criteriaProvider can be used to define a class which will associate criteria with topics. Criteria defined using this extension point will be merged with those defined in the table of contents and if multiple criteria providers are defined each will contribute to the criteria of an ITopic or IToc.

Criteria localization

The names and values of criteria can be localized. Follow these steps to add localization information for criteria:

In plugin.xml, use the extension point org.eclipse.help.criteriaDefinition to provide the criteria definition file. (if no translation file is provided, then the id of criteria name and value will be displayed). For example:
```
 <extension point="org.eclipse.help.criteriaDefinition">
      <criteriaDefinition file="criteria.xml"/>
 </extension>
```
In the definition file, define the translation of criteria information. Node 'criterion' represents the criterion name. Node 'criterion-value' represents the criterion value. All 'id' attributes represent the id of criterion name or value. All 'name' attributes represent the display name of criteria name or value in one specific locale. For example:
```
 <criteriaDefinition>
      <criterion id="platform" name="Platform">
          <criterion-value id="AIX" name="AIX Server"/>
          <criterion-value id="Windows" name="Windows Server"/>
      </criterion>
 </criteriaDefinition>
```

How to set the preferences to enable criteria

Define the necessary preferences in your plugin customization file.

enableCriteria. This preference must be true to enable filtering by criteria.
```
example: org.eclipse.help/enableCriteria = true
```
supportedCriteria. A comma separated list of the criteria which will be supported in the help system.
```
example: org.eclipse.help/supportedCriteria = platform,version
```
which means that 'platform' and 'version' are the supported criteria in help system.