Forms Web : pages d'aide HTML contextuelles

À un moment ou un autre, dans une phase de développement d'une application, se pose la question de l'aide en ligne.

Il est difficilement concevable de livrer une application professionnelle ne disposant pas d'un système d'aide en ligne.
Cependant, les ressources mises à la disposition des équipes de développement ne permettent parfois tout simplement pas de mettre en place un tel système (sans parler de la documentation utilisateur et technique…)

Il existe certes nombre de générateurs d'aide en ligne, mais leur acquisition n'est pas toujours justifiée, et leur mise en œuvre représente souvent une charge de formation supplémentaire

Dans un mode de fonctionnement Web, la solution la plus simple à mettre en œuvre passe par la constitution d'un ou de plusieurs fichiers d'aide au format HTML.
En effet, la possibilité de placer des signets et autres liens Internet facilite grandement la navigation intra et extra document

Dans le cadre d'une application Oracle Forms, l'unique difficulté réside dans la transmission de ces signets.

L'objet de cet article est de présenter un système simple et générique qui permet d'appeler une page d'aide HTML et de pointer directement à l'endroit voulu dans cette page en transmettant le signet correspondant.

Quel que soit l'item de la forme sur lequel se trouve le focus, l'utilisateur dispose de quatre modes d'accès à son aide en ligne

• l'appui sur les touches Ctrl+Shift+F1 permet d'afficher l'aide sur l'item en cours ;
• l'appui sur les touches Ctrl+Shift+F2 permet d'afficher l'aide sur le bloc en cours ;
• l'appui sur les touches Ctrl+Shift+F3 permet d'afficher l'aide sur l'onglet en cours ;
• l'appui sur les touches Ctrl+Shift+F4 permet d'afficher l'aide sur l'écran en cours.

La mise en œuvre de ce mécanisme demande peu de travail au niveau de l'application Forms

• Ajout de quatre options de menu dans la barre de menu.
• Ajout de quatre triggers de niveau forme dans la forme.
• Ajout d'une procédure PL/SQL en librairie.

That's all Folks !!!

Il ne reste alors qu'à générer les pages HTML correspondant à vos écrans, sachant que cette tâche peut être réalisée en parallèle par une autre équipe.

Une procédure Affiche_aide() placée en librairie pour être partagée par toutes les formes de votre application

Cette procédure accepte un unique paramètre qui définit le niveau de détail souhaité

• 1 pour déterminer l'item en cours ;
• 2 pour déterminer le bloc en cours ;
• 3 pour déterminer l'onglet en cours ;
• 4 pour déterminer la forme en cours.

Voici le code de cette procédure :

PROCEDURE Affiche_aide
 (
    PN$Scope in PLS_INTEGER
 )
IS
  LC$Form    Varchar2(80)  := Lower( Name_in( 'system.current_form' ) );
  LC$Block   Varchar2(60)  := Lower( Name_in( 'system.cursor_block' ) );
  LC$Item    Varchar2(60)  := Lower( Name_in( 'system.cursor_item' ) );
  LC$TabCan  Varchar2(60) ;
  LC$Path    Varchar2(128) ;
  LC$Cmd     Varchar2(128) ;
BEGIN

LC$Path := 'file://D:/Forms9i/tools/web90/html/' ;
LC$TabCan := GET_ITEM_PROPERTY(LC$Item , ITEM_TAB_PAGE ) ;

LC$Item := Replace( LC$Item, '.', '_' ) ;

-- Constitution de l'url d'appel --
LC$Cmd := LC$Path || LC$Form || '.htm' ;    -- nom de l'écran

If PN$Scope = 1 Then
     LC$Cmd := LC$Cmd || '#' || LC$Item ;   -- signet item
End if ;

If PN$Scope = 2 Then
    LC$Cmd := LC$Cmd || '#' || LC$Block ;   -- signet bloc
End if ;

If PN$Scope = 3 Then
    LC$Cmd := LC$Cmd || '#' || LC$TabCan ;  -- signet onglet
End if ;

-- Affichage de la page HTML --
Web.show_document(LC$Cmd, '_blank') ;

Clear_message ; 

END;

Le nom de la forme et donc de la page HTML est alimenté par la variable : system.current_form.
Le nom de l'item est alimenté par la variable : system.cursor_item.
Le nom du bloc est alimenté par la variable : system.cursor_block.
Le nom de l'onglet est alimenté par la fonction : GET_ITEM_PROPERTY(LC$Item , ITEM_TAB_PAGE );

Dans cet exemple, le chemin d'accès aux fichiers HTML est indiqué en dur dans la variable : LC$Path

Dans la réalité, cette variable devrait être valorisée par un ordre Select depuis une table de paramètres
En effet, les environnements de développement, intégration et production sont rarement installés sur la même machine !

L'appel final de la page HTML est réalisé avec l'instruction Web.show_document()

Au niveau de la forme, le système n'a besoin que de quatre triggers de niveau forme pour fonctionner

• un trigger KEY-F1 avec le code pl/sql : Affiche_aide(1) ;
• un trigger KEY-F2 avec le code pl/sql : Affiche_aide(2) ;
• un trigger KEY-F3 avec le code pl/sql : Affiche_aide(3) ;
• un trigger KEY-F4 avec le code pl/sql : Affiche_aide(4).

Chacun de ces triggers appelle la procédure Affiche_aide() avec le détail souhaité.

Afin de n'utiliser que les ressources en ma possession, j'ai créé mes pages d'aide avec MSWord.

Le placement des signets ne pose aucun problème particulier, si ce n'est que le point n'étant pas permis, la syntaxe d'un signet de type item doit être : nombloc_nomitem

Un signet portant le nom de chaque onglet est placé avant chaque description d'onglet.

Un signet portant le nom de chaque bloc est placé avant chaque description de bloc.

Un signet portant le nom de chaque item est placé avant chaque description d'item.

Cet écran non basé et sans aucun sens fonctionnel n'est proposé qu'à titre d'exemple.

Il est composé d'un canvas principal hébergeant deux onglets.

Le canvas principal dispose d'un bloc maître BL1 constitué de trois items (CH1, CH2 et CH3)

L'onglet Page1 dispose d'un bloc détail BL2 constitué de trois items (CH1, CH2 et CH3)

L'onglet Page2 dispose de deux blocs détail BL3 et BL4 constitués respectivement de 3 et 4 items (CH1, CH2 et CH3 / CH1, CH2, CH3 et CH4)

Effectuons un test

Le curseur est placé sur le troisième item du premier bloc de l'onglet Page2

L'utilisateur appuie sur les touches Ctrl+Shift+F1 pour afficher l'aide sur le champ en cours

La page d'aide test_aide.htm s'ouvre alors et place le curseur au niveau du signet bl3_ch3, ce qui est bien le résultat attendu.

Certains développeurs préfèrent mettre à disposition un unique fichier d'aide regroupant la description de l'ensemble des écrans de l'application

Dans ce cas, il convient d'apporter une modification mineure à la procédure Affiche_aide() afin que celle-ci appelle toujours la même page HTML.
Et appeler cette page en passant le nom de la forme en signet.

• Un menu Forms9i en français (MENU_AIDE.MMB) contenant les options d'aide.
• Une librairie Forms9i (AIDE.PLL) contenant la procédure Affiche_aide.
• Un écran Forms9i de test (TEST_AIDE.FMB).
• Une page d'aide HTML (test_aide.htm) pour l'écran de test.

L'ensemble de ce matériel est regroupé dans le fichier archive forms_aide.zip téléchargeable ici

Chaleureux remerciements à Developpez.com et à l'équipe SGBD.