API Reference

OmnisInterface

The main interface between your native app and Omnis.

Statics

Property Name Type Description
DEVICE_ID String A read-only unique identifier for this device. May be reset if the app is uninstalled then later re-installed.

Properties

Property Name Type Description
features Features Contains the device features this app supports.
settings settings The current settings used by the interface.
database LocalDBController
scafHandler ScafHandler Controls access to and features of offline forms.
viewController UIViewController The View Controller the OmnisInterface was initialised with.
webNavigationDelegate OMWebNavigationDelegate The delegate which receives page navigation events from the webview.
commsDelegate OMCommsDelegate The delegate which receives messages from the JS Client.

Methods

Method Name Description
init(webviewContainer, [viewController, settings]) Constructor: Initialises the interface, and creates a webview within the container.
loadURL(url, [withParams]) Loads the passed URL in the attached webview.
callJS(jsString, [completionHandler]) Executes the passed JS string in the webview. Optional callback with result.
callJSFunctionText(functionText, [params, completionHandler]) Executes the passed JS function text in the webview (inside an IIFE). Optional callback with result.

 

 

init()

init(webviewContainer, [viewController, settings])

Constructor: Initialise the OmnisInterface, ready to be used.
This must be called before you can interact with the OmnisInterface.

Parameters

Name Type Description
webviewContainer OMWebContainer! A UIView with class OMWebContainer, which will be used to host the Omnis JS Client. It must have no child views.
viewController (Optional) UIViewController? The viewController on which the OmnisInterface may attach new views (e.g. for barcode scanning, dialogs, image pickers, etc). If nil, will attempt to find the webviewContainer's ViewController.
settings (Optional) Settings Initial Settings to use with the OmnisInterface. If nil, a default set of Settings will be created during initialization.

Returns

None.

loadURL()

loadURL(url, [withParams])

Loads the passed URL in the attached webview.
Use this to load your Remote Form.

Parameters

Name Type Description
url URL The URL to load.
withParams Dictionary A Dictionary of String names and values to set as URL Query parameters. These will be received as a JSON string, in the form's $construct row (first parameter to $construct - make it of type Row)

Returns

None.

 

callJS()

callJS(jsString, [completionHandler])

Executes the passed JS code in the webview. Calling an optional completion handler once complete.
If called from a background thread, this will be posted to run on the main thread as soon as possible.

Parameters

Name Type Description
jsString String! The JS code to execute.
completionHandler (Optional)
func (Any?, Error?) -> Void
A handler to be called with the results of the execution.

Returns

None.

Example

omnisInterface.callJS("12 + 7", completionHandler: {(result, error) in
    print(result!)
})

 

callJSFunctionText()

callJSFunctionText(functionText, [params, completionHandler])

Executes the passed JS function text in the webview (inside an IIFE). Calling an optional completion handler once complete.
If called from a background thread, this will be posted to run on the main thread as soon as possible.
Used to call a callback function provided with a device message request.

Parameters

Name Type Description
functionText String The JS Function content to run.
params [String] An array of params, expressed as strings, to be used as raw JS, to pass to the function.Any String values must be surrounded in extra (escaped) quotes.
completionHandler (Any?, Error?) -> Void A handler to be called with the results of the execution.

Returns

None.

  
 
 

Features

A class containing the device features supported by this app.

Statics

Name Type
FeatureTypes struct

 

FeatureTypes

Contains constant values for the built-in features.

Key                          Description
NATIVE_DIALOGS The app supports the overriding of Omnis' JS dialogs with native dialogs. (It handles the "showDialog" message sent to the Comms delegate. The OmnisInterface does by default)
SHOW_PDF The app supports displaying PDFs. (It handles the "showPDF" message sent to the Comms delegate. The OmnisInterface does by default)
PRINT_PDF The app supports printing of PDFs. (It handles the "printPDF" message sent to the Comms delegate. The OmnisInterface does by default)
STORED_PREFS The app supports a native implementation for storing preferences, rather than using localStorage in JS. (It handles the "savePref" & "loadPref" messages sent to the Comms delegate. The OmnisInterface does by default)

Methods

Method Name Description
addFeature(featureID) Add a feature to the list of supported features.
removeFeature(featureID) Remove a feature from the list of supported features.
getFeatures() Get an array of the features (by ID) which are currently supported.
hasFeature(featureID) Checks whether a feature has been enabled.

 
 

addFeature()

addFeature(featureID)

Add a feature to the list of supported features.

