A contextual html help pages system for low budget project

Collected from: http://sheikyerbouti.developpez.com/formshtmlhelp/formshtmlhelp.htm

1.    Purpose

When you deliver an application, the job is not really complete if it is not shipped with a help system.

Sometimes, for small projects, the budget allowed does not take into account the help system.

(talking about buying a tiers robot help maker solution and formation that comes with...).

This is a solution to get an Oracle Forms contextual html help system that does not cost anything.

The help system contents only html pages that could be build with a simple html editor.

The simple mechanism is provided with html bookmarks inside.

This system provide the following benefits:

q       No third-part soft to buy

q       No special formation

q       The conception/realisation phase could be done by another team - what about the communication/artistical department ? (it’s so modern !)

q       The html system allows to use internal and external navigation mechanisms like bookmarks and hyperlinks.

2.    What is a contextual help system ?

This system allows to a user to display some help on a current topic.

In an Oracle Forms application, this could be the whole dialog, a specific canvas, block or item.

With html documents, we could use the bookmark functionality to jump anywhere we want in the page.

3.    How to call the html page and jump to the correct bookmark ?

You can assign some form-level key triggers that indicate the target topic, then use the Web.Show_Document() Forms web built-in to call the html page with the corresponding bookmark.

4.    Assign the form-level key triggers

In this example, I Assign four form-level key triggers:

q       KEY-F1 (Ctrl+Shift+F1) to get the current item help

q       KEY-F2 (Ctrl+Shift+F2) to get the current block help

q       KEY-F3 (Ctrl+Shift+F3) to get the current tab canvas help

q       KEY-F4 (Ctrl+Shift+F4) to get the current dialog help

Each trigger calling the same procedure, passing its particular argument

KEY-F1 code:  Display_Help(1) ;

KEY-F2 code:  Display_Help(2) ;

KEY-F3 code:  Display_Help(3) ;

KEY-F4 code:  Display_Help(4) ;

5.    Display the html page

To display the corresponding html page, we use the Web.Show_Document built-in.

We need to build a correct url with the page name and the corresponding bookmark.

This html page is stored in a server directory pointed in the httpd.conf or the forms.conf configuration files.

The html file name is the same as the Forms module name (with lower case).

The following code show the procedure that build the url and call the page:

PROCEDURE Display_Help

 (

    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

--------------------------------------------------------

-- Only used to test on a Developer Suite environment --

LC$Path := 'file://D:\Dev10gR2/tools/web/help/' ;

--------------------------------------------------------

LC$TabCan := GET_ITEM_PROPERTY(LC$Item , ITEM_TAB_PAGE ) ;

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

-- Build the calling url --

LC$Cmd := LC$Path || LC$Form || '.htm' ;    -- dialog name

If PN$Scope = 1 Then

     LC$Cmd := LC$Cmd || '#' || LC$Item ;   -- item bookmark

End if ;

If PN$Scope = 2 Then

    LC$Cmd := LC$Cmd || '#' || LC$Block ;   -- block bookmark

End if ;

If PN$Scope = 3 Then

    LC$Cmd := LC$Cmd || '#' || LC$TabCan ;  -- tab bookmark

End if ;

-- Display the html page --

Web.show_document(LC$Cmd, '_blank') ;

Clear_message ;

END;

 

 

 

6.    The html page content

In the corresponding html page, I added the correct bookmarks before each corresponding entry.

The html file must have the same name that the Forms module.

q       tab canvas bookmark name is the tab canvas name property

q       block bookmark name is the block name property

q       item bookmark name is build with the block name and the item name, separated with the _ (underscore) character.

7.    The sample dialog

Ø      Download the formshtmlhelp.zip file

Ø      Unzip the formshtmlhelp.zip file

Ø      Copy the help_ctx.htm file in the /forms/html/ virtual directory (see the /forms/server/forms.conf file)

Ø      Open the HELP_CTX.fmb module (Oracle Forms 10.1.2)

Ø      Compile and run the module

Place the cursor anywhere you want and call the help. (Ctrl+Shift+F1 to get the current item help)

In this example, i call the help from the EMP.SAL item