15.5. Cheat Sheets

In addition to the static help provided through the Eclipse Help system and the context-sensitive help provided through the dynamic Help view and infopop windows, Eclipse includes cheat sheets that are designed to walk you through a series of steps to complete a task and automatically launch any required tools.

15.5.1. Using a cheat sheet

Users can access your product's cheat sheets via the Help > Cheat Sheets... menu (see Figure 15-21).

This will open the Eclipse Cheat Sheet Selection dialog (see Figure 15-22). Available cheat sheets are grouped by category. Double-click on a cheat sheet or select one and click the OK button.

The selected cheat sheet will open as a view (see Figure 15-23). Only one cheat sheet can be active at one time, so any currently open cheat sheet will be closed first. Every cheat sheet starts with an introduction followed by a set of steps. After reading the introduction, you can begin working with the cheat sheet by clicking on the Click to Begin button. This will expand and highlight the next step. Use the Click to Perform button to execute the task associated with that step. Once completed, the next task in the sequence will be highlighted. If a step is optional, you may also skip it with the Click to Skip button. After the last step in the cheat sheet is completed, it will automatically restart.

15.5.2. Creating a simple cheat sheet

Creating a cheat sheet requires several steps. Start by opening the plugin.xml file in the help project and switching to the Extensions page. Next, click the Add... button. When the New Extension wizard opens, uncheck the Show only extension points from the required plug-ins checkbox and select org.eclipse.ui.cheatsheets.cheatSheetContent from the list of all available extension points (see Figure 15-24). Click the Finish button to add this extension to the plug-in manifest. Answer Yes when asked whether to add a dependency on the org.eclipse.ui.cheatsheets plug-in.

Every cheat sheet must exist in a category, so create one before creating the cheat sheet itself. In the Extensions page of the plug-in manifest editor, right-click on the org.eclipse.ui.cheatsheets.cheatSheetContent extension and select New > category. This adds a category to the manifest. Clicking on this new category item reveals the properties so that they can be modified as follows (see Figure 15-25).

id "com.qualityeclipse.favorites.cheatSheets"

The id of the cheat sheet category.

name "Favorites"

The name of the cheat sheet category.

After creating the category, you can create the cheat sheet itself. Right-click on the org.eclipse.ui.cheatsheets.cheatSheetContent extension and select New > cheatsheet to add it to the manifest. Clicking on this new cheat sheet item reveals the properties so that they can be modified as follows (see Figure 15-26).

id "com.qualityeclipse.favorites.cheatsheet"

The id of the cheat sheet.

name "Adding a favorite to the Favorites view"

The name of the cheat sheet.

category "com.qualityeclipse.favorites.cheatSheets"

The category in which to place the cheat sheet.

contentFile "cheatsheets/FavoritesCheatSheet.xml"

The path of the cheat sheet content file.

If you switch to the plugin.xml page of the plug-in manifest editor, you will see the following new section of XML defining the new cheat sheet and category:

<extension
   point="org.eclipse.ui.cheatsheets.cheatSheetContent">
   <category
      id="com.qualityeclipse.favorites.cheatSheets"
      name="Favorites"/>
   <cheatsheet
      category="com.qualityeclipse.favorites.cheatSheets"
      contentFile="cheatsheets/FavoritesCheatSheet.xml"
      id="com.qualityeclipse.favorites.cheatsheet"
      name="Adding a favorite to the Favorites view"/>
</extension>

After creating the cheat sheet, you should add a brief description that will be displayed in the Cheat Sheet Selection dialog. Add the following to the <cheatsheet> section of the above XML.

<description>
   This cheat sheet will show you how to add
   an item to the Favorites view.
</description>

The final step is to create the cheat sheet content file. Use the File > New > File command and enter "cheatsheets/FavoritesCheatSheet.xml" to create a blank content file. At a minimum, cheat sheets must have an introduction and at least one cheat sheet item, so enter the following into the FavoritesCheatSheet.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Adding a favorite to the Favorites view">
   <intro>
      <description>
         This cheat sheet will show you how to add an item
         to the Favorites view.
      </description>
   </intro>
   <item title="Select a file">
      <description>
         Select the file that should be a favorite.
      </description>
   </item>
</cheatsheet>

Now that you have completed the definition of the cheat sheet, test it by lauching the Runtime Workbench, opening the Cheat Sheet Selection dialog (see Figure 15-27), selecting the Favorites > Adding a favorite to the Favorites view item, and then clicking OK.

The new Favorites cheat sheet will appear in a new view with its introduction initially expanded (see Figure 15-28).

15.5.3. Adding cheat sheet actions

At this point, the cheat sheet is completely static without any interactive elements. Cheat sheets can have active content defined by Eclipse actions. Once the user has selected a file during the first step in the cheat sheet, it would be nice to add a second step that would add that file to the Favorites view.

The main plug-in already has an AddToFavoritesActionDelegate class defined (see Section 6.3.3, IObjectActionDelegate, on page 233), which you can use to derive an AddToFavoritesAction class that looks like this:

package com.qualityeclipse.favorites.actions;

import ...

public class AddToFavoritesAction extends Action {

   public void run() {
      ISelection selection = PlatformUI
         .getWorkbench()
         .getActiveWorkbenchWindow()
         .getActivePage()
         .getSelection(JavaUI.ID_PACKAGES);

       if (selection instanceof IStructuredSelection) {
          FavoritesManager mgr = FavoritesManager.getManager();
          Iterator iter =
             ((IStructuredSelection) selection).iterator();
           mgr.addFavorites(mgr.newFavoritesFor(iter));
      }
   }
}

Note that the above AddToFavoritesAction class is rather simple in that it assumes a selection in the Java Packages view. It could be improved by allowing a selection in any view but will suffice for the purposes here.

Next, you need to add a new item to the cheat sheet definition, so add the following into the FavoritesCheatSheet.xml file.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Adding a favorite to the Favorites view">
   ...
   <item
      href="/com.qualityeclipse.favorites.help
            /html/gettingstarted/adding_favorites.html"
      title="Select the Favorites > Add command">
      <action
         pluginId="com.qualityeclipse.favorites"
         class="com.qualityeclipse.favorites.actions.
                AddToFavoritesAction"/>
      <description>
         Select the Favorites > Add command.
      </description>
   </item>
   ...
</cheatsheet>

The href tag is optional and used to link a help page with the cheat sheet task. The link needs to be fully qualified with the name of the plug-in containing the help page, followed by the plug-in relative path to the help page. Even if the help page is in the same plug-in as the cheat sheet, the link must be fully qualified.

The action element describes what action will be invoked by the cheat sheet task. The pluginId attribute contains the ID of the plug-in containing the action class (the main plug-in in this case). The class attribute specifies the fully qualified name of the action class. Any simple action that implements IAction can be used here. For more complex actions that require additional parameters or state information from the cheat sheet itself, you can subclass the org.eclipse.ui.cheatsheets.ICheatSheetAction class instead.

Now that you have added a second step to the cheat sheet, you can test it as done earlier. After completing the first step of selecting a file, the second step will appear (see Figure 15-29). Use the Click to Perform button to execute the task and add the selected file to the Favorites view. Clicking on the Open Related Help button will open the help page associated with adding an item to the Favorites view.