Inhalt der Spickzetteldatei im XML-Format

Version 3.0

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. <cheatsheet> Es gibt folgende Attribute für das Element:

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 Spickzetteintrags. 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;" und "&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|perform-when] | (subitem|repeated-subitem|conditional-subitem)*))> 
<!ATTLIST item 
  title               CDATA #REQUIRED
  skip                ("true" | "false") "false"
  contextId           CDATA #IMPLIED 
  href                CDATA #IMPLIED
>

Jedes Element <item> beschreibt einen Schritt der höchsten Ebene im Spickzettel. Das Element <item> ist entweder einfach oder kombiniert. <item> Es gibt folgende Attribute für das Element:

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

Einfache Einträge haben eine Beschreibung und eine optionale Aktion. In der normalen Darstellung werden die Titel der Spickzetteleinträge meistens für den Benutzer angezeigt. Die Beschreibung eines Eintrags wird nur dann angezeigt, wenn der Prozess gerade ausgeführt wird. Einem vorhandenen Element <action> (oder <perform-when>) ist in der Regel eine Schaltfläche zugeordnet, durch deren Auswahl der Benutzer die Aktion des Schrittes ausführen kann. Wenn keine Aktion 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.

Kombinierte Schritte sind in Unterschritte aufgeteilt, was durch die Unterelemente <subitem> angegeben wird. Anders als Einträge, die der Benutzer in einer genauen Reihenfolge befolgen muss, können die Untereinträge eines Eintrags in einer beliebigen Reihenfolge ausgeführt werden. Alle Untereinträge innerhalb eines Eintrags müssen aufgerufen (oder übersprungen) werden, bevor mit dem nächsten Eintrag fortgefahren wird. (Dies bedeutet, dass Aktionen, die in einer bestimmten Reihenfolge ausgeführt werden müssen, nicht als Untereinträge 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|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 Untereinträge. Für das Element <subitem> gibt es die folgenden Attribute:

Untereinträge haben eine optionale Aktion. Einem vorhandenen Element <action> (oder <perform-when>) ist in der Regel eine Schaltfläche zugeordnet, durch deren Auswahl der Benutzer die Aktion des Unterschrittes ausführen kann. Wenn keine Aktion 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 Einträge, die in einer genauen Reihenfolge befolgt werden müssen, können die Untereinträge eines jeweiligen Eintrags in einer beliebigen Reihenfolge ausgeführt werden. Alle Untereinträge innerhalb eines Eintrags müssen aufgerufen (oder übersprungen) werden, bevor mit dem nächsten Eintrag fortgefahren wird. Dies bedeutet, dass Aktionen, die in einer bestimmten Reihenfolge ausgeführt werden müssen, nicht als Untereinträge 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 Eintrags 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 der Eintrag 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 der folgende Eintrag 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 der zweite Untereintrag ausgewählt, und der Eintrag 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 einen Untereintrag, der 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 der Eintrag 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 der folgende Eintrag 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 der Eintrag 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:

perform-when

<!ELEMENT perform-when (action+)> 
<!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 der Eintrag 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 der folgende Eintrag 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" />
     </conditional-subitem>
  </subitem>
</item>
In diesem Fall wird die zweite Aktion ausgewählt, und der Eintrag 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:

<?xml version="1.0" encoding="UTF-8"?>
<cheatsheet title="Beispiel">
  <intro>
    <description>Beispielspickzettel mit zwei Schritten.</description>
  </intro>
  <item title="Schritt 1">
     <description>Dieser Schritt enthält eine Aktion.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
  </item>
  <item title="Schritt 2">
     <description>Dieser Schritt ist vollständig manuell.</description>
  </item>
</cheatsheet>