Le pagine di aiuto sono viste speciali che consentono di guidare l'utente attraverso una serie di attività complesse per raggiungere un obiettivo globale. Ad esempio, una pagina di aiuto potrebbe essere utilizzata per aiutare l'utente attraverso tutte le fasi necessarie per la creazione, la compilazione e l'esecuzione di un semplice programma Java. Le pagine di aiuto sono avviate dal menu ?>Pagine di aiuto.... Le pagine di aiuto possono anche essere avviate da una pagina introduttiva.
Le pagine di aiuto sono definite utilizzando il punto di estensione org.eclipse.ui.cheatsheets. Il contenuto della pagina di aiuto viene definito in un file separato, in modo che possa essere convertito facilmente in altre lingue.
L'aggiunta di una pagina di aiuto è piuttosto semplice. Di seguito viene riportata una pagina di aiuto fornita dal JDT per la generazione di un'applicazione Java semplice.
<extension point="org.eclipse.ui.cheatsheets.cheatSheetContent"> <cheatsheet name="%cheatsheet.helloworld.name" contentFile="$nl$/cheatsheets/HelloWorld.xml" id="org.eclipse.jdt.helloworld"> <description>%cheatsheet.helloworld.desc</description> </cheatsheet> ...Come altri contributi del workbench, un nome, una descrizione e un id possono essere specificati per la pagina di aiuto. Il nome e la descrizione vengono visualizzati quando l'utente accede all'elenco ?>Pagine di aiuto.... Una categoria per la pagina di aiuto può essere definita anche se si desidera inserire varie pagine di aiuto in un raggruppamento logico. Se non viene specificata alcuna categoria, la pagina di aiuto viene visualizzata nella categoria Altro.
Il lavoro effettivo per le pagine di aiuto viene eseguito nel file del contenuto. Il file del contenuto è un file XML il cui nome e percorso vengono specificati nell'attributo contentFile. Il percorso del file è relativo alla directory del plugin. La variabile $nl$ viene utilizzata nel nome della directory, il che significa che il file verrà inserito in una directory specifica della lingua nazionale dell'ambiente di destinazione.
Il formato del file include informazioni di panoramica sulla pagina di aiuto seguite da una descrizione di ciascuna fase (chiamata elemento) che verrà eseguita dall'utente. Un elemento è solo una descrizione dettagliata della fase che l'utente deve intraprendere. Tuttavia, un elemento può anche specificare un'azione che può essere effettuata per eseguire la fase per conto dell'utente. Di seguito viene riportata la prima parte del file del contenuto (HelloWorld.xml) per la pagina di aiuto Java.
<?xml version="1.0" encoding="UTF-8" ?> <cheatsheet title="Simple Java Application"> <intro href="/org.eclipse.ui.cheatsheets.doc/tasks/tcheatst.htm"> <description> Benvenuti nell'applicazione Java Hello, World. Questa attività consente di generare e di provare l'applicazione "hello world". Verranno creati un progetto java ed una classe java, che visualizzerà l'applicazione "hello world" nella console al momento dell'esecuzione. Iniziamo! </description> </intro> <item href="/org.eclipse.platform.doc.user/concepts/concepts-4.htm" title="Open the Java Perspective"> <action pluginId="org.eclipse.ui.cheatsheets" class="org.eclipse.ui.internal.cheatsheets.actions.OpenPerspective" param1="org.eclipse.jdt.ui.JavaPerspective"/> <description> Selezionare Finestra->Apri prospettiva->Java nella barra dei menu nella parte superiore del workbench. Questa fase consente di modificare la prospettiva di impostazione del workbench Eclipse per lo sviluppo Java. È possibile selezionare il pulsante "Fare clic per eseguire" per fare in modo che la prospettiva "Java" venga aperta automaticamente. </description> </item> ...
Il titolo e le informazioni introduttive vengono visualizzate nella parte superiore della pagina di aiuto. Quindi, vengono descritti gli elementi. Il primo elemento della pagina di aiuto descrive come aprire la prospettiva Java. L'attributo action specifica una classe che può essere utilizzata per eseguire l'azione per conto dell'utente. La classe deve implementare IAction. Questa operazione è utile perché consente di riutilizzare le classi di azione scritte per i contributi di menu o barre degli strumenti.
La classe di azione può facoltativamente implementare ICheatSheetAction, se l'azione utilizza i parametri o deve essere consapevole della pagina di aiuto e del relativo stato. In questo caso, l'azione trasferisce una matrice di parametri ed un riferimento a ICheatSheetManager, in modo da richiedere informazioni supplementari sulla pagina di aiuto. Qualsiasi parametro necessario può essere trasferito al metodo di esecuzione dell'azione, utilizzando gli attributi paramN.
Le azioni richiamate dalle pagine di aiuto devono riportare un risultato di successo/fallimento, se l'esecuzione dell'azione non dovesse riuscire. Ad esempio, l'utente potrebbe annullare l'azione dalla relativa finestra di dialogo. Per ulteriori dettagli, fare riferimento a IAction.notifyResult(boolean).
Gli elementi non devono definire le azioni. Se l'elemento deve essere eseguito manualmente dall'utente, non è necessario specificare un'azione. Di seguito viene riportata la terza fase della pagina di aiuto Java, che indica all'utente come codificare una semplice applicazione. Quando non viene specificata alcuna azione, la descrizione dell'elemento deve indicare all'utente di premere il pulsante appropriato, una volta completata l'attività.
<item href="/org.eclipse.jdt.doc.user/tasks/tasks-54.htm" title="Add a System.out.println line in your main method"> <description> Nella classe HelloWorld, nel metodo "public static void main", aggiungere la seguente istruzione: System.out.println("Hello world!"); e salvare le modifiche. Premere quindi il pulsante di conferma. </description> </item>Altri attributi controllano se l'elemento può essere ignorato completamente e quale documento deve essere avviato se l'utente richiede aiuto durante questa fase. Fare riferimento alla documentazione relativa al punto di estensione org.eclipse.ui.cheatsheets.cheatSheetContent per una descrizione di tutti gli attributi che possono essere definiti all'interno di una pagina di aiuto.
Gli elementi secondari possono essere definiti per organizzare ulteriormente la presentazione di un elemento. A differenza degli elementi, gli elementi secondari non devono essere visitati in un determinato ordine. Gli elementi secondari possono anche definire le azioni che eseguono automaticamente le attività secondarie per l'utente. Le azioni degli elementi secondari vengono descritte nello stesso modo delle azioni degli elementi.
Le espressioni condizionali possono essere utilizzate per definire gli elementi delle pagine di aiuto il cui contenuto o comportamento dipende dal fatto che una particolare condizione sia true. Le condizioni vengono descritte nell'elemento condition di un elemento secondario utilizzando i valori arbitrari della stringa che corrispondono all'attributo when di ciascuna scelta. Le condizioni in genere fanno riferimento alle variabili delle pagine di aiuto mediante il formato ${var}, dove var fa riferimento al nome di una variabile della pagina di aiuto. Alcune esempi semplici illustrano il funzionamento delle espressioni condizionali.
Gli elementi secondari condizionali possono essere utilizzati per scegliere un elemento secondario da un elenco di elementi secondari possibili. Solo il primo elemento secondario il cui attributo when corrisponde all'attributo della condizione è incluso nella pagina di aiuto. Ad esempio:
<item ...> <conditional-subitem condition="${v1}"> <subitem when="a" label="Step for A." /> <subitem when="b" label="Step for B." /> </conditional-subitem> </item>Questo elemento specifica due possibili elementi secondari che dipendono dal valore della variabile v1. Se il valore della variabile è a, verrà incluso il primo elemento secondario. Se il valore della variabile è b, verrà incluso il secondo elemento secondario. Se la variabile non presenta alcun valore, ciò viene considerato come un errore.
Le azioni condizionali sono simili agli elementi secondari condizionali. L'elemento perform-when specifica una condizione per l'esecuzione di un'azione tra un elenco di possibili azioni. La condizione è descritta allo stesso modo, utilizzando una stringa arbitraria che spesso fa riferimento ad una variabile. L'azione il cui attributo when corrisponde alla condizione è l'unica azione che verrà eseguita. Ad esempio:
<item ...> <perform-when condition="${v1}"> <action when="a" class="com.example.actionA" pluginId-"com.example" /> <action when="b" class="com.example.actionB" pluginId-"com.example" /> </perform-when> </item>L'azione da eseguire è scelta in base al valore della variabile v1. Se la variabile non presenta un valore a o b, ciò viene considerato come un errore.
Gli elementi secondari ripetuti descrivono un elemento secondario che può estendersi in 0, 1 o più fasi secondarie simili. Le fasi secondarie sono individualizzate utilizzando la variabile speciale ${this}. Questa variabile verrà sostituita dai valori specificati nell'attributo values. L'attributo values è una stringa di valori separati da virgole. Una variabile che si estende in un elenco di valori può essere utilizzata nell'attributo values. Ad esempio:
<item ...> <repeated-subitem values="${v1}"> <subitem label="Step ${this}" /> </repeated-subitem> </item>Se il valore della variabile è 1,b,three, tre elementi secondari vengono visualizzati nella pagina di aiuto, ciascuno con un'etichetta univoca ("Step 1," "Step b," "Step three"). Nell'etichetta può essere utilizzata la variabile o il valore del parametro di azione. È possibile accedere alla pagina di aiuto da ICheatSheetManager durante l'esecuzione dell'azione.
In alcuni casi, è possibile modificare altre parti dell'UI, se la pagina di aiuto è attiva. Ad esempio, è possibile che un editor mostri note particolari, se una pagina di aiuto guida l'utente attraverso un'attività di modifica. In questo caso, un listener può essere specificato come attributo della pagina di aiuto. L'attributo del listener deve essere il nome completo di una classe Java che ha come sottoclassi CheatSheetListener. I listener ricevono una notifica insieme a un ICheatSheetEvent quando si verifica una modifica nel ciclo di vita della pagina di aiuto, ad esempio l'apertura, la chiusura o il completamento.
L'estensione org.eclipse.ui.cheatsheets.cheatSheetItemExtension può essere utilizzata per fornire gli attributi arbitrari a una pagina di aiuto preesistente. Lo scopo di questo punto di estensione è consentire ad un plugin di aggiungere pulsanti supplementari che aiuteranno l'utente in una determinata fase. Questi pulsanti supplementari vengono visualizzati accanto all'icona della guida.
Per utilizzare questo meccanismo, è possibile definire un attributo arbitrario all'interno di una definizione di elemento nel file XML della pagina di aiuto. Il nome dell'attributo verrà associato a qualsiasi attributo fornito nelle estensioni per org.eclipse.ui.cheatsheets.cheatSheetItemExtension. Per ulteriori dettagli, fare riferimento alla documentazione relativa al punto di estensione.