提要內容檔 XML 格式

3.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 屬性。 當項目展開時,含相符的值的 <subitem> 元素會取代 <conditional-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> 子項提供範本。 當項目展開時,含有對應的字串值所取代的 "this" 變數之 <subitem> 元素的副本會取代 <repeated-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> 的屬性如下:

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 屬性。 當項目展開時,含相符的值的 <subitem> 元素會取代 <conditional-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>

範例

以下是簡式提要內容檔的範例,用來示範 command、perform-when 和 conditional-subitem 的用法。

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