备忘单内容文件的 XML 格式

V3.2

本文档通过一系列 DTD 片段(机器可读 XML 模式)来描述备忘单内容文件的结构。

cheatsheet

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

<cheatsheet> 元素定义备忘单内容文件的主体。<cheatsheet> 的属性如下所示:

intro

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

<intro> 元素用来描述所要显示的备忘单简介。<description> 子元素包含简介的主体。<intro> 的属性如下所示:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

<description> 元素包含备忘单或备忘单项的描述。此描述由插入了简单格式化标记的文本组成。备忘单将自动格式化文本并对其进行布局,以使其在 UI 中以合理的方式显示。在文本中,成对的 <b>...</b> 标记导致其中的文本显示成粗体。可以使用 <br/> 元素来强制换行。目前,只支持这些格式化标记(但是,将来可能会添加其他格式化标记)。文本中的某些字符对于 XML 解析器来说具有特殊意义;尤其是,“<”、“>”、“&”、“'”和“'”(引号)应该分别写成 “&lt;”、“&gt;”、“&amp;”、“&apos;”和“&quot;”。将把空格(空格和换行符)视为单词分隔符;并且将把相邻的空格和换行符视为单个单元并显示为单个空格或换行符。将忽略紧跟在 <description> 和 <br/> 标记后面的空格,并且将忽略 </description> 标记前面的空格。

item

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

每个 <item> 元素描述备忘单中的一个顶级步骤。<item> 可以包含 <subitem> 元素。<item> 的属性如下所示:

org.eclipse.ui.cheatsheets.cheatSheetItemExtension 允许对 UI 中要显示的项进行其他定制控制。此扩展点的添加项声明了附加的字符串值属性的名称,<item> 元素可以包含这些属性。

简单项具有描述以及可选的操作或命令。在典型的展示中,大部分时间会向用户显示备忘单项的标题。仅当步骤处于执行状态时,才会显示项的描述。所指定的 <action>、<command> 或 <perform-when> 元素与某个按钮相关联,用户可通过按下该按钮来执行该步骤的操作或命令。如果不存在任何操作或命令,则用户必须手工执行该步骤并明确指示他们已成功地完成该步骤。

可以将步骤分为多个由 <subitem> 子元素指定的子步骤。与要求用户严格遵循顺序的项不同,给定项的子项可以按任意顺序执行。在转到下一个项之前,必须先尝试(或跳过)当前项的所有子项。(这表示无法将必须按固定顺序执行的操作表示为子项)。

<conditional-subitem> 子元素允许步骤根据在先前步骤中获取了值的备忘单变量来定制子步骤的表示。<repeated-subitem> 子元素允许步骤包括一组类似的子步骤。同样,子步骤的确切集合可能基于在先前步骤中获取了值的备忘单变量。

subitem

<!ELEMENT subitem ( [action|command|perform-when] )> 
<!ATTLIST subitem 
  label               CDATA #REQUIRED
  skip                ("true" | "false") "false"
  when                CDATA #IMPLIED
>

每个 <subitem> 元素描述备忘单中的一个子步骤。<subitem> 具有简单的文本标签,但没有详细的描述和进一步的子项。<subitem> 的属性如下所示:

子项可以具有可选的操作或命令。所指定的 <action>、<command> 或 <perform-when> 元素通常与某个按钮相关联,用户可通过按下该按钮来执行该子步骤的操作或命令。如果不存在任何操作或命令,则用户必须手工执行该子步骤并明确指示他们已成功地完成该步骤。

与要求严格遵循顺序的项不同,给定项的子项可以按任意顺序执行。在转到下一个项之前,必须先完成或跳过当前项的所有子项。(这表示不应该将必须按固定顺序执行的操作表示为子项)。

conditional-subitem

<!ELEMENT conditional-subitem (subitem+)> 
<!ATTLIST conditional-subitem 
  condition               CDATA #REQUIRED
>

每个 <conditional-subitem> 元素描述单个子步骤。根据展开该项时已知条件的不同,此元素的格式也会有所变化。<conditional-subitem> 的属性如下所示:

<conditional-subitem> 元素的 condition 属性提供了一个字符串值(此值总是来自备忘单变量)。每个 <subitem> 子代的 when 属性必须是不同的字符串值。展开该项时,<conditional-subitem> 元素将被具有匹配值的 <subitem> 元素替换。如果没有具有匹配值的 <subitem> 元素,就会认为有错误。

例如,展开以下项时,如果名为“v1”的备忘单变量的值为“b”:

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
  </conditional-subitem>
</item>
于是,将选择第二个子项。因此,该项将展开成等同于以下的内容:
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

<!ELEMENT repeated-subitem (subitem)> 
<!ATTLIST repeated-subitem 
  values               CDATA #REQUIRED
>

每个 <repeated-subitem> 元素都描述一个子项,该子项将展开为 0 个、1 个或更多个类似的子步骤。<repeated-subitem> 的属性如下所示:

values 属性提供用逗号分隔的字符串列表;<subitem> 子代提供模板。展开该项时,<repeated-subitem> 元素将被 <subitem> 元素的副本替换,在该副本中,变量 "this" 已被替换为相应的字符串值。

例如,展开以下项时,如果名为“v1”的备忘单变量的值为“1,b,three”:

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
     </subitem>
  </repeated-subitem>
</item>
于是,该项将展开为与以下等同的内容:
<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
>

每个 <action> 元素描述备忘单中的一个操作。<action> 的属性如下所示:

command

<!ELEMENT command EMPTY> 
<!ATTLIST command 
  serialization       CDATA #REQUIRED
  returns             CDATA #IMPLIED
  confirm             ("true" | "false") "false"
  when                CDATA #IMPLIED
>

每个 <command> 元素都描述备忘单中的一个命令。<command> 的属性如下所示:

在以下示例中,项带有一个命令,该命令打开一个对话框并将结果存储在备忘单变量“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>

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

<onCompletion> 元素包含某个项完成时将要显示的文本。在备忘单的最终步骤中,可使用此元素来确认整个任务已完成,因此它特别有用。此描述由插入了简单格式化标记的文本组成,这些标记遵循的规则与 <description> 元素相同。<onCompletion> 元素还可以包含对备忘单变量的引用(格式为“"${var}”)。当此步骤完成时,将使用备忘单变量 var 的实际值来展开此格式。

perform-when

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

每个 <perform-when> 元素描述备忘单中的一个操作。<perform-when> 的属性如下所示:

<conditional-subitem> 元素的 condition 属性提供了一个字符串值(此值总是来自备忘单变量)。每个 <subitem> 子代的 when 属性必须是不同的字符串值。展开该项时,<conditional-subitem> 元素将被具有匹配值的 <subitem> 元素替换。如果没有具有匹配值的 <subitem> 元素,就会认为有错误。

例如,展开以下项时,如果名为“v1”的备忘单变量的值为“b”:

<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"/>
     </conditional-subitem>
         </subitem>
</item>
于是,将选择第二个操作。因此,该项将展开成等同于以下的内容:
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
         </subitem>
</item>

示例

以下是一个简单备忘单内容文件的示例,它演示了如何使用 commands、perform-when 和 conditional 子项。

<?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>