Embedding Commands as Links

by Chris Daly (cjdaly@us.ibm.com)
version 0.6 (9-Feb-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. This document is associated with bug 123921.

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:

object parameter values to be handled correctly by the serialization/deserialization mechanism described above
multiple handlers of a command to convert string to object parameter values in a consistent way
tooling to search for commands that operate on certain types of objects

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. The serialized command text is highlighted.

<!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 (see bugs 125632, 126651)

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)

    

Window Preferences - parameter indicates which preference page (no parameter means open the main page)

org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.team.ui.TextPreferences)

New Wizard - parameter indicates id of wizard to launch (no parameter opens chooser dialog)

org.eclipse.ui.newWizard(newWizardId=org.eclipse.pde.ui.NewProjectWizard)

Import Wizard - parameter indicates id of wizard to launch (no parameter opens chooser dialog)

org.eclipse.ui.file.import(importWizardId=org.eclipse.debug.internal.ui.importexport.breakpoints.WizardImportBreakpoints)

Export Wizard - parameter indicates id of wizard to launch (no parameter opens chooser dialog)

org.eclipse.ui.file.export(exportWizardId=org.eclipse.jdt.internal.ui.jarpackager.JarPackageWizard)

Workspace (see bug 126079)

Note: the examples below require resources to open/show. Simply create a new plugin called org.test to try these examples.

Open File - open a file given its path as parameter, no parameter opens a dialog to help find a file

org.eclipse.ui.navigate.openResource(filePath=/org.test/build.properties)

Show Resource in Navigator - show in Navigator view given resource path as parameter

org.eclipse.ui.navigate.showResourceByPath(resourcePath=/org.test/src/org)

User Assistance (see bugs 123040, 125908, 127031)

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 by Id - parameter indicates id of cheatsheet

org.eclipse.ui.cheatsheets.openCheatSheet(cheatSheetId=org.eclipse.jdt.helloworld)

Open Cheatsheet by URL - parameter for URL to load cheatsheed (additional parameters to give cheatsheet a name and id)

org.eclipse.ui.cheatsheets.openCheatSheetURL(cheatSheetId=my.cheatsheet.id,name=Foo,url=file://some/file/cheatsheet.xml)

Open Intro Content - no parameters, just opens the welcome front page

org.eclipse.ui.help.showIntro

Java (see bug 123198)

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 - parameter encodes handle identifier of java element

org.eclipse.jdt.ui.commands.openElementInEditor(elementRef=org.test/org.test.Activator)

Show JavaElement in Package Explorer View - parameter encodes handle identifier of java element

org.eclipse.jdt.ui.commands.showElementInPackageView(elementRef=org.test/org.test.Activator)

Show JavaElement in Type Hierarchy View - parameter encodes handle identifier of java element

      org.eclipse.jdt.ui.commands.showElementInTypeHierarchyView(elementRef=org.test/org.test.Activator)

Run/Debug

Open Run Configuration Dialog - no parameters

org.eclipse.debug.ui.commands.OpenRunConfigurations

Open Debug Configuration Dialog - no parameters

org.eclipse.debug.ui.commands.OpenDebugConfigurations

Update Manager (see bug 125071)

Open Manage Configuration Dialog - opens the dialog for managing product configuration (no parameters)

org.eclipse.ui.update.manageConfiguration

Open Install/Update Feature Dialog - opens the dialog for installing and updating features (no parameters)

org.eclipse.ui.update.findAndInstallUpdates

Browser (see bug 125795)

Open URL in Browser - parameters for URL, browserId, window name and tooltip

org.eclipse.ui.browser.openBrowser(url=http://www.google.com)

Dialogs (see bug 126993)

Note: these commands are in org.eclipse.ui.cheatsheets. They could eventually be moved up to org.eclipse.ui.workbench.

Open Input Dialog - parameters for title, message, .... This command returns the value typed by the user.

org.eclipse.ui.dialogs.openInputDialog(title=MyMessage,message=Hello,initialValue=World)

Open Message Dialog - parameters for title, message, button labels, .... This command returns the label string of the clicked button.

      org.eclipse.ui.dialogs.openMessageDialog(title=Hi,message=msg,buttonLabel0=YES,buttonLabel1=no,buttonLabel2=maYbe,defaultIndex=2,imageType=1)

Command Embedding Contexts

Help (see bug 122726)

The example above shows how to embed commands in Help.

Cheatsheets

Here's an example that shows how to embed commands in a Cheatsheet:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Example of Commands">
<intro>
    <description>A cheat sheet which tests command support</description>
</intro>
<item title="Step 1">
    <description>This is a step with a command which shows the search view.</description>
    <command serialization="org.eclipse.search.ui.views.SearchView"/>
</item>
<item title="Step 2">
    <description>This is a step with a command and parameters, shows package explorer.</description>
    <command serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
</item>
</cheatsheet>

Note also that bug 125420 proposes an enhancement to declare command return types and bug 125545 describes how return values can be captured to use later in cheatsheets. The basic idea is to use the returns attribute to identify what key to use when storing the return value in the ICheatSheetManager. Below is an example:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Example of Commands 2">
<intro>
    <description>Another cheat sheet which tests command support</description>
</intro>
<item title="Step 1">
    <description>This is a step with a command which shows an input dialog.</description>
    <command
      returns="MyData"
      serialization="org.eclipse.ui.dialogs.openInputDialog(title=Hello,message=Input Data)"/>
    <onCompletion>
      Input value was ${MyData}
    </onCompletion>
</item>
</cheatsheet>

In the above example a call to the ICheatSheetManager.setData(...) method will be made after the command completes with "MyData" as the key parameter and the command return value as the data parameter. If the command declares a return type than the value converter will be used to convert the object returned to a string. Otherwise, if the command returns a string it will be stored as-is and if the command doesn't return a string the return value will be ignored.

Intro (see bugs 124060, 124076, 124573)

Here's an example that shows how to embed commands in Intro content:

<?xml version="1.0" encoding="UTF-8" ?>
<introContent>

<extensionContent path="news/page-content/noteworthy-links/pdeAnchor">
    <link label="Test News1"
      url="http://org.eclipse.ui.intro/execute?command=org.eclipse.ui.views.showView()&standby=true"
      id="pde-noteworthy" style-id="noteworthy-link">
      <text>This is a test</text>
    </link>
    <link label="Test News2"
url="http://org.eclipse.ui.intro/execute?command=org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId%3dorg.eclipse.jdt.ui.PackageExplorer)&standby=true"
      id="pde-noteworthy" style-id="noteworthy-link">
      <text>This is another test</text>
    </link>
</extensionContent>
</introContent>