Inhaltsdatei für Spickzettel im XML-Format

Version 3.2

Dieses Dokument beschreibt die Struktur der Inhaltsdatei für den Spickzettel als Reihe von DTD-Fragmenten (maschinenlesbares XML-Schema).

cheatsheet

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

Das Element <cheatsheet> definiert den Hauptteil der Inhaltsdatei für den Spickzettel. Für das Attribut <cheatsheet> gibt es folgende Attribute:

intro

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

Mit dem Element <intro> wird die Einführung in den Spickzettel beschrieben, die angezeigt werden soll. Das Unterelement <description> enthält den Hauptteil der Einführung. Für das Element <intro> werden die folgenden Attribute verwendet:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

Das Element <description> enthält die Beschreibung eines Spickzettels oder eines Spickzettelements. Die Beschreibung besteht aus Text mit einfachen Formatierungstags. Der Spickzettel formatiert den Text automatisch und ordnet ihn so an, dass er in der Benutzerschnittstelle korrekt angezeigt wird. Im Text bewirken die Tagpaare <b>...</b>, dass der eingeschlossene Text in einer Fettdruckschriftart wiedergegeben wird. Mit dem Element <br/> kann ein Zeilenumbruch erzwungen werden. Gegenwärtig werden lediglich diese Formatierungstags unterstützt (künftig werden möglicherweise jedoch weitere Tags hinzugefügt). Bestimmte Zeichen im Text haben eine besondere Bedeutung für XML-Parser. Insbesondere sollten Sie statt "<", ">", "&", "'" und """ (Fragezeichen) die Schreibweise "&lt;", "&gt;", "&amp;", "&apos;" bzw. "&quot;" verwenden. Leerräume (Leerzeichen und Zeilenumbrüche) werden als Worttrennzeichen behandelt. Benachbarte Leerzeichen und Zeilenumbrüche werden als gemeinsame Einheit betrachtet und als einfaches Leerzeichen bzw. einfacher Zeilenumbruch wiedergegeben. Ein Leerzeichen, das unmittelbar nach den Tags <description> und <br/> angegeben ist, wird ignoriert, gleiches gilt für ein Leerzeichen direkt vor dem 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
>

Jedes Element <item> beschreibt einen Schritt der höchsten Ebene im Spickzettel. Ein Element <item> kann Elemente <subitem> enthalten. Für das Element <item> gibt es folgende Attribute:

Die Erweiterung "org.eclipse.ui.cheatsheets.cheatSheetItemExtension" ermöglicht das Anzeigen zusätzlicher Steuerelemente für das Element in der Benutzerschnittstelle. Ergänzungen für diesen Erweiterungspunkt deklarieren die Namen von zusätzlichen Attributen mit Zeichenfolgewerten, die für Elemente <item> angezeigt werden können.

Einfache Elemente haben eine Beschreibung und eine optionale Aktion bzw. einen optionalen Befehl. In der normalen Darstellung werden die Titel der Spickzettelelemente meistens für den Benutzer angezeigt. Die Beschreibung eines Elements wird nur dann angezeigt, wenn der Prozess gerade ausgeführt wird. Das Vorhandensein eines Elements <action>, <command> oder <perform-when> ist normalerweise mit einer Schaltfläche verbunden, durch deren Auswahl der Benutzer die Aktion oder den Befehl des entsprechenden Schrittes ausführen kann. Wenn keine Aktion bzw. kein Befehl vorhanden ist, handelt es sich um einen Schritt, den der Benutzer manuell ausführen und anschließend angeben muss, dass der Schritt erfolgreich ausgeführt wurde.

Schritte können in Unterschritte aufgeteilt werden, die durch die Unterelemente <subitem> angegeben werden. Anders als Elemente, die der Benutzer in einer genauen Reihenfolge befolgen muss, können die Unterelemente eines Elements in einer beliebigen Reihenfolge ausgeführt werden. Alle Unterelemente innerhalb eines Elements müssen aufgerufen (oder übersprungen) werden, bevor mit dem nächsten Element fortgefahren wird. (Dies bedeutet, dass Aktionen, die in einer bestimmten Reihenfolge ausgeführt werden müssen, nicht als Unterelemente dargestellt werden können.)

Durch ein Unterelement <conditional-subitem> kann ein Schritt die Darstellung eines Unterschrittes basierend auf Spickzettelvariablen anpassen, deren Werte in vorherigen Schritten erhalten wurden. Durch ein Unterelement <repeated-subitem> kann ein Schritt eine Reihe von ähnlichen Unterschritten aufnehmen. Die genaue Gruppe der Unterschritte kann auch hier auf Spickzettelvariablen basieren, deren Werte in früheren Schritten erhalten wurden.

subitem

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

Jedes Element <subitem> beschreibt einen Unterschritt auf einem Spickzettel. Ein Element <subitem> enthält eine einfache Textmarke, jedoch keine längere Beschreibung oder weitere Unterelemente. Für das Element <subitem> gibt es die folgenden Attribute:

Unterelemente können eine optionale Aktion oder einen optionalen Befehl enthalten. Das Vorhandensein eines Elements <action>, <command> oder <perform-when> ist normalerweise mit einer Schaltfläche verbunden, durch deren Auswahl der Benutzer die Aktion oder den Befehl des entsprechenden Unterschrittes ausführen kann. Wenn keine Aktion bzw. kein Befehl vorhanden ist, handelt es sich um einen Unterschritt, den der Benutzer manuell ausführen und anschließend angeben muss, dass der Schritt erfolgreich ausgeführt wurde.

Anders als Elemente, die in einer genauen Reihenfolge befolgt werden müssen, können die Unterelemente eines jeweiligen Elements in einer beliebigen Reihenfolge ausgeführt werden. Alle Unterelemente innerhalb eines Elements müssen abgeschlossen oder übersprungen werden, bevor mit dem nächsten Element fortgefahren wird. (Dies bedeutet, dass Aktionen, die in einer bestimmten Reihenfolge ausgeführt werden müssen, nicht als Unterelemente dargestellt werden sollten.)

conditional-subitem

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

Jedes Element <conditional-subitem> beschreibt einen einzelnen Unterschritt, dessen Format abhängig von einer Bedingung variieren kann, die zum Zeitpunkt der Erweiterung des Elements bekannt ist. Für das Element <conditional-subitem> gibt es die folgenden Attribute:

Das Attribut condition für das Element <conditional-subitem> stellt einen Zeichenfolgewert zur Verfügung (dieser Wert stammt unveränderbar aus einer Spickzettelvariablen). Jedes untergeordnete Element <subitem> muss ein Attribut when mit einem distinkten Zeichenfolgewert haben. Wenn das Element erweitert wird, wird das Element <conditional-subitem> durch das Element <subitem> mit dem übereinstimmenden Wert ersetzt. Falls kein Element <subitem> mit einem übereinstimmenden Wert vorhanden ist, gilt dies als Fehler.

Beispiel: Die Spickzettelvariable namens "v1" hat den Wert "b", und das folgende Element wird erweitert:

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
  </conditional-subitem>
</item>
In diesem Fall wird das zweite Unterelement ausgewählt, und das Element wird etwa wie folgt erweitert:
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

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

Jedes Element <repeated-subitem> beschreibt ein Unterelement, das in 0, 1 oder mehr ähnliche Unterschritte erweitert wird. Es gibt folgende Attribute für das Element <repeated-subitem>:

Das Attribut values stellt eine Liste von durch Kommata getrennten Zeichenfolgen zur Verfügung. Das untergeordnete Element <subitem> stellt die Schablone bereit. Wenn das Element erweitert wird, wird das Element <repeated-subitem> durch Kopien des Elements <subitem> ersetzt, wobei die Vorkommen der Variablen "this" durch den entsprechenden Zeichenfolgewert ersetzt werden.

Beispiel: die Spickzettelvariable namens "v1" hat den Wert "1,b,three", und das folgende Element wird erweitert:

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
     </subitem>
  </repeated-subitem>
</item>
In diesem Fall wird das Element etwa wie folgt erweitert:
<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
>

Jedes Element <action> beschreibt eine Aktion auf einem Spickzettel. Für das Element <action> gibt es die folgenden Attribute:

command

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

Jedes Element <command> beschreibt einen Befehl in einem Spickzettel. Für das Attribut <command> gibt es folgende Attribute:

Das folgende Beispiel zeigt ein Element mit einem Befehl, der ein Dialogfenster öffnet und das Ergebnis in der Spickzettelvariablen "result" speichert.

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

Das Element <onCompletion> enthält Text, der angezeigt wird, nachdem ein Element abgeschlossen wurde. Dies ist besonders beim letzten Schritt des Spickzettels sinnvoll, um den Abschluss der gesamten Tasks mitzuteilen. Die Beschreibung besteht aus Text mit einfachen Formatierungstags, die dieselben Regeln wie für ein Element <description> befolgen müssen. Elemente <onCompletion> können außerdem Verweise auf Spickzettelvariablen mit dem Format  "${var}" enthalten. Diese Verweise werden unter Verwendung des tatsächlichen Werts der Spickzettelvariablen var erweitert, sobald der entsprechende Schritt abgeschlossen wurde.

perform-when

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

Jedes Element <perform-when> beschreibt eine Aktion auf einem Spickzettel. Für das Element <perform-when> gibt es die folgenden Attribute:

Das Attribut condition für das Element <conditional-subitem> stellt einen Zeichenfolgewert zur Verfügung (dieser Wert stammt unveränderbar aus einer Spickzettelvariablen). Jedes untergeordnete Element <subitem> muss ein Attribut when mit einem distinkten Zeichenfolgewert haben. Wenn das Element erweitert wird, wird das Element <conditional-subitem> durch das Element <subitem> mit dem übereinstimmenden Wert ersetzt. Falls kein Element <subitem> mit einem übereinstimmenden Wert vorhanden ist, gilt dies als Fehler.

Beispiel: Die Spickzettelvariable namens "v1" hat den Wert "b", und das folgende Element wird erweitert:

<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>
In diesem Fall wird die zweite Aktion ausgewählt, und das Element wird etwa wie folgt erweitert:
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Beispiel

Das folgende Beispiel ist eine sehr einfache Inhaltsdatei für einen Spickzettel und veranschaulicht die Verwendung von Unterelementen "command", "perform-when" und "conditional":

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