Building cheat sheets in Eclipse V3.2

Learn about V3.2 enhancements

Cheat sheets, an important productivity tool for Eclipse users, have gotten even better with Eclipse V3.2. In this follow-up to his "Building cheat sheets in Eclipse" tutorial, IBM software engineer Philipp Tiedt outlines cheat sheets' new features and gives examples of how to use them.

Share:

Philipp Tiedt, Software Engineer, IBM

Philipp TiedtPhilipp Tiedt is a software engineer in IBM's Development Lab in Boeblingen Germany. He holds a bachelor's degree in computer science from the Open University. Before joining IBM Germany in 2004, he completed his bachelor's study at IBM's T.J. Watson Research Center in Hawthorne, N.Y. His areas of interest are Eclipse, user interface design, Java technology, and service-oriented architecture.



04 July 2011 (First published 08 August 2006)

Cheat sheets let Eclipse users view interactive tutorials from within the Eclipse Workbench to learn how to perform complex Eclipse tasks. (See "Building cheat sheets in Eclipse" for a comprehensive introduction to creating cheat sheets.) Cheat sheets are a great way to guide users of your Eclipse plug-ins or Eclipse-based products through the steps they must follow to use your software. Eclipse V3.2 enhances cheat sheet technology to make them easier to build and more versatile for users.

Search cheat sheets content

The Eclipse Help search engine has been enhanced significantly. One improvement is that cheat sheets now are indexed, so Help search results include matching cheat sheet content. For example, if you want help on creating a new plug-in, a Help search for the term "plug-in" will return cheat sheets -- along with other content -- that match your query. A search for "plug-in" returns almost 500 results in a basic Eclipse V3.2 installation, as shown in Figure 1.

Figure 1. Searching for "plug-in"
Searching for plug-in

With this many results, it still might be hard to locate cheat sheets having to do with plug-ins. But refining your search by adding "cheat sheet" to the query might narrow the results too much and exclude useful content. Fortunately, you can explicitly show the cheat sheet results if you display the search results in categories, using the category button shown in Figure 2.

Figure 2. Categorizing search results
Categorizing search results

Open cheat sheets from content files

Until now, cheat sheets were launched from the welcome page or from a list in the Cheat Sheet Selection dialog. The Cheat Sheet Selection dialog has been updated to let you open a content file directly from the file system (see Figure 3). This is especially helpful when you're writing and reviewing a cheat sheet. You don't need to deploy it as a plug-in or start a runtime workbench to see the result of your work. You can simply open it as is, providing the full path to your content file in the workspace.

Figure 3. Opening cheat sheet from a content file
Opening cheat sheet from a content file

Although this is a nice feature for viewing results as you develop your content, one restriction applies: All commands and actions you reference in such a content file must be loaded in the Eclipse instance you open the content in. That is, if you develop your own cheat sheet actions and Eclipse commands in your cheat sheet plug-in, you can't load and use them by simply opening the content file. The platform will display an error, telling you that the plug-in or class that you refer to is not loaded yet, as shown in Figure 4.

Figure 4. Error when trying to run an action
Error when trying to run an action

In this case, you need to go back to the old way: deploy your plug-in or start a runtime workbench to load your code.


Embed command links in user assistance content

With Eclipse V3.2, you can embed Eclipse commands in cheat sheets. This adds another alternative for automating your tutorials. Listing 1 shows how to embed a command.

Listing 1. Embedded commands
<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Open Browser">
  <intro>
    <description>This cheat sheet helps you to launch a browser via an 
        embedded command.</description>
  </intro>  
  <item title="Open Browser">
     <description>Use the following embedded command to launch the Eclipse Web site 
        in a browser</description>
     <command serialization=
        "org.eclipse.ui.browser.openBrowser(url=http://www.eclipse.org)"/>
  </item>
</cheatsheet>>

Parameterized commands

