Embedding Commands as Links

by Chris Daly (cjdaly@us.ibm.com)
version 0.2 (16-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. 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. 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

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>

Intro

Bug 124076 proposes a new IntroURL action to allow executing commands from Intro content. Here's what that would look like:

<?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>