虎の巻コンテンツ・ファイル 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;」を使用します。空白文字 (スペースおよび改行) は語のセパレーターとして扱われます。また、隣接するスペースおよび改行は、単一ユニットとして扱われ、1 つのスペースまたは 1 つの改行として表現されます。 <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> 要素は、虎の巻内の 1 つのトップレベル・ステップを記述します。<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>
このとき、2 番目のサブ項目が選択され、項目は以下と同等のものに展開されます。
<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> の属性は以下のとおりです。

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>次のステップで開かれるビューを選択します。</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>
このとき、2 番目のアクションが選択され、項目は以下と同等のものに展開されます。
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

以下に、コマンド perform-when および条件付きサブ項目の使用を示す単純な虎の巻コンテンツ・ファイルの例を示します。

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Sample Cheat Sheet">
  <intro>
    <description> perform-when および条件付きサブ項目の使用を示す虎の巻</description>
  </intro>
<item title="View Selection">
     <description>以下のステップで、開かれるビューを選択します。</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>開いた場合、「検索」ビューとパッケージ・エクスプローラーを閉じます。</description>
</item>
  <item title="Open the view from a perform when item" skip = "true">
     <description>perform when を使用して、前に選択したビューを開きます。</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>開いた場合、「検索」ビューとパッケージ・エクスプローラーを閉じます。</description>
</item>
  <item title="Open the view from a perform when subitem">
     <description>perform when を使用して、前に選択したビューを開きます。</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>開いた場合、「検索」ビューとパッケージ・エクスプローラーを閉じます。</description>
</item>
  <item title="Open the view from a conditional subitem">
     <description>perform when を使用して、前に選択したビューを開きます。</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>