Document revision: 2024-10-28
Refers to WEBDLG2 version: B0840 2409-1
Table of contents
Overview
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.
Invoking the document
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).
Passing arguments
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.
Restart the application
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">
…
Starting a specific application
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.
The eloqwebd2 start document
The eloqwebd2 internal web server provides
a default start document. 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>
The $((TITLE)) token may be used to set the default
document title:
<title>$((TITLE))</title>
- $((APP))
- dynamically replaced with the
app_id specified
as last component of the document URL path
- $((TITLE))
- dynamically replaced with the
application title
Please note: The $((APP)) and $((TITLE)) tokens
are recognized within the first 8,192 bytes of the document's content.
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.4/share/webdlg2/htdocs/eq-webdlg-app.html
- Windows
- C:\Program Files\Eloquence\8.4\share\webdlg2\htdocs\eq-webdlg-app.html
Creating an application menu
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.
Conditional CSS when 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;
}
Furthermore, in the eloqwebd2.app
configuration file additional
classes may be added to the <html> document element
to style the document depending on whether specific applications are active.
For example, the rules below visually remove the menu and/or the sidebar
from the document depending on whether the nomenu and
nosidebar classes are set on the <html> document
element:
html.nomenu #menu {
display: none;
}
html.nosidebar #sidebar {
display: none;
}
Applications may then
selectively set
the nomenu and nosidebar classes.
CssClass = nomenu, nosidebar
Neither the menu nor the sidebar will be displayed while this application
is active.
CssClass = nosidebar
The menu but not the sidebar will be displayed while this application
is active.
Integrate WEBDLG2 into existing website
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.
|
