Attachment 33881 Details for Bug 123921 – update to draft document (ver 0.4)

Some Eclipse Foundation services are deprecated, or will be soon. Please ensure you've read this important communication.

update to draft document (ver 0.4)

EmbeddingCommands.html (text/html), 22.23 KB, created by Christopher Daly

on 2006-01-31 15:01:19 EST

(hide)

Description:

Filename:

MIME Type:

Creator: Christopher Daly

Created: 2006-01-31 15:01:19 EST

Size: 22.23 KB

patch

obsolete

><!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
><html>
><head>
>  <meta content="text/html; charset=ISO-8859-1"
> http-equiv="content-type">
>  <title>Embedding Commands as Links</title>
></head>
><body>
><h1>Embedding Commands as Links</h1>
>by Chris Daly (cjdaly@us.ibm.com)<br>
>version 0.4 (31-Jan-2006)<br>
><br>
><br>
>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.&nbsp;
>The centerpiece of this document is a catalog of commands that are
>thought to be useful in embedded document contexts.&nbsp; This document
>is associated with <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=123921">bug 123921</a>.<br>
><br>
><h2>Background</h2>
>A <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=120523">recent
>enhancement</a> to the command framework allows commands and their
>parameter values to be serialized as strings and later deserialized and
>executed.&nbsp; This allows serialized commands to be embedded in
>documents and visualized as links such that activating the link has the
>effect of&nbsp; executing the embedded command.<br>
><br>
><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=121709">Another
>enhancement</a> introduces the notion of typed command
>parameters.&nbsp; Previously, parameter values were expressed as
>strings throughout the lifecycle of command parameterization and
>execution.&nbsp; Now command parameters can declare a type and the
>parameter values can be handled as objects instead of strings.&nbsp;
>This allows:<br>
><ul>
>  <li>object parameter values to be handled correctly by the
>serialization/deserialization mechanism described above</li>
>  <li>multiple handlers of a command to convert string to object
>parameter values in a consistent way</li>
>  <li>tooling to search for commands that operate on certain types of
>objects</li>
></ul>
>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.&nbsp; The functionality may also be useful in
>other contexts.<br>
><br>
>Two additional things are required for the ability to embed commands in
>documents to become a useful and used feature.&nbsp; First, we must
>have a reasonably large "catalog" of commands that do
>interesting/useful things when embedded in documents.&nbsp; 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).&nbsp; These topics
>are explored in detail below.<br>
><br>
><h2>An Example<br>
></h2>
>Below is an HTML document that represents a Help topic.&nbsp; The
>JavaScript <span style="font-family: monospace;">executeCommand</span>
>function takes a serialized command as its argument and executes the
>command when the link is clicked.&nbsp; The serialized command text is
>highlighted.<span style="font-style: italic;"></span><br>
><br>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span
> style="font-family: monospace;">&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD
>HTML 4.0 Transitional//EN"&gt;&lt;HTML&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;HEAD&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;TITLE&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">Help Link Test</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;/TITLE&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;script
>language="JavaScript" src="../../org.eclipse.help/livehelp.js"&gt;
>&lt;/script&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;/HEAD&gt;</span><br
> style="font-family: monospace;">
>      <br style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;body&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;p&gt;Execute command
>link to</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;a
>href='javascript:executeCommand(</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
>"<span style="background-color: rgb(255, 153, 102);">org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.ui.views.TaskList)</span>")'&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; show
>Tasks view&lt;/a&gt;.&lt;/p&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;/body&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;/HTML&gt;</span><br>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
><br>
><h2>Catalog of Commands</h2>
>What follows is a catalog of commands that may be useful in embedded
>document scenarios.&nbsp; Some of these are available today and some
>are not yet committed (indicated with [proposed] below).&nbsp; The
>format of the tables below is:<br>
><br>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Command
>Name</span> - brief description and mention of parameters<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><span
> style="font-family: monospace;">command.id(param.id=value)</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
>&laquo; <span style="font-style: italic;">example demonstrating usage</span><br>
>      </div>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
>Please refer to the JavaDoc for <span style="font-family: monospace;">ParameterizedCommand.serialize()</span>
>for a description of the command serialization format.<br>
><br>
><h3>General Workbench <small><small>(see bug <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125632">125632</a>)</small></small><br>
></h3>
><small> </small><small> </small>
><table style="text-align: left; width: 876px; height: 296px;" border="1"
> cellpadding="2" cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
>Perspective</span> - without parameters, opens a
>dialog with list of perspectives<br>
>      </td>
>    </tr>
>    <tr style="font-family: monospace;">
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;">org.eclipse.ui.perspectives.showPerspective</div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
>Perspective</span> - parameter
>indicates perspective id<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><small><span
> style="font-family: monospace;">org.eclipse.ui.perspectives.showPerspective(org.eclipse.ui.perspectives.showPerspective.perspectiveId=org.eclipse.ui.resourcePerspective)</span>
>      </small></div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
>View</span> - without parameters, opens a dialog with
>list of views<br>
>      </td>
>    </tr>
>    <tr style="font-family: monospace;">
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;">org.eclipse.ui.views.showView</div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
>View</span> - parameter indicates
>view id</td>
>    </tr>
>    <tr style="font-family: monospace;">
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;">org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.ui.views.TaskList)</div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Window
>Preferences</span> - parameter indicates which preference page (no
>parameter means open the main page)<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><span
> style="font-family: monospace;">org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.team.ui.TextPreferences)</span><br>
>      </div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">New
>Wizard</span> [proposed] - parameter indicates id of wizard to launch<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Import
>Wizard</span> [proposed] - parameter indicates id of wizard to launch</td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Export
>Wizard</span> [proposed] - parameter indicates id of wizard to launch</td>
>    </tr>
>  </tbody>
></table>
><br>
><h3>Workspace</h3>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
>Resource</span> [proposed] - open a resource given its path and/or URI
>as parameter<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
>Resource in Navigator</span> [proposed] - show in Navigator view given
>resource path and/or URI as parameter</td>
>    </tr>
>  </tbody>
></table>
><br>
><h3>User Assistance <small><small>(see bug <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=123040">123040</a>,
><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125908">125908</a>)</small></small><br>
></h3>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Display
>Help</span> - without parameters, opens the help system<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><span
> style="font-family: monospace;">org.eclipse.ui.help.displayHelp</span><br>
>      </div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Display
>Help</span> - parameter indicates help topic href<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><span
> style="font-family: monospace;">org.eclipse.ui.help.displayHelp(href=/org.eclipse.platform.doc.user/gettingStarted/qs-02a.htm)</span><br>
>      </div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
>Cheatsheet by Id</span> - parameter indicates id of cheatsheet<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><span
> style="font-family: monospace;">org.eclipse.ui.cheatsheets.openCheatSheet(cheatSheetId=org.eclipse.jdt.helloworld)</span><br>
>      </div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
>Cheatsheet by URL</span> - parameter for URL to load cheatsheed
>(additional parameters to give cheatsheet a name and id)<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><small><span
> style="font-family: monospace;">org.eclipse.ui.cheatsheets.openCheatSheetURL(cheatSheetId=my.cheatsheet.id,name=Foo,url=file://some/file/cheatsheet.xml)</span></small><br>
>      </div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
>Intro Content</span> [proposed] - look into this...<br>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
><h3>Java <small><small>(see bug <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=123198">123198</a>)</small></small><br>
></h3>
>Note: the examples below work on a class named <span
> style="font-family: monospace;">Activator</span> in a plugin called <span
> style="font-family: monospace;">org.test</span>.&nbsp; Simply create a
>new plugin called <span style="font-family: monospace;">org.test</span>
>to try these examples.<br>
><br>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
>JavaElement in Editor</span> - parameter encodes handle identifier of
>java element<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><small><span
> style="font-family: monospace;">org.eclipse.jdt.ui.commands.openElementInEditor(elementRef=org.test/org.test.Activator)</span></small><br>
>      </div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
>JavaElement in Package Explorer View</span> - parameter encodes handle
>identifier of java element</td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><small><span
> style="font-family: monospace;">org.eclipse.jdt.ui.commands.showElementInPackageView(elementRef=org.test/org.test.Activator)</span></small><br>
>      </div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
>JavaElement in Type Hierarchy View</span> - parameter encodes handle
>identifier of java element</td>
>    </tr>
>    <tr style="font-family: monospace;">
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><small>org.eclipse.jdt.ui.commands.showElementInTypeHierarchyView(elementRef=org.test/org.test.Activator)<br>
>      </small></div>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
><h3>Run/Debug</h3>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><br>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
><h3>Update Manager <small><small>(see bug <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125071">125071</a>)</small></small><br>
></h3>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
>Manage Configuration Dialog</span> - opens the dialog for managing
>product configuration (no parameters)<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><span
> style="font-family: monospace;">org.eclipse.ui.update.manageConfiguration</span><br>
>      </div>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
>Install/Update Feature Dialog</span> - opens the dialog for installing
>and updating features (no parameters)<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><span
> style="font-family: monospace;">org.eclipse.ui.update.findAndInstallUpdates</span><br>
>      </div>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
><br>
><h3>Browser <small><small>(see bug <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125795">125795</a>)</small></small><br>
></h3>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
>URL in Browser</span> - parameters for URL, browserId, window name and
>tooltip<br>
>      </td>
>    </tr>
>    <tr>
>      <td style="vertical-align: top;">
>      <div style="margin-left: 40px;"><span
> style="font-family: monospace;">org.eclipse.ui.browser.openBrowser(url=http://www.google.com)</span><br>
>      </div>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
><br>
><br>
><h2>Command Embedding Contexts</h2>
><h3>Help <small><small>(see bug <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=122726">122726</a>)</small></small><br>
></h3>
>The example above shows how to embed commands in Help.<br>
><br>
><h3>Cheatsheets</h3>
>Here's an example that shows how to embed commands in a Cheatsheet:<br>
><br>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span
> style="font-family: monospace;">&lt;?xml version="1.0"
>encoding="UTF-8"?&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;cheatsheet
>title="Example of Commands"&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp; &lt;intro&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
>&lt;description&gt;A cheat sheet which tests command
>support&lt;/description&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp; &lt;/intro&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp; &lt;item title="Step
>1"&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
>&lt;description&gt;This is a step with a command which shows the search
>view.&lt;/description&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
>&lt;command serialization="<span
> style="background-color: rgb(255, 153, 102);">org.eclipse.search.ui.views.SearchView</span>"/&gt;&nbsp;
>      </span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp; &lt;/item&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp; &lt;item title="Step
>2"&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
>&lt;description&gt;This is a step with a command and parameters, shows
>package explorer.&lt;/description&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
>&lt;command serialization="<span
> style="background-color: rgb(255, 153, 102);">org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)</span>"/&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp; &lt;/item&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;/cheatsheet&gt;</span><br>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
>Note also that bug <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125420">125420</a>
>proposes an enhancement to declare command return types and bug <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125545">125545</a>
>describes how return values can be captured to use later in
>cheatsheets.&nbsp; TODO: add an example of that here.<br>
><br>
><h3>Intro <small><small>(see bugs <a
> href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=124060">124060</a>,
><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=124076">124076</a>,
><a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=124573">124573</a>)</small></small><br>
></h3>
>Here's an example that shows how to embed commands in Intro content:<br>
><br>
><table style="width: 100%; text-align: left;" border="1" cellpadding="2"
> cellspacing="2">
>  <tbody>
>    <tr>
>      <td style="vertical-align: top;"><span
> style="font-family: monospace;">&lt;?xml version="1.0"
>encoding="UTF-8" ?&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;introContent&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp; &lt;!-- Extension to
>the SDK What's New Page. --&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp; &lt;extensionContent
>path="news/page-content/noteworthy-links/pdeAnchor"&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; &lt;link
>label="Test News1"</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
>url="http://org.eclipse.ui.intro/execute?command=<span
> style="background-color: rgb(255, 153, 102);">org.eclipse.ui.views.showView()</span>&amp;amp;standby=true"</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
>id="pde-noteworthy" style-id="noteworthy-link"&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
>&lt;text&gt;This is a test&lt;/text&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
>&lt;/link&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; &lt;link
>label="Test News2"</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">url="http://org.eclipse.ui.intro/execute?command=<span
> style="background-color: rgb(255, 153, 102);">org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId%3dorg.eclipse.jdt.ui.PackageExplorer)</span>&amp;amp;standby=true"</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
>id="pde-noteworthy" style-id="noteworthy-link"&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
>&lt;text&gt;This is another test&lt;/text&gt;</span><br
> style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
>&lt;/link&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&nbsp;
>&lt;/extensionContent&gt;</span><br style="font-family: monospace;">
>      <span style="font-family: monospace;">&lt;/introContent&gt;</span><br>
>      </td>
>    </tr>
>  </tbody>
></table>
><br>
></body>
></html>

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
  <meta content="text/html; charset=ISO-8859-1"
 http-equiv="content-type">
  <title>Embedding Commands as Links</title>
</head>
<body>
<h1>Embedding Commands as Links</h1>
by Chris Daly (cjdaly@us.ibm.com)<br>
version 0.4 (31-Jan-2006)<br>
<br>
<br>
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.&nbsp;
The centerpiece of this document is a catalog of commands that are
thought to be useful in embedded document contexts.&nbsp; This document
is associated with <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=123921">bug 123921</a>.<br>
<br>
<h2>Background</h2>
A <a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=120523">recent
enhancement</a> to the command framework allows commands and their
parameter values to be serialized as strings and later deserialized and
executed.&nbsp; This allows serialized commands to be embedded in
documents and visualized as links such that activating the link has the
effect of&nbsp; executing the embedded command.<br>
<br>
<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=121709">Another
enhancement</a> introduces the notion of typed command
parameters.&nbsp; Previously, parameter values were expressed as
strings throughout the lifecycle of command parameterization and
execution.&nbsp; Now command parameters can declare a type and the
parameter values can be handled as objects instead of strings.&nbsp;
This allows:<br>
<ul>
  <li>object parameter values to be handled correctly by the
serialization/deserialization mechanism described above</li>
  <li>multiple handlers of a command to convert string to object
parameter values in a consistent way</li>
  <li>tooling to search for commands that operate on certain types of
objects</li>
</ul>
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.&nbsp; The functionality may also be useful in
other contexts.<br>
<br>
Two additional things are required for the ability to embed commands in
documents to become a useful and used feature.&nbsp; First, we must
have a reasonably large "catalog" of commands that do
interesting/useful things when embedded in documents.&nbsp; 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).&nbsp; These topics
are explored in detail below.<br>
<br>
<h2>An Example<br>
</h2>
Below is an HTML document that represents a Help topic.&nbsp; The
JavaScript <span style="font-family: monospace;">executeCommand</span>
function takes a serialized command as its argument and executes the
command when the link is clicked.&nbsp; The serialized command text is
highlighted.<span style="font-style: italic;"></span><br>
<br>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span
 style="font-family: monospace;">&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD
HTML 4.0 Transitional//EN"&gt;&lt;HTML&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;HEAD&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;TITLE&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">Help Link Test</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;/TITLE&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;script
language="JavaScript" src="../../org.eclipse.help/livehelp.js"&gt;
&lt;/script&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;/HEAD&gt;</span><br
 style="font-family: monospace;">
      <br style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;body&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;p&gt;Execute command
link to</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;a
href='javascript:executeCommand(</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
"<span style="background-color: rgb(255, 153, 102);">org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.ui.views.TaskList)</span>")'&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; show
Tasks view&lt;/a&gt;.&lt;/p&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;/body&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;/HTML&gt;</span><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<br>
<h2>Catalog of Commands</h2>
What follows is a catalog of commands that may be useful in embedded
document scenarios.&nbsp; Some of these are available today and some
are not yet committed (indicated with [proposed] below).&nbsp; The
format of the tables below is:<br>
<br>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Command
Name</span> - brief description and mention of parameters<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><span
 style="font-family: monospace;">command.id(param.id=value)</span>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&laquo; <span style="font-style: italic;">example demonstrating usage</span><br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
Please refer to the JavaDoc for <span style="font-family: monospace;">ParameterizedCommand.serialize()</span>
for a description of the command serialization format.<br>
<br>
<h3>General Workbench <small><small>(see bug <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125632">125632</a>)</small></small><br>
</h3>
<small> </small><small> </small>
<table style="text-align: left; width: 876px; height: 296px;" border="1"
 cellpadding="2" cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
Perspective</span> - without parameters, opens a
dialog with list of perspectives<br>
      </td>
    </tr>
    <tr style="font-family: monospace;">
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;">org.eclipse.ui.perspectives.showPerspective</div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
Perspective</span> - parameter
indicates perspective id<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><small><span
 style="font-family: monospace;">org.eclipse.ui.perspectives.showPerspective(org.eclipse.ui.perspectives.showPerspective.perspectiveId=org.eclipse.ui.resourcePerspective)</span>
      </small></div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
View</span> - without parameters, opens a dialog with
list of views<br>
      </td>
    </tr>
    <tr style="font-family: monospace;">
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;">org.eclipse.ui.views.showView</div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
View</span> - parameter indicates
view id</td>
    </tr>
    <tr style="font-family: monospace;">
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;">org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.ui.views.TaskList)</div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Window
Preferences</span> - parameter indicates which preference page (no
parameter means open the main page)<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><span
 style="font-family: monospace;">org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.team.ui.TextPreferences)</span><br>
      </div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">New
Wizard</span> [proposed] - parameter indicates id of wizard to launch<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Import
Wizard</span> [proposed] - parameter indicates id of wizard to launch</td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Export
Wizard</span> [proposed] - parameter indicates id of wizard to launch</td>
    </tr>
  </tbody>
</table>
<br>
<h3>Workspace</h3>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
Resource</span> [proposed] - open a resource given its path and/or URI
as parameter<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
Resource in Navigator</span> [proposed] - show in Navigator view given
resource path and/or URI as parameter</td>
    </tr>
  </tbody>
</table>
<br>
<h3>User Assistance <small><small>(see bug <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=123040">123040</a>,
<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125908">125908</a>)</small></small><br>
</h3>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Display
Help</span> - without parameters, opens the help system<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><span
 style="font-family: monospace;">org.eclipse.ui.help.displayHelp</span><br>
      </div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Display
Help</span> - parameter indicates help topic href<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><span
 style="font-family: monospace;">org.eclipse.ui.help.displayHelp(href=/org.eclipse.platform.doc.user/gettingStarted/qs-02a.htm)</span><br>
      </div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
Cheatsheet by Id</span> - parameter indicates id of cheatsheet<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><span
 style="font-family: monospace;">org.eclipse.ui.cheatsheets.openCheatSheet(cheatSheetId=org.eclipse.jdt.helloworld)</span><br>
      </div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
Cheatsheet by URL</span> - parameter for URL to load cheatsheed
(additional parameters to give cheatsheet a name and id)<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><small><span
 style="font-family: monospace;">org.eclipse.ui.cheatsheets.openCheatSheetURL(cheatSheetId=my.cheatsheet.id,name=Foo,url=file://some/file/cheatsheet.xml)</span></small><br>
      </div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
Intro Content</span> [proposed] - look into this...<br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<h3>Java <small><small>(see bug <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=123198">123198</a>)</small></small><br>
</h3>
Note: the examples below work on a class named <span
 style="font-family: monospace;">Activator</span> in a plugin called <span
 style="font-family: monospace;">org.test</span>.&nbsp; Simply create a
new plugin called <span style="font-family: monospace;">org.test</span>
to try these examples.<br>
<br>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
JavaElement in Editor</span> - parameter encodes handle identifier of
java element<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><small><span
 style="font-family: monospace;">org.eclipse.jdt.ui.commands.openElementInEditor(elementRef=org.test/org.test.Activator)</span></small><br>
      </div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
JavaElement in Package Explorer View</span> - parameter encodes handle
identifier of java element</td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><small><span
 style="font-family: monospace;">org.eclipse.jdt.ui.commands.showElementInPackageView(elementRef=org.test/org.test.Activator)</span></small><br>
      </div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Show
JavaElement in Type Hierarchy View</span> - parameter encodes handle
identifier of java element</td>
    </tr>
    <tr style="font-family: monospace;">
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><small>org.eclipse.jdt.ui.commands.showElementInTypeHierarchyView(elementRef=org.test/org.test.Activator)<br>
      </small></div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<h3>Run/Debug</h3>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
<h3>Update Manager <small><small>(see bug <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125071">125071</a>)</small></small><br>
</h3>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
Manage Configuration Dialog</span> - opens the dialog for managing
product configuration (no parameters)<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><span
 style="font-family: monospace;">org.eclipse.ui.update.manageConfiguration</span><br>
      </div>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
Install/Update Feature Dialog</span> - opens the dialog for installing
and updating features (no parameters)<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><span
 style="font-family: monospace;">org.eclipse.ui.update.findAndInstallUpdates</span><br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<br>
<h3>Browser <small><small>(see bug <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125795">125795</a>)</small></small><br>
</h3>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span style="font-weight: bold;">Open
URL in Browser</span> - parameters for URL, browserId, window name and
tooltip<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">
      <div style="margin-left: 40px;"><span
 style="font-family: monospace;">org.eclipse.ui.browser.openBrowser(url=http://www.google.com)</span><br>
      </div>
      </td>
    </tr>
  </tbody>
</table>
<br>
<br>
<br>
<h2>Command Embedding Contexts</h2>
<h3>Help <small><small>(see bug <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=122726">122726</a>)</small></small><br>
</h3>
The example above shows how to embed commands in Help.<br>
<br>
<h3>Cheatsheets</h3>
Here's an example that shows how to embed commands in a Cheatsheet:<br>
<br>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span
 style="font-family: monospace;">&lt;?xml version="1.0"
encoding="UTF-8"?&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;cheatsheet
title="Example of Commands"&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp; &lt;intro&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;description&gt;A cheat sheet which tests command
support&lt;/description&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp; &lt;/intro&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp; &lt;item title="Step
1"&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;description&gt;This is a step with a command which shows the search
view.&lt;/description&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;command serialization="<span
 style="background-color: rgb(255, 153, 102);">org.eclipse.search.ui.views.SearchView</span>"/&gt;&nbsp;
      </span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp; &lt;/item&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp; &lt;item title="Step
2"&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;description&gt;This is a step with a command and parameters, shows
package explorer.&lt;/description&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;command serialization="<span
 style="background-color: rgb(255, 153, 102);">org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)</span>"/&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp; &lt;/item&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;/cheatsheet&gt;</span><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
Note also that bug <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125420">125420</a>
proposes an enhancement to declare command return types and bug <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=125545">125545</a>
describes how return values can be captured to use later in
cheatsheets.&nbsp; TODO: add an example of that here.<br>
<br>
<h3>Intro <small><small>(see bugs <a
 href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=124060">124060</a>,
<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=124076">124076</a>,
<a href="https://bugs.eclipse.org/bugs/show_bug.cgi?id=124573">124573</a>)</small></small><br>
</h3>
Here's an example that shows how to embed commands in Intro content:<br>
<br>
<table style="width: 100%; text-align: left;" border="1" cellpadding="2"
 cellspacing="2">
  <tbody>
    <tr>
      <td style="vertical-align: top;"><span
 style="font-family: monospace;">&lt;?xml version="1.0"
encoding="UTF-8" ?&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;introContent&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp; &lt;!-- Extension to
the SDK What's New Page. --&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp; &lt;extensionContent
path="news/page-content/noteworthy-links/pdeAnchor"&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; &lt;link
label="Test News1"</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
url="http://org.eclipse.ui.intro/execute?command=<span
 style="background-color: rgb(255, 153, 102);">org.eclipse.ui.views.showView()</span>&amp;amp;standby=true"</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
id="pde-noteworthy" style-id="noteworthy-link"&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;text&gt;This is a test&lt;/text&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;/link&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp; &lt;link
label="Test News2"</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">url="http://org.eclipse.ui.intro/execute?command=<span
 style="background-color: rgb(255, 153, 102);">org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId%3dorg.eclipse.jdt.ui.PackageExplorer)</span>&amp;amp;standby=true"</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
id="pde-noteworthy" style-id="noteworthy-link"&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
&lt;text&gt;This is another test&lt;/text&gt;</span><br
 style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;&nbsp;&nbsp;
&lt;/link&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&nbsp;
&lt;/extensionContent&gt;</span><br style="font-family: monospace;">
      <span style="font-family: monospace;">&lt;/introContent&gt;</span><br>
      </td>
    </tr>
  </tbody>
</table>
<br>
</body>
</html>

Actions: View

Attachments on bug 123921: 33044 | 33132 | 33685 | 33881 | 34409 | 34444 | 34981 | 35216