备忘单内容文件 XML 格式

版本 3.0

本文档将备忘单内容文件结构描述为一系列 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> 元素容纳备忘单或备忘单项的描述。该描述由插入了简单格式化标记的文本组成。备忘单自动格式化文本并对其进行布局以使其在用户界面中显示时更为合理。在文本中,平衡的 <b>...</b> 标记导致封闭的文本以粗体字体呈现,而 <br/> 元素可用来强制换行。这些是此时支持的唯一格式化标记(但是,未来可能会添加其它格式化标记)。文本中的某些字符对 XML 解析器具有特殊意义;特别是要分别写为“<”、“>”、“&”和“'”(引号)而不是写为 “&lt;”、“&gt;”、“&amp;”、“&apos;”和“&quot;”。空格(空格和换行符)被视作字分隔符;相邻空格和换行符被视作单个单元且呈现为单个空格或换行符。紧跟在 <description> 和 <br/> 标记之后的空格会被忽略,紧跟在 </description> 标记之前的空格也一样。

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
>

每个 <item> 元素描述备忘单中的一个顶级步骤。<item> 为单一或组合体。<item> 属性如下所示:

org.eclipse.ui.cheatsheets.cheatSheetItemExtension 允许对要显示在用户界面中的项进行附加定制控制。此扩展点的添加项声明附加字符串值的属性的名称,这些属性可能会出现在 <item> 元素上。

简单项具有描述和可选操作。在典型表示中,大部分时间会对用户显示备忘单项的标题。仅当步骤正在执行时,才会显示项的描述。<action>(或 <perform-when>)元素的存在通常与某个按钮相关联,用户可按下该按钮来执行该步骤的操作。如果不存在任何操作,用户必须手工执行该步骤并公共指示他们已经成功完成该步骤。

组合步骤被分为若干子步骤,就象 <subitem> 子元素指定的那样。与项不同,用户必须严格遵循项的顺序,而给定项的子项可以任意顺序执行。在进至下一项之前,必须先尝试(或跳过)该项的所有子项。(这表示必须按必需顺序执行的操作不能被表示为子项)。

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

subitem

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

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

子项具有可选操作。<action>(或 <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> 元素会替换为带有被对应字符串值的变量 "this" 的 <subitem> 元素。

例如,如果名为“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> 属性如下所示:

perform-when

<!ELEMENT perform-when (action+)> 
<!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" />
     </conditional-subitem>
  </subitem>
</item>
于是第二个操作被选中而该项展开为与以下等效的内容:
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

示例

以下是非常简单的备忘单内容文件的示例:

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