platform-ua/documents/providers_api.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Help content providers API (3.3)</title>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>

<h1>
Help content providers API (3.3)
</h1>

<p>
Curtis d'Entremont, 10/30/2006
</p>

<h2>
Overview
</h2>

<p>
This document describes the new set of API that was added to
<code>org.eclipse.help</code> 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:
</p>

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

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

<p>
For example, if you want to write your help content in format XYZ, you can
provide an adapter plug-in, say <code>org.xyz.adapter</code>, 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.
</p>

<h2>
Details
</h2>

<p>
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 <code>tocProvider</code>
element of the <code>org.eclipse.help.toc</code> extension point. The two
exceptions are <code>org.eclipse.help.contentProducer</code> extension point
for providing html/xhtml documents, and
<code>org.eclipse.help.base.luceneSearchParticipants</code>, both of which
already existed prior to 3.3 and have not changed.
</p>

<h3>
Table of contents example
</h3>

<p>
Here is an example of a TOC provider extension:
</p>

<p>
<pre>
   &lt;extension
         point=&quot;org.eclipse.help.toc&quot;&gt;
      &lt;tocProvider
            class=&quot;org.myproject.MyTocProvider&quot;&gt;
      &lt;/tocProvider&gt;
   &lt;/extension&gt;
</pre>
</p>

<p>
And the implementation:
</p>

<p>
<pre>
   /*
    * 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 };
      }
   }
</pre>
</p>

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

<p>
As you may have noticed, an <code>ITocContribution</code> 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
<code>ITocContribution</code>. 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
<code>org.eclipse.help</code>.
</p>


</body>
</html>