Forms Web : pages d'aide HTML contextuelles

A 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 oeuvre représente souvent une charge de formation supplémentaire

Dans un mode de fonctionnement Web, la solution la plus simple à mettre en oeuvre 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 4 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 oeuvre de ce mécanisme demande peu de travail au niveau de l'application Forms

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

That's all Folks !!!

Dans la mesure ou ces objets sont positionnés dans votre forme de référence, cette technique ne demande alors aucun travail supplémentaire pour fonctionner !

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 );


L'application MSWord n'acceptant pas le point (.) dans un signet, il est remplacé par un tiret de soulignement(_) pour séparer le nom du bloc de celui de l'item

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 4 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

La page d'aide doit porter le même nom que l'écran Forms

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'exmple

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


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


L'onglet Page1 dispose d'un bloc détail BL2 constitué de 3 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

N'oubliez pas de placer une version exécutable des modules (.fmx, .mmx et .plx) dans un des répertoires mappés dans la variable FORMS90_PATH du fichier forms90.conf

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