Parameterized commands are Eclipse commands that can be serialized to a String. The serialized command string contains the command ID and optional parameter value pairs. For more information, have a look at the API specification of ParameterizedCommand (see Resources).

The command element is a new child of the item element. It lets you specify a serialized command using the serialization attribute. Usually this is just a String serialization of the command ID. Depending on the command, the serialization can have additional parameters. The command element can specify the confirm and when attributes, which are handled in the same manner as in an action element.

The embedded command in Listing 1 simply launches the Eclipse browser and opens the Eclipse.org Web site by passing in the URL as a parameter. Some commands can have a return value, which you can assign to a cheat sheet variable using the returns attribute. The returned value can then be used as a condition input or simply be presented to the user. For more information about the command element, see the cheat sheet content file format specification (see Resources).


Add completion messages

Cheat sheets now support completion messages for items and tasks. This is especially helpful for showing the user that a complex procedure has been completed. The completion message is a simple text string that can contain formatting tags, such as <b>/</b>. See the cheat sheet content file format specification for further information (see Resources).

The message can contain references to cheat sheet variables in order to display their content. The code below shows a simple completion message displaying a variable's content.

<onCompletion>The content of the \
cheat sheet variable is ${variableName}.</onCompletion>

Build composite cheat sheets

A fancy new feature of Eclipse V3.2 is the ability to build composite cheat sheets, which let you structure cheat sheets as a tree. A composite cheat sheet consists of tasks, where each task represents a cheat sheet. Tasks are grouped in task groups.

Registering a composite cheat sheet

The extension point for registering a composite cheat sheet is the same as for a simple one. However, a new composite attribute appears that flags whether the cheat sheet is simple or composite.

Listing 2. Registering a composite cheat sheet
<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.2"?>
<plugin>
   <extension
         point="org.eclipse.ui.cheatsheets.cheatSheetContent">
      <cheatsheet
         composite="true"
         contentFile="content/content.xml"
         id="devworks.tutorial.cheatsheets.updated.composite"
         name="Composite Cheat Sheet"/>
   </extension>
</plugin>

As with simple cheat sheets, a composite gets an ID, a name, and a content file. The composite attribute needs to be set to true. However, composite cheat sheets' content files follow a totally different XML schema specification.

Composite content

Listing 3 shows how tasks and task groups are used in a composite cheat sheet and also explains additional attributes and elements.

Listing 3. A composite cheat sheet
<?xml version="1.0" encoding="UTF-8"?>
<compositeCheatsheet name="Work with the Eclipse Platform">
   <taskGroup name="Work with the Eclipse Platform" kind="choice">
      <intro>
         This cheat sheet offers different groups of tasks. Choose
         one or more groups and complete them.
      </intro>
      <onCompletion>
         Great! You have completed one or more task groups.
      </onCompletion>
      <taskGroup name="Java Development Tools" kind="sequence">
         <intro>
            Creating a Java project and a SWT Application.
            <br />
            You need to first complete the Java project task before
            you can start with the SWT Application.
         </intro>
         <onCompletion>
            Congratulations you have built both Java applications.
         </onCompletion>
         <task kind="cheatsheet" name="A Java project"
            id="createJavaProject">
            ...
         </task>
         <task kind="cheatsheet" name="A simple SWT application"
            id="createSWTApplication">
            ...
         </task>
      </taskGroup>
      <taskGroup name="Other tutorials" kind="set">
         <intro>
            This group contains several different tutorials. Just
            complete them in any order.
         </intro>
         <onCompletion>
            Great! You have completed all tutorials
         </onCompletion>
         <task kind="cheatsheet" name="Simple Plug-in tutorial"
            skip="true">
            ...
         </task>
         <task kind="cheatsheet" name="An other tutorial">
            ...
         </task>
      </taskGroup>
   </taskGroup>
</compositeCheatsheet>

