XML formát souboru s obsahem Cheat sheet

Verze 3.2

Tento dokument popisuje strukturu souboru s obsahem Cheat sheet jako sérii DTD fragmentů (strojově čitelné schéma XML).

cheatsheet

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

Prvek <cheatsheet> definuje tělo souboru s obsahem cheat sheet. Atributy <cheatsheet> jsou následující:

intro

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

Prvek <intro> se používá k popisu úvodu Cheat sheet, který má být zobrazen. Podřízený prvek <description> obsahuje tělo úvodu. Atributy <intro> jsou následující:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

Prvek <description> obsahuje popis Cheat sheet nebo popis prvku Cheat sheet. Popis sestává z textu prokládaného jednoduchými formátovacími značkami. Cheat sheet automaticky formátuje a uspořádává text, aby se zobrazil v uživatelském rozhraní v přijatelné podobě. V rámci textu bude text ohraničený vyváženými značkami <b>...</b> zobrazen tučným písmem a prvek <br/> způsobí zalomení řádku. To jsou v současné době jediné podporované značky (v budoucnosti mohou být nicméně přidány další). Určité znaky v textu mají zvláštní význam pro analyzátory XML; zejména chcete-li napsat "<", ">", "&", "'" a """ (uvozovka), napište namísto toho "&lt;", "&gt;", "&amp;", "&apos;" a "&quot;" v uvedeném pořadí. Neviditelný znak (mezery a zalomení řádku) je považován za oddělovač slov; sousedící mezery a zalomení řádků jsou považovány za jednu jednotku a zobrazovány jako jedna mezera nebo zalomení řádku. Neviditelný znak bezprostředně po značkách <description> a <br/> je ignorován stejně jako neviditelný znak bezprostředně před značkou </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
>

Každý prvek <item> popisuje jeden krok na nejvyšší úrovni v Cheat sheet. <Položka> může obsahovat <dílčí_položky>. Atributy <item> jsou následující:

org.eclipse.ui.cheatsheets.cheatSheetItemExtension umožňuje, aby byly v uživatelském rozhraní zobrazeny další uživatelské obslužné prvky pro položku. Příspěvky do tohoto bodu rozšíření deklarují názvy dalších, na řetězci založených atributů, které se mohou objevit v prvcích <item>.

Jednoduché položky mají popis a volitelnou akci nebo příkaz. V typické prezentaci jsou uživateli zobrazovány titulky položek Cheat sheet po většinu času. Popis položky je zobrazen pouze během provádění daného kroku. Přítomnost prvku <action>, <command> nebo <perform-when>) je spojena s tlačítkem, jehož stisknutím může uživatel provést akci nebo příkaz daného kroku. Pokud není nabízena žádná akce ani příkaz, musí uživatel provést krok ručně a poté zřetelně ukázat, že byl daný krok dokončen.

Kroky se mohou dělit na dílčí kroky, jak je specifikováno dílčími prvky <subitem>. Na rozdíl od položek, u kterých musí uživatel dodržovat přesné pořadí, mohou být dílčí položky dané položky prováděny v libovolném pořadí. U všech dílčích položek v rámci položky musí být proveden pokus o jejich provedení (nebo musí být přeskočeny), než je možné přejít na další položku. (Což znamená, že akce, které musí být provedeny v požadovaném pořadí, nemohou být představovány dílčími položkami.)

Dílčí prvek <conditional-subitem> umožňuje, aby krok přizpůsobil prezentaci dílčího kroku v závislosti na proměnných Cheat sheet, jejichž hodnoty jsou získány v předchozích krocích. Dílčí prvek <repeated-subitem> umožňuje, aby krok zahrnoval sadu podobných dílčích kroků. Přesná sada dílčích kroků může být opět založena na proměnných Cheat sheet, jejichž hodnoty jsou získány v předchozích krocích.

subitem

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

Každý prvek <subitem> popisuje dílčí krok v Cheat sheet. <Subitem> nese jednoduché textové označení, ale nemá ani dlouhý popis ani další dílčí položky. Atributy <subitem> jsou následující:

Dílčí položky mohou mít volitelnou akci nebo příkaz. Přítomnost prvku <action>, <command> nebo <perform-when> je obvykle spojena s tlačítkem, jehož stisknutím může uživatel provést akci nebo příkaz daného kroku. Pokud není nabízena žádná akce ani příkaz, musí uživatel provést krok ručně a poté zřetelně ukázat, že byl daný krok dokončen.

Na rozdíl od položek, u kterých musí uživatel dodržovat přesné pořadí, mohou být dílčí položky dané položky prováděny v libovolném pořadí. Všechny podřízené položky v rámci položky musí být dokončeny nebo vynechány, aby bylo možno přejít na další položku. (Což znamená, že akce, které musí být provedeny v požadovaném pořadí, nemohou být představovány dílčími položkami.)

conditional-subitem

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

Každý prvek <conditional-subitem> popisuje jeden dílčí krok, jehož forma se může lišit v závislosti na podmínce známé v době, kdy je položka rozbalena. Atributy <conditional-subitem> jsou následující:

Atribut condition v prvku <conditional-subitem> poskytuje hodnotu typu řetězec (tato hodnota vždy pochází z proměnné Cheat sheet). Každý z podřízených prvků <subitem> musí obsahovat when s jednoznačnou hodnotou typu řetězec. Když je položka rozbalena, je prvek <conditional-subitem> nahrazen prvkem <subitem> s odpovídající hodnotou. Je považováno za chybu, pokud se nevyskytuje žádný prvek <subitem> s odpovídající hodnotou.

Například pokud má proměnná Cheat sheet nazvaná "v1" hodnotu "b" při rozbalení následující položky:

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
     </conditional-subitem>
</item>
V tom případě je vybrána druhá dílčí položka (subitem) a položka (item) je rozbalena do něčeho, co odpovídá
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

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

Každý prvek <repeated-subitem> popisuje dílčí položku, která se rozbalí do 0, 1 nebo více podobných dílčích kroků. Atributy <repeated-subitem> jsou následující:

Atribut values poskytuje seznam čárkou oddělených řetězců; podřízený prvek <subitem> poskytuje šablonu. Když je položka rozbalena, je prvek <repeated-subitem> nahrazen kopiemi prvku <subitem>, přičemž výskyty proměnné "this" jsou nahrazeny odpovídající hodnotou typu řetězec.

Například pokud má proměnná Cheat sheet nazvaná "v1" hodnotu "1,b,three" při rozbalení následující položky:

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
  </subitem>
  </repeated-subitem>
</item>
V tom případě je položka rozbalena do něčeho, co odpovídá:
<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
>

Každý prvek <action> popisuje akci v Cheat sheet. Atributy <action> jsou následující:

command

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

Každý prvek <command> popisuje příkaz v pohledu Cheat Sheet. Atributy <command> jsou následující:

Níže je uveden příklad položky s příkazem, který otevírá dialogové okno a ukládá výsledek do proměnné "result" pohledu Cheat Sheet.

<item title="Výběr pohledu">
     <description>Vybere pohled, který se otevře v následujícím kroku.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Vybrat pohled,buttonLabel0=Průzkumník balíčků,message=Vybrat pohled ,buttonLabel1=Pohled Vyhledávání)"/>
      <onCompletion> Vybráno: ${result}. </onCompletion>
</item>

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

Prvek <onCompletion> obsahuje text, který se zobrazí při dokončení položky. Tento prvek je obzvláště užitečný v konečném kroku pohledu Cheat Sheet pro potvrzení dokončení celé úlohy. Popis obsahuje následující text přerušovaný jednoduchými formátovacími značkami dle stejných pravidel, jaká platí pro prvek <description>. Prvky <onCompletion> mohou také obsahovat odkazy na proměnné pohledu Cheat Sheet formuláře   "${var}", které budou rozbaleny s použitím skutečné hodnoty proměnné pohledu Cheat Sheet var v okamžiku dokončení tohoto kroku.

perform-when

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

Každý prvek <perform-when> popisuje akci v Cheat sheet. Atributy <perform-when> jsou následující:

Atribut condition v prvku <conditional-subitem> poskytuje hodnotu typu řetězec (tato hodnota vždy pochází z proměnné Cheat sheet). Každý z podřízených prvků <subitem> musí obsahovat when s jednoznačnou hodnotou typu řetězec. Když je položka rozbalena, je prvek <conditional-subitem> nahrazen prvkem <subitem> s odpovídající hodnotou. Je považováno za chybu, pokud se nevyskytuje žádný prvek <subitem> s odpovídající hodnotou.

Například pokud má proměnná Cheat sheet nazvaná "v1" hodnotu "b" při rozbalení následující položky:

<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>
V tom případě je vybrána druhá akce a položka je rozbalena do něčeho, co odpovídá
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Příklad

Následuje příklad souboru s obsahem jednoduchého pohledu Cheat Sheet, který demonstruje použití prvků příkazů, prvků perform-when a podmíněných dílčích položek.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Ukázkový pohled Cheat Sheet">
  <intro>
    <description>Pohled Cheat Sheet, který demonstruje použití prvků perform-when a podmíněných dílčích položek</description>
</intro>
  <item title="Výběr pohledu">
     <description>Vybere pohled, který se otevře v následujících krocích.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Vybrat pohled,buttonLabel0=Průzkumník balíčků,message=Vybrat pohled ,buttonLabel1=Pohled Vyhledávání)"/>
      <onCompletion> Vybráno: ${result}. </onCompletion>
</item>
  <item title="Zavřít pohledy">
     <description>Zavře pohled Vyhledávání a průzkumník balíčků, pokud je otevřen</description>
</item>
  <item title="Otevřít pohled z položky perform when" skip = "true">
     <description>Používá položku perform when k otevření vybraného pohledu.</description>
     <perform-when condition = "${result}">
           <command when = "Průzkumník balíčků"
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
           <command when = "Pohled Vyhledávání"
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>      
	</perform-when>
</item>
  <item title="Zavřít pohledy">
     <description>Zavře pohled Vyhledávání a průzkumník balíčků, pokud je otevřen</description>
</item>
  <item title="Otevřít pohled z dílčí položky perform when">
     <description>Používá položku perform when k otevření vybraného pohledu.</description>
     <subitem label="Dílčí položka perform when" skip = "true">
     <perform-when condition = "${result}">
           <command when = "Průzkumník balíčků"
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "Pohled Vyhledávání"
            serialization="org.eclipse.search.ui.views.SearchView"/>
	</perform-when>
  </subitem>
</item>
  <item title="Zavřít pohledy">
     <description>Zavře pohled Vyhledávání a průzkumník balíčků, pokud je otevřen</description>
</item>
  <item title="Otevřít pohled z dílčí položky conditional">
     <description>Používá položku perform when k otevření vybraného pohledu.</description>
      <conditional-subitem condition="${result}">
         <subitem when="Průzkumník balíčků" label="Otevřít Průzkumníka balíčků.">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
  </subitem>
         <subitem when="Pohled Vyhledávání" label="Otevřít Pohled Vyhledávání">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
  </subitem>
     </conditional-subitem>
</item>
</cheatsheet>