Embedding Commands as Links

by Chris Daly (cjdaly@us.ibm.com)
version 0.1 (15-Jan-2006)


This document is meant to serve as a guide to authors of Help, Cheatsheets, Intro and possibly other document types who would benefit from the ability to embed commands in their documents as links.  The centerpiece of this document is a catalog of commands that are thought to be useful in embedded document contexts.

Background

A recent enhancement to the command framework allows commands and their parameter values to be serialized as strings and later deserialized and executed.  This allows serialized commands to be embedded in documents and visualized as links such that activating the link has the effect of  executing the embedded command.

Another enhancement introduces the notion of typed command parameters.  Previously, parameter values were expressed as strings throughout the lifecycle of command parameterization and execution.  Now command parameters can declare a type and the parameter values can be handled as objects instead of strings.  This allows:
This work was done with the goal of allowing commands to be embedded as links in the various types of User Assistance documents: Help, Cheatsheets and Intro.  The functionality may also be useful in other contexts.

Two additional things are required for the ability to embed commands in documents to become a useful and used feature.  First, we must have a reasonably large "catalog" of commands that do interesting/useful things when embedded in documents.  Second, each type of document must specify how commands may be embedded and its supporting code must present the commands in some way that allows them to be invoked by users (such as a clickable link).  These topics are explored in detail below.

An Example

Below is an HTML document that represents a Help topic.  The JavaScript executeCommand function takes a serialized command as its argument and executes the command when the link is clicked.  Note that this requires the patch for bug 122726, which is not yet committed.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML>
<HEAD>
<TITLE>
Help Link Test
</TITLE>
<script language="JavaScript" src="../../org.eclipse.help/livehelp.js"> </script>
</HEAD>

<body>
<p>Execute command link to
<a href='javascript:executeCommand(
    "org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.ui.views.TaskList)")'>
    show Tasks view</a>.</p>
</body>
</HTML>


Catalog of Commands

What follows is a catalog of commands that may be useful in embedded document scenarios.  Some of these are available today and some are not yet committed (indicated with [proposed] below).  The format of the tables below is:

Command Name - brief description and mention of parameters
command.id(param.id=value)        « example demonstrating usage

Please refer to the JavaDoc for ParameterizedCommand.serialize() for a description of the command serialization format.

General Workbench

Show Perspective - without parameters, opens a dialog with list of perspectives
org.eclipse.ui.perspectives.showPerspective
Show Perspective - parameter indicates perspective id
org.eclipse.ui.perspectives.showPerspective(org.eclipse.ui.perspectives.showPerspective.perspectiveId=org.eclipse.ui.resourcePerspective)
Show View - without parameters, opens a dialog with list of views
org.eclipse.ui.views.showView
Show View - parameter indicates view id
org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.ui.views.TaskList)

Workspace

Open Resource [proposed] - open a resource given its path and/or URI as parameter
Show Resource in Navigator [proposed] - show in Navigator view given resource path and/or URI as parameter

User Assistance

Display Help - without parameters, opens the help system
org.eclipse.ui.help.displayHelp
Display Help - parameter indicates help topic href
org.eclipse.ui.help.displayHelp(href=/org.eclipse.platform.doc.user/gettingStarted/qs-02a.htm)
Open Cheatsheet [proposed] - Chris G. indicated there would be several variants
Open Intro Content [proposed] - look into this...

Java

Note: the examples below work on a class named Activator in a plugin called org.test.  Simply create a new plugin called org.test to try these examples.

Open JavaElement in Editor [proposed] - parameter encodes handle identifier of java element
org.eclipse.jdt.ui.commands.openElementInEditor(elementHandleId=%=org.test/src<org.test{Activator.java[Activator)
Show JavaElement in Package Explorer View [proposed] - parameter encodes handle identifier of java element
org.eclipse.jdt.ui.commands.showElementInPackageView(elementHandleId=%=org.test/src<org.test{Activator.java[Activator)
Show JavaElement in Type Hierarchy View [proposed] - parameter encodes handle identifier of java element
org.eclipse.jdt.ui.commands.showElementInTypeHierarchyView(elementHandleId=%=org.test/src<org.test{Activator.java[Activator)

CVS

Add Repository Location [proposed] - parameter like ":pserver:anonymous@dev.eclipse.org:/cvsroot/eclipse"
Checkout Project [proposed] - parameter as in map files

Update Manager

Add Update Site [proposed] - params include site URL/path and label (see org.eclipse.update.standalone)
Install Feature [proposed] - params for feature id, version, site, ...?


Browser

Open URL in Browser [proposed] - parameter is URL



Command Embedding Contexts

Help

The example above shows how to embed commands in Help.  See bug 122726 for discussion.

Cheatsheets

Talk to Chris G. about this...

Intro

Investigate this...