HTML-BROWSER Widget and OCX Replacement¶

HTML-BROWSER Widget and OCX Replacement

Introduction¶

HTML-BROWSER widget is capable to render html pages and their associated resources loaded from absolute urls or from the file system relative to the FWD client process. It is an extension to the 4GL language and behaves as any other traditional widget. That is, it can be part of a FRAME widget, can be sized, positioned, can react to user input and so on.

The widget can load html pages from absolute urls, like "https://www.example.org", or from relative paths, like "/mywebpath/index.html". The latter case requires a mapping of the request path to the file system where the html resources are loaded from. This mapping is performed for every instance of the widget using the widget attributes CONTEXT-PATH and RESOURCE-BASE. CONTEXT-PATH defines the root request path. RESOURCE-BASE is the file path location on the system where FWD client process runs where the html resources will be located. Setting CONTEXT-PATH to "/mywebpath" and RESOURCE-BASE to "file:///wwwroot" will make the request to "mywebpath/index.html" load index.html from "/wwwroot/index.html", likewise request to "mywebpath/img/image.png" will be resolved to "/wwwroot/img/image.png" (assuming <base href="..."> is correctly set in the html page).

Note that serving of pages from local file system is currently supported only in Web GUI driver, but not in Swing GUI. The work to implement this control was done in #3768 and #3910.

4GL Syntax¶

To create the widget, use:

DEFINE VAR h AS HANDLE.
CREATE HTML-BROWSER h ASSIGN NAME = "mybrowser" CONTEXT-PATH = "/mywebpath" RESOURCE-BASE = "file:///wwwroot" FRAME = FRAME f:HANDLE VISIBLE = TRUE WIDTH = 50 HEIGHT = 20.

Where CONTEXT-PATH and RESOURCE-BASE are optional and only needed when the requested paths must resolve to local file system (local to the FWD client process).

To navigate to a html page do:

h:OPEN-WEB-PAGE("/wwwroot/index.html")
or:
h:OPEN-WEB-PAGE("https://www.example.org").

In the former case the page is loaded from local file system on the FWD client. Any links in the loaded page pointing to "/mywebpath" will resolve to the local file system at the path "/wwwroot" (since CONTEXT-PATH in the example above is set to "/mywebpath" and RESOURCE-BASE is set to "file:///wwwroot").

Attributes¶

Attribute Name	Type	Read Only	Default	Description
CONTEXT-PATH	character	no	unknown	Optional. This sets the context path for all the HTTP requests. When the HTTP request matches the context the requested resource will be resolved in the file system directory defined with `RESOURCE-BASE`. When never set or set to unknown value the effective context path will be "/<numeric widget handle>". For more information see above.
RESOURCE-BASE	character	no	unknown	Optional. This is the file system directory where HTML resources will be served from. When not assigned or set to `unknown` value the effective resource base is the working directory of the FWD client process. For more information see above.

Methods¶

Method Name	Return Type	Parameters	Description
OPEN-WEB-PAGE	logical	url:CHARACTER The url to navigate to.	Opens a HTML page. Supported schemes are `http`, `https` and `file`. When `file` scheme is specified, the pages will be served from local file system (local to FWD client process). Returns `true` if the page opens successfully, `false` otherwise.
OPEN-HTML-STRING	void	url:LONGCHAR A valid event before the user interacting with the loaded page navigates away to another page, that is when the user clicks on a html link (`<a href="page.html">`). To handle this event declare the following internal procedure in the same procedure file where the widget is created:HTML string.	Assigns the supplied HTML string to the widget.
POST-MESSAGE	void	message:LONGCHAR Any string.	Posts the supplied message to the widget as a web message. It is delivered to the content loaded in the widget using the standard DOM event handling mechanism. To handle the message use the following code snippet `window.addEventListener("message", messageHandler)`.
PRINT	void	none	Prints the opened html page.

Events¶

Event Name	Semantics	Parameter	Type	Input/Output	Description
BeforeNavigate2	The event is fired before the user interacting with the loaded page navigates away to another page, that is when the user clicks on a html link for example. Please note the event is fired only when the content is served by FWD.	DISP	COM-HANDLE	INPUT	Not used in the current implementation.
		URL	CHARACTER	INPUT	The url of the new page to be loaded.
		FLAGS	CHARACTER	INPUT	Not used in the current implementation.
		TARGETFRAMENAME	CHARACTER	INPUT	Not used in the current implementation.
		POSTDATA	CHARACTER	INPUT	Not used in the current implementation.
		HEADERS	CHARACTER	INPUT	Not used in the current implementation.
		CANCEL	LOGICAL	INPUT-OUTPUT	Set to TRUE if the navigation request is to be canceled.
OnNavigationCompleted	Fires when the content has loaded in the widget. Please note the event is fired only when the content is served by FWD.	URL	CHARACTER	INPUT	This is the URL of the content that just finished loading.
OnWebMessageReceived	Fires when the content loaded in the widget posts a message on the parent window using the `window.parent.postMessage` function.	URL	CHARACTER	INPUT	This is the URL of the content that posted the message.
OnWebMessageReceived		MSG	LONGCHAR	INPUT	The actual message.

postMessage interoperability¶

Web Client only

FWD supports incoming and outgoing postMessage traffic with the HTML-BROWSER control.
This can be used to exchange data between [A] converted 4GL code and [B] JavaScript inside the iframe of the FWD Web GUI.

When posting a message from a JavaScript served by FWD, always use window.parent as the target of the message and window.location.origin as the target origin.
1. Example: window.parent.postMessage("Hello world!", window.location.origin)
When handling the event from 4GL code subscribe the message event on the window object. Also check the origin of the message, it must equal to the origin of the FWD gui frontend. If the HTML resources are served by FWD just make sure it is equal to window.location.origin.
1. Example (implement the check yourself):
```
<script>
  window.addEventListener("message", function(event) { alert("event origin: " + event.origin + "\r\n" + "event data: " + event.data); }, false);
</script>
```

OCX Conversion¶

FWD is capable to convert OCX HTML controls with a compatible API, the following methods are supported: openWebPage, navigate2 and print.

To enable the conversion create the file <procedurefile.p>.ext-hints with the following structure. Put the file in the same directory as the procedure file <procedurefile.p>.

<extension>
   <ocx control-frame="CtrlFrame" control-frame-handle="chCtrlFrame" com-handle="chCtrlFrame:html" target-widget="html-browser" target-handle="hHtml"/>
</extension>

The xml element ocx defines the control frame (control-frame) hosting the tree control, the control handle of the control frame (control-frame-handle), com handle of the object being converted (com-handle), target widget type (target-widget) and the target tree handle for the converted tree widget (target-handle).

To give an example, the following code sample will convert with the xml configuration given above.

define variable CtrlFrame as widget-handle no-undo.
define variable chCtrlFrame as component-handle no-undo.

procedure control_load :
define variable UIB_S    as logical    no-undo.
define variable OCXFile  as character  no-undo.

OCXFile = search( "html.wrx":U ).
  assign
    chCtrlFrame = CtrlFrame:com-handle
    UIB_S = chCtrlFrame:LoadControls( OCXFile, "html":U)
  .
end procedure.

run control_load.
chCtrlFrame:html:navigate2 (...).

procedure CtrlFrame.html.BeforeNavigate2.
   ...
end procedure.

Project

General

Profile

FWD

Wiki