Conception d'un fichier d'aide HTML et intégration dans une application Delphi

La première étape du projet consiste tout simplement à prendre une feuille de papier et à noter en vrac tous les points devant être abordés par le système d'aide. Pour cela, il faut se mettre dans la peau d'un utilisateur découvrant le produit et se demander sur quels points il aura besoin d'informations complémentaires.

Dans votre application, l'utilisateur doit saisir son nom, son prénom, sélectionner sa date de naissance et choisir une couleur. Ce sont donc sur ces points que l'aide devra être développée. Les rubriques devant être conçues pourraient être les suivantes :

• Message de bienvenue
• Historique de l'application

• Utilisation du produit

  • Saisie du nom
  • Saisie du prénom
  • Sélection de la date de naissance
  • Choix de la couleur

Pour chaque rubrique, une page HTML devra être élaborée.

En observant les notes prises au brouillon, il est possible de distinguer deux rubriques indépendantes (Message de bienvenue et Historique de l'application) et un chapitre contenant quatre rubriques.

Dès lors, nous pouvons d'ores et déjà définir la structure du sommaire de l'aide. Cette structure sera de la forme :

Message de bienvenue
Historique de l'application
Utilisation du produit
Saisie du nom
Saisie du prénom
Sélection de la date de naissance
Choix de la couleur

Cette structure sera contenue dans le fichier Contents dont l'extension est HHC de votre projet d'aide. Nous verrons plus loin comment le concevoir.

La création des différentes rubriques d'aide se fait à l'aide de l'éditeur HTML de votre choix. Chaque rubrique () correspond à une page HTML. L'ensemble de votre système d'aide se conçoit comme un site Internet classique.

Afin de vous éviter quelques soucis, voici quelques conseils pratiques.

• Créez un modèle de page (template) et utilisez-le pour la création de toutes vos pages HTML.
• Donnez un titre explicite à chacune de vos pages HTML. Cela vous simplifiera le travail dans le compilateur.
• Si vous insérez des images dans vos pages HTML, utilisez les chemins relatifs par rapport au document et non par rapport à la racine de votre site. En effet, le compilateur ne trouvera pas vos images si vous utilisez des chemins par rapport à la racine de votre site.
• Pensez au format et aux dimensions de vos images, car plus vos images seront imposantes en taille, plus votre fichier CHM sera impressionnant en kilo-octets.

Vous venez de terminer la partie la plus longue de la création d'un fichier d'aide CHM !!!
Maintenant que vos pages HTML sont terminées, il ne vous reste plus qu'à élaborer le projet sous Microsoft HTML Help Workshop.

Un fichier d'aide HTML, dont l'extension est CHM nécessite la création de quatre fichiers distincts :

• un fichier dont l'extension est HHP : il s'agit du fichier 'projet' ;
• un fichier dont l'extension est HHC : il s'agit du fichier 'sommaire' ;
• un fichier dont l'extension est HHK : il s'agit du fichier 'index' ;
• un fichier dont l'extension est H : il s'agit du fichier où seront stockés les identifiants et les alias permettant des appels depuis Delphi.

Pour créer le fichier 'projet', il vous suffira de lancer Microsoft HTML Help Workshop, de faire |File|-|New| et de choisir 'Project' dans la liste proposée :

Un assistant apparaît vous demandant de spécifier les propriétés de votre projet :

• le premier écran vous demande s'il s'agit d'une conversion d'un projet WinHelp (16 bits) ;
• le second écran vous demande d'attribuer un nom à votre projet ;
• le troisième écran vous demande si vous avez déjà créé le fichier 'sommaire', le fichier 'index' et les fichiers HTML ;
• en l'occurrence, vous avez déjà conçu les pages HTML, cochez la troisième case ;
• le quatrième écran vous demande de spécifier les fichiers HTML à intégrer au projet. En cliquant sur le bouton [Add], une boîte de dialogue de sélection apparaît, cette boîte accepte les sélections multiples ;
  
• validez vos paramètres en cliquant sur le bouton [Terminer] ;

La fenêtre principale du compilateur apparaît.

Ne vous inquiétez pas, nous allons étudier ce compilateur au fur et à mesure du tutoriel… :-)

Avant toute chose, vous allez créer un nouveau fichier 'sommaire' et un nouveau fichier 'index'.
Pour cela, cliquez tout d'abord sur l'onglet 'Contents', la boîte de dialogue suivante apparaît :

Choisissez la première option et nommez, pour les besoins de ce tutoriel, votre fichier 'sample.hhc'.
Enfin, cliquez sur l'onglet 'Index' pour faire apparaître la boîte de dialogue ci-après dans laquelle vous choisirez la première option et vous nommerez le fichier 'sample.hhk'.

