Jukselappens innholdsfil i XML-format

Versjon 3.2

Dette dokumentet beskriver strukturen i innholdsfilen for en jukselapp som en serie av DTD-fragmenter (maskinlesbart XML-skjema).

cheatsheet

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

Elementet <cheatsheet> definerer hoveddelen av jukselappens innholdsfil. Dette er <cheatsheet>-attributtene:

intro

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

Elementet <intro> brukes til å beskrive jukselappintroduksjonen som skal vises. Underelementet <description> inneholder hoveddelen av introduksjonen. Dette er <intro>-attributtene:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

Elementet <description> inneholder beskrivelsen av en jukselapp eller av et jukselappelement. Beskrivelsen består av tekst med enkle formateringskoder. Jukselappen formaterer og bestemmer layouten for teksten automatisk slik at den vises på en fornuftig måte i brukergrensesnittet. I teksten gjør par av kodene <b>...</b> at teksten blir gjengitt med fet skrift, og elementet <br/> kan brukes til å fremtvinge et linjeskift. Dette er de eneste formateringskodene som støttes nå (det kan bli tilføyd andre senere). Bestemte tegn i teksten har spesialbetydning for XML-analysatorer. Hvis du vil skrive "<", ">", "&", "'" og """ (spørsmålstegn), skriver du i stedet henholdsvis "&lt;", "&gt;", "&amp;", "&apos;" og "&quot;". Blanktegn (mellomrom og linjeskift) behandles som et ordskilletegn. Tilstøtende mellomrom og linjeskift behandles som en enkeltenhet og gjengis som ett enkelt mellomrom eller linjeskift. Blanktegn umiddelbart etter kodene <description> og <br/> blir ignorert, på samme måte som blanktegn umiddelbart før 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 toppnivåtrinn i en jukselapp. Et <item> kan inneholde <subitem>-elementer. Dette er <item>-attributtene:

Ved hjelp av org.eclipse.ui.cheatsheets.cheatSheetItemExtension kan ekstra tilpassede kontroller for elementet vises i brukergrensesnittet. Bidrag til dette utvidelsespunktet deklarerer navnene på tilleggsattributter med strengverdier som kan bli vist i <item>-elementer.

Enkle elementer har en beskrivelse og en valgfri handling eller kommando. I den vanlige presentasjonen blir titlene på jukselappelementer vist til brukeren det meste av tiden. Et elements beskrivelse blir bare vist mens trinnet er i ferd med å bli utført. Forekomsten av et <action>-, <command>- eller <perform-when>-element er knyttet til en knappe som brukeren kan trykke på for å utføre trinnets handling eller kommando. Hvis det ikke finnes noen handling eller kommando, må brukeren utføre trinnet manuelt og deretter oppgi at trinnet er fullført på en vellykket måte.

Trinn brytes ned i undertrinn slik det oppgis av <subitem>-underelementer. I motsetning til elementer, som brukeren må følge i streng rekkefølge, kan underelementene i et gitt element utføres i en hvilken som helst rekkefølge. Alle underelementer i et element må forsøkes (eller hoppes over) før neste trinn behandles. (Det betyr at handlinger som må utføres i en obligatorisk rekkefølge, ikke kan representeres som underelementer.)

Ved hjelp av et <conditional-subitem>-underelement er det mulig å skreddersy presentasjonen av et undertrinn i et trinn, basert på jukselappvariabler med verdier som kommer fra tidligere trinn. Et <repeated-subitem>-underelement tillater at et trinn inkluderer et sett av liknende undertrinn. Og igjen kan det nøyaktige settet av undertrinn være basert på jukselappvariabler med verdier fra tidligere trinn.

subitem

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

Hvert <subitem>-element beskriver et undertrinn i en jukselapp. Et <subitem> har en enkel tekstetikett, men det har verken en lang beskrivelse eller andre underelementer. Dette er <subitem>-attributtene:

Underelementer kan ha en valgfri handling eller kommando. Forekomsten av et <action>-, <command>- eller <perform-when>-element er vanligvis knyttet til en knapp som brukeren kan trykke på for å utføre undertrinnets handling eller kommando. Hvis det ikke finnes noen handling eller kommando, må brukeren utføre undertrinnet manuelt og deretter oppgi at trinnet er fullført på en vellykket måte.

I motsetning til elementer, som må følges i streng rekkefølge, kan underelementene i et gitt element utføres i en hvilken som helst rekkefølge. Alle underelementer i et element må fullføres eller hoppes over før neste trinn behandles. (Det betyr at handlinger som må utføres i en obligatorisk rekkefølge, ikke bør representeres som underelementer.)

conditional-subitem

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

Hvert <conditional-subitem>-element beskriver et enkelt undertrinn med en form som kan variere basert på en betingelse på tidspunktet da elementet utvides. Dette er <conditional-subitem>-attributtene:

Attributtet condition i <conditional-subitem>-elementet oppgir en strengverdi (denne verdien kommer alltid fra en jukselappvariabel). Hver enkelt av de underordnede <subitem> må ha et when-attributt med en distinkt strengverdi. Når elementet er utvidet, blir <conditional-subitem>-elementet erstattet av <subitem>-elementet med den samsvarende verdien. Det blir betraktet som en feil hvis det ikke finnes noe <subitem>-element med en samsvarende verdi.

Hvis jukselappvariabelen "v1" for eksempel har verdien "b" når det følgende elementet utvides:

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
     </conditional-subitem>
</item>
så velges det andre underelementet og elementet utvides til noe som likner på dette:
<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 blir utvidet til 0, 1, eller mer liknende undertrinn. Dette er <repeated-subitem>-attributtene:

Attributtet values har en liste over strenger med komma som skilletegn. Den underordnede <subitem> oppgir malen. Når elementet er utvidet, blir <repeated-subitem>-elementet erstattet av kopier av <subitem>-elementet med forekomster av variabelen "this", erstattet av den tilsvarende strengverdien.

Hvis jukselappvariabelen "v1" for eksempel har verdien "1,b,three", blir det følgende elementet utvidet:

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
  </subitem>
  </repeated-subitem>
</item>
Deretter utvides elementet til noe som likner på dette:
<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 handling i en jukselapp. Dette er <action>-attributtene:

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 en jukselapp. Dette er <command>-attributtene:

Nedenfor finner du et eksempel på et element med en kommando som åpner en dialogboks og lagrer resultatene i jukselappvariabelen "result".

  <item title="View Selection">
     <description>Select a view which will be opened in the next step.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/>  
      <onCompletion> Selected the ${result}. </onCompletion>
</item> 

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

Elementet <onCompletion> inneholder tekste som blir vist når et element er fullført. Dette er spesielt nyttig i det siste trinnet av jukselappen for å godkjenne fullføringen av hele oppgaven. Beskrivelsen består av tekst med enkle formateringskoder som følger de samme reglene som for et <description>-element. <onCompletion>-elementene kan også inneholde referanser til jukselappvariabler i formen  "${var}", som blir utvidet ved hjelp av den faktiske verdien av jukselappvariabelen var på det tidspunktet dette trinnet fullføres.

perform-when

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

Hvert <perform-when>-element beskriver en handling i en jukselapp. Dette er <perform-when>-attributtene:

Attributtet condition i <conditional-subitem>-elementet oppgir en strengverdi (denne verdien kommer alltid fra en jukselappvariabel). Hver enkelt av de underordnede <subitem> må ha et when-attributt med en distinkt strengverdi. Når elementet er utvidet, blir <conditional-subitem>-elementet erstattet av <subitem>-elementet med den samsvarende verdien. Det blir betraktet som en feil hvis det ikke finnes noe <subitem>-element med en samsvarende verdi.

Hvis jukselappvariabelen "v1" for eksempel har verdien "b" når det følgende elementet utvides:

<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>
Deretter velges den andre handlingen og elementet utvides til noe som likner på dette:
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
     </subitem>
</item>

Eksempel

Nedenfor finner du et eksempel på en enkel innholdsfil for en jukselapp som demonstrerer bruken av command, perform-when og betingede underelementer.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Sample Cheat Sheet">
  <intro>
    <description>A cheat sheet which demonstrates the use of perform-when and conditional subitems</description>
  </intro>
  <item title="View Selection">
     <description>Select a view which will be opened in the following steps.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Select a view ,buttonLabel1=Search View)"/>  
      <onCompletion> Selected the ${result}. </onCompletion>
</item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
</item>
  <item title="Open the view from a perform when item" skip = "true">
     <description>Uses perform when to open the view seleted previously.</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 = "Search View" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>      
	</perform-when>
</item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
</item>
  <item title="Open the view from a perform when subitem">
     <description>Uses perform when to open the view seleted previously.</description> 
     <subitem label="Perform when subitem" skip = "true">
     <perform-when condition = "${result}">
           <command when = "Package Explorer" 
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "Search View" 
            serialization="org.eclipse.search.ui.views.SearchView"/>      
	</perform-when>
     </subitem>
</item> 
  <item title="Close Views">
     <description>Close the search view and package explorer if open</description>
</item>
  <item title="Open the view from a conditional subitem">
     <description>Uses perform when to open the view seleted previously.</description> 
      <conditional-subitem condition="${result}">
         <subitem when="Package Explorer" label="Open package explorer.">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
     </subitem>
         <subitem when="Search View" label="Open Search View">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
     </subitem>
     </conditional-subitem>
</item>
</cheatsheet>