A cheat sheet is an XML file that has a top-level description and a number of item elements that have a title and description. The idea is to provide a series of steps, like a bulleted list, to perform and in turn achieve a particular goal.

For example, a cheat sheet to create a Java project might start off by giving an introduction of what the cheat sheet is about with an initial step. The following can be saved in cheatsheets/javaApplication.xml:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Creating a Java application">
  <intro>
    <description>This cheat sheet shows how to create
     and run a simple Java application</description>
  </intro>
  <item title="Creating a new Java project">
    <description>Firstly, create a new Java project
     called “HelloWorld”</description>
  </item>
</cheatsheet>

The cheat sheet is then referenced from the plugin.xml file:

<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
  <cheatsheet composite="false"
   contentFile="cheatsheets/javaApplication.xml"
   id="com.packtpub.e4.advanced.doc.cheatsheet.javaApplication"
   name="Creating a Java application">
  </cheatsheet>
</extension>

Provided that the cheatsheets folder is included in the plug-in (via the build.properties), it should now be possible to open up an Eclipse instance, and navigate to Help | Cheat Sheets... to get the following dialog:

When the cheat sheet is selected, it will open on the right-hand side of the Eclipse application with a window rendered from the content, as follows:

Clicking on the Click to Begin link will open the next item in the sequence. Each item will have a Click when complete link that will allow moving on to the next step.

As well as the steps being manually listed in each of the elements, it is also possible to provide hyperlinks to execute commands in the Eclipse workbench. The commands are represented in the command serialization format, which is defined in the ParameterizedCommand class of the org.eclipse.core.commands package.

The format represents the command as a pseudo function with hard-coded arguments. The function name is the command's ID, and the parameters are specified as comma-separated key=value pairs.

For example, to open the New Java Project wizard, the command is org.eclipse.ui.newWizard. This takes a parameter of newWizardId, which provides the wizard identifier to be used—in this case, org.eclipse.jdt.ui.wizards.JavaProjectWizard. Add the following to the cheat sheet:

<item title="Creating a new Java project">
  <description>Firstly, create a new Java project called
   “<b>HelloWorld</b>”, followed by pressing
   <b>Finish</b>
  </description>
  <command serialization="org.eclipse.ui.newWizard(
    newWizardId=org.eclipse.jdt.ui.wizards.JavaProjectWizard)"/>
</item>

Not all commands or steps need to be performed. It is possible to mark an item as skippable, so that the user can elect to perform or skip the step. Without this, the user will be forced to follow each step in the sequence before they can make progress.

To recommend opening the Java Browsing perspective, the command is org.eclipse.ui.perspectives.showPerspective, and the argument is org.eclipse.ui.perspectives.showPerspective.perspectiveId with a value of org.eclipse.jdt.ui.JavaBrowsingPerspective. To make it optional, since not everyone likes the Java Browsing perspective, add the following to the cheat sheet:

<item title="Switch to the Java Browsing perspective" skip="true">
  <description>The Java Browsing perspective can be more efficient
   for navigating large projects, as it presents a logical view
   rather than a file-oriented view of the contents</description>
  <command
   serialization="org.eclipse.ui.perspectives.showPerspective(
    org.eclipse.ui.perspectives.showPerspective.perspectiveId
    =org.eclipse.jdt.ui.JavaBrowsingPerspective)"/>
</item>

To find out what the command's arguments are, go to the Plug-in Registry view (which can be opened by navigating to Window | Show View | Other … | Plug-in Development | Plug-in Registry) and search for the command ID. The commandParameter elements will be shown. These are the identifiers required to be added to the command itself:

Cheat sheets can be responsive to user input by prompting for choices during an operation. The result of the choice can be stored in a cheat sheet variable, and subsequent steps can be conditionally displayed based on the result of that choice.

The cheat sheet variable can be used during conditional command execution, allowing differing commands to be executed based on user choice. For example, to permit the user to choose either the Java Perspective or the Java Browsing Perspective, a dialog can be presented with these choices.

The org.eclipse.ui.dialogs.openMessageDialog command allows up to three buttons to be displayed to the user to perform an interactive choice. The text of the chosen button can be stored in a variable, and then subsequently used in later steps. Adding a when condition to the command and wrapping it in a perform-when block allows the value to be compared with a set of known values and the appropriate action to be taken:

