Tanti software, in aggiunta al classico manuale cartaceo, prevedono una guida in linea che spiega come utilizzare le funzionalità disponibili. La Sun mette a disposizione dei programmatori java, un tool gratuito e Java Help, che permette di creare facilmente delle guide integrabili in qualsiasi applicazione, sia desktop che Web.
Il lavoro necessario alla creazione dell'help consiste nella definizione di alcuni semplici file XML, oltre ovviamente ai file HTML, contenenti le reali pagine di descrizione del software e del suo funzionamento.
Il sito ufficiale del progetto è javahelp.dev.java.net. Scarichiamo la versione 2.0_05, scompattiamo tutto in una directory e definiamo una variabile d'ambiente, JHHOME, con il percorso della directory scelta. Inoltre aggiungiamo la directory demos/bin alla variabile d'ambiente PATH (Installazione su sistemi Windows).
In questo articolo vediamo come creare una semplicissima guida composta da tre pagine. I componenti fondamentali da creare sono i seguenti:
- Mappa: file XML che contiene l'elenco di tutte le pagine con i corrispondenti ID univoci;
- Indice: file XML con estenzione JHM, che contiene le etichette delle singole pagine della guida;
- TOC (Table Of Contents): file XML che contiene la struttura del menu della guida;
- HelpSet: file XML che contiene le informazioni generali della guida.
Il file Mappa è costituito da tanti nodi mapID, per ciascuno dei quali occorre definire due attributi obbligatori: URL, che contiene il nome del file HTML, e target, che rappresenta l'ID univoco da associare alla pagina. Il file Mappa ha una struttura simile alla seguente:
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE map PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Map Version 2.0//EN"
"http://java.sun.com/products/javahelp/map_2_0.dtd">
<map version="1.0">
<mapID target="pagina1" url="contenuti/pagina1.html"/>
<mapID target="pagina2" url="contenuti/pagina2.html"/>
<mapID target="pagina3" url="contenuti/pagina3.html"/>
</map>
Nel nostro file abbiamo definito tre pagine, pagina1, pagina2 e pagina3. Il file Indice è costituito da tanti nodi indexitem, per ciascuno dei quali occorre definire l'attributo obbligatorio text, che rappresenta il nome con il quale l'elemento apparirà nell'indice della guida. Ciascun elemento può essere facoltativamente legato a una pagina della guida utilizzando l'attributo target, il cui valore deve corrispondere a uno degli ID definiti nel file Mappa. La struttura dell'indice è ad albero e non ha limiti di profondità. Il file degli Indici ha una struttura simile alla seguente:
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE index PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 2.0//EN"
"http://java.sun.com/products/javahelp/index_2_0.dtd">
<index version="2.0">
<indexitem text="Pagina Uno" target="pagina1">
<indexitem text="Pagina Tre" target="pagina3" />
</indexitem>
<indexitem text="Pagina Due" target="pagina2" />
</index>
Il nostro indice contiene le 3 pagine precedentemente definite nel file Mappa: pagina1 e pagina2 sono due nodi principali, mentre pagina3 è un nodo figlio di pagina1.
Il file TOC è costituito da tanti nodi tocitem, per ciascuno dei quali occorre definire due attributi obbligatori: text e target, che abbiamo già visto a cosa servono. Anche in questo file è possibile utilizzare una struttura ad albero, senza limiti di profondità. Il file TOC ha una struttura simile alla seguente:
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE toc PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp TOC Version 2.0//EN"
"http://java.sun.com/products/javahelp/toc_2_0.dtd">
<toc version="2.0">
<tocitem text="Pagina Uno" target="pagina1">
<tocitem text="Pagina Tre" target="pagina3" />
</tocitem>
<tocitem text="Pagina Due" target="pagina2" />
</toc>
Il file HelpSet contiene le informazioni generali della guida. In questo file è possibile definire il titolo della guida (HtmlHelp), la home page della guida, il nome del file che contiene la mappa (map.xml), il file che contiene i contenuti (TOC - toc.xml) ed il file che contiene l'indice (index.jhm).
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE helpset PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp HelpSet Version 2.0//EN"
"http://java.sun.com/products/javahelp/helpset_2_0.dtd">
<helpset version="2.0" xml:lang="it">
<title>HtmlHelp</title>
<maps>
<homeID>pagina1</homeID>
<mapref location="map.xml"/>
</maps>
<view mergetype="javax.help.AppendMerge">
<name>TOC</name>
<label>Table of Contents</label>
<type>javax.help.TOCView</type>
<data>toc.xml</data>
</view>
<view mergetype="javax.help.AppendMerge">
<name>Index</name>
<label>Index</label>
<type>javax.help.IndexView</type>
<data>index.xml</data>
</view>
</helpset>
Per visualizzare la guida, utilizziamo un'applicazione di test inclusa nella directory demosbin di Java Help, che possiamo eseguire lanciando il seguente comando da riga di comando:
java -jar hsviewer.jar
Selezioniamo il nostro file helpset utilizzando il classico button Browse, e confermiamo. La nostra guida avrà il seguente aspetto:
