.
Eloquence WEBDLG2 contact contact

Documentation / WEBDLG2 / HTML document configuration

HTML document configuration

 
.
  Document revision: 2022-08-15
Refers to WEBDLG2 version: PE83-2207080 (beta version 57)


Table of contents


WEBDLG2 is a single-page web application. The HTML document displaying the application user interface loads a lightweight and low-latency WebSocket communication protocol to dynamically update the document in place.

A single WEBDLG2 document may contain one active application at once. Applications may use DLG SET "Application.start" or DLG SET "System.start" to start other applications (aka. secondary sessions). This opens a new browser window/tab with the current document URL and passes the app= query string argument to start the specified application.

This is an example for a minimum WEBDLG2 document:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <script id="eq-webdlg"
            src="eq-webdlg.js">
    </script>
    <link href="eq-webdlg.css"
          rel="stylesheet" type="text/css">
    <title>
      Eloquence WEBDLG2
    </title>
    <meta name="viewport"
          content="width=device-width,initial-scale=1.0">
    <meta name="format-detection"
          content="telephone=no,date=no,address=no,email=no,url=no">
  </head>
  <body></body>
</html>


In detail:

Line 1
WEBDLG2 requires that the document is HTML5.
Line 4
WEBDLG2 requires that the document encoding is UTF-8. This must come early in the document (within the first 1024 bytes).
Lines 5..7
This loads the WEBDLG2 client Javascript code.

The eq-webdlg.js script is a tiny loader which does not measurably delay loading the document.

It should be loaded early in the document because it provides interfaces for dependencies like configuration scripts and plugins (not shown here). For this reason it should be synchronously loaded, i.e., the async or defer attributes should not be set (1).

When loaded, eq-webdlg.js triggers asynchronous loading of the WEBDLG2 user interface client (eq-webdlg-ui.js) which in turn starts the application interface worker thread (eq-webdlg-api.js).

id="eq-webdlg" is required to start the WEBDLG2 client.
Lines 8..9
This loads the WEBDLG2 client CSS rules (eq-webdlg.css).
Lines 13..14
Specifying the viewport meta tag improves the document layout on mobile browsers (2).
Lines 15..16
Specifying the format-detection meta tag disables automatic text formatting on mobile browsers. For example, the browser might wrongly display a customer identifier as telephone number or date, or an item descrition as address (3, 4, 5).
Line 18
This minimum document has an empty body. WEBDLG2 will dynamically add its Dialogs as <body> child elements.

Please note: A slightly different HTML document is required if an external web server is used.


The above minimum document does not specify which application to use, therefore the application needs to be specified when the document is invoked. For example:
http://SERVER.NAME/path/to/DOCUMENT.html?app=APPLICATION

The app= query string argument expects an application identifier (app-id). The specified application is started immediately when loading the document has completed.

Please note:

The app= query string argument takes immediate precedence over any other method mentioned below to start an application. However, the document needs to "remain neutral" to allow that a different application is started afterwards. Therefore, the app= query string argument is removed from the URL immediately when the document is invoked.

If the eloqwebd2 server cannot be connected, or if the specified app-id is not configured, or if the WEBDLG2 client protocol version does not match the connected eloqwebd2 server, the connection is silently dropped due to browser security constraints (e.g., an attacker could gain valuable information if the exact failure reason would be reported).


Additonal query string arguments may be passed to an application, for example:
http://SERVER.NAME/path/to/DOCUMENT.html?app=APPLICATION&id=1234

Here, the id argument is passed with a value of 1234.

The application may receive additional arguments as environment variables and/or as System atoms. To avoid that an attacker could set arbitrary environment variables or System atoms, arguments need to be allowed explicitly to be passed to the application.

In the eloqwebd2.app configuration file, ArgEnvAccept may be set to the arguments allowed to be passed. For example:

ArgEnvAccept = id, doc, custno

This allows to pass the id and/or the doc and/or the custno arguments as environment variables to the application. ArgEnvAccept is a comma- or space-separated list. The argument name comparison is case sensitive.

In the same way, ArgAtomAccept may be used to specify arguments allowed to be passed as System atoms. The same argument may be passed both as environment variable and as System atom.

The application then uses the GETENV$ function and/or the DLG GET "System.atom[]" statement to obtain the passed argument values, such as:

Id$=GETENV$("id")
DLG GET "System.atom[doc]",Doc$