<item title="Choose a perspective">
  <description>Choose your favourite perspective</description>
  <command returns="perspective"
   serialization="org.eclipse.ui.dialogs.openMessageDialog(
    title=Choose Perspective,
    message=Choose your favourite perspective,
    buttonLabel0=Java Perspective,
    buttonLabel1=Java Browsing Perspective)"/>
  <onCompletion>Your favourite perspective is the
   ${perspective}.
  </onCompletion>
</item>
<item title="Switch to the perspective" skip="true">
  <description>Switching to the appropriate perspective will
   facilitate working with Java projects.</description>
  <perform-when condition="${perspective}">
    <command when="Java Browsing Perspective"
     serialization="org.eclipse.ui.perspectives.showPerspective(
      org.eclipse.ui.perspectives.showPerspective.perspectiveId
      =org.eclipse.jdt.ui.JavaBrowsingPerspective)"/>
    <command when="Java Perspective"
     serialization="org.eclipse.ui.perspectives.showPerspective(
      org.eclipse.ui.perspectives.showPerspective.perspectiveId
      =org.eclipse.jdt.ui.JavaPerspective)"/>
  </perform-when>
</item>

Now when the cheat sheet is run, the user is asked for their preferred perspective, which is then opened. The perspective can be reused in later steps of the cheat sheet if necessary.

Note that there is an editor for help context files. As long as the XML file starts with <cheatsheet>, the file can be double-clicked and opened in a cheat sheet editor, or via the context menu by navigating to Open With | Simple Cheat Sheet Editor. This is especially useful for commands, since the commands are shown in an easy-to-select drop-down list, along with the command parameters:

A composite cheat sheet allows several cheat sheets to be collected together and presented in a single sheet. This is useful if several smaller cheat sheets have been created previously but can be presented as a unified set.

A composite cheat sheet is specified in an XML file, with a <compositeCheatsheet> root element. This contains a <taskGroup>, which has an optional <intro> description, and then one or more <task> or <taskGroup> elements.

Each task has a name and refers to a cheat sheet, either by path to a reference in the current plug-in, or by its id. The cheat sheet can have its own intro and an onCompletion message, which is shown when the cheat sheet is complete.

A simple cheat sheet collection can be represented as follows:

<compositeCheatsheet name="A collection of cheat sheets">
  <taskGroup kind="choice" skip="false"
   name="Example Cheat Sheets Collection">
    <intro><b>Overview of cheat sheets</b></intro>
    <onCompletion>
      <b>Congratulations of completing the cheat sheets</b>
    </onCompletion>
    <task kind="cheatsheet" skip="false"
     name="Example Cheat Sheet">
      <intro>The cheat sheet provided in this plug-in</intro>
      <onCompletion>
        Congratulations, you have completed the tasks
      </onCompletion>
      <param name="path" value="javaApplication.xml"/>
    </task>
  </taskGroup>
</compositeCheatsheet>

The composite cheat sheet is referenced in the plugin.xml file, with the composite="true" attribute, along with an appropriate category:

<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent">
  <category name="Example cheat sheets"
   id="com.packtpub.e4.advanced.doc.category"/>
  <cheatsheet name="Composite cheatsheets"
   contentFile="cheatsheets/composite.xml"
   id="com.packtpub.e4.advanced.doc.cheatsheet.composite"
   composite="true"/>
</extension>

When loaded in the runtime Eclipse, it will look like the following:

To refer to other cheat sheets, use the id that is defined in the extension point. For example, the standard JDT cheat sheets uses org.eclipse.jdt.helloworld and org.eclipse.jdt.helloworld.swt (that are visible from the extension point browser as well as the JDT plugin.xml file). These can be added as a task group in composite.xml:

<taskGroup kind="choice" name="JDT Cheat Sheets" skip="false">
  <intro>
    <b>Introduction</b>
    These are the cheat sheets provided by the JDT
  </intro>
  <onCompletion>
    Congratulations, you have completed the tasks
  </onCompletion>
  <task kind="cheatsheet" name="JDT Hello World" skip="false">
    <intro>Provides a simple Hello World project</intro>
    <onCompletion>Congratulations,
     you have completed the task</onCompletion>
    <param name="id" value="org.eclipse.jdt.helloworld"/>
  </task>
  <task kind="cheatsheet" name="SWT Hello World" skip="false">
    <intro>Provides a SWT hello world project</intro>
    <onCompletion>Congratulations,
     you have completed the task</onCompletion>
    <param name="id" value="org.eclipse.jdt.helloworld.swt"/>
  </task>
</taskGroup>

Now, when the composite sheet is shown, the JDT cheat sheets are shown as well: