XML formátumú áttekintő-tartalomfájl

3.0 verzió

A dokumentum az áttekintő-tartalomfájl struktúráját DTD töredékek sorozataként írja le (géppel olvasható XML séma).

cheatsheet

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

Az <áttekintő> elem megadja az áttekintő tartalomfájl törzsét. A <cheatsheet> attribútumok az alábbi módon néznek ki:

intro

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

Az <intro> leírja az áttekintő megjelenítendő bevezetőjét. A <description> részelem a bevezetés törzsét tartalmazza. Az <intro> attribútum az alábbi módon néz ki:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

A <description> elem tartalmazza egy áttekintő vagy egy áttekintőelem leírását. A leírás szövegből és egyszerű formázási címkékből áll. Az áttekintő automatikusan formázza és elrendezi a szöveget, hogy érthetően megjelenjen a felhasználói felületen. A szövegben a <b>...</b> címkepárok hatására az általuk bezárt szöveg félkövér betűkészlettel kerül előállításra, a <br/> elem pedig sortöréshez használható. Pillanatnyilag csak ezek a formázási címkék támogatottak (elképzelhető, hogy a jövőben továbbiak is rendelkezésre állnak). Bizonyos karaktereknek különleges jelentősége van az XML elemzők számára; "<", ">", "&", "'", és """ (kérdőjel) helyett "&lt;", "&gt;", "&amp;", "&apos;" és "&quot;" karaktert kell írni, értelemszerűen. A szóközszerű karaktereket (szóköz és sortörés) a rendszer szóelválasztóként használja; szomszédos szóközöket és sortöréseket egyetlen egységként kezel a rendszer, és egy szóközként vagy sortörésként állítja elő őket. Közvetlenül a <description> és <br/> címkék után, valamint a </description> címke előtt szereplő szóközszerű karakter figyelmen kívül marad.

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
>

Minden <item> elem egy felső szintű lépést ír le egy áttekintőben. Az <item> lehet egyszerű vagy összetett. Az <item> attribútumok az alábbiak:

Az org.eclipse.ui.cheatsheets.cheatSheetItemExtension segítségével a felhasználói felületen az elemhez további egyedi vezérlőelemek jeleníthetők meg. Ezen kiterjesztési pont kiegészítései megadják a kiegészítő, karaktersorozat értékű attribútumok neveit, amelyek megjelenhetnek az <item> elemeken.

Az egyszerű elemek egy leírással és egy elhagyható tevékenységgel rendelkeznek. A jellemző megjelenítésben az áttekintőelemek címei az idő nagy részében megjelennek a felhasználó számára. Egy elem leírása csak addig jelenik meg, amíg a lépés feldolgozás alatt van. Az <action> (vagy <perform-when>) elem jelenléte jellemzően egy gombhoz van társítva, amelyet a felhasználó a lépés tevékenységének végrehajtásához megnyomhat. Ha nincs tevékenység jelen, akkor a lépést a felhasználónak kézzel kell végrehajtania, majd nyíltan jelezni, hogy a lépés sikeresen végrehajtásra került.

Az összetett lépések a <subitem> részelem által megadott részlépésekre vannak osztva. Az elemekkel ellentétben, amelyet a felhasználónak szigorú sorrendben kell végrehajtania, egy adott elem részelemei tetszőleges sorrendben végrehajthatók. Egy elem minden részelemének végrehajtását (vagy átugrását) megkísérli a rendszer, mielőtt továbblépne a következő elemre. (Ez azt jelenti, hogy az adott sorrendben végrehajtandó tevékenységek nem ábrázolhatók részelemekként.)

A <conditional-subitem> részelem segítségével a lépés az áttekintőváltozók alapján - amelyek értékei korábbi lépésben kerülnek megadásra - testreszabhatja a részlépés megjelenítését. A <repeated-subitem> részelem segítségével a lépés hasonló részlépések halmazát adhatja meg. A részlépések pontos halmaza az áttekintőváltozókra épülhet, amelyek értéke korábbi lépésekből származik.

subitem

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

Minden <subitem> elem az áttekintő egy részlépését írja le. A <subitem> egy egyszerű szövegcímkét tartalmaz, de nem rendelkezik hosszú leírással és további részelemekkel. A <subitem> attribútumok az alábbiak:

A részelemek rendelkeznek egy elhagyható tevékenységgel. Az <action> (vagy <perform-when>) elem jelenléte jellemzően egy gombhoz van társítva, amelyet a felhasználó megnyomhat a részlépés tevékenységének végrehajtásához. Ha nincs tevékenység jelen, akkor a részlépést a felhasználónak kézzel kell végrehajtania, majd nyíltan jelezni, hogy a lépés sikeresen végrehajtásra került.

A szigorú sorrendben végrehajtandó elemekkel ellentétben egy adott elem részelemei tetszőleges sorrendben végrehajthatók. Egy elem minden részelemének végrehajtását (vagy átugrását) megkísérli a rendszer, mielőtt továbblépne a következő elemre. (Ez azt jelenti, hogy egy adott sorrendben végrehajtandó tevékenységek nem ábrázolhatók részelemekként.)

conditional-subitem

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

Minden <conditional-subitem> elem egy részlépést ír le, amelynek formája az elem kiterjesztésekor ismert feltétel alapján különbözhet. A <conditional-subitem> attribútumok az alábbiak:

A <conditional-subitem> elem condition attribútuma egy karaktersorozat-értéket biztosít (ez az érték mindig egy áttekintőváltozóból származik). A <subitem> minden leszármazottjának tartalmaznia kell a when attribútumot egy különböző karaktersorozat-értékkel. Az elem kiterjesztésekor a <conditional-subitem> elemet a megfelelő értékkel rendelkező <subitem> elem helyettesíti. Ez hibát jelent, ha nincs megfelelő értékkel rendelkező <subitem> elem.

Ha például a "v1" nevű áttekintőváltozó "b" értékkel rendelkezik az alábbi elem kibontásakor:

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
  </conditional-subitem>
</item>
majd a második részelem kiválasztásra kerül, és az elem az alábbihoz hasonlóan kerül kibontásra:
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

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

Minden <repeated-subitem> elem egy részelemet ír le, amely 0, 1 vagy több részlépésre bomlik ki. A <repeated-subitem> attribútumok az alábbiak:

A values attribútum vesszővel elválasztott karaktersorozatok listáját biztosítja; a <subitem> leszármazott biztosítja a sablont. Az elem kibontásakor a <repeated-subitem> elemet a <subitem> másolatai, a "this" változó előfordulásait pedig a megfelelő karaktersorozat-érték helyettesít.

Ha például a "v1" nevű áttekintőváltozó "1,b,three" értékkel rendelkezik az alábbi elem kibontásakor:

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
     </subitem>
  </repeated-subitem>
</item>
akkor az elem kibontása az alábbihoz hasonlót eredményez:
<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
>

Minden <action> elem egy áttekintőtevékenységet ír le. Az <action> attribútumok az alábbiak:

perform-when

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

Minden <perform-when> elem egy áttekintőtevékenységet ír le. A <perform-when> attribútumai az alábbiak:

A <conditional-subitem> elem condition attribútuma egy karaktersorozat-értéket biztosít (ez az érték mindig egy áttekintőváltozóból származik). A <subitem> minden leszármazottjának tartalmaznia kell a when attribútumot egy különböző karaktersorozat-értékkel. Az elem kibontásakor a <conditional-subitem> elemet a megfelelő értékkel rendelkező <subitem> elem helyettesíti. Ez hibát jelent, ha nincs megfelelő értékkel rendelkező <subitem> elem.

Ha például a "v1" nevű áttekintőváltozó "b" értékkel rendelkezik az alábbi elem kibontásakor:

<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>
majd a második tevékenység kiválasztásra kerül, és az elem az alábbihoz hasonlóan kerül kibontásra:
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Példa

Az alábbi egy nagyon egyszerű áttekintő-tartalomfájl példa:

<?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>Ez egy lépés egy tevékenységgel.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
  </item>
  <item title="Step 2">
     <description>Ez egy teljesen kézi lépés.</description>
  </item>
</cheatsheet>