Formato XML del file del contenuto della pagina di aiuto

Versione 3.2

Questo documento descrive la struttura del file del contenuto della pagina di aiuto come una serie di frammenti DTD (Schema XML leggibile dalla macchina).

cheatsheet

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

L'elemento <cheatsheet> definisce il corpo del file del contenuto della pagina di aiuto. Gli attributi <cheatsheet> sono:

intro

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

L'elemento <intro> viene utilizzato per descrivere l'introduzione della pagina di aiuto da visualizzare. L'elemento secondario <description> contiene il corpo dell'introduzione. Gli attributi <intro> sono:

description

<!ELEMENT description EMPTY>
<!ATTLIST description 
>

L'elemento <description> contiene la descrizione di una pagina di aiuto o di un elemento di una pagina di aiuto. La descrizione è composta dal testo intervallato da tag di formattazione semplici. La pagina di aiuto formatta automaticamente e dispone il testo in modo che venga visualizzato in modo chiaro nell'UI. All'interno del testo, i tag bilanciati <b>...</b> fanno in modo che il testo racchiuso vengono visualizzato in neretto e l'elemento <br/> può essere utilizzato per forzare un'interruzione di riga. Si tratta degli unici tag di formattazione supportati (altri tag possono essere aggiunti in futuro). Alcuni caratteri del testo hanno un significato speciale per i parser XML; in particolare, per scrivere "<", ">", "&", "'" e """ (punto interrogativo) anziché scrivere rispettivamente "&lt;", "&gt;", "&amp;", "&apos;" e "&quot;". Spazi e interruzioni di riga vengono considerati come separatori di parole, spazi adiacenti e interruzioni di riga vengono considerati come una singola unità e visualizzati come un unico spazio o un'interruzione di riga. Gli spazi subito dopo i tag <description> e <br/> vengono ignorati, come lo spazio subito prima del 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
>

Ciascun elemento <item> descrive una fase di livello elevato di una pagina di aiuto. Un elemento <item> può contenere elementi <subitem>. Gli attributi <item> sono:

L'attributo org.eclipse.ui.cheatsheets.cheatSheetItemExtension consente altri controlli personalizzati per l'elemento da visualizzare nell'UI. I contributi a questo punto di estensione indicano i nomi di altri attributi della stringa che possono essere visualizzati negli elementi <item>.

Gli elementi semplici presentano una descrizione e un'azione o un comando facoltativo. In una presentazione tipica, i titoli degli elementi delle pagine di aiuto vengono visualizzati all'utente la maggior parte delle volte. La descrizione di un elemento viene visualizzata solo quando la fase è in corso di esecuzione. La presenza di un elemento <action>, <command> o <perform-when>) è associata a un pulsante che può essere selezionato dall'utente per eseguire l'azione o il comando dell'operazione. Se non è presente alcuna azione o comando, l'operazione deve essere eseguita manualmente dall'utente che deve quindi chiaramente indicare che l'operazione è stata completata correttamente.

Le fasi composite sono divise in fasi secondarie, come specificato dagli elementi secondari <subitem>. A differenza degli elementi, che un utente deve seguire in una determinata sequenza, gli elementi secondari di un determinato elemento possono essere eseguiti in qualsiasi ordine. Tutti gli elementi secondari all'interno di un elemento devono essere tentati (o ignorati) prima di procedere con l'elemento successivo. Ciò significa che le azioni che devono essere eseguite in una determinata sequenza non possono essere rappresentate come elementi secondari.

Un elemento secondario <conditional-subitem> consente di adattare la presentazione di una fase secondaria in base alle variabili di una pagina di aiuto, i cui valori sono stati acquisiti nelle fasi precedenti. Un elemento secondario <repeated-subitem> consente di includere in una fase un insieme di fasi secondarie simili. L'insieme di fasi secondarie può essere basato sulle variabili delle pagine di aiuto i cui valori sono stati acquisiti nei passi precedenti.

subitem

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

Ciascun elemento <subitem> descrive una fase secondaria di una pagina di aiuto. Un elemento <subitem> presenta una semplice etichetta di testo, ma non presenta alcuna descrizione o altri elementi secondari. Gli attributi <subitem> sono:

Gli elementi secondari presentano un'azione o un comando facoltativo. La presenza di un elemento <action>, <command> o <perform-when> è di solito associata a un pulsante che può essere selezionato dall'utente per eseguire l'azione o il comando dell'operazione secondaria. Se non è presente alcuna azione o comando, l'operazione secondaria deve essere eseguita manualmente dall'utente che deve quindi chiaramente indicare che l'operazione è stata completata correttamente.

