XML-format for indholdsfil til snydeark

Version 3.2

Dette dokument beskriver snydearkets indholdsfilstruktur som en række DTD-fragmenter (maskinlæsbart XML-skema).

cheatsheet

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

Elementet <cheatsheet> definerer indholdet af indholdsfilen til snydearket. <cheatsheet>-attributterne er som følger:

intro

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

Elementet <intro> bruges til at beskrive den introduktion til snydearket, som bliver vist. Underelementet <description> indeholder indholdet af introduktionen. <intro>-attributterne er som følger:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

Elementet <description> indeholder en beskrivelse af snydearket eller af snydearkselementet. Beskrivelsen består af tekst, hvori der er enkle formateringskoder. Snydearket formaterer automatisk teksten og sørger for layoutet, så den ser rimelig ud, når den vises på UI. Inde i teksten får koderne <b>...</b> den tekst, de omgiver, til at vises med fed skrift. Du kan bruge elementet <br/>, hvis du vil indsætte et fast linjeskift. Det er de eneste formateringskoder, der understøttes for øjeblikket (der kan dog komme flere til senere). Visse tegn i teksten har særlig betydning for XML-parsere. Hvis du skal skrive "<", ">", "&", "'" og """ (citationstegn), skal du i stedet skrive henholdsvis "&lt;", "&gt;", "&amp;", "&apos;" og "&quot;". Tomme pladser (mellemrum og linjeskift) behandles som ordskilletegn. Mellemrum og linjeskift ved siden af hinanden behandles som en enkelt enhed og gengives som et enkelt mellemrum eller et enkelt linjeskift. En tom plads umiddelbart efter koden <description> og <br/> ignoreres, ligesom tomme pladser umiddelbart foran koden </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
>

Hvert <item>-element beskriver et af de øverste trin i et snydeark. Et <element> kan indeholde <underordnede elementer>. <item>-attributterne er som følger:

org.eclipse.ui.cheatsheets.cheatSheetItemExtension tillader, at der vises flere tilpassede kontroller for elementet i UI. Bidrag til dette udvidelsespunkt erklærer navnene på flere streng-værdi-attributter, som eventuelt vises på <item>-elementerne.

Enkle elementer har en beskrivelse og en valgfri funktion eller kommando. I den typiske præsentation får brugeren det meste af tiden vist titlerne på snydearkets elementer. Et elements beskrivelse vises kun, mens trinnet er ved at blive udført. Tilstedeværelsen af et element af typen <action>, <command> eller <perform-when> forbindes med en knap, som brugerne kan trykke på for at udføre undertrinnets funktion. Hvis der ikke er en funktion eller kommando, er trinnet et, som brugeren skal udføre manuelt, og derefter angive, at trinnene er udført.

Trin opdeles i undertrin, som angivet af <subitem>-underelementerne. I modsætning til elementer, som brugeren skal følge i en helt bestemt rækkefølge, kan underelementer til et givent element udføres i en vilkårlig rækkefølge. Alle underelementer i en element skal være forsøgt anvendt (eller være sprunget over), før man kan gå videre til næste element. Det betyder, at funktioner, der skal udføres i en bestemt rækkefølge, ikke kan præsenteres som underelementer.

Underelementet <conditional-subitem> gør det muligt for et trin at skræddersy præsentationen af en undertrin, som er baseret på de variabler i snydearket, hvis værdier er anskaffet i tidligere trin. Underelementet <repeated-subitem> gør det muligt for et trin at inkludere et sæt af lignende undertrin. Igen gælder det, at det præcise undertrinsæt kan være baseret på snydearkvariabler, hvis værdi er anskaffet i tidligere trin.

subitem

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

Hvert <subitem>-element beskriver et undertrin i et snydeark. Et <subitem> har en enkel tekstetiket, men har hverken en længere beskrivelse eller flere underelementer. <subitem>-attributterne er som følger:

Underelementer kan have en valgfri funktionel kommando. Tilstedeværelsen af et element af typen <action>, <command> eller <perform-when> forbindes typisk med en knap, som brugerne kan trykke på for at udføre undertrinnets funktion. Hvis der ikke er en funktion eller kommando, er trinnet et, som brugeren skal udføre manuelt, og derefter angive, at trinnene er udført.

I modsætning til elementer, som skal følges i en helt bestemt rækkefølge, kan underelementer til et givent element udføres i en vilkårlig rækkefølge. Alle underelementer i en element skal være udført eller være sprunget over, før man kan gå videre til næste element. Det betyder, at funktioner, der skal udføres i en bestemt rækkefølge, ikke kan præsenteres som underelementer.

conditional-subitem

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

Hvert <conditional-subitem>-element beskriver en enkelt undertrin, hvis form kan variere afhængigt af en betingelse, som var kendt på det tidspunkt, elementet blev udvidet. <conditional-subitem>-attributterne er som følger:

condition-attributten på elementet <conditional-subitem> giver en strengværdi (denne værdi kommer uundgåeligt fra en snydearkvariabel). Hvert af de underordnede <subitem>-elementer skal indeholde attributten when sammen med en speciel strengværdi. Når elementet udvides, erstattes <conditional-subitem>-elementet med elementet <subitem>, der har en tilsvarende værdi. Det betragtes som en fejl, hvis der ikke er et <subitem>-element med en tilsvarende værdi.

Hvis snydearksvariablen "v1" f.eks. har værdien "b", når følgende element udvides

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
     </conditional-subitem>
</item>
så vælges det andet underelement, og elementet udvides til noget, der svarer til
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

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

Hvert <repeated-subitem>-element beskriver et underelement, som udvides til 0, 1 eller flere lignende undertrin. <repeated-subitem>-attributetterne er som følger:

values-attributten giver en liste med kommaseparerede strenge. Det underordnede <subitem> giver skabelonen. Når elementet udvides, erstattes <repeated-subitem>-elementet med kopier af <subitem>-elementet, hvor forekomster af variablen "this" er udskiftet med den tilsvarende strengværdi.

Hvis snydearksvariablen "v1" f.eks. har værdien "1,b,three", når følgende element udvides

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
  </subitem>
  </repeated-subitem>
</item>
udvides element til noget, der svarer til:
<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
>

Hvert <action>-element beskriver en funktion i et snydeark. <action>-attributterne er som følger:

command

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

Hvert <command>-element beskriver en kommando i et snydeark. <command>-attributter er som følger:

Nedenfor er et eksempel på et element med en kommando, der åbner en dialogboks og gemmer resultatet i snydearkets variabel "result".

<item title="Vis valg">
     <description>Vælg en oversigt, der skal åbnes i næste trin.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Vælg en oversigt ,buttonLabel1=Søg efter oversigt)"/>
      <onCompletion> ${result} er valgt. </onCompletion>
</item>

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

Elementet <onCompletion> indeholder tekst, der vises, når et element er afsluttet. Det er især nyttigt i det afsluttende trin for snydearket for at godkende afslutningen af hele opgaven. Beskrivelsen består af tekst, hvori der er enkle formateringskoder, der følger de samme regler som for elementet <description>. <onCompletion>-elementer kan også indeholde referencer til snydearksvariabler i formatet "${var}", der udvides ved at bruge den aktuelle værdi for snydearksvariablen var på det tidspunkt, dette trin er afsluttet.

perform-when

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

Hvert <perform-when>-element beskriver en funktion i et snydeark. <perform-when>-attributterne er som følger:

condition-attributten på elementet <conditional-subitem> giver en strengværdi (denne værdi kommer uundgåeligt fra en snydearkvariabel). Hvert af de underordnede <subitem>-elementer skal indeholde attributten when sammen med en speciel strengværdi. Når elementet udvides, erstattes <conditional-subitem>-elementet med elementet <subitem>, der har en tilsvarende værdi. Det betragtes som en fejl, hvis der ikke er et <subitem>-element med en tilsvarende værdi.

Hvis snydearksvariablen "v1" f.eks. har værdien "b", når følgende element udvides

<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>
så vælges den anden funktion, og elementet udvides til noget, det svarer til
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Eksempel

Følgende eksempel viser en enkel indholdsfil for et snydeark, der viser brugen af kommandoer, perform-when og betingede underordnede elementer.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Eksempelsnydeark">
  <intro>
    <description>Et snydeark, der viser brugen af perform-when og betingede underordnede elementer</description>
</intro>
<item title="Vis valg">
     <description>Vælg en oversigt, der skal åbnes i næste trin.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Vælg en oversigt ,buttonLabel1=Søg efter oversigt)"/>
      <onCompletion> ${result} er valgt. </onCompletion>
</item>
  <item title="Luk oversigter">
     <description>Luk søgeoversigten og Package Explorer, hvis den er åben</description>
</item>
  <item title="Åbn oversigten fra et perform-when-element" skip = "true">
     <description>Anvender perform-when til at åbne den oversigt, der tidligere er valgt.</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 = "Søg efter oversigt"
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>      
	</perform-when>
</item>
  <item title="Luk oversigter">
     <description>Luk søgeoversigten og Package Explorer, hvis den er åben</description>
</item>
  <item title="Åbn oversigten fra et underordnet perform-when-element">
     <description>Anvender perform-when til at åbne den oversigt, der tidligere er valgt.</description>
     <subitem label="Underordnet perform-when-element" skip = "true">
     <perform-when condition = "${result}">
           <command when = "Package Explorer" 
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "Søg efter oversigt"
            serialization="org.eclipse.search.ui.views.SearchView"/>      
	</perform-when>
  </subitem>
</item>
  <item title="Luk oversigter">
     <description>Luk søgeoversigten og Package Explorer, hvis den er åben</description>
</item>
  <item title="Åbn oversigten fra et betinget underordnet element">
     <description>Anvender perform-when til at åbne den oversigt, der tidligere er valgt.</description>
      <conditional-subitem condition="${result}">
         <subitem when="Package Explorer" label="Åbn Package Explorer.">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
     </subitem>
         <subitem when="Søg efter oversigt" label="Åbn Søg efter oversigt">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
     </subitem>
     </conditional-subitem>
</item>
</cheatsheet>