Creating RCP Cheat Sheets (Eclipse 3.4 - Ganymede)

Cheat sheets guide the user through a series of steps to achieve a specific goal in the application. This is more like a hands-on tutorial and would be very useful for new users of the application. In this article, we will explore how to create cheats for your application.

Adding cheat sheet to the help menu:

1. Add org.eclipse.ui.cheatSheets as dependency for the plugin.
2. Add org.eclipse.ui.actionSets extension point
3. Under this add a new action set for cheat sheets and give it the id org.eclipse.ui.cheatsheets.actionSet
4. Create an action under the action set and give it the id org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction. Give it a menubarpath (id of the help menu\path), label and style.
   

Now when you run your plugin, you can see Help->Cheat sheets menu. When you click on it, you can see the "Cheat Sheet Selection" dialog, but the contents would be empty since we haven't added the cheat sheet content yet.

Creating Cheat Sheet:

1. Add org.eclipse.ui.cheatsheets.cheatSheetContent extension point.
2. Go to File->New->Other->User Assistance->Cheat Sheet
3. Select the folder where you want to create the cheat sheet, type in the file name and choose whether you want to create a simple or composite cheat sheet. We will create a simple cheat sheet in this article.
4. When the editor comes up, it would just have Title and Introduction. Replace the defaults with your own title and introduction.
   
5. Click on Register Cheat Sheet in the top right to register the cheat sheet before adding contents to it.
6. In Register cheat sheet dialog, set the category (Optional - but highly recommended so that they are grouped properly in the "Cheat Sheet Selection" dialog) and enter description. This basically adds your cheat sheet under the cheatSheetContent in plugin.xml.
   
7. After this you can add how many number of steps you want and each step can have many sub-steps under it.
8. Apart from the instructions, we can also add links to the help content by using Help section in the cheat sheet editor.
   
9. One of the main advantages in cheat sheet is user can either do the step manually and click on "Click when complete" or click on "Click to perform" to automatically perform the action. Click to perform can either be achieved by adding an action or by adding a command to the step.
   
10. To add the command click on Command->Browse in cheat sheet editor and select the appropriate command. If required, enter the parameter to that command.
11. We can also add an action to a step, but that is not currently supported by the cheat sheet editor. We can go directly to the xml and add the action though. An example of an action looks like this below: <action
    required="false"
    pluginId="com.xyz.myplugin"
    class="com.xyz.myplugin.actions.MyAction>
    
    Here we specify the action class and the plugin id it lives in. Required = "false" attribute displays the "Click when complete" link. If required is true, then it means user has to use the click to perform and so click when complete will not be displayed.

Advanced Options through XML:

Some of the advanced options are not available via the cheat sheet editor. We can add them directly to the XML since cheat sheet is persisted in XML anyway. Click on the source tab in cheat sheet editor to open the XML.

1. In the XML, each step is represented by an item and each sub-step is represented by a sub-item.
   
2. If a particular step involves bringing up a modal dialog, you can add dialog=true attribute in the item element in XML and that will make sure to bring the cheat sheet view along with the dialog so that cheat sheet view can be operated while in a modal dialog.
   
3. We already saw action above. An item can also have perform-when, onCompletion, conditional-subitem and repeated-subitem elements. You can guess what they are used for from the name. Sample XML for some of these are shown below:

<item ...>
  <conditional-subitem condition="${v1}">
   <subitem when="x" label="Proceed to x" />
   <subitem when="y" label="Proceed to y" />
  <conditional-subitem>
</item>

The above code picks the sub-step based on the value of variable v1.

<item ...>
  <subitem label="Sub step">
   <perform-when condition="${v1}">
     <action when="a" class="com.xyz.action1"
                         pluginId="com.xyz" />
     <action when="b" class="com.xyz.action2"
                         pluginId="com.xyz" />
   </perform-when>
  </subitem>
</item>

The above code picks the action for the sub-step based on
the value of variable v1.

Conclusion:

We saw how to add cheat sheet to the menu and contribute
cheat sheet content. We also saw how to add the content
directly through the editor or using the XML. I hope this
article helps you to create cheat sheets in your
application.

References:

1. Building Commercial-Quality Plug-ins by Eric Clayberg and Dan Rubel.
2. All the articles on cheat sheets in my delicious bookmarks:http://delicious.com/search?context=userposts&p=cheat%20sheet&lc=1&u=rajak27