Composite cheat sheets

Composite Cheat Sheets

Composite cheat sheets provide guidance through complex problems by breaking the problem into a set of smaller tasks. Composite cheat sheets are registered using the the org.eclipse.ui.cheatsheets.cheatSheetContent extension point.

Content File Format

The composite cheat sheet content itself is defined in a separate file which conforms to the composite cheat sheet content file specification. The content file is an XML file and consists of a set of tasks organized in groups into a tree structure.

<compositeCheatsheet> is the root element of a composite cheat sheet. It will have a single root task which may be a <task> or <taskGroup>. <taskGroup> elements may have one or more children each of which can be a <task> or <taskGroup>. A <task> does not have child tasks.

Tasks and task groups may contain <intro> elements which contain the text to be displayed before the task has been started and <onCompletion> elements which contain the text to be displayed once the task is completed. Both the <intro> and <onCompletion> elements may contain form text markup, in the example below the tags <b> and </b> are used to make text bold.

Tasks may also contain <param> elements. A cheat sheet task may have any of the following parameters: "id" is the id of a registered cheatsheet, "path" is the relative path or URL of the cheat sheet content file and "skipIntro" is a boolean parameter which if true causes the cheat sheet to start at the first step rather than at the introduction. Either "id" or "path" but not both must be specified.

A <dependency> node from task "B" to task "A" represents a requirement that task A is completed before task B can be started.

Cheat Sheet Task Parameters

If a task has kind = "cheatsheet" a cheat sheet will be opened when that task is started, There are three possible parameters to a cheat sheet task.

Parameter name	Description
id	The id of a cheat sheet which has been registered using the extension point org.eclipse.ui.cheatsheets.cheatSheetContent. This identifies the cheatsheet which will be associated with this task. Either the id or the path parameter (but not both) should be specified.
path	The URL of a cheat sheet content file. This may be an absolute URL, or relative to the content file for the composite cheat sheet. If both id and path are specified the path will be used to locate the content file and the id parameter will be ignored.
showIntro	A boolean parameter with default value of true. If "false" the cheat sheet when started will initially show the first step rather than the introduction..

Example of a Composite Cheat Sheet

The file below is an example of how to create a composite cheat sheet from existing cheat sheets. It shows how to create task groups and make tasks skippable.

<?xml version="1.0" encoding="UTF-8"?>
<compositeCheatsheet name="Composite cheat sheet example">
    <taskGroup name= "Composite cheat sheet example">
         <intro> This is an example of a <b>composite cheat sheet</b> built from existing cheat sheets.
                 <br/><br/>You can select a task to work on either by following the hyperlinks or by
                 selecting a task in the tree. 
         </intro>  
         <onCompletion>Congratulations you have completed all the tasks.</onCompletion>             
         <task kind="cheatsheet" name= "Branching and merging using CVS" skip="true">

              <param name = "id" value = "org.eclipse.platform.cvs_1" />
              <intro>This cheat sheet is intended for CVS users. If you are not using CVS or do
              not intend to branch and merge you may skip this task.
              </intro>
               <onCompletion>Congratulations you now know how to branch and merge.</onCompletion>                  
         </task>
         <taskGroup name= "Create Java Projects" kind = "sequence">

             <intro> First you will learn how to create a simple java project, then you will create 
             an java project which uses SWT. 
             <br/><br/>This task group is a sequence which means that
             if you click on the subtask "Standalone SWT Application" it will not let that task be started 
             until "Create a java project" has been completed.
             </intro>
              <onCompletion>Congratulations you have built both Java applications.</onCompletion>
             <task kind="cheatsheet" name= "Create a java project" id = "createJavaProject">

                 <param name="id" value = "org.eclipse.jdt.helloworld"/>
                 <param name="showIntro" value = "false"/>
                 <intro>This cheat sheet walks through the process of creating a simple hello world application. 
                        The cheat sheet can launch wizards to create a new project and a new class. 
                 </intro>
                 <onCompletion>Congratulations you have succeeded in creating a hello world application</onCompletion>
             </task>

             <task kind="cheatsheet" name= "Standalone SWT Application">
                 <intro>Eclipse plugins which contribute to the user interface use The Standard Widget Toolkit (SWT). 
                    This task guide can be used to learn more about SWT. 
                 </intro>
                 <param name = "id" value = "org.eclipse.jdt.helloworld.swt" />
                  <onCompletion>Congratulations you have succeeded in creating an SWT application.</onCompletion>           
             </task>      
         </taskGroup>

    </taskGroup>
</compositeCheatsheet>

Composite Cheat Sheet Extensibility - Provisional in Eclipse 3.2

Composite cheat sheets are extensible, however in Eclipse 3.2 this extensibility is provisional and the classes could change before they become API. Composite cheat sheet support can be extended by using the extension point org.eclipse.ui.cheatsheets.cheatSheetContent which has two new elements taskEditor and taskExplorer which allow for contribution of task editors and task explorers.

Contributing a task editor defines a new kind of task which displays in the task detail section. To contribute a task editor implement a concrete subclass of TaskEditor, then add a taskEditor element to plugin.xml.

The representation of the task explorer is also configurable with an extension point, a tree explorer is included with the Eclipse platform. By default the explorer for a composite cheat sheet when first opened is a tree, an attribute on the <compositeCheatSheet> element will allow that default to be overridden. If more than one explorer is registered the view menu will contain a menu item to switch between explorers. To contribute a task explorer first implement a concrete subclass of TaskExplorer, then add a taskExplorer element to plugin.xml.