Help content providers API (3.3)

Curtis d'Entremont, 10/30/2006

Overview

This document describes the new set of API that was added to org.eclipse.help in 3.3 to allow Eclipse to read help content in any format. It allows you to plug-in Java classes that will be called on at appropriate times to provide the following types of content:

• Table of contents
• Keyword index
• Context-sensitive help
• Help topics (html/xhtml)
• Topic extensions (contributions into anchors, element replacements)
• Search results

The extender of help would typically supply an adapter plug-in that contributes one provider for each type of content (listed above), and exposes new extension points to accept any type of file.

For example, if you want to write your help content in format XYZ, you can provide an adapter plug-in, say org.xyz.adapter, that exposes new extension points for XYZ content, reads the XYZ files then converts them into content that Eclipse help understands, and provides the content to Help using the new providers API.

Details

Providers are contributed via extension points. However there aren't any new extension points; a new element was added alongside the existing extension points where an element was used to supply the XML file. For example, to plug-in a TOC (table of contents) provider, use the new tocProvider element of the org.eclipse.help.toc extension point. The two exceptions are org.eclipse.help.contentProducer extension point for providing html/xhtml documents, and org.eclipse.help.base.luceneSearchParticipants, both of which already existed prior to 3.3 and have not changed.

Table of contents example

Here is an example of a TOC provider extension:

   <extension
         point="org.eclipse.help.toc">
      <tocProvider
            class="org.myproject.MyTocProvider">
      </tocProvider>
   </extension>

And the implementation:

   /*
    * A simple provider that contributes a single book to the
    * table of contents named "Hello, World".
    */
   public class MyTocProvider extends AbstractTocProvider {
      
      public ITocContribution[] getTocContributions(String locale) {
         ITocContribution contribution = new ITocContribution() {
            public String getId() {
               // a way to identify our book
               return "org.myplugin.contribution.helloworld";
            }
            public String getCategoryId() {
               // our book does not belong to any category of books
               return null;
            }
            public boolean isPrimary() {
               // this is a primary, top-level contribution (a book)
               return true;
            }
            public IToc getToc() {
               return new IToc() {
                  public String getLabel() {
                     return "Hello, world";
                  }
                  public String getHref() {
                     return "/mydocs/helloworld.html";
                  }
               };
            }
            public String getLocale() {
               // this provider only provides content for the en_US locale
               return "en_US";
            }
            public String[] getExtraDocuments() {
               // there are no extra documents associated with this book
               return new String[0];
            }
            public String getLinkTo() {
               // this book does not link into any other book
               return null;
            }
         };
         return new ITocContribution[] { contribution };
      }
   }

Upon opening Help, you will see a single new static book in the table of contents with the label "Hello, World".

As you may have noticed, an ITocContribution is equivalent to (or as powerful as) a toc file extension. That is, anything you can do with a toc XML file contributed via extension can be done with an ITocContribution. This is generally the pattern with the providers API. In fact, the XML files are not treated in any special way by the help system; they are parsed and contributed by a provider in org.eclipse.help.