COSMOS Design 220594

Provide contextual help for toolkit UI

This is the design document for bugzilla 220594.

Change History

Name:	Date:	Revised Sections:
David Whiteman	February 26, 2009	Initial version
David Whiteman	March 3, 2009	Purpose and design
David Whiteman	March 5, 2009	Reworked per Ruth Lee feedback to provide view-level help instead of field-level help

Workload Estimation

Rough workload estimate in person weeks

Process	Sizing	Names of people doing the work
Design	0.1	David Whiteman
Code	0.3	David Whiteman
Test	0.1	David Whiteman
Documentation	0
Build and infrastructure	0.1	Saurabh Dravid
Code review, etc.*	0
TOTAL	0.6

'* - includes other committer work (e.g. check-in, contribution tracking)

Purpose

The purpose of this enhancement is to provide contextual help for the UI in the MDR toolkit. The user, when using the MDR creation wizard, will be able to press F1 to display help viewing the chapter in the Developer Guide with overall description of the usage of the MDR Toolkit. The implementation will leverage Eclipse functionality for help integration.[1]

Design

A new plug-in will need to be created: org.eclipse.cosmos.me.dmtoolkit.help. This plug-in will hold a contexts.xml file that contains a topic with a reference to the Creating a Data Manager chapter of the Developer Guide. It will also hold the HTML itself from the Developer Guide so it can be displayed. For example:

<context id="dataManagerConfigPage">
	<topic label="Creating an MDR Project" href="html/creatinganmdrproject.html" />
</context>

Important note: be sure to omit the <description> element from the context, as Eclipse 3.4 has a feature that automatically redirects the help view to the topic when there is no description provided.

The new plug-in will need to be added to the COSMOS SDK feature by the RE team, so that it will be included in the download.

The code for building the UI in org.eclipse.cosmos.me.dmtoolkit.common will need to be updated to hook in the help facility. For example:

static String CONTEXT_ID_MDR_CONFIG_PAGE = "org.eclipse.cosmos.me.dmtoolkit.common.dataManagerConfigPage";
 
...
 
PlatformUI.getWorkbench().getHelpSystem().setHelp(composite, CONTEXT_ID_MDR_CONFIG_PAGE);

There is currently only one page in the UI for the MDR toolkit. Any future pages added to the MDR toolkit UI will likewise also require updating the new help plug-in.

Resources

1. Eclipse documentation on implementing contextual help