See other branches for alternative versions compatible with other Omnis Studio versions.
Omnis Studio 10.22.
- Copy the jsclient_bridge folder into Omnis' htmlcontrols folder (in the application area), or html/htmlcontrols if you are using Studio 11, and wish to run the htmlcontrols using http (advised).
- Copy the following folders from Omnis' html directory of the Omnis version you are connecting to (in the writeable files section of the install) into
htmlcontrols/jsclient_bridge.
- css
- scripts
- icons
- images
- themes
- Also copy the studio folder from Omnis' iconsets folder (in the application area) into htmlcontrols/jsclient_bridge/icons.
(this jsclient_bridge folder, with JS Client resources, can now be moved around as a complete component - e.g. added to a runtime tree)
If you are using Omnis Studio 11 or later, it's advised that you set oBrowser's $htmlcontrolsusehttp property to true.
It will then load the htmlcontrols from Omnis' html/htmlcontrols folder, and serve them over HTTP, using Omnis' internal HTTP server, rather than using a file:/// URL. This avoids restrictions the browser places on pages hosted over file:/// URLs.
You will need to make sure that you added the jsclient_bridge folder, and all of the scripts etc to Omnis' html/htmlcontrols folder, rather than htmlcontrols in the root directory.
If you have set $htmlcontrolsusehttp to true, you can ignore this.
This control requires some Chromium flags to be set, in order to allow CORS inside oBrowser (to allow access to localhost from file:// URLs).
Add the following to config.json, inside the obrowser section:
"cefSwitches": [
"allow-file-access-from-files",
"disable-web-security"
]
- Add an oBrowser external component to your window.
- Set oBrowser's $urlorcontrolname property to 'jsclient_bridge'.
- Edit oBrowser's $htmlcontroloptions, and set the omnisclass, omnislibrary and serverport columns.
This will cause the form to be loaded automatically, and will also display the form in design mode.
- If you wish to load a form from another Omnis server, you'll also need to populate the webserverurl and omnisserverandport properties.
If you wish to change the form, call oBrowser's $callmethod(), passing 'loadForm' as first param, and a row with 'omnisclass' and 'omnislibrary' columns as the second param. This row could also optionally contain 'webserverurl' and/or 'omnisserverandport' cols, if you wish to load a form hosted elsewhere.
You use oBrowser's $callmethod() method to call the sendMessageToJSClient method.
This takes a Row containing a column named messageID (type Character) and a column named data (any supported type).
In order to send complex data to the client, you would make the data column type Row.
E.g:
Do lJSCMessageRow.$define(messageID, data)
Do lJSCMessageRow.$assigncols("SetCustomerDetails",iCustomersList.[iCustomersList.$line])
Do $cinst.$objs.oBrowser.$callmethod("sendMessageToJSClient",lJSCMessageRow)
If the form has not yet loaded, the message will be deferred until it has.
You must, however, wait until the CONTROL_READY message has been fired before attempting to send a message (see below).
You should implement a private class method on the remote form which oBrowser is running named htmlcontrolMessage (No '$'. It can be client- or server-executed).
This method will receive 2 parameters - the first will be the messageID passed from the fat client, and the second will be the data passed from the fat client.
You need to execute the following JavaScript code to send a message to the fat client:
jControl.callbackObject.sendMessageToFatClient(pID, pData);
- pID should be a string identifying the message.
- pData should be a supported JavaScript data type (e.g. a string, boolean, number, omnis_date. Could also be a JavaScript object containing these types (it will be converted to a row), or an omnis_raw_list or omnis_list instance.).
You would probably do this using the JavaScript: command from a client-executed method.
oBrowser's evControlEvent will be fired when the fat client receives a message from the JS client.
- pInfo.id will contain the message ID.
- pInfo.data will contain any data sent with the message.
The control sends some special messages automatically, with the following IDs:
- CONTROL_READY: The control has initialised, the web socket is connected, and you may now call methods on it.
- JSC_LOADED: The Omnis JavaScript client has loaded, along with the initial form(s).
Properties are set on oBrowser's $htmlcontroloptions property.
| Property Name | Property Value |
|---|---|
| omnislibrary | The name of the Omnis library containing the form to load automatically. (Required for automatic form loading) |
| omnisclass | The name of the Remote Form class to load automatically. (Required for automatic form loading) |
| webserverurl | The URL to the Omnis web server plugin. (Optional for automatic form loading). Omit to use the local Omnis server. |
| omnisserverandport | The $serverport or ip-address:$serverport of the Omnis server. (Optional for automatic form loading) Omit to use the local Omnis server. |
| serverport | The $serverport of Omnis. (Optional) Only used for local connections, when webserverurl is not provided. Only necessary if you've changed the htmlControlPort config.json option. |
Methods are called with oBrowser's $callMethod method.
The first parameter is the name of the method you wish to call, the second parameter is the method's parameter (it can have only one).
Sends a message to the Remote Form. The form's htmlcontrolMessage method will be called, with the passed data.
Its parameter is a Row with the following columns:
| Column Name | Type | Column Value |
|---|---|---|
| messageID | Character | An identifier for the message. |
| data | Any | The data to pass through to the JS client. Use a Row to send complex data. |
| form | Character | (Optional) The name of the form to pass the message to. If omitted, will attempt to get the active form. |
Example:
Do lRow.$define(messageID, form, data)
Do lRow.$assigncols("doSomething", "jsMyForm", iDataRow)
Do $cinst.$objs.oBrowser.$callMethod("sendMessageToJSClient", lRow)
Loads a Remote Form.
Its parameter is a Row. The column names of which will be added as "data-" attributes of the omnisobject1 element. As such, it could likely contain the following columns:
| Column Name | Type | Column Value |
|---|---|---|
| omnislibrary | Character | The name of the Omnis library containing the form. |
| omnisclass | Character | The name of the Remote Form class. |
| webserverurl | Character | (Optional) The URL to the Omnis web server plugin. Leave empty/omit to connect directly to the local Omnis instance. |
| omnisserverandport | Character | (Optional) $serverport/:$serverport of Omnis server. Leave empty if using a direct connection. |
Example:
Do lRow.$define(omnislibrary, omnisclass)
Do lRow.$assigncols("myLibrary", "jsMyForm")
Do $cinst.$objs.oBrowser.$callMethod("loadForm", lRow)
Finishes the current download requested by the client. (Requires scripts of revision 31907 or later)
The JS Client File control uses a cookie to detect when a download completes. But cookies aren't supported when using file:// URLs (as Omnis htmlcontrols do), so the client is not able to automatically detect the completion of downloads when running in the JSC Bridge.
If you are using the File control to download, you should call this method from oBrowser's evBrowserFinishedDownload event to notify the client to unlock its UI and allow further downloads.
You may also need to call it from evBrowserStartDownload, if you don't always download the file there.
Its parameter is a Row. The column names do not matter - only their order:
| Column Description | Type | Column Value |
|---|---|---|
| success | Boolean | If true, the download was successful. |
| showErrorMessage | Boolean | (Optional) If true, and 'success' is false, show an error message to the user. |
Example:
On evBrowserFinishedDownload
Do $cobj.$callmethod("forceCurrentDownloadComplete",row(pErrorText="",kTrue))