XML-bestand met inhoud voor hulpblad

Versie 3.2

In dit document vindt u een beschrijving van de hulpbladbestandsstructuur als een reeks DTD-fragmenten (door computer te lezen XML-schema).

cheatsheet

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

Met het element <cheatsheet> (hulpblad) definieert u de inhoud van het bestand met de content van het hulpblad. Kenmerken van <cheatsheet> zijn:

intro

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

Het element <intro> wordt gebruikt om een beschrijving weer te geven als inleiding voor het hulpblad. Het subelement <description> (beschrijving) bevat de tekst van de inleiding. Kenmerken van <intro> zijn:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

Het element <description> bevat de beschrijving van een hulpblad of een hulpbladitem. De beschrijving bestaat uit tekst die her en der is voorzien van eenvoudige opmaaktags. De tekst wordt door het hulpblad automatisch zo ingedeeld en opgemaakt, dat deze er netjes uitziet in de gebruikersinterface. In de tekst kunt u de tags <b>...</b> gebruiken om de tekst tussen de tags vetgedrukt weer te geven. Met het element <br/> forceert u een regeleinde. Dit zijn de enige opmaaktags die momenteel worden ondersteund (mogelijk worden in de toekomst ook andere tags ondersteund). Bepaalde tekens in de tekst hebben een speciale betekenis voor XML-parsers. In plaats van de tekens "<", ">", "&", "'" en """ (vraagteken) dient u respectievelijk "&lt;", "&gt;", "&amp;", "&apos;" en "&quot;" te gebruiken. Witruimten (spaties en regeleinden) worden behandeld als woordscheidingstekens. Aangrenzende spaties en regeleinden worden behandeld als een afzonderlijke eenheid en worden weergegeven als één spatie of regeleinde. Witruimten direct na de tags <description> en <br/> worden genegeerd, evenals witruimten direct vóór de tag </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
>

Elk <item>-element vormt een beschrijving van één stap van het hoogste niveau in een hulpblad. Het item <item> kan elementen van het type <subitem> bevatten. Kenmerken van <item> zijn:

In org.eclipse.ui.cheatsheets.cheatSheetItemExtension kunt u aanvullende aangepaste besturingselementen opgeven voor het item dat in de gebruikersinterface wordt weergegeven. Bijdragen aan dit extensiepunt bevatten declaraties van de namen van aanvullende, tekenreekskenmerken die worden weergegeven via <item>-elementen.

Eenvoudige items bevatten een beschrijving en een optionele actie of opdracht. Gewoonlijk zijn de titels van hulpbladitems het grootste deel van de tijd zichtbaar voor de gebruiker. De beschrijving van een item wordt alleen afgebeeld terwijl de stap wordt uitgevoerd. De aanwezigheid van het element <action>, <command> (of <perform-when>) wordt gewoonlijk gekoppeld aan een knop waarop kan worden geklikt om de bijbehorende actie of opdracht uit te voeren. Als er geen actie of opdracht aanwezig is, moet de gebruiker de desbetreffende stap handmatig uitvoeren en vervolgens aangeven dat de stap is voltooid.

Stappen kunnen worden onderverdeeld in substappen, die worden opgegeven in <subitem>-subelementen. In tegenstelling tot items, die door de gebruiker in de juiste volgorde moeten worden uitgevoerd, kunnen subitems van een gegeven item in een willekeurige volgorde worden uitgevoerd. Alle subitems in een item moeten worden uitgevoerd (of overgeslagen) voordat het volgende item wordt uitgevoerd. (Oftewel, acties die in een bepaalde volgorde moeten worden uitgevoerd, kunnen niet worden gedefinieerd als subitems.)

Met het subelement <conditional-subitem> kunt u de presentatie van een substap aanpassen op basis van hulpbladvariabelen waarvan de waarden in eerdere stappen zijn verkregen. Met het subelement <repeated-subitem> kunt u een reeks vergelijkbare substappen in een stap opnemen. Ook hierbij kan de exacte reeks substappen worden gebaseerd op hulpbladvariabelen waarvan de waarden in eerdere stappen zijn verkregen.

subitem

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

Elk element <subitem> vormt een beschrijving van een substap in een hulpblad. Een <subitem> is voorzien van een eenvoudig tekstlabel, maar kan verder geen lange beschrijving of subitems bevatten. Kenmerken van <subitem> zijn:

Subitems kunnen een optionele actie of opdracht bevatten. De aanwezigheid van het element <action>, <command> of <perform-when> wordt gewoonlijk gekoppeld aan een knop waarop de gebruiker kan klikken om de bijbehorende actie of opdracht uit te voeren. Als er geen actie of opdracht bestaat, moet de gebruiker de desbetreffende substap handmatig uitvoeren en vervolgens aangeven dat de stap is voltooid.

In tegenstelling tot items, die door de gebruiker in de juiste volgorde moeten worden uitgevoerd, kunnen subitems van een gegeven item in willekeurige volgorde worden uitgevoerd. Alle subitems in een item moeten worden voltooid (of overgeslagen) voordat het volgende item wordt uitgevoerd. (Oftewel, acties die in een bepaalde volgorde moeten worden uitgevoerd, kunnen niet worden gedefinieerd als subitems.)

conditional-subitem

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

Een element <conditional-subitem> bevat een beschrijving van één substap waarvan de vorm kan verschillen, afhankelijk van een voorwaarde die bekend wordt wanneer het item wordt uitgebreid. Kenmerken van <conditional-subitem> zijn:

Het kenmerk condition van het element <conditional-subitem> biedt een tekenreekswaarde (deze waarde is altijd afkomstig van een hulpbladvariabele). Alle onderliggende <subitemelementen> moeten het kenmerk when met een unieke tekenreekswaarde bevatten. Wanneer het item wordt uitgebreid, wordt het <conditional-subitem>-element vervangen door het <subitem>-element met de overeenkomende waarde. Als er geen <subitem>-element met een overeenkomende waarde is, wordt dit door het programma gezien als een fout.

Als de hulpbladvariabele "v1" de waarde "b" heeft wanneer het volgende item wordt uitgebreid

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Stap voor A." />
     <subitem when="b" label="Stap voor B." />
     </conditional-subitem>
</item>
dan wordt het tweede subitem geselecteerd en wordt het item ongeveer als volgt uitgebreid:
<item ...> 
  <subitem label="Stap voor B."/>
</item>

repeated-subitem

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

Elk <repeated-subitem>-element beschrijft een subitem dat kan worden uitgebreid met 0, 1 of meer soortgelijke substappen. Kenmerken van <repeated-subitem> zijn:

Het kenmerk values biedt een lijst met waarden die door komma's zijn gescheiden; de sjabloon is gebaseerd op het onderliggende element <subitem>. Wanneer het item wordt uitgebreid, wordt het element <repeated-subitem> vervangen door kopieën van het element <subitem> en worden voorvallen van de variabele "this" vervangen door de bijbehorende tekenreekswaarde.

Als de hulpbladvariabele "v1" de waarde "1,b,drie" wanneer het volgende item wordt uitgebreid

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Stap ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
     </subitem>
  </repeated-subitem>
</item>
dan wordt het item ongeveer als volgt uitgebreid:
<item ...> 
  <subitem label="Stap 1.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="1"/>
     </subitem>
  <subitem label="Stap b.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="b"/>
     </subitem>
  <subitem label="Stap drie.">
     <action class="com.xyz.myaction" pluginId="com.xyz" param1="drie"/>
     </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
>

Elk element <action> staat voor een actie in een hulpblad. Kenmerken van <action> zijn:

command

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

Elk <command>-element staat voor een beschrijving van een opdracht in een hulpblad. De kenmerken van <command> zijn als volgt:

Hieronder vindt u een voorbeeld van een item met een opdracht die ervoor zorgt dat er een dialoogvenster wordt geopend en dat het resultaat wordt opgeslagen in de hulpbladvariabele "result".

<item title="View selecteren">
     <description>Selecteer een view die in de volgende stap wordt geopend.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=View selecteren,buttonLabel0=Pakketverkenner,message=Selecteer een view,buttonLabel1=View Zoeken)"/>
      <onCompletion> View ${result} geselecteerd. </onCompletion>
</item>

onCompletion

<!ELEMENT onCompletion EMPTY>
<!ATTLIST onCompletion 
>

Het element <onCompletion> bevat tekst die wordt weergegeven wanneer een item is voltooid. Dit is vooral handig in de laatste stap van het hulpblad om aan te geven dat de hele taak is afgerond. De beschrijving bestaat uit tekst die her en der is voorzien van eenvoudige opmaakcodes volgens dezelfde regels als voor <description>-elementen. <onCompletion>-elementen kunnen ook verwijzingen bevatten naar hulpbladvariabelen in de notatie "${var}", die bij voltooiing van deze stap worden uitgebreid met de werkelijke waarde van de hulpbladvariabele var.

perform-when

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

Elk element <perform-when> staat voor een beschrijving van een actie in een hulpblad. Kenmerken van <perform-when> zijn:

Het kenmerk condition van het element <conditional-subitem> biedt een tekenreekswaarde (deze waarde is altijd afkomstig van een hulpbladvariabele). Alle onderliggende <subitemelementen> moeten het kenmerk when met een unieke tekenreekswaarde bevatten. Wanneer het item wordt uitgebreid, wordt het <conditional-subitem>-element vervangen door het <subitem>-element met de overeenkomende waarde. Als er geen <subitem>-element met een overeenkomende waarde is, wordt dit door het programma gezien als een fout.

Als de hulpbladvariabele "v1" de waarde "b" heeft wanneer het volgende item wordt uitgebreid

<item ...>
  <subitem label="Hoofdstap">
     <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>
dan wordt de tweede actie geselecteerd en wordt het item ongeveer als volgt uitgebreid:
<item ...> 
  <subitem label="Hoofdstap">
     <action class="com.xyz.action2" pluginId="com.xyz" />
     </subitem>
</item>

Voorbeeld

Hieronder ziet u een voorbeeld van de inhoud van een eenvoudig hulpbladbestand waarin het gebruik van de elementen command, perform-when en conditional-subitems wordt uitgelegd.

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Voorbeeldhulpblad">
  <intro>
    <description>Een hulpblad waarin wordt uitgelegd hoe de elementen perform-when en conditional subitems worden gebruikt</description>
  </intro>
  <item title="View selecteren">
     <description>Selecteer een view die in de volgende stappen wordt geopend.</description>
     <command returns = "result"
      serialization="org.eclipse.ui.dialogs.openMessageDialog(title=View selecteren,buttonLabel0=Pakketverkenner,message=Selecteer een view,buttonLabel1=View Zoeken)"/>
      <onCompletion> View ${result} geselecteerd. </onCompletion>
</item>
  <item title="Views sluiten">
     <description>View Zoeken en Pakketverkenner sluiten als deze zijn geopend</description>
</item>
  <item title="View openen met item perform-when" skip = "true">
     <description>Gebruikt perform-when om de eerder geselecteerde view te openen.</description>
     <perform-when condition = "${result}">
           <command when = "Pakketverkenner"
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.jdt.ui.PackageExplorer)"/>
           <command when = "View Zoeken"
            serialization="org.eclipse.ui.views.showView(org.eclipse.ui.views.showView.viewId=org.eclipse.search.ui.views.SearchView)"/> 
	</perform-when>
</item>
  <item title="Views sluiten">
     <description>View Zoeken en Pakketverkenner sluiten als deze zijn geopend</description>
</item>
  <item title="View openen met item perform-when">
     <description>Gebruikt perform-when om de eerder geselecteerde view te openen.</description>
     <subitem label="Subitem perform-when" skip = "true">
     <perform-when condition = "${result}">
           <command when = "Pakketverkenner"
            serialization="org.eclipse.jdt.ui.PackageExplorer"/>
           <command when = "View Zoeken"
            serialization="org.eclipse.search.ui.views.SearchView"/>
	</perform-when>
     </subitem>
</item>
  <item title="Views sluiten">
     <description>View Zoeken en Pakketverkenner sluiten als deze zijn geopend</description>
</item>
  <item title="View openen met conditional-subitem">
     <description>Gebruikt perform-when om de eerder geselecteerde view te openen.</description>
      <conditional-subitem condition="${result}">
         <subitem when="Pakketverkenner" label="Pakketverkenner openen">
             <command serialization = "org.eclipse.jdt.ui.PackageExplorer"/>
     </subitem>
         <subitem when="View Zoeken" label="View Zoeken openen">
             <command serialization = "org.eclipse.search.ui.views.SearchView"/>
     </subitem>
     </conditional-subitem>
</item>
</cheatsheet>