The main interface between your native app and Omnis.
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. |
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. |
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(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(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(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(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.
A class containing the device features supported by this app.
Name | Type |
---|---|
FeatureTypes | struct |
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) |
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(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(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() |
Get an array of the features (by ID) which are currently supported.
Parameters
None.
Returns
Type | Description |
---|---|
[String] | An array of featureID strings. |
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. |
The current settings used by the OmnisInterface.
Change these settings to alter various aspects of behaviour.
These settings are not saved to disk.
Name | Type | Description |
---|---|---|
SettingNames | struct | Contains the setting key names for built-in settings. |
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(). |
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(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(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(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() |
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.
An interface into the local database used by Omnis' $sqlobject.
Must be initialised for local database and Sync Server support to work.
None
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([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(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() |
Closes the local database resources (threads etc).
Parameters
None.
Returns
None.
Contains methods which will be called when communication messages from the JS Client are received.
Accessed via OmnisInterface's commsDelegate property.
Method Name | Description |
---|---|
messageFromJSClient(data, omnisInterface) | Called whenever a message to the app comes in from the JS Client. |
messageFromJSClient(data, omnisInterface) |
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.
}
}
}
Provides callbacks for when web navigation events occur (a page starts/end loading etc).
Accessed via OmnisInterface's webNavigationDelegate property.
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(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(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(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. |
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.
Property Name | Type | Description |
---|---|---|
delegate | OMScafHandlerDelegate | A delegate to receive callbacks regarding SCAF update progress etc. |
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(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(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.
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(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() |
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([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.
Provides callbacks regarding SCAF update progress etc.
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). |
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(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(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(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()
}
A class providing helper methods to display dialogs and loading overlays.
Everything is accessed statically.
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. |
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(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(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. |