Cheat Sheet Content File XML Format

Identifier:
org.eclipse.ui.cheatsheets.cheat_sheet_schema

Since:
3.2

Description:

This document describes the cheat sheet content file structure as a series of DTD fragments (machine readable XML schema).

A cheat sheet consists of a series of items (steps) which must be completed in order. Items can be divided into subitems and can launch commands or actions which will perform some of the steps for the user.

Configuration Markup:

<!ELEMENT cheatsheet (intro , item+)>

<!ATTLIST cheatsheet

title CDATA #REQUIRED

>

The root element of a cheatsheet.



<!ELEMENT intro (description)>

<!ATTLIST intro

contextId CDATA #IMPLIED

href      CDATA #IMPLIED

>

The <intro> element is used to define the introductory text to be displayed when the cheat sheet is opened.



<!ELEMENT description (#PCDATA)>

The <description> element holds the description of a cheat sheet or of a cheat sheet item. The description consists of text interspersed with form text markup. The cheat sheet automatically formats and lays out the text to make it show up reasonably in the UI. Hyperlinks are expressed using <a href="URL">text<a>, where URL is a valid URL to an external web site or a CheatSheet URL that represents a CheatSheat action. All cheat sheet URLs have the following form: http://org.eclipse.ui.cheatsheet/<action name>?param1=value1&param2=value2 and will be processed by the cheat sheet framework.
The following predefined actions are included in the cheat sheet framework:

showView - activates view with given view id
id - a view id

execute - executes the specified command. See the serialize() method on org.eclipse.core.command.ParameterizedCommand for details of the command serialization format. Since 3.2.
command - a serialized ParameterizedCommand

Within the text, balanced <b>...</b> tags cause the enclosed text to be rendered in a bold font, and the <br/> element can be used to force a line break. These are the only formatting tags supported at this time (however, others may be added in the future). Certain characters in the text have special significance for XML parsers; in particular, to write "<", ">", "&", "'", and """ (quotation mark) instead write "&lt;", "&gt;", "&amp;", "&apos;", and "&quot;" respectively. Whitespace (spaces and line breaks) is treated as a word separator; adjacent spaces and line breaks are treated as single unit and rendered as a single space or a line break. Whitespace immediately after the <description> and <br/> tags is ignored, as is whitespace immediately before the </description> tag.



<!ELEMENT item (description , (action | command | perform-when | (subitem | conditional-subitem | repeated-subitem)*) , onCompletion?)>

<!ATTLIST item

title     CDATA #REQUIRED

dialog    (true | false) "false"

skip      (true | false) "false"

contextId CDATA #IMPLIED

href      CDATA #IMPLIED

>

Each <item> element describes one top-level step in a cheat sheet. An <item> may contain <subitem> elements.

The org.eclipse.ui.cheatsheets.cheatSheetItemExtension allows additional custom controls for the item to be displayed in the UI. Contributions to this extension point declare the names of additional, string-valued attributes that may appear on <item> elements.

Simple items have a description and an optional action or command. In the typical presentation, the titles of cheat sheet items are shown to the user most of the time. An item's description is only shown while the step is in the process of being executed. The presence of an <action>, <command> or <perform-when>)element is associated with a button that the user can press to perform the step's action or command. If no action or command is present, the step is one that the user must carry out manually and then overtly indicate that they have successfully completed the step.

Steps may be broken down into sub-steps as specified by the <subitem> subelements. Unlike items, which the user must follow in strict sequence, the sub-items of a given item can be performed in any order. All sub-items within an item have to be attempted (or skipped) before progressing to the next item. (Which means actions that must be performed in a required sequence cannot be represented as sub-items.)

A <conditional-subitem> subelement allow a step to tailor the presentation of a sub-step based on cheat sheet variables whose values are acquired in earlier steps. A <repeated-subitem> subelement allows a step to include a set of similar sub-steps. Again, the exact set of sub-steps may be based on cheat sheet variables whose value are acquired in earlier steps.



<!ELEMENT subitem (description? , (action | command | perform-when)?)>

<!ATTLIST subitem

label CDATA #REQUIRED

skip  (true | false) "false"

when  CDATA #IMPLIED

>

Each <subitem> element describes a sub-step in a cheat sheet. A <subitem> carries a simple text label, but has neither a lengthy description nor further sub-items.

Sub-items may have an optional action or command. The presence of an <action>, <command> or <perform-when> element is associated with a button that the user can press to perform the sub-step's action or command. If no action or command is present, the sub-step is one that the user must carry out manually and then overtly indicate that they have successfully completed the step.

Unlike items, which must be followed in strict sequence, the sub-items of a given item can be performed in any order. All sub-items within an item have to be completed or skipped before progressing to the next item. (Which means actions that must be performed in a required sequence should not be represented as sub-items.)

Since version 3.4 a description has been allowed in a subitem in place of the label attribute, which allows for formatting tags to be used.



<!ELEMENT conditional-subitem (subitem+)>

<!ATTLIST conditional-subitem

condition CDATA #REQUIRED

>

Each <conditional-subitem> element describes a single sub-step whose form can differ based on a condition known at the time the item is expanded.

The condition attribute on the <conditional-subitem> element provides a string value (invariably this value comes from a cheat sheet variable). Each of the <subitem> children must carry a when attribute with a distinct string value. When the item is expanded, the <conditional-subitem> element is replaced by the <subitem> element with the matching value. It is considered an error if there is no <subitem> element with a matching value.

For example, if the cheat sheet variable named "v1" has the value "b" when the following item is expanded

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
  </conditional-subitem>
</item>
then the second sub-item is selected and the item expands to something equivalent to
<item ...> 
  <subitem label="Step for B."/>
</item>


<!ELEMENT repeated-subitem (subitem)>

<!ATTLIST repeated-subitem

values CDATA #REQUIRED

>

Each <repeated-subitem> element describes a sub-item that expands into 0, 1, or more similar sub-steps.

The values attribute provides a list of comma-separated strings; the <subitem> child provide the template. When the item is expanded, the <repeated-subitem> element is replaced by copies of the <subitem> element with occurrences of the variable "this" replaced by the corresponding string value.

For example, if the cheat sheet variable named "v1" has the value "1,b,three" when the following item is expanded

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
     </subitem>
  </repeated-subitem>
</item>
then the item expands to something equivalent to:
<item ...> 
  <subitem label="Step 1.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/>
  </subitem>
  <subitem label="Step b.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/>
  </subitem>
  <subitem label="Step three.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="three"/>
  </subitem>
</item>


<!ELEMENT action EMPTY>

<!ATTLIST action

class     CDATA #REQUIRED

pluginId  CDATA #REQUIRED

paramN    CDATA #IMPLIED

confirm   (true | false) "false"

when      CDATA #IMPLIED

required  (true | false) "true"

translate CDATA #IMPLIED

>

Each <action> element describes an action in a cheat sheet.



<!ELEMENT command EMPTY>

<!ATTLIST command

serialization CDATA #REQUIRED

returns       CDATA #IMPLIED

confirm       (true | false) "false"

when          CDATA #IMPLIED

required      (true | false) "true"

translate     CDATA #IMPLIED

>

Each <command> element describes an command in a cheat sheet.

Below is an example of an item with a command which opens a dialog box and stores the result in the cheat sheet variable "result".

<item title="View Selection">
     <description>Select a view which will be opened in the next step.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/>  
      <onCompletion> Selected the ${result}. </onCompletion>
</item>


<!ELEMENT onCompletion (#PCDATA)>

Contains text which will be displayed when an item is completed. This is particularly useful in the final step of the cheat sheet to acknowledge completion of the entire task. The description consists of text interspersed with form text markup following the same rules as for a <description> element. <onCompletion> elements may also contain references to cheat sheet variables of the form  "${var}", which will be expanded using the actual value of the cheat sheet variable var at the time this step was completed.



<!ELEMENT perform-when (action | command)+>

<!ATTLIST perform-when

condition CDATA #REQUIRED

>

Each <perform-when> element describes an action in a cheat sheet.

The condition attribute on the <conditional-subitem> element provides a string value (invariably this value comes from a cheat sheet variable). Each of the <subitem> children must carry a when attribute with a distinct string value. When the item is expanded, the <conditional-subitem> element is replaced by the <subitem> element with the matching value. It is considered an error if there is no <subitem> element with a matching value.

For example, if the cheat sheet variable named "v1" has the value "b" when the following item is expanded

<item ...>
  <subitem label="Main 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" />
        <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/>
     </perform-when>
  </subitem>
</item>
then the second action is selected and the item expands to something equivalent to
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>


Examples:

The following is an example of a simple cheat sheet content file which demonstrates the use of commands, perform-when and conditional subitems.

 
<?xml version="1.0" encoding="UTF-8"?> 
<cheatsheet title="Sample Cheat Sheet">
  <intro>
    <description>A cheat sheet which demonstrates the use of perform-when and conditional subitems</description>
  </intro>
  <item title="View Selection">
     <description>Select a view which will be opened in the following steps.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/>  
      <onCompletion> Selected the ${result}. </onCompletion>
  </item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
  </item>
  <item title="Open the view from a perform when item" skip = "true">
     <description>Uses perform when to open the view seleted previously.</description> 
     <perform-when condition = "${result}">
           <command when = "Package Explorer" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
           <command when = "Search View" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>      
     </perform-when>
  </item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
  </item>
  <item title="Open the view from a perform when subitem">
     <description>Uses perform when to open the view seleted previously.</description> 
     <subitem label="Perform when subitem" skip = "true">
     <perform-when condition = "${result}">
           <command when = "Package Explorer" 
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "Search View" 
            serialization="org.eclipse.search.ui.views.SearchView"/>      
     </perform-when>
     </subitem>
  </item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
  </item>
  <item title="Open the view from a conditional subitem">
     <description>Uses perform when to open the view seleted previously.</description> 
      <conditional-subitem condition="${result}">
         <subitem when="Package Explorer" label="Open package explorer.">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
         </subitem>
         <subitem when="Search View" label="Open Search View">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
         </subitem>
     </conditional-subitem>
  </item>
</cheatsheet>


Copyright (c) 2004, 2007 IBM Corporation and others.
This program and the accompanying materials are made available under the terms of the Eclipse Public License 2.0 which accompanies this distribution, and is available at https://www.eclipse.org/legal/epl-2.0/ SPDX-License-Identifier: EPL-2.0