Cheat Sheet Content File XML Format

Version 3.0

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

 

cheatsheet

<!ELEMENT cheatsheet (intro, item+)> 
<!ATTLIST cheatsheet 
  title               CDATA #REQUIRED
>

The <cheatsheet> element defines the body of the cheat sheet content file. <cheatsheet> attributes are as follows:

 

intro

<!ELEMENT intro (description)>
<!ATTLIST intro 
  contextId           CDATA #IMPLIED 
  href                CDATA #IMPLIED 
>

The <intro> element is used to describe the cheat sheet introduction to be displayed. The <description> subelement contains the body of the introduction. <intro> attributes are as follows:

 

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

The <description> element holds the description of a cheat sheet or of a cheat sheet item. The description consists of text interspersed with simple formatting tags. The cheat sheet automatically formats and lays out the text to make it show up reasonably in the UI. 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.

 

item

<!ELEMENT item (description ([action|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> 
<!ATTLIST item 
  title               CDATA #REQUIRED
  skip                ("true" | "false") "false"
  contextId           CDATA #IMPLIED 
  href                CDATA #IMPLIED
>

Each <item> element describes one top-level step in a cheat sheet. The <item> is either simple or composite. <item> attributes are as follows:

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. 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> (or <perform-when>) element is typically associated with a button that the user can press to perform the step's action. If no action is present, the step is one that the user must carry out manually and then overtly indicate that they have successfully completed the step.

Composite steps are 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.

 

subitem

<!ELEMENT subitem ( [action|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. <subitem> attributes are as follows:

Sub-items have an optional action. The presence of an <action> (or <perform-when>) element is typically associated with a button that the user can press to perform the sub-step's action. If no action 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 attempted (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.)

 

conditional-subitem

<!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. <conditional-subitem> attributes are as follows:

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>

 

repeated-subitem

<!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. <repeated-subitem> attributes are as follows:

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>

 

action

<!ELEMENT action EMPTY> 
<!ATTLIST action 
  class               CDATA #REQUIRED
  pluginId            CDATA #REQUIRED
  param1              CDATA #IMPLIED
  ...
  param9              CDATA #IMPLIED
  confirm             ("true" | "false") "false"
  when                CDATA #IMPLIED
>

Each <action> element describes an action in a cheat sheet. <action> attributes are as follows:

 

perform-when

<!ELEMENT perform-when (action+)> 
<!ATTLIST perform-when 
  condition               CDATA #REQUIRED
>

Each <perform-when> element describes an action in a cheat sheet. <perform-when> attributes are as follows:

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" />
     </conditional-subitem>
  </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>

 

Example

The following is an example of a very simple cheat sheet content file:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Example">
  <intro>
    <description>Example cheat sheet with two steps.</description>
  </intro>
  <item title="Step 1">
     <description>This is a step with an action.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
  </item>
  <item title="Step 2">
     <description>This is a fully manual step.</description>
  </item>
</cheatsheet>