I. Introduction▲
L'API JavaHelp permet de construire aisément une documentation pour l'utilisateur final.
Site officiel : http://java.sun.com/products/javahelp/
Téléchargez JavaHelp sur le site officiel.
Ce document a pour but de présenter cette API, vous apprendre à l'utiliser pour construire un manuel et l'utiliser dans vos applications Java.
II. Autres solutions▲
La construction d'un manuel utilisateur est une étape obligée de tout projet de développement logiciel.
Plusieurs techniques sont possibles :
- un format HTML ou PDF mais avec une navigation limitée ;
- un système applicatif personnalisé, très coûteux à mettre en place ;
- réutiliser un système tierce partie, moins cher avec un temps de développement nul.
JavaHelp appartient à la 3e catégorie et a l'avantage d'être gratuit.
III. Fonctionnalités principales▲
- Aide à la navigation avec une table des matières, des index et une recherche en « full text ».
- Compression des données et encapsulation dans une archive JAR.
- Extensibilité et personnalisation : l'API JavaHelp peut être dérivée et ses fonctionnalités étendues (IHM, recherche, etc.).
- Sensibilité au contexte (grâce à Swing notamment). La fusion de plusieurs manuels est possible.
- Mise à jour automatique d'un manuel en ligne.
- Adaptabilité de l'interface utilisateur.
- Internationalisation du contenu (I18N).
IV. Atouts▲
- Il est écrit en Java, il est donc portable sur toute plateforme.
- Il peut être utilisé par des applications non Java.
V. Déploiement▲
JavaHelp peut être déployé selon plusieurs scénarios :
- en local, embarqué avec l'application qui va l'appeler. Le visualisateur JavaHelp peut être lancé dans un processus distinct de l'application ;
- en réseau, le visualisateur peut appeler des manuels distants. Cela permet d'avoir une seule source cohérente d'informations dont les mises à jour sont répercutées immédiatement ;
- une Applet peut appeler le visualisateur JavaHelpet, présenter le manuel dans un navigateur web ;
- JavaHelp peut être intégré à un serveur d'applications et utiliser son visualisateur en tant que GUI distant.
VI. Navigateur JavaHelp▲
Voici l'aspect du visualisateur de JavaHelp :
VII. Création du manuel▲
Le helpset consiste en les métadonnées ainsi que les fichiers de votre manuel.
En voici les étapes de création :
- créer les fichiers HTML contenant les sujets du manuel ;
- créer le fichier helpset (hs) ;
- créer la carte de correspondances (map) ;
- créer la table des matières (toc) ;
- créer le fichier d'index (index) * ;
- créer la base de données pour la recherche sur mot-clé * ;
- compresser et encapsuler tout ceci dans un fichier JAR à distribuer.
Les étapes 5 et 6 sont facultatives, utiles seulement si vous souhaitez intégrer à votre manuel une fonctionnalité de recherche par mot-clé dans le texte.
VIII. Visualisation du manuel▲
Pour visualiser le manuel généré, il suffit de passer le fichier helpset généré au visualisateur JavaHelp.
Exemple :
set $JAVAHELP_HOME = "c:\jh2.0\";
set $MANUEL_HOME = "c:\myHelp\";
java -jar $JAVAHELP_HOME\demos\bin\hsviewer.jar -helpset $MANUEL_HOME\monHelpSet.hsIX. Écriture du contenu du manuel▲
Un préalable à la génération de votre manuel au format JavaHelp, il faut en écrire le contenu dans des fichiers HTML. Ces fichiers seront parsés par le moteur du JRE indépendant de JavaHelp.
Les fichiers HTML doivent respecter les normes HTML 3.2 et CSS1.
X. Exemple de fichier HTML▲
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN">
<HTML>
<HEAD>
<TITLE>Préface de l'aide</TITLE>
</HEAD>
<BODY>
<H1>Ma première aide en ligne</H1>
<hr><p>Une petite introduction…</p><hr>
<ul>
<li><a href="profiles.html">Gestion de nos profils</a></li>
<li><ahref="perfs.html">Nos performances</a></li>
<li><ahref="ihm.html">Ergonomie</a></li>
</ul>
</BODY>
</HTML>XI. Le fichier HelpSet▲
Le fichier HelpSet généré portera l'extension .hs, il est le seul fichier reconnu par l'application. Il est au format XML. Il contient toutes les informations nécessaires à l'utilisation du manuel :
- la carte de correspondances (Map file) qui associe les identifiants des sujets du manuel à leur URL ou chemin de fichier respectif ;
- les informations de visualisation, c'est-à-dire la liste des composants de navigation utilisables. Ils peuvent être : la table des matières, l'index, le moteur de recherche par mots-clés, le glossaire, les favoris ;
- le titre du manuel (Helpset title) ;
- l'identifiant du sujet (Home ID) à afficher par défaut lors de l'ouverture du manuel ;
- les attributs de la fenêtre (Presentation) dans laquelle le manuel sera affiché ;
- d'autres fichiers HelpSet (Sub-helpsets) à fusionner (optionnel) ;
- d'autres informations relatives à l'implémentation d'un registre (Implementation) (optionnel).
XII. Exemple de fichier HelpSet▲
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE helpset
PUBLIC "-//Sun Microsystems Inc.//DTDJavaHelp HelpSet Version 2.0//EN"
"../dtd/helpset_2_0.dtd">
<helpsetversion="1.0">
<title>My SampleHelp -Online</title>
<maps>
<homeID>top</homeID>
<mapreflocation="Map.jhm"/>
</maps>
<view>
<name>TOC</name>
<label>Table Of Contents</label>
<type>javax.help.TOCView</type>
<data>SampleTOC.xml</data>
</view>
<view>
<name>Index</name>
<label>Index</label>
<type>javax.help.IndexView</type>
<data>SampleIndex.xml</data>
</view>
<view>
<name>Search</name>
<label>Search</label>
<type>javax.help.SearchView</type>
<dataengine="com.sun.java.help.search.DefaultSearchEngine">
JavaHelpSearch
</data>
</view>
<presentationdefault="true"displayviewimages="false">
<name>mainwindow</name>
<sizewidth="700"height="400" />
<location x="200" y="200" />
<title>My SampleHelp -Online</title>
<image>toplevelfolder</image>
<toolbar>
<helpaction>javax.help.BackAction</helpaction>
<helpaction>javax.help.ForwardAction</helpaction>
<helpaction>javax.help.SeparatorAction</helpaction>
<helpaction>javax.help.HomeAction</helpaction>
<helpaction>javax.help.ReloadAction</helpaction>
<helpaction>javax.help.SeparatorAction</helpaction>
<helpaction>javax.help.PrintAction</helpaction>
<helpaction>javax.help.PrintSetupAction</helpaction>
</toolbar>
</presentation>
<presentation>
<name>main</name>
<sizewidth="400"height="400" />
<location x="200" y="200" />
<title>My SampleHelp -Online</title>
</presentation>
</helpset>XIII. La carte de correspondances▲
La carte de correspondances contient la liste des alias et les URL ou chemins de fichiers correspondant aux sujets du manuel.
Il est au format XML et d'extension jhm. Son élément racine est map.
L'élément mapID prend les attributs suivants :
| Attribut | Description |
| target | Alias du sujet pointé |
| url | URL ou chemin de fichier du sujet |
XIV. Exemple de carte de correspondances▲
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE map
PUBLIC "-//Sun Microsystems Inc.//DTDJavaHelp Map Version 1.0//EN"
"http://java.sun.com/products/javahelp/map_1_0.dtd">
<map version="1.0">
<mapID target="toplevelfolder" url="images/toplevel.gif" />
<mapID target="top" url="help/welcome.html" />
<mapID target="intro" url="help/welcome.html" />
<mapID target="start" url="help/start.html" />
<mapID target="overview" url="help/welcome.html" />
<mapID target="one" url="help/start.html" />
<mapID target="two" url="help/start.html" />
</map>XV. La table des matières▲
La table des matières contient la liste structurée des liens vers les différents sujets du manuel.
C'est un fichier XML d'élément racine toc et porte l'extension xml. L'élément tocitem peut contenir 0 ou plusieurs autres tocitem. Un tocitem a les paramètres suivants :
| Attribut | Description |
| text | le texte qui sera affiché |
| image | une icône devant le texte |
| target | l'alias du sujet pointé |
| expand | vaut true pour forcer l'affichage des sous-items |
| presentationname | le nom d'une fenêtre définie dans HelpSet |
| presentationtype | le nom d'un type de présentation : popup ou autre |
XVI. Exemple de table des matières▲
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE toc
PUBLIC "-//Sun Microsystems Inc.//DTDJavaHelp TOC Version 2.0//EN"
"../dtd/toc_2_0.dtd">
<toc version="2.0">
<tocitem text="mon petit manuel" image="toplevelfolder">
<tocitem text="Introduction" target="intro"/>
<tocitem text="Tutoriel"target="start"expand="true">
<tocitem text="Preface" target="overview"/>
<tocitem text="chap1" target="un"/>
<tocitem text="chap2" target="deux"/>
</tocitem>
<tocitem text="Historique" target="story"/>
<tocitem text="Historique dans une autre fenêtre" target="story"
presentationtype="javax.help.SecondaryWindow"presentationname="main"/>
<tocitem text="Historique en Popup"target="story"
presentationtype="javax.help.Popup"/>
</tocitem>
</toc>XVII. L'index▲
L'index contient une liste hiérarchique de mots-clés ou de concepts-clés faisant référence à des sujets du manuel.
C'est là encore un fichier XML portant l'extension xml. Son élément racine : index. Il contient des éléments indexitem. L'élément indexitem peut contenir 0 ou plusieurs autres indexitem. Un indexitem possède les attributs suivants :
| Attribut | Description |
| text | le texte qui sera affiché |
| target | l'alias du sujet pointé |
| expand | vaut true pour forcer l'affichage des sous-items |
XVIII. Exemple d'index▲
<?xml version='1.0' encoding='ISO-8859-1' ?>
<!DOCTYPE index
PUBLIC "-//Sun Microsystems Inc.//DTD JavaHelp Index Version 1.0//EN"
"http://java.sun.com/products/javahelp/index_1_0.dtd">
<index version="1.0">
<indexitem text=".prof extension (profile data)" target="prof.profile"/>
<indexitem text="accelerators (keyboard), see 'keyboardcommands'"/>
<indexitem text="adding an existing project" expand="false">
<indexitem text="naming the project" target="proj.importdirectory"/>
<indexitem text="naming the storage directory" target="proj.importdirectory"/>
<indexitem text="procedures for" target="proj.importproject2"/>
</indexitem>
<indexitem text="arguments" expand="false">
<indexitem text="passing" target="debug.arguments"/>
<indexitem text="specifying" target="debug.arguments"/>
</indexitem>
</index>XIX. Visualisation du manuel▲
En cours de débogage, voici une méthode simple :
créez dans un répertoire $MANUEL_HOME et entreposez-y tous les fichiers cités précédemment :
| Fichier | Description |
| Map.jhm | Carte de correspondances |
| Sample.hs | Fichier HelpSet |
| SampleIndex.xml | Index |
| SampleTOC.xml | Table des matières |
| welcome.html | Page HTML par défaut du manuel |
créez un sous-répertoire help\ et copiez-y le fichier welcome.html ;
ensuite, exécutez cette ligne de commande :
java -jar $JAVAHELP_HOME\demos\bin\hsviewer.jar -helpset $MANUEL_HOME\Sample.hsXX. Archivage du manuel▲
Après cette visualisation de test, nous allons créer une archive JAR qui contiendra notre manuel :
syntaxe :
jar -cvf manuel.jar $MANUEL_HOME\*et maintenant, visualisons le manuel archivé :
java -jar $JAVAHELP_HOME\demos\bin\hsviewer.jar -helpset $MANUEL_HOME\manuel.jarXXI. Rendu final▲
Et voilà, notre manuel est opérationnel.
XXII. Création du moteur de recherche▲
Ce moteur permet de rechercher parmi les sujets du manuel des mots-clés. Les mots-clés seront mis en surbrillance dans le texte trouvé.
Pour être utilisé, il faut au préalable créer la base de données grâce à la commande jhindexer située dans le répertoire $JAVAHELP_HOME\javahelp\bin\.
Syntaxe :
$JAVAHELP_HOME\javahelp\bin\jhindexer welcome.htmlIl en résulte la création du répertoire JavaHelpSearch\ qui contient toutes les données nécessaires au moteur de recherche.
XXIII. Test de la base de recherche▲
La commande jhsearch située dans le répertoire $JAVAHELP_HOME\javahelp\bin\ permet de tester la base de recherche.
Syntaxe :
$JAVAHELP_HOME\javahelp\bin\jhsearch JavaHelpSearchIl s'affiche alors :
initialized; enter querytapez un mot-clé ou quittez en tapant « . »
XXIV. Ajout de JavaHelp à votre application▲
import java.net.*;
import javax.help.*;
import javax.swing.*;
import java.awt.event.*;
public classHelpMenu{
JFramef;
JMenuItem topics;
public HelpMenu() {
f = newJFrame("Mon application");
JMenuBar mbar = new JMenuBar();
// menus Fichier et Aide
JMenu file = new JMenu("Fichier");
JMenuhelp = newJMenu("Aide");
// ajout d'un item dans le menu Aide
help.add(topics = new JMenuItem("Aide"));
// ajout des menus à la barre de menu
mbar.add(file);
mbar.add(help);
// création des objets HelpSet et HelpBroker
HelpSet hs = getHelpSet("Sample.hs");
HelpBroker hb = hs.createHelpBroker();
// affectation de l'aide au composant
CSH.setHelpIDString(topics, "top");
// gestion des évènements
topics.addActionListener(new CSH.DisplayHelpFromSource(hb));
// attachement de la barre de menu à la fenêtre
f.setJMenuBar(mbar);
f.setSize(500, 300);
f.setVisible(true);
}
public HelpSet getHelpSet(Stringhelpsetfile) {
HelpSet hs = null;
ClassLoader cl = this.getClass().getClassLoader();
try{
URL hsURL = HelpSet.findHelpSet(cl,helpsetfile);
hs = newHelpSet(null,hsURL);
} catch(Exceptione e) {
System.out.println("HelpSet: " + ee.getMessage());
System.out.println("HelpSet: " + helpsetfile + " non trouvé");
}
return hs;
}
public static void main(String argv[]) {
new HelpMenu();
}
}XXV. Outils connexes▲
La création des fichiers de correspondances, d'index, etc. peut être générée par des outils graphiques.
XXVI. Historique▲
23 mai 2004 : création du document (27 diapos).
Agissez sur la qualité de ce document en envoyant vos critiques et suggestions à l'auteur.
Pour toute question technique, se reporter au forum Java de Developpez.com.
Reproduction autorisée uniquement pour un usage non commercial.
XXVII. Note et remerciement du gabarisateur▲
Cet article a été mis au gabarit de developpez.com. Voici le lien vers le PDF d'origine : javahelp.pdf.
Le gabarisateur remercie Claude LELOUP pour sa correction orthographique.