Parameters

Name Type Description
featureID String A string denoting the feature to add. May be a custom String, or a FeatureTypes value.

Returns

None.

removeFeature()

removeFeature(featureID)

Remove a feature from the list of supported features.

Parameters

Name Type Description
featureID String A string denoting the feature to remove. May be a custom String, or a FeatureTypes value.

Returns

None.

getFeatures()

getFeatures()

Get an array of the features (by ID) which are currently supported.

Parameters

None.

Returns

Type Description
[String] An array of featureID strings.

hasFeature()

hasFeature(featureID)

Checks whether a feature has been enabled.

Parameters

Name Type Description
featureID String The ID of the feature you wish to check. May be a custom String, or a FeatureTypes value.

Returns

Type Description
Bool Whether the feature is enabled.

 

Settings

The current settings used by the OmnisInterface.

Change these settings to alter various aspects of behaviour.

These settings are not saved to disk.

Statics

Name Type Description
SettingNames struct Contains the setting key names for built-in settings.

 

SettingNames

Contains the setting key names for built-in settings.

Key Description
USE_LOCAL_TIME If true, when running in offline mode, dates will not be converted to UTC during transmission (online mode reads from remote task's $localtime property).
EXPECT_SCAFS If true, give an error if SCAF files are not found initially. Must be set before calling initScafController().

 

Methods

Method Name Description
setSetting(name, value) Sets the value for a named setting.
setSettings(dictionary) Sets multiple settings from a provided Dictionary.
getSetting(name, defaultValue) Gets the current value for a named setting.
resetSettings() Resets the settings to their default initial values.

setSetting()

setSetting(name, value)

Sets the value for a named setting.

Parameters

Name Type Description
name String! The name of the setting to apply. Could be a SettingNames value, or a custom string. Overwrites any existing setting with the same name.
value Any The value for the setting.

Returns

None.

setSettings()

setSettings(dictionary)

Sets multiple settings from a provided Dictionary.

Parameters

Name Type Description
settings Dictionary A Dictionary of key-values. The keys should refer to setting names (e.g. SettingNames values)

Returns

None.

getSetting()

getSetting(name, defaultValue)

Gets the current value for a named setting.

Parameters

Name Type Description
name String! The name of the setting whose value should be returned.
defaultValue Any? A default value to return in the event that the setting was not found.

Returns

Type Description
Any? The value for the specified setting (or the default value).

resetSettings()

resetSettings()

Resets the settings to their default initial values, i.e. any custom settings will be removed, and the built-in settings will be reverted to their initial values.

Parameters

None.

Returns

None.


 
 

LocalDBController

An interface into the local database used by Omnis' $sqlobject.

Must be initialised for local database and Sync Server support to work.

Properties

None

Methods

Method Name Description
initLocalDatabase([dbName]) Initialises local Database and Sync Server support.
sendLocalDBRequest(request) Adds a database request to the queue. Only for use with the payload sent to the Comms delegate's "ExecuteSQL" message.
close() Closes the local database resources (threads etc).

 
 

initLocalDatabase()

initLocalDatabase([dbName])

Initialises local Database and Sync Server support. This must be called in order for the JS Client's local database support to work (and the associated request spooling thread, etc).

Parameters

Name Type Description
dbName String The name (including ".db" extension) for the local SQLite database to be used. If not provided, "local.db" will be used by default.

Returns

None.

sendLocalDBRequest()

sendLocalDBRequest(request)

Adds a database request to the queue. Only for use with the payload sent to the Comms delegate's "ExecuteSQL" message. Once executed, the results will be sent back to the JS Client's omnis_sql_callbackFromWrapper (internal) method. So this is not suitable for making general SQL requests from outside the JS Client.

Parameters

Name Type Description
request String! A JSON string describing the database request.

Returns

None.

close()

close()

Closes the local database resources (threads etc).

Parameters

None.

Returns

None.

 
 

OMCommsDelegate

Contains methods which will be called when communication messages from the JS Client are received.

Accessed via OmnisInterface's commsDelegate property.

Methods

Method Name Description
messageFromJSClient(data, omnisInterface) Called whenever a message to the app comes in from the JS Client.

  

messageFromJSClient

messageFromJSClient(data, omnisInterface)

Called whenever a message to the app comes in from the JS Client. It should return a boolean denoting whether the default handling (if any) should occur for this message.

Parameters

Name Type Description
data [String: AnyObject] The JSON data passed with the message. For built-in messages, this will usually contain an "ID" (String) member, a "data" member (usually [String: AnyObject]), and often a "retID" (String - a JS function to call to pass the results back to the JS Client)
omnisInterface OmnisInterface The OmnisInterface which is calling this delegate.

Returns

Type Description
Bool True if default handling for this message should occur. False if you've handled it yourself and do not want default behaviour.

iOS Example

extension MyClass: OMCommsDelegate
{
  func messageFromJSClient(data: [String:AnyObject], omnisInterface: OmnisInterface) -> Bool!
  {
    let ID = data["ID"] as? String // The ID for the message action.
    switch ID
    {
        case "myMessage"?:
          // Handle a custom message
          let theMessage = data["myKey"] as? String ?? ""
          handleMyMessage(theMessage)
          return true // We've handled this message
        default:
          return false // We've not handled the message - allow the default handling to try.
    }
  }
}

 

 

 

 

OMWebNavigationDelegate

Provides callbacks for when web navigation events occur (a page starts/end loading etc).

Accessed via OmnisInterface's webNavigationDelegate property.

Methods

Method Name Description
omnisBeginLoading(webView, navigation) Called when the webview begins loading a page.
omnisLoadingComplete(webView, navigation) Called when the webview successfully completes loading of a page.
omnisLoadingFailed(webView, navigation, error) Called when the webview fails to load a page.

 
 

omnisBeginLoading()

omnisBeginLoading(webView, navigation)

Called when the webview begins loading a page.

Parameters

Name Type Description
webView WKWebView The webview
navigation WKNavigation The navigation object which initiated the page load.

Returns

Type Description
Bool True if you have handled the event, or false if you wish default handling to occur. Default handling is to add a loading overlay to the webView.

omnisLoadingComplete()

omnisLoadingComplete(webView, navigation)

Called when the webview successfully completes loading of a page.

Parameters

Name Type Description
webView WKWebView The webview.
navigation WKNavigation The navigation object which initiated the page load.

Returns

Type Description
Bool True if you have handled the event, or false if you wish default handling to occur. Default handling is to remove any loading overlay from the webView.

omnisLoadingFailed()

omnisLoadingFailed(webView, navigation, error)

Called when the webview fails to load a page.

Parameters

Name Type Description
webView WKWebView The webview.
navigation WKNavigation The navigation object which initiated the page load.
error Error The error that occurred.

Returns

Type Description
Bool True if you have handled the event, or false if you wish default handling to occur. Default handling is to remove any loading overlay from the webView & show an OK message with the error.

ScafHandler

A class used to administer the handling of SCAFs (Serverless Client Application Files), and functionality to do with running offline forms.

The only instance of this you will need will be accessed via your OmnisInterface's scafHandler property.

Properties

Property Name Type Description
delegate OMScafHandlerDelegate A delegate to receive callbacks regarding SCAF update progress etc.

Static Methods

Method Name Description
deleteOfflineFiles(atSubfolder) Deletes any offline files from the specified folder.
moveOfflineFiles(fromSubfolder, toSubfolder) Moves all of the offline files from one folder to another.

 

deleteOfflineFiles()

deleteOfflineFiles(atFolder)
deleteOfflineFiles(atFolder, context)

Deletes the specified folder (relative to the app's Documents directory)

Parameters

Name Type Description
atSubfolder String A relative path to the folder to delete. E.g. "subfolder/moreFiles"
context Context The Context from which to resolve the file paths.

Returns

Type Description
Bool Whether the directory was successfully found & deleted.

moveOfflineFiles()

moveOfflineFiles(fromSubfolder, toSubfolder) throws
moveOfflineFiles(fromSubfolder, toSubfolder, context) throws

Moves the contents of a subfolder (relative to Documents directory) to another subfolder.
The destination folder must not exist.
Throws an Error on failure.

Parameters

Name Type Description
fromSubfolder String A relative path to the folder to delete. E.g. "subfolder/moreFiles"
toSubfolder String A relative path to the folder to move to. Must not exist.
context Context The Context from which to resolve the file paths.

Returns

None.

Methods

Method Name Description
initScafController(inSubfolder, formName, scafName, omnisWebUrl, [omnisServer, omnisPlugin]) Initialise the SCAF controller, to enable offline mode. This must be called before other (non-static) methods.
updateScafs() Query the configured Omnis server for any updates. Any available updates will be downloaded and applied.
loadOfflineForm([queryParams]) Load the configured offline form.

  

initScafController()

initScafController(inSubfolder, formName, scafName, omnisWebUrl, [omnisServer, omnisPlugin])

Initialise the SCAF controller, to enable offline mode. This must be called before other (non-static) methods.

Parameters

Name Type Description
inSubfolder String A path (relative to the app's Documents directory) in which the app's offline files will be stored. E.g. "offlineForm"
formName String The name of the offline form (including ".htm" extension)
scafName String The App SCAF name (usually lower-cased version of the library name)
omnisWebUrl String The URL to the Omnis server, or web server. (If using a web server, you must provide omnisServer and omnisPlugin params below)
omnisServer String If provided, the route to the Omnis server from the web server plugin.
omnisPlugin String If provided, the relative URL to the web server plugin, from the root of the web server.

Returns

None.

Example

omnis omnisInterface.scafHandler.initScafController( inSubfolder: "offline", formName: "jsOffline.htm", scafName: "myapp", omnisWebUrl: "https://mysite.com", omnisServer: "192.168.1.123:9816", omnisPlugin: "/omnis_apache")

Example

omnis omnisInterface.scafHandler.initScafController( inSubfolder = "offline", formName = "jsOffline.htm", scafName = "myapp", omnisWebUrl = "https://mysite.com", omnisServer = "192.168.1.123:9816", omnisPlugin = "/omnis_apache")

updateScafs()

updateScafs()

Updates SCAFs from the Omnis server configured in initScafController().
OMScafHandlerDelegate methods will be called with results.

Parameters

None.

Returns

None. (OMScafHandlerDelegate methods will be called with results)

loadOfflineForm()

loadOfflineForm([queryParams])

Load the configured offline form.

Parameters

Name Type Description
queryParams Map<String, String> A Map of key-value pairs to send as URL query parameters. These can be obtained from the Remote Form by using the JavaScript: command to call:
jOmnis.getURLParameters()
This will return a JSON object containing these keys & values.

or

Name Type Description
queryParams [String: String] A dictionary of key-value pairs to send as URL query parameters. These can be obtained from the Remote Form by using the JavaScript: command to call:
jOmnis.getURLParameters()
This will return a JSON object containing these keys & values.

Returns

None.

 
 
 

OMScafHandlerDelegate

Provides callbacks regarding SCAF update progress etc.

Methods

Method Name Description
onScafHandlerError(errorText, action) (Optional) Called when an error occurs during the SCAF update/extraction process.
onScafUpdateCompleted(didUpdate, withErrors, newHtmlPath) (Optional) Called when the SCAF update process completes (possibly with errors).
onOfflineModeConfigured(htmlPath) Called when offline mode is first ready (either around startup time if offline files are already present, or after a successful SCAF update).

Enumerations

ScafAction

An enum containing the various actions the ScafHandler may execute.
Used in specifying which action failed when onScafHandlerError is called.

Key Description
Unknown No specific action.
CheckFiles Checking for local HTML files or SCAF.
ExtractSCAF Extracting a SCAF.
ReadSCAF Reading the contents of a SCAF.
AccessForm Accessing the offline form.
UpdateSCAFs Updating SCAFs from the Omnis server.

 
 
 

onScafHandlerError()

onScafHandlerError(errorText, action)

(Optional) Called when an error occurs during the SCAF update/extraction process.

Parameters

Name Type Description
errorText String A description of the error which has occurred.
action ScafAction The action which failed.

Returns

Type Description
Bool True if you have handled the error, false if you wish default handling to occur. Default handling varies based on the action, but will generally show an OK message, or print a message to the console.

onScafUpdateCompleted()

onScafUpdateCompleted(didUpdate, withErrors, newHtmlPath)

(Optional) Called when the SCAF update process completes (possibly with errors).

Parameters

Name Type Description
didUpdate Bool Whether an update occurred. If this is false, and withErrors is empty, then no updates were available.
withErrors [String] An array of error strings for any errors which occurred.

Returns

Type Description
Bool True if you have handled the message, false for default behaviour to occur. Default behaviour is to show an OK message with the results (Success, failure with errors, or no updates available).

Example

func onScafUpdateCompleted(didUpdate: Bool!, withErrors: [string]?, newHtmlPath: String!) -> Bool
{
  if (withErrors.count == 0)
  {
    let message = didUpdate ? "Update successful" : "No updates available"
    OMDialogs.showOKMessage(message: message, title: "SCAF Update")
  }
  else {
    OMDialogs.showOKMessage(message: withErrors.componentsJoined(by: ", "), title: "SCAF Update Error")
  }
  self.offlineFormPath = newHtmlPath
}

onOfflineModeConfigured()

onOfflineModeConfigured(htmlPath)

Called when offline mode is first ready (either around startup time if offline files are already present, or after a successful SCAF update).

Parameters

Name Type Description
htmlPath String The path to the directory containing the offline form. Each time a SCAF update occurs, this will change (to avoid caching issues). Use the updated value passed to onScafUpdateCompleted to update any references you are keeping to this.

Returns

None.

Example

func onOfflineModeConfigured(htmlPath: String!) {
  self.offlineDir = htmlPath
  self.omnisInterface.scafHandler.loadOfflineForm()
}

 
 
 

OMDialogs

A class providing helper methods to display dialogs and loading overlays.

Everything is accessed statically.

Static Properties

Name Type Description
LOADING_OVERLAY_FONT UIFont The font used for text on loading overlays. Defaults to UIFont.systemFont.
LOADING_OVERLAY_TEXT_SIZE CGFloat The text size used for loading overlays. Defaults to 16.
LOADING_OVERLAY_TEXT_COLOR UIColor The color used for text on loading overlays. Defaults to white.

Static Methods

Method Name Description
showOKMessage(message, title)
showOKMessage(context, message, title, callback)
Show a dialog with a single 'OK' button.
showDialog(message, title, buttons) showDialog(context, message, title, buttons) Show a dialog with a list of defined buttons.
showYesNoMessage(message, title, onYes, onNo)
showYesNoMessage(context, message, title, onYes, onNo)
Show a dialog with 'Yes' and 'No' buttons, with a handler for each.
showDialogForOmnisInterface(omnisInterface, data) A helper function to show a dialog using the JSON data provided by the JS client for such dialogs.
showLoadingOverlay(onView, text, cancelAppearsAfter, cancelHandler)
showLoadingOverlay(context, onViewID, inLayout, text, cancelAppearsAfter, cancelHandler)
Adds a dark loading overlay to a view.

Blurs the background, and shows a centered Activity Indicator and optional text.
removeLoadingOverlay(onView) removeLoadingOverlay(onViewID, inLayout) Removes any loading overlay from the passed view.

  

 

showLoadingOverlay()

showLoadingOverlay(context, onViewID, inLayout, [text, cancelAppearsAfter, cancelHandler])

Adds a loading overlay to a view.
Blurs the background, and shows a centered Activity Indicator with optional text and cancel handler.

Parameters

Name Type Description
context Context The Context in which to execute.
onViewID Int The Resource ID of the view to which the overlay should be added.
inLayout ConstraintLayout The layout which contains the view which should be overlaid. (Currently only ConstraintLayout is supported)
text String? A message to display on the overlay.
cancelAppearsAfter Long Number of milliseconds to wait before showing a cancel button. Set to less than 0 for no cancel button to appear.
cancelHandler () → Boolean Callback function to call when the cancel button is pressed. Return false from this if you wish the overlay to be removed automatically.

Returns

None.

Styling

The colour of the overlay background and text can be overridden by adding color xml resources named "omnis_loading_overlay_background" and "omnis_loading_overlay_text" to your project.

Similarly, the text size can be altered by adding a dimen xml resource named "omnis_loading_overlay_text_size".

showLoadingOverlay()

showLoadingOverlay(onView, [text, cancelAppearsAfter, cancelHandler])

Adds a loading overlay to a view.
Blurs the background, and shows a centered Activity Indicator with optional text and cancel handler.

Parameters

Name Type Description
onView UIView The view to which the overlay should be added.
text String? A message to display on the overlay.
cancelAppearsAfter Long Number of milliseconds to wait before showing a cancel button.Set to less than 0 for no cancel button to appear.
cancelHandler () → Bool Callback function to call when the cancel button is pressed. Return false from this if you wish the overlay to be removed automatically.

Returns

None.

Styling

The appearance of the loading overlay can be edited by changing the following static properties of OMDialogs:

Name Type Description
LOADING_OVERLAY_FONT UIFont The font used for text on loading overlays. Defaults to UIFont.systemFont.
LOADING_OVERLAY_TEXT_SIZE CGFloat The text size used for loading overlays. Defaults to 16.
LOADING_OVERLAY_TEXT_COLOR UIColor The color used for text on loading overlays. Defaults to white.