XML formát souboru s obsahem Cheat sheet

Verze 3.0

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|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> 
<!ATTLIST item 
  title               CDATA #REQUIRED
  skip                ("true" | "false") "false"
  contextId           CDATA #IMPLIED 
  href                CDATA #IMPLIED
>

Každý prvek <item> popisuje jeden krok na nejvyšší úrovni v Cheat sheet. Atribut <item> je buď jednoduchý, nebo složený. 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. 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> (nebo <perform-when>) je obvykle spojena s tlačítkem, jehož stisknutím může uživatel provést akci daného kroku. Pokud není žádná akce nabízena, musí uživatel provést krok ručně a poté zřetelně ukázat, že byl daný krok dokončen.

Složené kroky se dělí na dílčí kroky, jak jsou specifikovány 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|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 mají volitelnou akci. Přítomnost prvku <action> (nebo <perform-when>) je obvykle spojena s tlačítkem, jehož stisknutím může uživatel provést akci daného dílčího kroku. Pokud není žádná akce nabízena, musí uživatel provést dílčí 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í. 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.)

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í:

perform-when

<!ELEMENT perform-when (action+)> 
<!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" />
     </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 velmi jednoduchého souboru s obsahem Cheat sheet:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Příklad">
  <intro>
    <description>Příklad obsahu Cheat sheet se dvěma kroky.</description>
</intro>
  <item title="Krok 1">
     <description>Toto je krok s akcí.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
</item>
  <item title="Step 2">
     <description>Toto je plně ruční krok.</description>
</item>
</cheatsheet>