The cheat sheet content in Listing 3 defines a root task group containing two subtask groups, each containing two tasks. You use the taskgroup element to define task groups. Task groups are usually used to group a set of related cheat sheets. You use the kind attribute to set the task group as one of three kinds:

  • set -- The contained cheat sheets can be completed in any order. However, all of them must be completed to complete the group.
  • sequence -- The contained cheat sheets must all be completed in the order they are listed.
  • choice -- Any of the cheat sheets can be completed in any order.

The skip attribute should be set to true if the whole task group can be skipped. The name attribute specifies the name displayed for this task group. The additional intro and onCompletion elements are used in the same manner as for simple cheat sheet items and result in an introduction message and completion message, respectively, for the task group.

Listing 3 composes cheat sheets to guide the user through some tutorials about different areas of the Eclipse Platform. A major topic is Java™ Development Tools in the first task group, and the other major topics are other tutorials that might be of interest for the user. (Note that this is just a sample and not a complete overview of tutorials in Eclipse.)

The root task group is of the choice kind, which means the user can select any subtask group and complete it. The task group for the Java Development Tools is defined as a sequence, so the user first must complete the Java Project tutorial before creating a simple SWT application. The last task group is defined as a set, so the user is free to complete the subtasks in any order. Figure 5 shows the cheat sheet's tree structure.

Figure 5. Composite cheat sheet structure
Composite cheat sheet structure

In Figure 5, note that different icons represent the different kinds of task groups. Also, the second task in the Java Development Tools group is grayed out because it can't be started before the first task is completed.

Tasks

A task represents a cheat sheet and is implemented using the task element. Listing 4 explains this in a bit more detail.

Listing 4. The task element
<task kind="cheatsheet" name="A Java project"
   id="createJavaProject">
   <param name="id" value="org.eclipse.pde.helloworld" />
   <param name="showIntro" value="false" />
   <intro>
      This tutorial guides you through the creation of a Java project.
   </intro>
   <onCompletion>
      Finished creating a Java project.
   </onCompletion>
</task>

You give each task a name and an ID. The name is displayed in the cheat sheet tree, as shown above in Figure 5. You use the value of the id attribute to reference a task -- when declaring dependencies between tasks or task groups, for example. You can set the optional skip to true if the user can skip the task. As with task groups, you can use the intro and onCompletion elements to display an introduction and completion message for the task. The parameter element is used to reference a cheat sheet. Typically the cheat sheet is referenced by its ID, as shown in Listing 4. The parameter element contains a name and a value attribute.

Table 1 shows the parameters that are currently defined.

Table 1. Parameters
namevalue
idThe ID (as defined in the org.eclipse.ui.cheatsheets.cheatSheetContent extension) of the cheat sheet that should be associated with the task.
pathThis can be an absolute URL to another cheat sheet content file or a URL of the content file relative to the content file of the composite content file. Note that only one of the id and path parameters should be specified -- not both.
showIntroIf this is set to false, the cheat sheet's introduction will be suppressed.

Dependencies

If a task or task group depends on the completion of another task or task group, you can use the dependency element to achieve this. It simply contains the task attribute, which specifies the ID of the task or task group that must be completed before starting this task or task group.

An example is a task that can only be executed if a Java project has been created first. This task would have a dependency on the task shown in Listing 4. The code below shows a dependency element with a reference to the task that creates a Java project.

<dependency task="createJavaProject"/>

Conclusion

This article has given you a short overview of what's new for cheat sheets in Eclipse V3.2, including the composite cheat sheets feature. Cheat sheets are a key concept in Eclipse user assistance and are getting increasingly important. The technology will undergo further improvements. Some additional new features are in a provisional state for Eclipse V3.2.

Take a look at the org.eclipse.ui.cheatsheets.cheatSheetContent extension point documentation to find out more about the taskEditor and taskExplorer concepts (see Resources).

Resources

Learn

Get products and technologies

Discuss

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Open source on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Open source
ArticleID=151985
ArticleTitle=Building cheat sheets in Eclipse V3.2
publish-date=07042011