A differenza degli elementi, che un utente deve seguire in una determinata sequenza, gli elementi secondari di un determinato elemento possono essere eseguiti in qualsiasi ordine. Tutti gli elementi secondari all'interno di un elemento devono essere completati (o ignorati) prima di procedere con l'elemento successivo. Ciò significa che le azioni che devono essere eseguite in una determinata sequenza non devono essere rappresentate come elementi secondari.

conditional-subitem

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

Ciascun elemento <conditional-subitem> descrive una singola fase secondaria il cui formato può essere diverso in base a una condizione conosciuta al momento dell'espansione dell'elemento. Gli attributi <conditional-subitem> sono:

L'attributo condition dell'elemento <conditional-subitem> fornisce il valore di una stringa (questo valore deriva da una variabile della pagina di aiuto). Ciascun elemento secondario <subitem> deve presentare un attributo when con un valore di stringa diverso. Quando l'elemento viene esteso, l'elemento <conditional-subitem> viene sostituito dall'elemento <subitem> con il valore corrispondente. Se non esiste alcun elemento <subitem> con un valore corrispondente, ciò viene considerato un errore.

Ad esempio, se la variabile della pagina di aiuto denominata "v1" presenta il valore "b" quando viene esteso l'elemento

<item ...> 
  <conditional-subitem condition="${v1}">
     <subitem when="a" label="Step for A." />
     <subitem when="b" label="Step for B." />
  </conditional-subitem>
</item>
viene selezionato il secondo elemento secondario e l'elemento viene esteso a qualcosa di equivalente a
<item ...> 
  <subitem label="Step for B."/>
</item>

repeated-subitem

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

Ciascun elemento <repeated-subitem> descrive un elemento secondario che si estende in 0, 1 o più fasi secondarie. Gli attributi <repeated-subitem> sono:

L'attributo values fornisce un elenco di stringhe separate da virgole, l'elemento secondario <subitem> fornisce il modello. Quando l'elemento viene esteso, l'elemento <repeated-subitem> viene sostituito dalle copie dall'elemento <subitem> con ricorrenze della variabile "this" sostituite dal valore della stringa corrispondente.

Ad esempio, se la variabile della pagina di aiuto denominata "v1" presenta il valore "1,b,three" quando viene esteso l'elemento

<item ...> 
  <repeated-subitem values="${v1}">
     <subitem label="Step ${this}.">
        <action class="com.xyz.myaction" pluginId="com.xyz" param1="${this}"/>
     </subitem>
  </repeated-subitem>
</item>
l'elemento si estende in qualcosa di simile a:
<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
>

Ciascun elemento <action> descrive un'azione di una pagina di aiuto. Gli attributi <action> sono:

command

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

Ogni elemento <command> descrive un comando in una pagina di aiuto. Gli attributi dell'elemento <command> sono:

Di seguito è riportato un esempio di elemento con un comando che apre una finestra di dialogo e che memorizza il risultato nella variabile della pagina di aiuto "result".

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

L'elemento <onCompletion> contiene il testo che verrà visualizzato una volta completato un elemento. Ciò è particolarmente utile nell'operazione finale della pagina di aiuto per sapere che l'intera attività è stata completata. La descrizione è composta dal testo intervallato da tag di formattazione semplici che seguono le stesse regole valide per l'elemento <description>. Gli elementi <onCompletion> possono contenere riferimenti a variabili di pagine di aiuto con formato  "${var}", che verranno espansi utilizzando il valore corrente della variabile var nel momento in cui è stata completata l'operazione.

perform-when

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

Ciascun elemento <perform-when> descrive un'azione di una pagina di aiuto. Gli attributi <perform-when> sono:

L'attributo condition dell'elemento <conditional-subitem> fornisce il valore di una stringa (questo valore deriva da una variabile della pagina di aiuto). Ciascun elemento secondario <subitem> deve presentare un attributo when con un valore di stringa diverso. Quando l'elemento viene esteso, l'elemento <conditional-subitem> viene sostituito dall'elemento <subitem> con il valore corrispondente. Se non esiste alcun elemento <subitem> con un valore corrispondente, ciò viene considerato un errore.

Ad esempio, se la variabile della pagina di aiuto denominata "v1" presenta il valore "b" quando viene esteso l'elemento

<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>
viene selezionata la seconda azione e l'elemento viene esteso a qualcosa di equivalente a
<item ...> 
  <subitem label="Main step">
     <action class="com.xyz.action2" pluginId="com.xyz" />
  </subitem>
</item>

Esempio

Di seguito è riportato un esempio di file di contenuto di una pagina di aiuto semplice che dimostra l'uso degli elementi commands, perform-when e 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>