On-line Help

3 Eloquence Graphical User Interface

On-line Help

The Eloquence dialog server provides a mechanism which calls an external program to provide (context sensitive) on-line help.

The Eloquence dialog server relies on the popular Netscape WWW browser to provide on-line help. This makes it possible to have the on-line documentation in standard HTML format placed on a server system (running a HTTP server) or in a local directory.

As another benefit, the on-line documentation format is portable across the different systems such as HP-UX and Microsoft Windows which allows easier maintenance of the documentation files.

NOTE: This functionality requires Netscape revision 1.1 or above.

NOTE: The help mechanism built into former Eloquence dialog server releases worked different, depending on the dialog server. The motif dialog server called the HP VUE help subsystem (by executing helpview). The Microsoft Windows dialog server called the Microsoft Windows help subsystem. This implied different documentation formats from system to system. The help context passed to the external program was created from information contained in the dialog variable HelpVolume and an object specific help attribute.

NOTE: Netscape is not included with Eloquence. It can be purchased separately from Netscape Communications Corp. Netscape can either be obtained from a local distributor or may be downloaded from the anonymous ftp server of Netscape Communications Corp. at ftp.netscape.com.

The Microsoft Windows Platform

The Microsoft Windows dynamic data exchange (DDE) communication protocol is used to communicate with Netscape.

NOTE: Please refer to section The RUNSRV Utility, RUNSRV DDE Communication prior in this chapter for details about Microsoft Windows dynamic data exchange.
Additional information is provided in chapter Configuring Eloquence, section Customize the ELOQ.INI File on the PC Platform, Section [modules].

The Motif Platform

Eloquence uses the communication mechanism built in Netscape. It calls the Netscape executable passing any arguments on the command line.

Netscape will then pass the request to an already running Netscape process on the current display. If Netscape is not currently running on the display, it will be started. In order to locate the Netscape executable, the dialog server relies on the configuration item Netscape in section [dmsrv] of the eloq.ini file on the HP-UX system.

NOTE: Please refer to chapter Configuring Eloquence, section Customize the ELOQ.INI File on the HP-UX System, Section [dmsrv] for details.

Accessing the On-line Documentation

Before the on-line documentation can be accessed, two configurations are necessary:

The configuration item HelpBaseURL defines the base location of the on-line documentation. It is defined in the [dlgsrv] of the file eloqcl.ini.

Example:

HelpBaseURL = http://www/application/help/

You can think of HelpBaseURL as the on-line help document root for a specific Eloquence application. Below this root there should be separate hierarchy levels, one for each functional area inside the application.

NOTE: Please refer to chapters Configuring Eloquence, section Customize the ELOQ.INI File on the HP-UX System, Section [dlgsrv] and Configuring Eloquence, section Customize the ELOQ.INI File on the PC Platform, Section [dlgsrv] for details.

The EqHelpPath dialog variable defines the on-line document location relative to HelpBaseURL. This variable can either be set to a fixed value in your Dialog Manager dialog file, e.g.:

config variable string EqHelpPath := "accounting/Dialog.html";

Alternatively, it can be dynamically set in your Eloquence program using the DLG SET statement, e.g.:

DLG SET "EqHelpPath!value","accounting/Dialog.html"

You can think of EqHelpPath as the on-line help document hierarchy level for a specific functional area inside the Eloquence application. The objects inside this functional area should be each associated with a separate help tag in order to realize a context sensitive on-line help system.

NOTE: Please refer to section Dialog Manager, Accessing the Dialog Manager Variables later in this chapter for details.

If these prerequisites are fulfilled, a help tag can be defined for every dialog object using the .help attribute. This is normally done in your Dialog Manager dialog file, e.g.:

   window My_window
   {
      ...
      .help "#My_window";
      ...
   }

Alternatively, it can be dynamically set in your Eloquence program using the DLG SET statement, e.g.:

   DLG SET "My_window.help","#My_window"

With these settings, the final document address is composed by concatenating HelpBaseURL, EqHelpPath and My_window.help. The resulting document is:

   http://www/application/help/accounting/Dialog.html#My_window

Pressing the F1 function key or triggering an EqRule -1 will then automatically invoke the Netscape WWW browser, which in turn loads the resulting document named above.

