Adding criteria to help content

### Eclipse Workspace Patch 1.0 #P org.eclipse.platform.doc.isv Index: guide/ua_help_content_criteria.htm =================================================================== RCS file: guide/ua_help_content_criteria.htm diff -N guide/ua_help_content_criteria.htm --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ guide/ua_help_content_criteria.htm 1 Jan 1970 00:00:00 -0000 @@ -0,0 +1,113 @@ + + + + + + + + +Adding criteria to help content + + + +

Adding criteria to help content

+ +

This page will explain how to activate criteria. Criteria must be defined either in the toc or using a +criteria provider and that the preferences must be set to enable criteria.

+ +

What is criteria

+ +

Some topics of the plug-in might only focus on some special fields. +Criteria information is added to represent these fields, which will be helpful for users to locate topics they interested in. +

+ +

Define criteria in table of contents

+ +

When defining Toc structure, 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 rule to follow when adding criteria:

The criteria name's id is case insensitive but the criteria value's id is case sensitive.
Comma is not suggested to contain in criteria name or value's id.
Criteria set of one topic need to be the superset of criteria set of all its descendant topics.
Any criteria with empty value are invalid and they will be ignored.

+ +

Define criteria using criteria provider

Uses class AbstractCriteriaProvider to allow for criteria to be defined dynamically. +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. +

+ +

Pending for Chris to fill in some detail information...

+ + +

Criteria localization

Localization is supported in criteria definition. +Follow these steps to add localization information for criteria:

In plugin.xml, using the extension point -- 'org.eclipse.help.criteriaDefinition' +to provide the criteria definition file(if no such translation file, 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 definition file, define the translation of criteria information. +Node 'criterion' represent the criterion name. +Node 'criterion-value' represent the criterion value. +All 'id' attribute represent the id of criterion name or value. +All 'name' attribute 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>
+
```
+

Set preference to enable criteria

Define necessary parameter in org.eclipse.help/preference.ini to enable criteria

Parameter -- enableCriteria. This parameter is the switch of the criteria filtering. +Set true/false to enable/disable criteria filtering. +
```
example: enableCriteria = true/false
```
Parameter -- supportedCriteria. This parameter is to define supported criteria in help system. +All supported criteria's ids can be listed here, comma is used to separated them. +
```
example: supportedCriteria = platform,version
```
+which means that 'platform' and 'version' are the supported criteria in help system. +

+ + \ No newline at end of file Index: topics_Guide.xml =================================================================== RCS file: /cvsroot/eclipse/org.eclipse.platform.doc.isv/topics_Guide.xml,v retrieving revision 1.199 diff -u -r1.199 topics_Guide.xml --- topics_Guide.xml 13 Apr 2010 17:10:29 -0000 1.199 +++ topics_Guide.xml 14 May 2010 06:27:51 -0000 @@ -384,6 +384,7 @@ +