Another way of reducing the cost of service for your plug-ins is to provide on-line help. In Eclipse, help contents are structured as extensions to the help extension point. In this chapter we'll see how to
Add our own help contents
Link to our help contents from the user interface (context sensitive help)
There are several places we might want to integrate our help:
Stand-alone help
An “infopop” on the
ResultViewand theTestReportViewThe auto-test property page
The run test action
All of the help contents in Eclipse follow the Contribution Rule. Every plug-in has the opportunity to contribute help. The help window is the only place you can see all the help together.
The basic unit of help is the table of contents, or toc. A toc is a tree containing other tocs or topics. Each toc or topic can have an html file associated with it. Figure 27.1 shows part of the help for the Plug-In Development Environment.
A contribution to the table of contents is represented in Eclipse as an extension to the extension point org.eclipse.help.toc. The user documentation for PDE is contributed in the separate plug-in org.eclipse.pde.doc.user. This plug-in only contains documentation and no code:
Example . org.eclipse.pde.doc.user/plugin.xml
<extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true"> </toc> </extension>
This extension states that the table of contents will be found in a file called toc.xml (by convention, the root of the table of contents is always in toc.xml). Looking in toc.xml, we see the declaration of the structure above:
Example . org.eclipse.pde.doc.user/toc.xml
<toc label="PDE Guide">
<topic label="Introduction to PDE" href="guide/pde.htm"/>
<topic label="Concepts" href="guide/pde_concepts.htm"/>
<topic label="Configuring PDE" href="guide/pde_configuring.htm"/>
<topic label="Setting up the workbench"
href="guide/pde_setup.htm"/>
<topic label="Creating a plug-in" href="guide/pde_creating.htm"/>
<topic label="Plug-in manifest editor"
href="guide/pde_manifest.htm">
<topic label="Welcome page"
href="guide/pde_manifest_welcome.htm" />
<topic label="Overview page"
href="guide/pde_manifest_overview.htm" />
...
</topic>
...
</toc>
The topic elements nest inside the toc element, and each topic has an associated file as well as a label. When a topic is selected in the left-hand pane of the help window, the associated file is shown in the right-hand pane.
We'll put our help in the same plug-in as our code. Often, help comes in its own plug-in as we have seen above in org.eclipse.pde.doc.user, making it easy for a documentation team to work independently of the development team. First we need to make our plug-in dependent on the help plug-in, so we can see the toc extension point, then we'll make our extension:
Example . org.eclipse.contribution.junit/plugin.xml
<requires> ... <import plugin="org.eclipse.help"/> </requires> <extension point="org.eclipse.help.toc"> <toc file="toc.xml" primary="true" /> </extension>
Our help topic isn't referenced from anywhere. We therefore set the primary attribute to true so that it shows up in the top-level list of topics. For the moment, our table of contents will only have one topic, linked to a file called help.html:
Example . org.eclipse.contribution.junit/toc.xml
<?xml version="1.0" encoding="UTF-8"?> <?NLS TYPE="org.eclipse.help.toc"?> <toc label="Auto-testing"> <topic label="Auto-testing" href="help.html"/> </toc>
We add a file help.html to our plug-in, containing the (currently sketchy) help contents:
Example . org.eclipse.contribution.junit/help.html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN"> <html> <head> <title>Auto-testing</title> <meta http-equiv=Content-Type content="text/html; charset=ISO-8859-1"> </head> <body lang="EN-US"> <h2>Introduction to Auto-Testing</h2> <p>Auto-testing is the ability to automatically run all the tests for a project every time the project is built. Failing tests appear as text markers, similar to compile errors.</p> <h2>Turning on Auto-Testing</h2> <p>Open the properties for a Java project. You will see a page labelled "Auto-testing". Click on it, and click on the "Auto-test" check box.</p> </body> </html>
When we start up the run-time workbench and open help, we see our help contents, as shown in Figure 27.2.
We don't actually want our discussion of auto-testing to occur at the same level as those other topics. Auto-testing is a refinement of the Java development features of Eclipse. Following the Integration Rule, we'd like our help to fit in nicely with the rest of the JDT help. Fortunately, help has its own version of the Invitation Rule called anchors. An anchor is a point in the help tree where new help can be introduced. We can look at the JDT help to see how anchors appear. In the file topics_Concepts.xml, we find a likely table of contents into which we can integrate our auto-test help:
Example . org.eclipse.jdt.docs.user/topics_Concepts.xml
<toc label="Concepts" href="concepts/concepts-1.htm" > ... <topic label="Java builder" href="concepts/concepts-4.htm"/> <anchor id="c_javabuilder" /> ... </toc>
To splice our help into the help on Java programming concepts, we give our toc element the attribute link_to, and name the file and the anchor where we'd like to see our help appear:
Example . org.eclipse.contribution.junit/toc.xml
<toc label="Auto-testing" link_to="../org.eclipse.jdt.doc.user/ topics_Concepts.xml#c_javabuilder"> <topic label="Auto-testing" href="help.html"/> </toc>
Now when we look at the help in the run-time workbench, we see our help integrated with the rest of the help on Java, as shown in Figure 27.3.
We'd also like to add a page to the section of Java help on Java project property pages, but unfortunately that toc tree doesn't declare any anchors. We can't add a page where we'd like it.
Another kind of help is the context-sensitive help that appears when you click F1 in a view. When we click F1 in our test report view, we get the generic help, as shown in Figure 27.4.
We'd like to see help on tests and auto-testing. Context-sensitive help is contributed by creating a help context extension and associating that context with a view.
We'll copy from the implementation of infopops in the search view, shown in Figure 27.5.
The class WorkbenchHelp provides an entry point for registering the availability of context-sensitive help. Help is associated with an SWT control. Looking at the class SearchResultView, we see that the help is registered when the view is created:
Example . org.eclipse.search.internal.ui/SearchResultView
public void createPartControl(Composite parent) { ... WorkbenchHelp.setHelp(fViewer.getControl(), ISearchHelpContextIds.SEARCH_VIEW); }
We add a similar line to TestReportView.createPartControl():
Example . org.eclipse.contribution.junit/TestReportView
public void createPartControl(Composite parent) {
...
WorkbenchHelp.setHelp(viewer.getControl(),
"org.eclipse.contribution.junit.autoTestContext");
}
For now we just add the context id in the code directly. Common practice in Eclipse is to centralize the help context ids in an interface I…HelpContextIds. There the context ids are categorized by the user-interface component (views, actions, wizards).
Example . org.eclipse.platform.doc.user/plugin.xml
<extension point="org.eclipse.help.contexts">
<contexts file="contexts_Search.xml"
plugin="org.eclipse.search"/>
</extension>
Example . org.eclipse.contribution.junit/plugin.xml
<extension point="org.eclipse.help.contexts">
<contexts file="contexts.xml"
plugin="org.eclipse.contribution.junit"/>
</extension>
Looking at the context file for search help, we see:
Example . org.eclipse.platform.doc.user/contexts_Search.xml
<contexts>
...
<context id="search_view_context" >
<description>This view displays the results
of recent searches.</description>
<topic label="Search view" href="reference/ref-26.htm"/>
<topic label="File search" href="reference/ref-45.htm"/>
</context>
...
</contexts>
We copy this to provide the infopop for the test results:
Example . org.elipse.contribution.junit/contexts.xml
<contexts>
<context id="autoTestContext">
<description>These tests were run during
auto-testing.</description>
<topic label="Auto-testing" href="help.html" />
</context>
</contexts>
We have defined the plugin name when we contributed to the org.eclipse.help.contexts extension point. The ID autoTestContext is now prefixed by this plug-in name. When we click F1 in the TestReportView, we see our help, as shown in Figure 27.6.
When adding help context IDs you want to cover the following UI elements:
Views
Editors
Actions
Dialogs
Wizards
Preference pages
Property pages
From this to-do list we can see that we should also assign a help context to the auto-test property page and to the RunTestAction. For the property page, we assign a help context in the same way as we did for the TestReportView. The RunTestAction is contributed in the plug-in manifest so we cannot define the help context in the code. Instead, we define the help context as an attribute in the plugin.xml definition. Here is how search defines a help context for one of its actions:
Example . org.eclipse.search/plugin.xml
<action id="org.eclipse.search.OpenFileSearchPage"
menubarPath="org.eclipse.search.menu/internalDialogGroup"
label="%openFileSearchPageAction.label"
icon="icons/full/obj16/tsearch_obj.gif"
helpContextId="file_search_action_context"
class="org.eclipse.search.internal.ui.OpenFileSearchPageAction"/>
We do the same for our RunTestAction:
Example . org.eclipse.contribution.junit/plugin.xml
<action
label="Run Test"
class="org.eclipse.contribution.junit.RunTestAction"
enablesFor="1"
helpContextId="runTestActionContext"
id="org.eclipse.contribution.junit.runtest.action">
</action>
Next we add a corresponding context:
Example . org.eclipse.contribution.junit/contexts.xml
<contexts>
<context id="runTestActionContext">
<description>Runs all tests defined in the selected
class.</description>
</context>
</contexts>
When we click F1 while the Run Test menu item is highlighted, we will see the context-sensitive help. F1 help consists of only a description without a topic link, as shown in Figure 27.7.
We're nearing the end of the circle. In the next chapter, we'll internationalize our user interface. Reviewing this chapter, we
Added a help topic by declaring an extension to
org.eclipse.help.tocand creating a table-of-contents treeSpliced our help into the existing help by linking to an anchor
Created an infopop help context by extending
org.eclipse.help.contextsand creating the help contents and we connected to the context from ourTestReportViewAdded a help context to the contributed
RunTestAction
Putting help in a zip file—. To avoid the hassles of dealing with a large number of files in a plug-in, you can put all the help contents in a doc.zip file. Help first looks into the doc.zip file before looking into the plug-in directory.
Eclipse supports active help—. You can define links in your documentation that invoke code from a plug-in.