Pour les étapes suivantes, je vous laisse définir les options à sélectionner dans les différents onglets des fenêtres de paramétrage. Seules seront indiquées les étapes à suivre pour que votre fichier soit réussi.

Revenez sur le premier onglet ('Project') et cliquez sur le troisième bouton situé sur la gauche pour définir un style de fenêtre pour votre système d'aide.

Cliquez ensuite sur le premier bouton situé sur la gauche pour modifier les options du projet.

Créez maintenant le fichier dont l'extension est H pour stocker les identifiants et les alias permettant les appels depuis votre application Delphi. Ouvrez le bloc-notes de Windows et saisissez les lignes de définition sous le modèle suivant :

#define ALIAS HELPCONTEXT

Un ALIAS est un mot-clé unique qui permettra d'appeler une rubrique de l'aide.
Un HELPCONTEXT est un identifiant unique qui permettra aussi d'appeler une rubrique d'aide.

Le processus d'appel d'une rubrique d'aide peut se définir schématiquement de la manière suivante :

Ainsi, chaque rubrique devra correspondre à une ligne de définition, comme le montre l'écran suivant :

Désormais, vous pouvez cliquer sur le quatrième bouton situé sur la gauche afin de définir les alias et inclure le fichier créé dans le projet.

Pour inclure le fichier à l'extension H, cliquez sur le bouton [Header file] et sélectionnez votre fichier :

Pour la création des alias, vous devez cliquer sur l'onglet 'Alias' et créez autant d'alias que ceux qui ont été définis dans le fichier précédent :

La partie 'Project' de votre projet est terminée.

Vous allez maintenant concevoir le sommaire.

Cliquez sur l'onglet 'Contents' afin d'afficher la fenêtre suivante :

Toutes les rubriques seront créées en cliquant sur le bouton 'Insert a page' .
Tous les chapitres seront créés en cliquant sur le bouton 'Insert a heading' .

Commencez par insérer la rubrique 'Bienvenue !'. Pour cela, cliquez sur le bouton d'insertion de page. Dans cette page, il faut :

1. Affecter un nom à la rubrique ;
2. Ajouter l'URL de la page HTML à laquelle elle se réfère ;
3. Valider la saisie en cliquant sur [OK].

Toutes les rubriques seront conçues de la même manière.

La création des chapitres est sensiblement identique, à la différence qu'il n'y a, en général, pas d'ajout de page HTML.

Différentes options sont disponibles dans l'onglet 'Advanced' comme le choix des icônes pour chaque rubrique ou chapitre. Je vous laisse le soin d'étudier ces options…

Pensez à enregistrer votre sommaire régulièrement en cliquant sur le bouton 'Save File' .

Le sommaire est désormais créé. Vous touchez bientôt au but, il ne vous reste qu'à concevoir l'index…

Cliquez sur l'onglet 'Index' pour faire apparaître la fenêtre de conception suivante :

Un index est une liste de mots-clés permettant d'afficher une ou plusieurs rubriques.
Afin de bien appréhender ce concept, vous allez créer le mot-clé 'Saisie' qui se réfère à trois rubriques de votre fichier d'aide :

• Saisie du nom ;
• Saisie du prénom ;
• Saisie de la date de naissance.

Cliquez sur le bouton 'Insert a keyword' pour créer votre mot-clé. La fenêtre suivante apparaît :

Pour définir votre index, vous devez :

1. Lui attribuer un nom, en l'occurrence 'Saisie' ;
2. Lui lier une ou plusieurs pages HTML en cliquant sur le bouton [Add] ;
3. Valider la saisie en cliquant sur [OK].

Tous les mots-clés seront conçus de la même façon.

Pensez à enregistrer votre sommaire régulièrement en cliquant sur le bouton 'Save file' .

Et voilà, tous vos fichiers source sont créés, il ne reste plus qu'à compiler votre fichier CHM…

Il existe deux méthodes pour lancer la compilation.

• Méthode 1 : cliquez sur le bouton 'Compile HTML file'

  

  situé dans la barre d'outils.
  Attention, cette méthode n'enregistre pas automatiquement vos fichiers source, vous devez le paramétrer dans la boîte de dialogue qui apparaît :
  

  

• Méthode 2 : revenez sur l'onglet 'Project' et cliquez sur le bouton 'Save all files and compile' . Avec cette méthode, tous vos fichiers seront sauvegardés.

Ces deux méthodes génèrent le fichier d'aide CHM et un journal de compilation dont l'extension est LOG.
Ce journal doit impérativement être parcouru afin de vérifier si votre fichier d'aide ne comporte aucune erreur !!!

Lors du premier lancement de votre fichier d'aide, pensez à tout tester.

• Parcours dans le sommaire.
• Recherche d'un mot.
• Utilisation de l'index.
• Utilisation des favoris.
• Etc.

Félicitations, vous venez de créer votre premier fichier d'aide au format CHM. :-)))