| <!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> |
| <extension |
| point="org.eclipse.help.toc"> |
| <tocProvider |
| class="org.myproject.MyTocProvider"> |
| </tocProvider> |
| </extension> |
| </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> |