NOTE: You can specify a different .help attribute for each dialog object in order to provide real context sensitive on-line help. However, if an object does not have a .help attribute, the parent object's .help attribute is used if present. This way, the object hierarchy is traced up to the root (window) object until a .help attribute is found.

NOTE: If you want to arrange your on-line help document hierarchy in the local file system rather than on a HTTP server, you simply define a different HelpBaseURL, e.g.:
HelpBaseURL = file://opt/application/help/

The DLG HELP Statement

The DLG HELP statement is now implemented with the dialog server. It provides access to a specific help tag as if the F1 function key had been pressed or an EqRule -1 had been triggered.

Following the example in the former section, if you issue the following statement:

   DLG HELP "#My_window"

Netscape will be invoked loading the same document as in the example above.

The EqHelpOnObject Function

This function is used internally to enable context sensitive on-line help when pressing the F1 function key or triggering an EqRule -1.

You can apply this function inside a Dialog Manager rule, e.g.:

   on WINDOW help
   {
      EqHelpOnObject(this);
   }

It cannot be applied inside a Eloquence program, since it expects an object identifier argument which Eloquence cannot provide.

This function must be declared in your Dialog Manager dialog file if you want to apply it, the declaration should look like:

   function boolean EqHelpOnObject(object input);

Please refer to the file /opt/eloquence/lib/defaults.eq, where you will find the function declaration as well as the on WINDOW help rule.

The EqHelpOnTag Function

This function is similar to the EqHelpOnObject function, except that an additional parameter must be provided which refers to a specific help tag.

You can apply this function inside a Dialog Manager rule to provide on-line help for a specific help tag, e.g.:

   on Help_on_help_button select
   {
      EqHelpOnTag(this,"#HelpOnHelp");
   }

It cannot be applied inside a Eloquence program, since it expects an object identifier parameter which Eloquence cannot provide.

This function must be declared in your Dialog Manager dialog file if you want to apply it, the declaration should look like:

   function boolean EqHelpOnObject(object input, string input);

Please refer to the file defaults.eq, where you will find the function declaration.

The EqHelpViewFile Function

You apply this function to view the contents of any text file using the Netscape WWW browser.

The configuration item FileBaseURL defines the base location of the files to be viewed. This is similar to the HelpBaseURL configuration item.

On the HP-UX system, you define FileBaseURL in section [dmsrv] of the eloq.ini file on the HP-UX system.

On the PC platform, you define FileBaseURL in section [dlgsrv] of the eloq.ini file on the PC.

Example:

   FileBaseURL = http://www/application/documents/

You can think of FileBaseURL as the root directory containing any files related to a specific Eloquence application.

The EqHelpViewFile function expects a string argument which is appended to FileBaseURL to compose the final document address.

Example:

   DLG CALL FUNCTION "EqHelpViewFile"("order.lst")

This will invoke Netscape, which in turn will load the following document:

   http://www/application/documents/order.lst

This function must be declared in your Dialog Manager dialog file if you want to apply it, the declaration should look like:

   function boolean EqHelpViewFile(string input);

Please refer to the file defaults.eq, where you will find the function declaration.

NOTE: If you want to arrange your file hierarchy in the local file system rather than on a HTTP server, you simply define a different FileBaseURL, e.g.:
FileBaseURL = file://opt/application/documents/

The EqHelpManPage Function

You apply this function to view the contents of any manual page using the Netscape WWW browser.

The configuration item ManBaseURL should be set to the location of a CGI script providing the functionality to retrieve a manual page using a search expression.

On the HP-UX system, you define ManBaseURL in section [dmsrv] of the eloq.ini file on the HP-UX system.

On the PC platform, you define ManBaseURL in section [dlgsrv] of the eloq.ini file on the PC.

Example:

   ManBaseURL = http://www/cgi-bin/man2html

The EqHelpManPage function expects a string argument which is appended to ManBaseURL to compose the final man page address.

Example:

   DLG CALL FUNCTION "EqHelpManPage"("?man")

This will invoke Netscape, which in turn will load the following document:

   http://www/cgi-bin/man2html?man

This function must be declared in your Dialog Manager dialog file if you want to apply it, the declaration should look like:

   function boolean EqHelpManPage(string input);

Please refer to the file /opt/eloquence/lib/defaults.eq, where you will find the function declaration.

Eloquence Dialog Manual - 19 DEC 2002