Omnis Technical Note TNWE0024 Updated Nov 2011

Using the JavaScript Client with PHP

For Omnis Studio 4/5
By Omnis Tech Support

With the introduction of Omnis Studio 5.2, there are now two options for serving remote web-based clients: the Omnis Web Client, which is a plug-in, and the Omnis JavaScript Client which uses JavaScript to render forms and controls in the user's browser and therefore does not require a plug-in. This tech note discusses using the JavaScript Client in PHP pages. (You will notice references to the Web Client in the package files which may be useful for existing users to compare, but for JavaScript client development you can ignore these references.)

Omnis JavaScript Client

With Omnis Studio 5.2 you can create remote forms based on JavaScript running on the client browser. A typical HTML-page for the JavaScript client will look like:

<html>
<head>
<title>Studio 5.2 Test</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<!-- This makes mobile device support work -->
<meta name="viewport" content="width=device-width">
<!-- The style sheets must be present in the directory /css/ -->
<link type="text/css" href="/css/omn_dlg.css" rel="stylesheet"
media="print,screen" />
<link type="text/css" href="/css/omn_menu.css" rel="stylesheet"
media="print, screen" />
<link type="text/css" href="/css/smoothness/jquery-ui-1.8.15.custom.css"
rel="stylesheet" />
<link type="text/css" href="/css/slick.grid.css" rel="stylesheet" />
<link type="text/css" href="/css/slick.columnpicker.css" rel="stylesheet"
/>
<link type="text/css" href="/css/slick.pager.css" rel="stylesheet" />
<!-- Must occur after other stylesheets e.g. jquery-ui-1.8.15.custom.css,
as it overrides values -->
<link type="text/css" href="/css/omnis.css" rel="stylesheet"/>
<!-- Omnis Studio JavaScript client scripts, must be present in the
directory /scripts/ -->
<script type="text/javascript" src="/scripts/omjsclnt.js"></script>
<script type="text/javascript" src="/scripts/omjqclnt.js"></script>
</head>
<body onload="jOmnis.onLoad()" onunload="jOmnis.onUnload()"
style="margin:0;">
<h1>Test JavaScript Client Studio 5.2</h1>
<div id="omnisobject1" WebServerUrl="http://192.168.0.4/omnis_apache"
OmnisServerAndPort="192.168.0.8:5914" OmnisLibrary="ScriptClient52_Test"
OmnisClass="rfTest" param1="A1" param2="B1" param3="C1"
param4="D1"></div>

</body>
</html>

Using the .ini-file provided, the blue lines can be created by php. Thus a complete PHP /
HTML page for the JavaScript client would be something like:

<html>
<head>
<title>Studio 5.2 Test</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<?php
$phplib = dirname(__FILE__) . '/../phpsub'
set_include_path(get_include_path() . PATH_SEPARATOR . $phplib);
require_once('OmnisWebClass.php');
$x = new OmnisWebClass('ScriptClient52_Test.ini', 'rfTest');
$params = array ("A1", "B1", "C1", "D1");
$x->set_additional_params($params);
$x->display_header_body_omnis_js('/css','/scripts','margin:0;');
?>
<h1>Test JavaScript Client Studio 5.2</h1>
<?php
$x->display_client_omnis_js();
?>

</body>
</html>

Several different options and parameters can be set, have a look at the comments in OmnisWebClass.php from line 185 onwards. In particular, you can define your own absolute path to the css and scripts directories.

Easy Reconfiguration

If the width of the remote form changes, you only need to change the appropriate parameter in the .ini-file. This will be automatically built into the code both for the Internet Explorer and for Netscape, Firefox and others.

While testing with the Omnis IDE the web browser and the Omnis App Server are usually running on the same PC. In this case you can omit the line OmnisServer = XXX; PHP will analyze the HTTP request and evaluate the client's IP address. If no IP address is provided in the .ini-file, PHP will use the client's IP address. Consequently, several developers can use the same web address from different PCs.

The OmnisXXX parameters from the .ini-file, such as the library or remote class name, can be placed after the cgi parameters. Therefore, if you enter the URL:

http://192.168.0.2/test/webclient.php?lib=TEST&class=rfTest_2&width=200

into the browser PHP will create a web page with Omnis parameters so that the remote form rfTest2 from the library TEST is displayed with a width of 200 pixels. All missing parameters will be taken from the .ini-file. This is documented in detail in the OmnisWebClass.php file.

HTTP Parameters

When analyzing the HTTP request, PHP can retrieve further parameters from the HTTP header, such as the client's browser. This can be passed as an additional parameter to the remote task in Omnis. Have a look at the Extending Omnis manual, in the 'Developing Omnis Web Application' chapter under 'Manually editing your HTML Pages. You need to add to the HTML page the following code:

; for Internet-Explorer and
<paramname = "Param1" value="myParameter = myValue">

; for Netscape and others
Param1 = "myParameter=myValue"

The class OmnisWebClass.php has built-in functionality for handling parameters. After instantiating the PHP object, and immediately before the line $x->display_plugin(); you need to create an array, fill it with data, and pass it to the instance:

$params = array ();
$params['myParam'] = 'myValue';
$params['Browser']=
$_SERVER['HTTP_USER_AGENT'];
// insert here further parameters, see below
$X->set_additional_params($params);

If access to the web page is protected with htaccess you even can retrieve the user name and password and pass that to Omnis. The following PHP code will do that:

if (isset($_SERVER['REMOTE_USER']))
$params['User1'] = $_SERVER['REMOTE_USER'];
if (isset($_SERVER['PHP_AUTH_USER']))
$params['User2'] = $_SERVER['PHP_AUTH_USER'];
if (isset($_SERVER['PHP_AUTH_PW']))
$params['Password'] = $_SERVER['PHP_AUTH_PW'];

However, this will not work if 'safe mode restrictions' are set in PHP.

Server Off-Line Recognition

Usually an Omnis App Server will remain very stable, but even then maintenance will be necessary from time to time. When the server is off-line and you call a remote form from a browser, the browser will freeze for several minutes and with the response 'Error reading the response from the WEB server'. The most frequent cause for that is - according to the experience of tech support in Hamburg - an incorrect port configuration of the Omnis App Server.

This can be avoided by using the OmnisWebClass.php class and adding a few amendments to the Omnis library. In this case, the Omnis App Server needs to be able to write into the file system of the web server. Furthermore, some 'safe mode restrictions' in PHP must be relaxed. Then the Omnis application server can, immediately after opening the library, create a file, for example with the name Semaphore_ WEBCLIENT.txt in the directory where the webclient.php is located. Upon closing the library, this file must be deleted.

The instance of OmnisWebClass.php can check whether this file exists. If not, instead of displaying the code for the Omnis plug-in, a message like '<h3>Omnis App. Server with Library "WEBCLIENT" is off-line!</h3>' is displayed. The exact text is configurable. To implement this behavior, a line must be added to the webclient.php file which informs the instance about the name of the semaphore file.

$x->set_semaphore('Semaphore_WEBCLIENT.txt');

Program Package

The class OmnisWebClass.php consists of 650 code lines, more than one third however are comments and explanations how to use. The code is not provided here, but you can download it in the .zip-archive below. In that archive you will also find this documentation, the demo library webclient.lbs (for Studio 4.3.1 non-unicode) and the files webclient.ini and webclient.php. Download the package: DynamicWebPages.zip