<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> | |
<html> | |
<head> | |
<title>Adding Help Support to a Rich Client Application</title> | |
<meta http-equiv="Content-Type" | |
content="text/html; charset=windows-1252"> | |
<link href="../article.css" type="text/css" rel="stylesheet"> | |
</head> | |
<body> | |
<h1>Adding Help Support to a Rich Client Platform (RCP) Application</h1> | |
<div class="summary"> | |
<h2>Summary</h2> | |
<p>In this article we show you how you can incorporate the Eclipse help | |
system into your Rich Client Application in a series of easy to follow steps. We | |
also show you how to set up context help and how to fine tune your help | |
settings.</p> | |
<div class="author">By Chris Goldthorpe, IBM Corporation and Adam Archer, IBM | |
Corporation</div> | |
<div class="copyright">Copyright © 2007 IBM Corporation, Source code in | |
this article is made available under the EPL, v1.0, remainder of the | |
presentation is licensed under Creative Commons Att. Nc Nd 2.5 license <br> | |
</div> | |
<div class="date">September 10, 2007</div> | |
</div> | |
<div class="content"> | |
<h2>Introduction</h2> | |
<p>Online help can be added to an Eclipse Rich Client Platform (RCP) application with a modest amount of | |
effort by adding the plug-ins that comprise the Eclipse help system. The first | |
section of this article discusses the benefits of integrating the help system | |
into your application. This is followed by a tutorial which describes in detail | |
the steps required to add help system support to a newly created RCP application | |
while avoiding commonly encountered pitfalls. Finally we describe how to | |
add context help and how to fine tune the settings of your help system.</p> | |
<h2>Why include the Eclipse Help System in your Application?</h2> | |
<p>Very few applications are self explanatory to the point where they require no | |
documentation. For an RCP application the easiest way to add that documentation | |
support is to use the Eclipse help system. The Eclipse help system is supported | |
on all of the same platforms as Eclipse and has developed over years into a | |
robust, feature rich and extensible component, which continues to grow in terms | |
of both quality and features.</p> | |
<p>The Eclipse help system uses a browser-based presentation and therefore has | |
full support for HTML. Search is automatically included in the help system; | |
context help and keyword index are supported if you provide the appropriate | |
content files. If you want to allow the same help pages that you provide in | |
your application to be accessed from the Internet you can host them on | |
an InfoCenter: a web server which serves help pages. Localization is | |
supported so that you can provide documentation in additional languages.</p> | |
<p>The help system (since 3.3) has extension points for content producers that | |
programmatically generate help content including a table of | |
contents, keyword index, and content pages. This can be useful when converting | |
documentation from some other format into HTML.</p> | |
<h2>Tutorial </h2> | |
<p>The next sections walk through the process of adding help support to a newly | |
created RCP application. You may already have an RCP application but we | |
recommend that you create a new application for this exercise. That way you can | |
experiment on a sample before modifying your application. </p> | |
<h3>Create a Rich Client Application</h3> | |
<p>The Plug-in Development Environment (PDE) has some templates for | |
creating RCP applications. For this article we will use the Mail Template as it already has some | |
menus in place.</p> | |
<p>From the workbench select the menu item "<strong>File > New > Project...</strong>" and select the | |
"<strong>Plug-in Project</strong>" template.</p> | |
<p>Enter "<strong>org.eclipse.helprcp</strong>" in the "<strong>Project name</strong>" field and hit "<strong>Next</strong>".</p> | |
<div class="figure"> | |
<img border="0" src="images/pde_wizard1.png" width="500" height="500" > | |
</div> | |
<p>On the second screen be sure to select the "<strong>Yes</strong>" option | |
in the | |
"<strong>Rich Client Application</strong>" section.</p> | |
<div class="figure"><img border="0" src="images/pde_wizard2.png" width="500" height="500"></div> | |
<p>And on the final screen select the "<strong>RCP Mail Template</strong>".</p> | |
<div class="figure"><img border="0" src="images/pde_wizard3.png" width="500" height="500"></div> | |
<p>Hit "<strong>Finish</strong>" and your project will be created. You can test your | |
application by opening the "<strong>Plug-in Manifest Editor</strong>" and, in the "<strong>Overview</strong>" tab, | |
clicking on "<strong>Launch an Eclipse Application</strong>". You will see an application start | |
which already has a "<strong>Help</strong>" menu with an "<strong>About RCP Product</strong>" submenu. Click on the "<strong>About RCP Product</strong>" | |
submenu and this is what you will see.</p> | |
<p class = "figure"><img border="0" src="images/rcp1.png" width="600" height="400"></p> | |
<h3>Create a Product Configuration</h3> | |
<div class="note"><p><img border="0" src="images/tip.gif" width="62" height="13"> Adding the help | |
system is easiest if you have a plug-in based product configuration. </p></div> | |
<p>To create the product configuration, perform the following steps:</p> | |
<ol> | |
<li>Switch to the <strong>Plug-in Development</strong> perspective if you are not already there | |
(Use the <strong>Window > Open Perspective</strong> menu option).</li> | |
<li>Select "<strong>File > New > Product Configuration</strong>" from the main menu.</li> | |
<li>Select "<strong>org.eclipse.helprcp</strong>" in the resulting "<strong>New Product Configuration</strong>" | |
wizard page.</li> | |
<li>Input "<strong>helprcp.product</strong>" into the "<strong>File name</strong>" text box.</li> | |
<li>Select the "<strong>Use an existing product</strong>" radio button inside the "<strong>Initialize | |
the file content</strong>" group and click "<strong>Finish</strong>". The "<strong>Product Configuration Editor</strong>" | |
will open.</li> | |
<li>Input "<strong>Help RCP Application</strong>" into the "<strong>Product Name</strong>" text box.</li> | |
<li>Verify "<strong>org.eclipse.helprcp.product</strong>" is the default value in the "<strong>Product ID</strong>" drop down menu.</li> | |
<li>Select "<strong>File > Save</strong>" from the main menu.</li> | |
<li>From the "<strong>Overview</strong>" tab of the "<strong>Product Configuration Editor</strong>" click on | |
"<strong>Launch an Eclipse Application</strong>" and verify that the application launches.</li> | |
</ol> | |
<h3>Add Source Code</h3> | |
<p>In your rich client plug-in project you will find a class called | |
"<strong>ApplicationActionBarAdvisor</strong>". Open this in an editor. You will make a few source | |
changes to add the help actions to the menu. Add the lines marked "<strong>// NEW</strong>" to the | |
class as follows:</p> | |
<pre>public class ApplicationActionBarAdvisor extends ActionBarAdvisor { | |
// Actions - important to allocate these only in makeActions, and then use them | |
// in the fill methods. This ensures that the actions aren't recreated | |
// when fillActionBars is called with FILL_PROXY. | |
private IWorkbenchAction exitAction; | |
private IWorkbenchAction aboutAction; | |
private IWorkbenchAction showHelpAction; <strong>// NEW</strong> | |
private IWorkbenchAction searchHelpAction; <strong>// NEW</strong> | |
private IWorkbenchAction dynamicHelpAction; <strong>// NEW</strong></pre> | |
<p>Add the lines marked "<strong>// NEW</strong>" to function | |
"<strong>ApplicationActionBarAdvisor.makeActions()</strong>" as follows:</p> | |
<pre> protected void makeActions(final IWorkbenchWindow window) { | |
// Creates the actions and registers them. | |
// Registering is needed to ensure that key bindings work. | |
// The corresponding commands keybindings are defined in the plugin.xml file. | |
// Registering also provides automatic disposal of the actions when | |
// the window is closed. | |
exitAction = ActionFactory.QUIT.create(window); | |
register(exitAction); | |
aboutAction = ActionFactory.ABOUT.create(window); | |
register(aboutAction); | |
showHelpAction = ActionFactory.HELP_CONTENTS.create(window); <strong>// NEW</strong> | |
register(showHelpAction); <strong>// NEW</strong> | |
searchHelpAction = ActionFactory.HELP_SEARCH.create(window); <strong>// NEW</strong> | |
register(searchHelpAction); <strong>// NEW</strong> | |
dynamicHelpAction = ActionFactory.DYNAMIC_HELP.create(window); <strong>// NEW</strong> | |
register(dynamicHelpAction); <strong>// NEW</strong></pre> | |
<p>And add the lines marked "<strong>// NEW</strong>" to function | |
"<strong>ApplicationActionBarAdvisor.fillMenuBar()</strong>" as follows:</p> | |
<pre>protected void fillMenuBar(IMenuManager menuBar) { | |
MenuManager fileMenu = new MenuManager("&File", IWorkbenchActionConstants.M_FILE); | |
MenuManager helpMenu = new MenuManager("&Help", IWorkbenchActionConstants.M_HELP); | |
menuBar.add(fileMenu); | |
// Add a group marker indicating where action set menus will appear. | |
menuBar.add(new GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS)); | |
menuBar.add(helpMenu); | |
// File | |
fileMenu.add(newWindowAction); | |
fileMenu.add(new Separator()); | |
fileMenu.add(messagePopupAction); | |
fileMenu.add(openViewAction); | |
fileMenu.add(new Separator()); | |
fileMenu.add(exitAction); | |
// Help | |
helpMenu.add(aboutAction); | |
helpMenu.add(showHelpAction); <strong>// NEW</strong> | |
helpMenu.add(searchHelpAction); <strong>// NEW</strong> | |
helpMenu.add(dynamicHelpAction); <strong>// NEW</strong></pre> | |
<h3>Test</h3> | |
<p>Launch the application from the "<strong>Product Configuration Editor</strong>" and see what | |
happens. You will notice that the help menu now has additional entries for "<strong>Help | |
Contents</strong>" and "<strong>Search</strong>" but neither of them does anything. This is because we | |
still need to import the plug-ins that comprise the Eclipse help system.</p> | |
<h3>Add Required Plug-ins</h3> | |
<ol> | |
<li>In the "<strong>Configuration</strong>" tab of the "<strong>Product Configuration Editor</strong>" add "<strong>org.eclipse.help.webapp</strong>" | |
and "<strong>org.eclipse.help.ui</strong>" to the list in the "<strong>Plug-ins and Fragments</strong>" section.</li> | |
<li>Select the checkbox to "<strong>Include optional dependencies when computing required | |
plug-ins</strong>". | |
<div class="note"><img border="0" src="images/tip.gif" width="62" height="13"> If you | |
omit this step the help system will not have all the plug-ins it needs and you | |
will see an exception at startup.</div></li> | |
<li>Click the "<strong>Add Required Plug-ins</strong>" button.</li> | |
<li>Select "<strong>File > Save</strong>" from the main menu.</li> | |
</ol> | |
<h3>Test Again</h3> | |
<p>Launch the application from the "<strong>Product Configuration Editor</strong>" again. Now | |
"<strong>Help > Help Contents</strong>" will open a new window to display help.</p> | |
<p class = "figure"><img border="0" src="images/emptyHelp.png" width="689" height="550"></p> | |
<h3>Add Sample Help Content</h3> | |
<p>You can create a plug-in with help content as follows:</p> | |
<ol> | |
<li>Select "<strong>File > New > Project > Plug-in project</strong>".</li> | |
<li>On the first screen uncheck "<strong>Create a Java Project</strong>"</li> | |
<li>Enter "<strong>org.eclipse.helprcp.content</strong>" in the "<strong>Project name</strong>" field and hit "<strong>Next</strong>" twice.</li> | |
<li>From the templates page select "<strong>Plug-in with sample help content</strong>" and hit | |
"<strong>Finish</strong>".</li> | |
<li>In the "<strong>Product Configuration Editor</strong>" add your new plug-in to the list in | |
the "<strong>Plug-ins and Fragments</strong>" section.</li> | |
<li>Launch the application from the "<strong>Product Configuration Editor</strong>". It will look | |
like this after you expand the nodes in the tree.</li> | |
</ol> | |
<p class = "figure"><img border="0" src="images/help.png" width="689" height="550"></p> | |
<p>"<strong>Help > Search</strong>" is also enabled and looks like this. You will want to increase | |
the size of the help view.</p> | |
<p class = "figure"><img border="0" src="images/search.png" width="600" height="400"></p> | |
<h3>Add Context Help Support</h3> | |
<p>In this section you will add context help to the "<strong>Message</strong>" view included in the application.</p> | |
<p>The first thing you will need to do is create a context id for the view. To do this you | |
will need to modify the code for the "<strong>View</strong>" class in the | |
"<strong>org.eclipse.helprcp</strong>" project. Open it in an editor and add the | |
line marked "<strong>// NEW</strong>" to the "<strong>View.createPartControl(Composite parent)</strong>" | |
as follows:</p> | |
<pre>public void createPartControl(Composite parent) { | |
Composite top = new Composite(parent, SWT.NONE); | |
GridLayout layout = new GridLayout(); | |
layout.marginHeight = 0; | |
layout.marginWidth = 0; | |
top.setLayout(layout); | |
PlatformUI.getWorkbench().getHelpSystem().setHelp(top, "org.eclipse.helprcp.message"); <strong>// NEW</strong></pre> | |
<p>After adding the code, you will have an error. To resolve it select "<strong>Source > Organize Imports</strong>" | |
from the main menu. Save your changes when you are done.</p> | |
<p>Once the context id is created you need to create content to associate to it. | |
We will put the content in the "<strong>org.eclipse.helprcp.content</strong>" plug-in. | |
Add a new file to the root directory for the project called "<strong>contexts.xml</strong>". | |
Open the new file in an editor, input the following text and save your changes:</p> | |
<pre><contexts> | |
<context id="message"> | |
<description>This is the sample context-sensitive help. There is a link to the help content below.</description> | |
<topic href="html/subtopic.html" label="Subtopic" /> | |
</context> | |
</contexts></pre> | |
<p>Next you will need to link the content to the context id. This can be done as follows:</p> | |
<ol> | |
<li>Open the "<strong>Plug-in Manifest Editor</strong>" for the | |
"<strong>org.eclipse.helprcp.content</strong>" plug-in.</li> | |
<li>Switch to the "<strong>Extensions</strong>" tab and click | |
the "<strong>Add...</strong>" button.</li> | |
<li>In the "<strong>New Extension</strong>" wizard select the | |
"<strong>org.eclipse.help.context</strong>" extension point and click "<strong>Finish</strong>". | |
<div class="note"><img border="0" src="images/tip.gif" width="62" height="13"> You will need to uncheck the | |
"<strong>Show only extension points from the required plug-ins</strong>" checkbox to select the extension point.</div></li> | |
<li>You will be asked if you want to add a dependency to the "<strong>org.eclipse.help</strong>" | |
plug-in. Click "<strong>No</strong>".</li> | |
<li>Right-click your new extension in the list and select "<strong>New > contexts</strong>"</li> | |
<li>In the "<strong>file</strong>" field enter "<strong>contexts.xml</strong>".</li> | |
<li>In the "<strong>plug-in</strong>" field enter "<strong>org.eclipse.helprcp</strong>".</li> | |
<li>Select "<strong>File > Save</strong>" from the main menu.</li> | |
</ol> | |
<p>The last step required to ensure that the correct context is sent to the help system | |
is to forward focus to the view's composite when its "<strong>setFocus()</strong>" method is called. | |
To do this you will first have to make the composite a private variable. In | |
class "<b>View</b>" add the line marked "<strong>// NEW</strong>" | |
in the code segment below and update the line marked "<strong>// MODIFIED</strong>" as indicated:</p> | |
<pre>public static final String ID = "org.eclipse.helprcp.view"; | |
private Composite top; <strong>// NEW</strong> | |
public void createPartControl(Composite parent) { | |
top = new Composite(parent, SWT.NONE); <strong>// MODIFIED</strong> | |
GridLayout layout = new GridLayout();</pre> | |
<p>Next add content to the "<strong>View.setFocus()</strong>" method as follows:</p> | |
<pre>public void setFocus() { | |
if(top != null) <strong>// NEW</strong> | |
top.setFocus(); <strong>// NEW</strong> | |
}</pre> | |
<h3>Test context help</h3> | |
<p>Context-sensitive help should now be configured for the Message view. To test it, run your application again, | |
select the view titled "<strong>Message</strong>" and choose "<strong>Help > Dynamic Help</strong>" from the main menu. When you do this, | |
you should see the following:</p> | |
<div class = "figure"><img border="0" src="images/context.png" width="600" height="400"></div> | |
<h3>Setting Help Preferences</h3> | |
<p>Any eclipse based product has the option to customize the default preferences of the plug-ins it ships with. | |
This is no different for your RCP application. To customize the help system settings you will first need to create | |
a "<strong>plugin_customization.ini</strong>" file and reference it from your product plug-in's | |
"<strong>plugin.xml</strong>". To setup the file, perform the following steps:</p> | |
<ol> | |
<li>Create a new file called "<strong>plugin_customization.ini</strong>" in the root of | |
the "<strong>org.eclipse.helprcp</strong>" project. Leave it empty for now.</li> | |
<li>Open the "<strong>Plug-in Manifest Editor</strong>" for the | |
"<strong>org.eclipse.helprcp.content</strong>" plug-in.</li> | |
<li>Switch to the "<strong>Extensions</strong>" tab and expand the | |
"<strong>org.eclipse.core.runtime.products</strong>" node.</li> | |
<li>Right click on "<strong>Help RCP Application (product)</strong>" and select | |
"<strong>New > property</strong>" from the context menu.</li> | |
<li>Enter "<strong>preferenceCustomization</strong>" in the "<strong>name</strong>" | |
field and "<strong>plugin_customization.ini</strong>" in the "<strong>value</strong>" field.</li> | |
<li>Select "<strong>File > Save</strong>" from the main menu.</li> | |
</ol> | |
<p>Once the file is configured for the product, you can place name/value pairs as specified in the following | |
help document to customize the help system:</p> | |
<p><a href="http://help.eclipse.org/help33/topic/org.eclipse.platform.doc.isv/guide/ua_help_setup_preferences.htm"> | |
http://help.eclipse.org/help33/topic/org.eclipse.platform.doc.isv/guide/ua_help_setup_preferences.htm</a></p> | |
<p>The most common usage of this functionality is to control the order in which contributed parts of the table of contents are | |
displayed for your product | |
or to hide parts of the table of contents that some of your plug-ins contribute. Both of these can be done with the | |
"<strong>HELP_DATA</strong>" property. This property references a plug-in relative path to an xml file that | |
contains the toc ordering and hiding information. For instance, if you created | |
"<strong>helpData.xml</strong>" in the root of your product plug-in you would put a line reading | |
"<strong>org.eclipse.help/HELP_DATA=helpData.xml</strong>" in your "<strong>plugin_customization.ini</strong>" file. | |
Here is a small sample of the xml file format:</p> | |
<pre><extensions> | |
<tocOrder> | |
<toc id="/org.eclipse.helprcp.content/testToc.xml"/> | |
<toc id="/org.eclipse.other.content/toc.xml"/> | |
</tocOrder> | |
<hidden> | |
<toc id="/org.eclipse.third.content/toc.xml"/> | |
</hidden> | |
</extensions></pre> | |
<p>This sample would display your table of contents from the "<strong>org.eclipse.helprcp.content</strong>" | |
plug-in first followed by the referenced book from the "<strong>org.eclipse.other.content</strong>" plug-in. | |
It would also hide the contents of the toc referenced from the "<strong>org.eclipse.third.content</strong>" | |
plug-in. Note that the "<strong>org.eclipse.other.content</strong>" and "<strong>org.eclipse.third.content</strong>" | |
plug-ins do not exist and are simply used as an example. For more information on the format of the xml file, see it's schema | |
from the help documentation:</p> | |
<p><a href="http://help.eclipse.org/help33/topic/org.eclipse.platform.doc.isv/guide/ua_help_setup_help_data.htm"> | |
http://help.eclipse.org/help33/topic/org.eclipse.platform.doc.isv/guide/ua_help_setup_help_data.htm</a></p> | |
<h2>Conclusion</h2> | |
<p>This article has shown how to add the Help System and context help support to | |
a simple RCP application, the exact steps will vary for different RCP | |
applications but the general principles remain the same. The authors believe | |
that this article and tutorial will be a time saver for RCP | |
developers and we hope that you have found it useful. Feedback including | |
suggestions for additional articles can be sent to | |
<a href="http://dev.eclipse.org/mailman/listinfo/platform-ua-dev"> | |
platform-ua-dev@eclipse.org</a>.</p> | |
</body> | |
</html> |