Simple cheat sheets

Cheat sheets guide the user through a series of complex tasks to achieve an overall goal. For example, a cheat sheet could be used to help guide the user through all the steps needed to create, compile, and run a simple Java program. Cheat sheets are launched from the Help > Cheat Sheets... menu item. Cheat sheets can also be launched from an intro page.

Cheat sheets are defined using the org.eclipse.ui.cheatsheets.cheatSheetContent extension point. The cheat sheet content itself is defined in a separate file so that it can be more easily translated into other languages.

Contributing a cheat sheet

Contributing a cheat sheet is pretty straightforward. Let's look at a cheat sheet contributed by the JDT for building a simple Java application.

<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
	<cheatsheet
		name="%cheatsheet.helloworld.name"
		contentFile="$nl$/cheatsheets/HelloWorld.xml"
		id="org.eclipse.jdt.helloworld">
		<description>%cheatsheet.helloworld.desc</description>
	</cheatsheet>
	...

Much like other workbench contributions, a name, description, and id can be specified for the cheat sheet. The name and description are shown when the user accesses the

Help > Cheat Sheets... list. A category for the cheat sheet can also be defined if you want to place several cheat sheets into a logical grouping. If no category is specified, the cheat sheet will appear in the Other category.

Cheat sheet dialog

Cheat sheet items

The real work for cheat sheets is done in the content file. The content file is an XML file whose name and location are specified in the contentFile attribute. The path for the file is relative to the plug-in's directory. (Note the use of the $nl$ variable in the directory name, which means the file will be located in a directory specific to the national language of the target environment.)

The file format itself includes overview information about the cheat sheet followed by a description of each step (called an item) that the user will perform. At its simplest, an item is just a detailed description of the step that the user should take. However, an item can also specify an action that can be run to perform the step on behalf of the user. Let's look at the first part of the content file (HelloWorld.xml) for the Java cheat sheet.

<?xml version="1.0" encoding="UTF-8" ?> 
<cheatsheet title="Simple Java Application">
	<intro 
		href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm">
		<description>
Welcome to the Hello, World Java tutorial.
It will help you build the famous "hello world" application and try it out. You will create a java project, and a java class that will print "hello world" in the console when run.
Let's get started!
		</description>
</intro>
	<item
		href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm"
		title="Open the Java Perspective">
		<action
			pluginId="org.eclipse.ui.cheatsheets"
			class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective"
			param1="org.eclipse.jdt.ui.JavaPerspective"/>
		<description>
Select Window->Open Perspective->Java in the menu bar at the top of the workbench.
This step changes the perspective to set up the Eclipse workbench for Java development.
You can click the "Click to Perform" button to have the "Java" perspective opened automatically.
		</description>
</item>
...

Simple java cheat sheet

The title and intro information are shown at the top of the cheat sheet. Then, the items are described. The first item for this cheat sheet describes how to open the Java perspective. Better still, the action attribute specifies a class that can be used to run the action on behalf of the user. The class must implement IAction. This is rather convenient, as it allows you to reuse the action classes written for menu or toolbar contributions.

The class for the action can optionally implement ICheatSheetAction if the action uses parameters or needs to be aware of the cheat sheet and its state. In this case, the action will be passed an array of parameters and a reference to the ICheatSheetManager so that it can request additional information about the cheat sheet. Any necessary parameters can be passed to the action's run method using the paramN attributes.

It is strongly recommended that actions invoked from cheat sheets report a success/fail outcome if running the action might fail. (For example, the user might cancel the action from its dialog.) See IAction.notifyResult(boolean) for more detail.

Items do not have to define actions. If your item must be performed manually by the user, you need not specify an action at all. Below is the third step of the Java cheat sheet, which merely tells the user how to code the simple application. When no action is specified, the item description must instruct the user to press the appropriate button after the task has been completed.

<item
	href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm"
	title="Add a System.out.println line in your main method">
	<description>
