Proposal

Dynamic Content in Eclipse Help System Pages

Summary
This document describes a proposal to introduce dynamic and reusable content in the Eclipse Help System pages. This support will be part of the Eclipse 3.2 release and will be introduced in M4. It is expected that apis will be finalized by M5.

 

The Problem

With the widespread popularity of the Eclipse platform as the base for many software products and with the increasing scope of the technology behind these products, the size of the online documentation is also scaling accordingly. This puts more emphasis on supporting reusable and dynamic content in the Eclipse Help System documentation pages. The requirement is that it should be possible to reuse content, and this can be accomplished in two ways: by including content from another existing page, or by contributing content to an existing help system page. Also, conditional filtering is needed to allow for exposing only the appropriate portion of the documentation to the end user. Portions of content can be made visible to the end user based on certain filtering criteria.

Proposed Solution

As of Eclipse 3.1, Help System documents where static. They where html documents that where served statically and as-is to the Help System browser. In order to enable dynamic content manipulation Help documents, the content of these files needs to be parsed, manipulated and then served to the browser. To enable this, a new support for using XHTML documents as pages in the Help System is added.

XHTML pages are contributed and used in a TOC just like any other html page. The only difference is that the declaring plugin that hosts these pages needs to declare to the Help system that it is a special plugin and that it needs to be consulted when pages are to be served from this plugin. This is done using an existing Help System extension point called org.eclipse.help.contentProducer. The only difference is that the plugin will reuse an existing pre-supplied class that will handle all the content from this plugin, including the XHTML pages. Here is how a plugin would declare itself as a plugin that needs to serve XHTML documents: 

<extension point="org.eclipse.help.contentProducer"
  id="some.id.dynamicContentProducer"
  name="XHTML content producer">
   <contentProducer
    producer="org.eclipse.help.internal.DynamicContentProducer">
   </contentProducer>
 </extension>

With the above declaration, a plugin can then define and contribute XHTML pages in TOCs just like any other html page. These XHTML pages can now be displayed as is, or they can be manipulated to support dynamic content and filtering. The rest of the document will describe how conditional filtering and dynamic content will be supported.

 

Conditional Filtering

Portions of a Help document need to be filtered out based on certain conditions. These conditions are operating system (os), windowing system (ws), Eclipse platform category, activity, or product, and finaly, the existence of a given plugin in the current install. Also, user defined filtering keys can be used as filtering criteria. These would be defined as system properties that are passed to the vm, and they would then be used in documents to control filtering. A filter can be applied to any element in an XHTML document. If an element has a filter applied to it, the it will only be shown if the filtering criteria is met.

Filtering by pre-defined properties

Here is how an element (for example, a paragraph) in an XHTML document can be filtered using pre-defined filtering criteria: 

filtering by OS:
<p filter="os=win32,linux">
   This text should only show up when running on a Win32 or a Linux based operating system.
   Short hand version of the filter element can only be used for a single filter criteria.
   Colon separated values of the filter attribute represent multiple values.
</p>

filtering by WS:
<p filter="ws=win32">
   This text should only show up when running on a machine using the Windows windowing system.
</p>

filtering by Eclipse Category:
<p filter="category=org.eclipse.categories.developmentCategory">
   This text should only show up when the Development category defined in the Eclipse 
   SDK is enabled.
</p>

filtering by Eclipse Activity:
<p filter="activity=org.eclipse.javaDevelopment">
   This text should only show up when the Java Development activity defined in the Eclipse 
   SDK is enabled.
</p>

filtering based on the existance of an Eclipse Plugin:
<p filter="plugin=org.eclipse.platform">
   This text should only show up if the org.eclpise.platform plugin is installed and is 
   in an active state.
</p>

filtering by Eclipse Product:
<p filter="product=org.eclipse.platform.ide">
   This text should only show up when the platform is run as a product with 
   id org.eclipse.platform.ide.
</p>
   note: filtering by "product" and "plugin" is not implemented in M4. Will be in M5.


Filtering by multiple criteria

When there is a need to filter by multiple criteria, the filtering markup is different. In the simple cases above, the filtering markup was tagged to the XHTML element as an attribute. When two or more filtering criteria are needed, the filtering markup is tagged as a child element of the XHTML element to be filtered. Here are two examples: 
<p>
   This text should only show up when running product org.eclipse.platform.ide on 
   a Win32 based operating system.
   <filter name="os" value="win32" />
   <filter name="product" value="org.eclipse.platform.ide" />
</p>

<p>
   This text should only show up when running on a Win32 or a Linux based operating system,
   and when  Development category defined in the Eclipse SDK is enabled.
   <filter name="os" value="win32,linux" />
   <filter name="category" value="org.eclipse.categories.developmentCategory" />
</p>

note: filtering by multiple criteria is not implemented in M4. Will be in M5.


Filtering by user defined criteria

User defined keys can be used as filtering criteria. This is done by passing a key/value pair as a Java system property to the VM running the Eclipse platform. The Help system pages can then be filtered based on this key/value pair. For example, only if you pass "-Dauthor=john smith" to the vm at runtime, would the following paragraph show up: 
<p>
   This text should only show up on Linux when the Java system property "author" has the 
   value "john smith".
   <filter name="os" value="linux"/>
   <filter name="author" value="john smith"./>
</p>



Dynamic Content

Filtering can be essential in presenting to the end user the appropriate portion of the online documentation based on a set of criteria. However, there is also a need to support dynamic content in Help pages that follows the same architecture as the platform. Instead of static pages, Help system pages become dynamic pages that are assembled at runtime into coherent pages depending on the markup used in the page. This dynamic nature can be accomplished by two concepts: including content from existing pages and contributing content to existing pages.

Content reuse using Includes

To support content reuse, a new Eclipse-specific element is introduced to the XHTML markup. The <include> element enables documents to be built top down. Authors "include" content from any Help document by referencing the content in the target document as follows:

<include path="plugin_id/path_to_xhtml_file/id_of_element_to_include" />

The above markup can be included in a Help document. By specifying the id of the target plugin, the target page and the target element to be included, the markup can then be resolved at runtime and the content copied into the location where this include element was inserted.

Content contribution using Anchors

Dynamic content can also be accomplished using content contribution into existing documents. The Eclipse-specific element <anchor> enables documents to be built bottom up. A Help document can define one or more anchors to declare its willingness to accept contributions. Anchors act as place holders that declare that their location is open for content contributions. Authors subsequently "contribute" content into any Help document by referencing an anchor in that document. A new extension point is introduced for this support. 

<extension point= "org.eclipse.help.contentExtension"> 
 	<contentExtension file="contentExtensionFile.xml"/>
</extension>
The above extension specifies the file that defines the content to be contributed and the target location of where this content needs to be inserted. The file contentExtensionFile.xml is an XML file that has the following syntax:

 <contentExtension>
	 <topicExtension content="plugin/relative/path/topicExtensionFile.xhml" 
		path="plugin_id/path_to_xhtml_file/anchor_id"/>
	 <topicReplace content="topicReplaceFile.xhml" path="plugin_id/path_to_xhtml_file/element_id" />
 </contentExtension>

topicExtension is the markup used to insert content at the target anchor location. topicReplace is the markup used to replace the content of the target element by the specified content. In other words, content can be contributed that either adds to the target location or replaces the content of the target location.