ArgEnvPrefix may be used to specify a prefix for argument environment variables, for example to distinguish passed arguments from other variables. For example:

ArgEnvPrefix = WWW_

The application would then use GETENV$("WWW_id") to obtain the value of a passed id argument.

In the same way, ArgAtomPrefix allows to specify a prefix for argument System atoms.


To automatically restart an application when it has terminated, add the eq-restart class to the <html> document element:
<!DOCTYPE html>
<html class="eq-restart">
...

Please note: In the current implementation this causes an endless loop if the application does not start, e.g., due to a program error.


The app= query string argument may be specified for the eq-webdlg.js script to start a specific application. For example:
<script id="eq-webdlg"
        src="eq-webdlg.js?app=APPLICATION">
</script>

This way, a document becomes application-specific. The specified application is started immediately when loading the document has completed.

Please note: Invoking the document with the app= query string argument in the document URL takes precedence.


When using the eloqwebd2 internal web server to start an application, the app-id is specified as last component of the document URL path, such as:
http://SERVER.NAME/APPLICATION

To achieve this, a variant of the method described in the previous section is used, by specifying the app=$((APP)) query string argument for the eq-webdlg.js script:

<script id="eq-webdlg"
        src="eq-webdlg.js?app=$((APP))">
</script>

When the start script is invoked, the $((APP)) token is dynamically replaced with the app-id specified as last component of the document URL path.

The default eloqwebd2 start document eq-webdlg-app.html is installed in the htdocs subdirectory below the Eloquence share/webdlg2 directory:

HP-UX, Linux
/opt/eloquence/8.3/share/webdlg2/htdocs/eq-webdlg-app.html
Windows
C:\Program Files (x86)\Eloquence\8.3\share\webdlg2\htdocs\eq-webdlg-app.html


The document may contain an application menu consisting of one or multiple clickable elements. These elements need to have the eq-start class set. For example:
<button type="button"
        class="eq-start"
        data-app="APP1">
 Start application #1
</button>
<button type="button"
        class="eq-start"
        data-app="APP2">
 Start application #2
</button>

This defines two buttons to start two different applications having app-id APP1 and APP2, respectively.

If the data-app attribute is not set, the default application is used if specified.

Please note:

If a default application is specified and the document contains any eq-start element, the default application is not started immediately.

Invoking the document with the app= query string argument in the document URL takes precedence and starts the specified application immediately when loading the document has completed.

The eq-disabled class is added to the start elements while the application is active. For example, the CSS rule below hides the start elements and shows them again when the application has terminated:

.eq-start.eq-disabled {
  visibility: hidden;
}

In addition, the disabled attribute is set if applicable. For <button> elements, as used in the example above, this causes the elements to become click-insensitive while the application is active.


WEBDLG2 supports conditional CSS to style the document depending on whether or not the application is active. The eq-webdlg class is added to the <html> document element while the application is active.

For example, assumed the document contains a menu container element having the id="menu" attribute set, the CSS rule below visually removes the menu from the document while the application is active:

html.eq-webdlg #menu {
  display: none;
}


WEBDLG2 may be integrated into existing websites, provided that the documents are HTML5 (<!DOCTYPE html>) and the document encoding is UTF-8 (<meta charset="utf-8">).

The minimum requirements are that the eq-webdlg.js script and the eq-webdlg.css CSS rules are loaded into all documents where the application should be used (see above):

<script id="eq-webdlg"
        src="eq-webdlg.js">
</script>
<link href="eq-webdlg.css"
      rel="stylesheet" type="text/css">

WEBDLG2 applications may then be started in these documents, for example using an application menu.

Alternatively, the eq.start() Javascript API may be used, which allows to specify the application to start along with arguments to be passed to the application. For example:

result = eq.start("APPLICATION", {
  id     : "1234",
  doc    : "IV9876",
  custno : "A23456"
});

The first argument is an application identifier (app-id). The optional second argument is an object holding the arguments to be passed to the application.

In this example, three arguments are passed, id and doc and custno.

The eq.start() method returns true if the application has been started and false otherwise, for example if the document already has an active application.

When an application is active and the document changes, i.e., another document is loaded into the same browser window/tab, and WEBDLG2 is integrated into this document, the application is seamlessly resumed in the new document.


 
 
 
  Privacy | Webmaster | Terms of use | Impressum Revision: 2022-08-15  
  Copyright © 1995-2022 Marxmeier Software AG