Based on the great response we have had to our previous cheat sheets articles, (why they rock and tips and tricks), I have decided to post a more in depth tutorial. One of the many benefits of Cheat sheets is that they provide an immediate improvement to your product’s usability and are simple to implement. This article will allow you to quickly create multiple cheat sheets.

To help get you started we have created a cheat sheet on cheat sheets: This cheat sheet can be opened from within eclipse and will guide you through the simple steps for setting up a cheat sheet for your own project.

To use our Cheat Sheet cheat sheet simply open Eclipse. go to ‘Help ->Cheat Sheets..’ and choose ‘Enter the URL of a cheat sheet.’ Enter the following url in the box provided:

<b>http://www.architexa.com/downloads/CheatSheetExample.xml</b>

Steps for creating a cheat sheet for an Eclipse Plugin

  1. In your project’s plugin.xml file, add the cheat sheet extension point under the Extensions tab: org.eclipse.ui.cheatsheets.cheatSheetContent

  2. You can group the cheatsheets you create into categories. These categories are what appear as the folders in Help > Cheatsheets. To create a category, right click the cheat sheet extension point and add a ‘New > category’. Give the category an id and a name. If you don’t create a category, your cheatsheets will just go into an “Other” category.

  3. Right click the extension again and choose ‘New > cheatsheet’. Again specify an id and name and also put the category that we just created.

  4. Notice you need to specify the cheatsheet’s content file. This will be an XML file of the instructions shown to the user.

Creating a cheat sheet content file

The xml structure for a cheat sheet is simple and intuitive. Knowing what you want to accomplish and what options are available to you are the most important parts. Learning by example is the simplest solution. I have compiled a list of the tags you will most commonly use and their function

An __ is one top-level step in a cheat sheet. Its title is shown all the time; the description is shown when the step is being executed. It can contain __, __, or __ elements that the user presses to perform the step’s instruction instead of doing it manually. If no action or command is present, the user is required to do it manually and then indicate they completed it by clicking a “Click when complete” button.

An item can contain __ elements, which describe a sub-step in a cheat sheet. A __ describes a sub-step that can differ based on a condition such as a value at the time the item is expanded of a variable set in an earlier step. A __ allows a step to include a set of similar sub-steps. See the list of tags below for details and other useful tags.

Cheat Sheet Tags:
  • intro: What’s shown before the task is started
  • description: block of descriptive text for an item or intro. Can include simple HTML tags
  • item: A top level step in the cheat sheet. It has a property ‘title’ which is the name of the step. It can contain the following:
    • subItem: A substep for this item. Can also contain any tag an item contains
    • description: block of descriptive text
    • command: allows you to run a command from within the cheat sheet.
    • action: allows you to run an action from within the cheat sheet.
    • perform-when: allows you to run a command or action when a certain condition is met
    • conditional-subitem: allows you to add a subitem based on the previous state of the cheat sheet
    • repeated-subitem: allows you to add multiple subitems in a variable loop

Here is an example of the common tags in action:

`




Welcome to the tutorial.  Let's get started!




Include some explanatory text here or list some instructional walkthrough steps.
1. Step 1..


2. Step 2..






More explanatory text or instructional steps here..



Open a view depending on a variable that has been set.










`

Composite cheatsheets

If you would like to have a composite cheatsheet that manages a set of related tasks, set the composite attribute to true. Composite cheatsheets have a different XML schema for their content files.

Composite Cheat Sheet Tags:
  • taskGroup: As stated, a composite cheatsheet manages a set of related tasks. A “task group” represents a collection of related tasks.
  • task: A task represents a single sub-cheatsheet that makes a section of the composite
  • onCompletion: Displayed in the completion panel, which appears once all the items in a cheatsheet are completed.
  • kind a property of task groups that specifies how the user must complete them and can be one of “set”, “sequence”, or “choice”.
    • Set: All children tasks must be completed
    • Sequence: All children tasks must be completed and in order
    • Choice: Complete when any child task is completed
  • skip: A property of tasks, if set to true the task or group of tasks can be skipped

An example of a composite cheat sheet:

`

<compositeCheatsheet
name=”Getting started with Architexa”>



Welcome!


Great! You have completed the tutorial!

<task
kind="cheatsheet" name="Using Layered Diagrams"
id="createLayeredDiagram">



This tutorial guides you through the creation of a Layered Diagram.


Finished creating a Layered Diagram.

</task>
<task .... more tasks...


</compositeCheatsheet>
`

Opening Cheat Sheets Programmatically

In many cases you may want to make your cheat sheets more accessible to the user. They can be included in wizards, help buttons/links, or anywhere else in your plugin. To launch a cheat sheet automatically create a new OpenCheatSheetAction instance with the parameter equal to the id of the desired cheat sheet as defined in the xml file. Running this action will open the cheat sheet.

More Information

For more information on these tags, additional properties, and specific information on their usage see the below references: