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

3.2 változat

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

Minden <item> elem egy felső szintű lépést ír le egy áttekintőben. Az <item> <subitem> elemeket is tartalmazhatnak. 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 vagy paranccsal 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>, <command> (vagy <perform-when>) elem jelenléte jellemzően egy gombhoz van társítva, amelyet a felhasználó megnyomhat a lépés tevékenységének vagy parancsának végrehajtásához. Ha nincs tevékenység vagy parancs jelen, akkor a lépést a felhasználónak kézzel kell végrehajtania, majd egyértelműen jeleznie, hogy a lépés sikeresen végrehajtásra került.

A lépések a <subitem> részelem által megadott részlépésekre oszthatók. 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|command|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 rendelkezhetnek egy elhagyható tevékenységgel vagy paranccsal. Az <action>, <command> 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 vagy parancsának végrehajtásához. Ha nincs tevékenység vagy parancs jelen, akkor a részlépést a felhasználónak kézzel kell végrehajtania, majd egyértelműen 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 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 ...> 
  <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:

command

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

Minden <command> elem az áttekintő egy parancsát írja le. A <command> attribútumok az alábbiak:

Alább egy példaelem látható egy paranccsal, amely megnyit egy párbeszédablakot és a "result" áttekintőváltozóban eltárolja az eredményt.

  <item title="Nézet kiválasztása">
     <description>A következő lépésben megjelenő nézet kiválasztása.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Nézet kiválasztása,buttonLabel0=Csomagböngésző,message=Válasszon egy nézetet ,buttonLabel1=Nézet keresése)"/>  
      <onCompletion> ${result} kiválasztva. </onCompletion>
</item> 

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

Az <onCompletion> elem a tétel befejezése esetén megjelenő szöveget tartalmazza. Ez különösen az áttekintő utolsó lépésében hasznos a teljes feladat befejezésének nyugtázásához. A leírás szövegből és egyszerű formázási címkékből áll, amelyek ugyanazt a szabályokat követik, mint a <description> elem. Az <onCompletion> elemek   "${var}" forma áttekintőváltozóira is tartalmazhatnak hivatkozásokat, amelyek a var áttekintőváltozó aktuális értékével kiterjesztésre kerülnek a lépés befejezésekor.

perform-when

<!ELEMENT perform-when ((action|command)+)> 
<!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" />
        <command when="c" serialization="org.eclipse.search.ui.views.SearchView"/>
     </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, amely a commands, perform-when és conditional részelemek használatát mutatja be:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Példa áttekintő">
  <intro>
    <description>Egy áttekintő, amely a perform-when és a conditional részelemek használatát mutatja be</description>
  </intro>
  <item title="Nézet kiválasztása">
     <description>A következő lépésben megjelenő nézet kiválasztása.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Nézet kiválasztása,buttonLabel0=Csomagböngésző,message=Válasszon egy nézetet ,buttonLabel1=Nézet keresése)"/>  
      <onCompletion> ${result} kiválasztva. </onCompletion>
</item> 
  <item title="Nézetek bezárása">
     <description>Bezárja a keresés nézetet és a csomagböngészőt, amennyiben meg vannak nyitva</description>
</item>
  <item title="Nézet megnyitása egy perform when elemből" skip = "true">
     <description>Perform when használata a korábban kiválasztott nézet megnyitására.</description> 
     <perform-when condition = "${result}">
           <command when = "Csomagböngésző" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
           <command when = "Nézet keresése" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>      
	</perform-when>
</item> 
  <item title="Nézetek bezárása">
     <description>Bezárja a keresés nézetet és a csomagböngészőt, amennyiben meg vannak nyitva</description>
</item>
  <item title="Nézet megnyitása egy perform when részelemből">
     <description>Perform when használata a korábban kiválasztott nézet megnyitására.</description> 
     <subitem label="Perform when részelem" skip = "true">
     <perform-when condition = "${result}">
           <command when = "Csomagböngésző" 
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "Nézet keresése" 
            serialization="org.eclipse.search.ui.views.SearchView"/>      
	</perform-when>
  </subitem>
</item> 
  <item title="Nézetek bezárása">
     <description>Bezárja a keresés nézetet és a csomagböngészőt, amennyiben meg vannak nyitva</description>
</item>
  <item title="Nézet megnyitása egy conditional részelemből">
     <description>Perform when használata a korábban kiválasztott nézet megnyitására.</description> 
      <conditional-subitem condition="${result}">
         <subitem when="Csomagböngésző" label="Csomagböngésző megnyitása.">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
  </subitem>
         <subitem when="Nézet keresése" label="Keresés nézet megnyitása">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
  </subitem>
     </conditional-subitem>
</item>
</cheatsheet>