Lathundens innehållsfil (XML-format)

Version 3.2

I det här dokumentet beskrivs strukturen på lathundens innehållsfil som en serie DTD-fragment (maskinläsbart XML-schema).

cheatsheet

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

<cheatsheet>-elementet definierar huvuddelen av lathundens innehållsfil. <cheatsheet>-attributen är följande:

intro

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

Du använder <intro>-elementet för att beskriva introduktionen till den lathund som ska visas. Underelementet <description> innehåller huvuddelen av introduktionen. <intro>-attributen är följande:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

<description>-elementet innehåller beskrivningen av en lathund eller ett lathundsobjekt. Beskrivningen består av text som är blandad med enkla formateringsmärkord. Lathunden formaterar och ordnar texten så att den ser acceptabel ut i användargränssnittet. Inuti texten gör märkorden <b>...</b> att den inneslutna texten visas i fetstilt format. Du kan använda <br/>-elementet för att skapa en hård radbrytning. Det är de enda formateringsmärkorden som kan användas för tillfället (andra kan dock komma att läggas till i framtiden). Vissa tecken i texten har särskilda betydelser för XML-tolkning, särskilt "<", ">", "&", "'" och """ (citattecken). Skriv i stället "&lt;", "&gt;", "&amp;", "&apos;" och "&quot;". Tomrum (blanktecken och radbrytningar) behandlas som ordavgränsare. Närliggande blanktecken och radbrytningar behandlas som en enskild enhet och återges som ett enskilt blanktecken eller en enskild radbrytning. Tomrum omedelbart efter märkorden <description> och <br/> ignoreras, liksom tomrum omedelbart före märkordet </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
>

Varje <item>-element beskriver ett steg på den översta nivån i en lathund. Ett <item> kan innehålla <subitem>-element. <item>-attributen är följande:

org.eclipse.ui.cheatsheets.cheatSheetItemExtension tillåter att ytterligare anpassade kontroller för objektet visas i användargränssnittet. Bidrag till den här utökningspunkten deklarerar namnen på ytterligare strängvärdesattribut som kan visas på <item>-element.

Enkla objekt har en beskrivning och en valfri åtgärd eller kommando. I en vanlig presentation brukar rubrikerna på lathundssobjekt visas för användaren. Beskrivningen av ett objekt visas endast när steget körs. Ett <action>-, <command>- eller <perform-when>-element är associerat med en knapp som användaren kan trycka på för att utföra stegåtgärden eller -kommandot. Om det inte finns någon åtgärd eller kommando måste användaren utföra steget manuellt och sedan offentligt ange att steget är utfört.

Steg delas upp i delsteg enligt vad som anges av <subitem>-delelementen. Till skillnad från objekt, som användaren måste följa i rätt ordning, kan delelement för ett visst objekt utföras i vilken ordning som helst. Alla delobjekt i ett objekt måste testas (eller hoppas över) innan användaren kan gå vidare till nästa objekt. (Det innebär att åtgärder som måste utföras i en viss ordning inte kan visas som delobjekt.)

Ett <conditional-subitem>-delelement tillåter att ett steg anpassar presentationen av ett delsteg baserat på lathundssvariabler vars värden angavs i tidigare steg. Ett <repeated-subitem>-delelement tillåter att ett steg innehåller en uppsättning liknande delsteg. Även här kan den exakta uppsättningen steg baseras på lathundssvariabler vars värden angavs i tidigare steg.

subitem

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

Varje <subitem>-element beskriver ett delsteg i en lathund. Ett <subitem>-element innehåller en enkel textetikett, men har varken en lång beskrivning eller ytterligare delobjekt. <subitem>-attribut är följande:

Delobjekt kan ha en valfri åtgärd eller kommando. Ett <action>-, <command>- eller <perform-when>-element är vanligen associerat med en knapp som användaren kan trycka på för att utföra delstegsåtgärden eller -kommandot. Om det inte finns någon åtgärd eller kommando måste användaren utföra delsteget manuellt och sedan offentligt ange att steget är utfört.

Till skillnad från objekt, som användaren måste följa i rätt ordning, kan delobjekt för ett visst objekt utföras i vilken ordning som helst. Alla delobjekt i ett objekt måste slutföras eller hoppas över innan användaren kan gå vidare till nästa objekt. (Det innebär att åtgärder som måste utföras i en viss ordning inte kan visas som delobjekt.)

conditional-subitem

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

Varje <conditional-subitem>-element beskriver ett enskilt delsteg vars form kan skilja sig åt, baserat på ett villkor som är känt vid den tidpunkt då objektet utökas. <conditional-subitem>-attributen är följande:

condition-attributet i <conditional-subitem>-elementet ger ett strängvärde (detta värde kommer alltid från en lathundssvariabel). Alla underordnade <subitem>-element måste ha ett when-attribut med ett tydligt strängvärde. När objektet utökas ersätts <conditional-subitem>-elementet av <subitem>-elementet med det matchande värdet. Om det inte finns något <subitem>-element med matchande värde, uppstår ett fel.

Exempel: Om lathundssvariabeln med namnet "v1" har värdet "b" när följande objekt utökas:

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Steg för A." />
     <subitem when="b" label="Steg för B." />
  </conditional-subitem>
</item>
markeras det andra delobjektet och objektet utökas till något som motsvarar:
<item ...> 
  <subitem label="Steg för B."/>
</item>

repeated-subitem

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

Varje <repeated-subitem>-element beskriver ett delobjekt som utökas till 0, 1 eller fler liknande delsteg. <repeated-subitem>-attributen är följande:

values-attributet visar en lista med kommaavgränsade strängar. Det underordnade <subitem>-elementet anger mallen. När objektet utökas ersätts <repeated-subitem>-elementet av kopior av <subitem>-elementet samtidigt som förekomster av variabeln "this" ersätts av motsvarande strängvärde.

Exempel: Om lathundssvariabeln med namnet "v1" har värdet "1,b,tre" när följande objekt utökas:

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Steg ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
     </subitem>
  </repeated-subitem>
</item>
utökas objektet till något som motsvarar:
<item ...> 
  <subitem label="Steg 1.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/>
  </subitem>
  <subitem label="Steg b.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/>
  </subitem>
  <subitem label="Steg tre.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="tre"/>
  </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
>

Varje <action>-element beskriver en åtgärd i en lathund. <action>-attributen är följande:

command

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

Varje <command>-element beskriver ett kommando i en lathund. <command>-attribut är följande:

Nedan är ett exempel på ett objekt med ett kommando som öppnar en dialogruta och lagrar resultatet i lathundsvariabeln "result".

  <item title="Visa urval">
     <description>Välj en vy som öppnas i nästa steg.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Välj en vy ,buttonLabel1=Sökvy)"/>  
      <onCompletion> Valde ${result}. </onCompletion>
  </item> 

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

Elementet <onCompletion> innehåller text som visas när objektet är slutfört. Det är särskilt praktiskt för att ange att hela uppgiften slutförts i det slutliga steget i lathunden. Beskrivningen består av text som är blandad med enkla formateringsmärkord som följer samma regler som gäller för elementet <description>. <onCompletion>-element kan även innehålla referenser till lathundsvariabler i formatet   "${var}" som utökas med det faktiska värdet för lathundsvariablen var när steget slutförs.

perform-when

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

Varje <perform-when>-element beskriver en åtgärd i en lathund. <perform-when>-attributen är följande:

condition-attributet i <conditional-subitem>-elementet ger ett strängvärde (detta värde kommer alltid från en lathundssvariabel). Alla underordnade <subitem>-element måste ha ett when-attribut med ett tydligt strängvärde. När objektet utökas ersätts <conditional-subitem>-elementet av <subitem>-elementet med det matchande värdet. Om det inte finns något <subitem>-element med matchande värde, uppstår ett fel.

Exempel: Om lathundssvariabeln med namnet "v1" har värdet "b" när följande objekt utökas:

<item ...>
  <subitem label="Huvudsteg">
     <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>
markeras den andra åtgärden och objektet utökas till något som motsvarar:
<item ...> 
  <subitem label="Huvudsteg">
     <action class="com.xyz.action2" pluginId="com.xyz" />
         </subitem>
</item>

Exempel

Följande är ett exempel på en mycket enkel innehållsfil för en lathund som visar hur commands-, perform-when- och conditional-delobjekt används.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Exempel på lathund">
  <intro>
    <description>En lathund som visar hur perform-when- och conditional-delobjekt används</description>
  </intro>
  <item title="Visa urval">
     <description>Välj en vy som öppnas i följande steg.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=Select View,buttonLabel0=Package Explorer,message=Välj en vy ,buttonLabel1=Sökvy)"/>  
      <onCompletion> Valde ${result}. </onCompletion>
  </item> 
  <item title="Stäng vyer">
     <description>Stäng sökvyn och paketutforskaren om de är öppna</description>
  </item>
  <item title="Öppna vyn från ett perform-when-objekt" skip = "true">
     <description>perform-when används till att öppna den vy som valdes tidigare</description> 
     <perform-when condition = "${result}">
           <command when = "Paketutforskaren" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
           <command when = "Sökvy" 
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/>      
     	</perform-when>
  </item> 
  <item title="Stäng vyer">
     <description>Stäng sökvyn och paketutforskaren om de är öppna</description>
  </item>
  <item title="Öppna vyn från ett perform-when-delobjekt">
     <description>perform-when används till att öppna den vy som valdes tidigare</description> 
     <subitem label="Perform-when-delobjekt" skip = "true">
     <perform-when condition = "${result}">
           <command when = "Paketutforskaren" 
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "Sökvy" 
            serialization="org.eclipse.search.ui.views.SearchView"/>      
     	</perform-when>
         </subitem>
  </item> 
  <item title="Stäng vyer">
     <description>Stäng sökvyn och paketutforskaren om de är öppna</description>
  </item>
  <item title="Öppna vyn från ett conditional-delobjekt">
     <description>perform-when används till att öppna den vy som valdes tidigare</description> 
      <conditional-subitem condition="${result}">
         <subitem when="Paketutforskaren" label="öppna paketutforskaren.">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
         </subitem>
         <subitem when="Sökvy" label="Öppna sökvyn">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
         </subitem>
  </conditional-subitem>
  </item>
</cheatsheet>