Now that you have your HelloWorld class,
In the "public static void main" method, add the following statement:  System.out.println("Hello world!"); and save your changes.  Press the "click when done" button below when finished.
	</description>
</item>

Additional attributes control whether the item can be skipped completely and what document should be launched if the user requests help during the step. See the org.eclipse.ui.cheatsheets.cheatSheetContent extension point documentation for a description of all of the attributes that can be defined inside a cheat sheet.

Subitems

Subitems may be defined to further organize the presentation of an item. Unlike items, subitems do not have to be visited in any particular order. Subitems may also define actions that automatically perform the subtask for the user. Subitem actions are described in the same way as item actions.

Conditional expressions and cheat sheet variables

Conditional expressions can be used to define cheat sheet elements whose content or behavior depends upon a particular condition being true. Conditions are described in the condition element of a subitem using arbitrary string values that are matched against the when attribute for each choice. Conditions typically reference cheat sheet variables using the form ${var}, where var refers to the name of a cheet sheet variable. A few simple examples will help demonstrate how conditional expressions work.

Conditional subitems can be used to chose one subitem from a list of possible subitems. Only the first subitem whose when attribute matches the condition attribute is included in the cheat sheet. For example:

<item ...>
	<conditional-subitem condition="${v1}">
		<subitem when="a" label="Step for A." />
		<subitem when="b" label="Step for B." />
	</conditional-subitem>
</item>

This item specifies two possible subitems that depend on the value of the variable v1. If the variable value is a, then the first subitem will be included. If the variable value is b, then the second subitem will be included. If the variable is neither value, it is considered an error.

Conditional actions are similar to conditional subitems. The perform-when element specifies a condition for performing one action among a list of possible actions. The condition is described the same way, using an arbitrary string that often references a variable. The action whose when attribute matches the condition is the one that will be performed. For example:

<item ...>
	<perform-when condition="${v1}">
		<action when="a" class="com.example.actionA" pluginId-"com.example" />
		<action when="b" class="com.example.actionB" pluginId-"com.example" />
	</perform-when>
</item>

The action to be performed is chosen based on the value of the v1 variable. If the variable value is neither a or b, it is considered an error.

Repeated subitems

Repeated subitems describe a subitem that can can expand into 0, 1, or more similar substeps. The substeps are individualized using the special variable ${this}. This variable will be replaced by the values specified in the values attribute. The values attribute is a string of values that are separated by commas. A variable that expands into a list of values may be used in the values attribute. For example:

<item ...>
	<repeated-subitem values="${v1}">
		<subitem label="Step ${this}" />
	</repeated-subitem>
</item>

If the value of the variable is 1,b,three, then three subitems will appear in the cheat sheet, each having a unique label ("Step 1," "Step b," "Step three"). The variable can be used in the label or the action paramater value. It can also be accessed from the ICheatSheetManager while the action is executing.

Cheat sheet listeners

In some cases, you may want to change other parts of your UI if a cheat sheet is active. For example, you may have an editor that shows special annotations if a cheat sheet is guiding the user through an editing task. In this case, a listener can be specified as an attribute of the cheatsheet. The listener attribute must be the fully qualified name of a Java class that subclasses CheatSheetListener. Listeners will receive notifications along with an ICheatSheetEvent when there is a change in the cheat sheet's life cycle, such as when it opens, closes, or completes.

Contributing attributes to an existing cheat sheet

The org.eclipse.ui.cheatsheets.cheatSheetItemExtension extension can be used to contribute arbitrary attributes to a pre-existing cheat sheet. The purpose of this extension point is to allow a plug-in to add additional buttons that will aid the user for a given step. These additional buttons are displayed beside the help icon.

To use this mechanism, you can define any arbitrary attribute inside an item definition in the cheat sheet XML file. The attribute name will be matched against any attributes contributed in extensions to org.eclipse.ui.cheatsheets.cheatSheetItemExtension. See the extension point documentation for more detail.