Omnis Technical Note TNJS0004Aug 2013

JavaScript Client Construct Row

for Omnis Studio 6.0 or above

When a form is opened and the Remote task and Remote form instances are created, Omnis passes a parameter variable of type Row to the $construct() method of the Remote task and then the Remote form (in that order). This parameter variable contains a column for each parameter of the JavaScript Client object instantiated on the client: therefore, it will include columns for OmnisLibrary and OmnisClass (as defined in your HTML file), as well as extra columns containing additional information about the client object.

The construct row variable will contain the following columns and typical values:

Column Description
OmnisLibrary <OmnisLibrayName>
OmnisClass <RemoteFormName>
param1, 2, .. 9 Up to 9 pre-defined custom parameters called param1, param2, etc, which you can add to the JavaScript Client object in your HTML page; you can add custom parameters prefixed with “data-“ to send further values to the task or form construct method
OmnisPlatform JSU, the JavaScript Client
JSscreenWidth The screen width of the client, e.g. 1280 for desktop PC
JSscreenHeight The screen height of the client, e.g. 1024 for desktop PC
JSscreenSize The initial setting of $screensize for the client, e.g. kSSZDesktop
userAgent The navigator.userAgent of the client, which usually contains the browser type and version
appName The navigator.appName of the client, i.e. the browser application name, such as “Microsoft Internet Explorer” or “Netscape”
Flags Currently indicates if the client supports animation: 1 means the browser does support animation, zero means that it does not
JStimezoneOffset offset from UTC in seconds, e.g. “120” for clients on UTC+2
ClientLocale the Locale language setting of the client, e.g. “en_GB” for clients in the UK, or “en_US” for America

The appName and userAgent columns return properties of the client browser and therefore allow you to determine which browser and version the client is using, such as whether it is a desktop or mobile browser.

Using the Construct Row Variable in your Code

If you want to use the values in this parameter variable, you can create a parameter variable of type Row in the $construct() method of your remote task or remote form which will receive the parameter variable when the task/form is constructed. To examine the values in the variable, you can set a breakpoint in the $construct() method of your remote task or remote form, open the form (using Ctrl-T), and Omnis will switch to the debugger allowing you to right-click on the variable to examine its value (in Windows 8 you will need to click on the Omnis task bar entry).

For example, many of the sample apps available in the Welcome window use the construct parameter variable to get the screen size of the client device in order to set the size and position of various controls in the initial remote form for the app. The following is the code for the $construct() method of the jsShop remote form in the Webshop app, which receives the screen size of the client device, and calls another method to setup the columns for a data grid control on the main jsShop remote form:

; $construct method containing a Parameter var called pRow of type Row; the form also contains an instance var iScreensize (Char)
Calculate iScreensize as pRow.JSScreensize
Do method setupSizes
; etc.
; code for setupSizes method
Switch iScreensize
Case kSSZjs320x480Portrait
  Do $cinst.$objs.pagePane.$objs.orderGrid.$::columnwidths.$assign("150,50,50,70")
Case kSSZjs320x480Landscape
  Do $cinst.$objs.pagePane.$objs.orderGrid.$::columnwidths.$assign("70,40,40,70")
Case kSSZjs768x1024Portrait
  Do $cinst.$objs.pagePane.$objs.orderGrid.$::columnwidths.$assign("300,75,75,175")
Case kSSZjs768x1024Landscape
  Do $cinst.$objs.pagePane.$objs.orderGrid.$::columnwidths.$assign("250,75,75,175")
  Do $cinst.$objs.pagePane.$objs.orderGrid.$::columnwidths.$assign("100,50,60,75")
End Switch

Sample app & library

There is a sample app and library to download in the JavaScript Components Gallery that shows how you can use the construct row variable: go to the gallery and select 'Construct Row'. In addition, there is more information about JavaScript remote forms and using remote tasks in the 'JavaScript Remote Forms' chapter in the 'Creating Web & Mobile Apps' manual which is available to download here from the Omnis website.