Format XML du fichier de contenu de l'aide-mémoire

Version 3.0

Le présent document décrit la structure du fichier de contenu de l'aide-mémoire sous la forme de fragments DTD (schéma XML lisible une machine).

cheatsheet

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

L'élément <cheatsheet> définit le corps du fichier de contenu de l'aide-mémoire. Les attributs <cheatsheet> sont les suivants :

intro

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

L'élément <intro> permet de décrire l'introduction de l'aide-mémoire à afficher. Le sous-élément <description> contient le corps de l'introduction. Les attributs <intro> sont les suivants :

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

L'élément <description> contient la description d'un aide-mémoire ou d'un élément de l'aide-mémoire. La description correspond à un texte associé à des balises de formatage simples. L'aide-mémoire formate et dispose automatiquement le texte afin de permettre un affichage optimal dans l'interface utilisateur. Au sein du texte, les balises <b>...</b> permettent de mettre en gras le texte qu'elles encadrent et l'élément <br/> peut être utilisé pour forcer un retour à ligne. Ces balises sont les seules balises prises en charge pour le moment. (Toutefois, d'autres pourraient être ajoutées dans le futur). Certains caractères utilisés dans le texte ont une signification particulière pour les programmes d'analyse syntaxique ; Par exemple, pour indiquer "<", ">", "&", "'" et """ (guillemet), indiquez respectivement "&lt;", "&gt;", "&amp;", "&apos;" et "&quot;". Les espaces (espaces et retours à la ligne) sont traités comme des séparateurs de mots ; Les espaces adjacents et les retours à la ligne sont traités comme des unités et apparaissent sous la forme d'un espace ou d'un retour à la ligne unique. Les espaces placés immédiatement après les balises <description> et <br/> sont ignorés tout comme ceux situés juste avant la balise </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
>

Chaque élément <item> décrit une étape de niveau supérieur dans un aide-mémoire. L'élément <item> est simple ou composé. Les attributs <item> sont les suivants :

org.eclipse.ui.cheatsheets.cheatSheetItemExtension permet de disposer d'autres options personnalisées pour l'affichage de l'élément dans l'interface utilisateur. Les contributions à ce point d'extension déclarent les noms des attributs supplémentaires (chaînes) qui peuvent apparaître pour les éléments <item>.

Les éléments simples sont associés à une description et une action facultative. Dans une présentation standard, les titres des éléments de l'aide-mémoire sont affichés. La description d'un élément apparaît uniquement lorsque l'étape est en cours d'exécution. La présence d'un élément <action> (ou <perform-when>) est généralement associé à un bouton sur lequel l'utilisateur peut cliquer pour exécuter l'action associée à l'étape. Si aucune action n'est disponible, l'étape doit être exécutée manuellement par l'utilisateur et le programme doit indiquer qu'elle s'est déroulée correctement.

Les étapes composées se divisent en sous-étapes indiquées par les sous-éléments <subitem>. Contrairement aux éléments, qui doivent être utilisés dans un ordre précis, les sous-éléments peuvent être exécutés dans n'importe quel ordre. Tous les sous-éléments d'un élément doivent être exécutés (ou ignorés) pour permettre l'accès à l'élément suivant. (Les actions qui doivent être effectuées dans un ordre déterminé ne doivent donc pas être représentées sous forme de sous-éléments.)

Un sous-élément <conditional-subitem> permet de personnaliser la présentation d'une sous-étape en fonction de variables de l'aide-mémoire, dont les valeurs sont obtenues lors des étapes précédentes. Un sous-élément <repeated-subitem> permet à une étape d'inclure un ensemble de sous-étapes identiques. De même, l'ensemble de sous-étapes peut reposer sur des variables dont les valeurs sont obtenues lors des étapes précédentes.

subitem

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

Chaque élément <subitem> décrit une sous-étape de l'aide-mémoire. Un élément <subitem> contient un libellé simple mais ne comporte pas de description détaillée ni d'autres sous-éléments. Les attributs <subitem> sont les suivants :

Les sous-éléments disposent d'une action facultative. La présence d'un élément<action> (ou <perform-when>) est généralement associé à un bouton sur lequel l'utilisateur peut cliquer pour exécuter l'action de la sous-étape. Si aucune action n'est disponible, l'étape doit être exécutée manuellement par l'utilisateur et le programme doit indiquer qu'elle s'est déroulée correctement.

Contrairement aux éléments, qui doivent être utilisés dans un ordre précis, les sous-éléments peuvent être exécutés dans n'importe quel ordre. Tous les sous-éléments d'un élément doivent être exécutés (ou ignorés) pour permettre l'accès à l'élément suivant. (Les actions qui doivent être effectuées dans un ordre déterminé ne doivent donc pas être représentées sous forme de sous-éléments.)

conditional-subitem

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

Chaque élément <conditional-subitem> décrit une sous-étape unique dont la forme peut varier en fonction d'une condition connue lorsque l'élément est développé. Les attributs <conditional-subitem> sont les suivants :

L'attribut condition de l'élément <conditional-subitem> fournit une chaîne (cette chaîne provient d'une variable de l'aide-mémoire). Chacun des enfants <subitem> doit être associé à un attribut when doté d'une chaîne distincte. Lorsque l'élément est développé, l'élément <conditional-subitem> est remplacé par l'élément <subitem> avec la chaîne correspondante. S'il n'y a pas d'élément <subitem> avec une chaîne concordante, le programme considère qu'il y a une erreur.

Par exemple, si la variable de l'aide-mémoire "v1" correspond à la chaîne "b" lorsque l'élément suivant est développé

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
  </conditional-subitem>
</item>
le second sous-élément est sélectionné et l'élément est développé sous la forme suivante :
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

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

Chaque élément <repeated-subitem> décrit un sous-élément qui comporte aucune, une ou plusieurs sous-étapes identiques. Les attributs de l'élément <repeated-subitem> sont les suivants :

L'attribut values fournit une liste de chaînes séparées par des virgules ; l'enfant <subitem> fournit le modèle. Lorsque l'élément est développé, l'élément <repeated-subitem> est remplacé par les copies de l'élément <subitem> avec les occurrences de la variable "this" remplacées par la chaîne correspondante.

Par exemple, si la variable de l'aide-mémoire "v1" correspond à la chaîne "1,b,three" lorsque l'élément suivant est développé

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz"  param1="${this}"/>
     </subitem>
  </repeated-subitem>
</item>
l'élément est développé sous la forme suivante :
<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
>

Chaque élément <action> décrit une action dans l'aide-mémoire. Les attributs <action> sont les suivants :

perform-when

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

Chaque élément <perform-when> décrit une action dans l'aide-mémoire. Les attributs de l'élément <perform-when> sont les suivants :

L'attribut condition de l'élément <conditional-subitem> fournit une chaîne (cette chaîne provient d'une variable de l'aide-mémoire). Chacun des enfants <subitem> doit être associé à un attribut when doté d'une chaîne distincte. Lorsque l'élément est développé, l'élément <conditional-subitem> est remplacé par l'élément <subitem> avec la chaîne correspondante. S'il n'y a pas d'élément <subitem> avec une chaîne concordante, le programme considère qu'il y a une erreur.

Par exemple, si la variable de l'aide-mémoire "v1" correspond à la chaîne "b" lorsque l'élément suivant est développé

<item ...>
  <subitem label="Etape principale">
     <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>
la seconde action est sélectionnée et l'élément est développé sous la forme suivante :
<item ...> 
  <subitem label="Etape principale">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Exemple

L'exemple suivant représente le fichier de contenu d'un aide-mémoire très simple :

<?xml version="1.0" encoding="UTF-8" ?>
<cheatsheet title="Exemple">
  <intro>
    <description>Exemple d'aide-mémoire comportant deux étapes.</description>
  </intro>
  <item title="Step 1">
     <description>Etape avec une action.</description>
     <action class="com.xyz.myaction" pluginId="com.xyz"/>
  </item>
  <item title="Etape 2">
     <description>Etape manuelle complète.</description>
  </item>
</cheatsheet>