Appworks-js NPM

appworks.js

What is appworks.js?

appworks.js is a javascript (TypeScript) library for building feature rich, hybrid enterprise apps. The OpenText AppWorks platform provides mobile and desktop clients that support apps that utilize appworks.js.

In a mobile environment the library provides access to on-device technology, and in the desktop environment some features of the underlying host OS (operating system) are exposed.

Supported platforms:

mobile
- iOS
- Android
desktop
- Windows
- OSX
- Linux

A limited number of appworks.js plugins are available in the desktop environment. They are marked in the API Usage and Examples section and are listed for quick reference below:

Update Notes

v22.3.2

Fixed return type issues in Cache, DesktopStorage, OnDeviceStorage.

v22.3.1

Added updateLastModifiedDate(path: string, date: Date, successCallback: (result: boolean) => void, errorCallback?: (result: Error) => void ) to update the last modified date of the specified file path with the supplied Date.

v22.3.0

Now Desktop Clients can use AWComponent to listen for close event using registerAppClose() method in AWComponent.
Only two methods of AWComponent i.e registerAppClose() and closeApp() are available to use for Desktop Clients.

v16.7

Import updates for AWCache, please see AWCache changes for 16.7 within the AWCache section
New first run methods added to AWAppManager

Installation

NPM:

npm install appworks-js --save

Yarn

yarn add appworks-js

Bower:

bower install --save appworks-js

You can find the production files in the dist directory.

Auto install:

If you are deploying an app to the gateway, the gateway will automatically add appworks.min.js to the root of your project. If you opt to use the bundled file make sure your script tag looks like this:

<script src="appworks.min.js"></script>

API Usage and Examples

Events
- Battery

API Usage and Examples

Plugin

All plugins have the following type definition:

abstract class AWPlugin {
    successHandler: () => void;
    errorHandler: () => void;
    /**
     * Base plugin class. Constructor takes in a success function and error function to be executed upon
     * return from call to native layer
     * @param successHandler - the function to be executed when the native call succeeds. passes an object as arg
     * @param errorHandler - the function to be executed when the native call fails. passes an object as arg.
     */
    constructor(successHandler: any, errorHandler: any) {
        this.successHandler = successHandler;
        this.errorHandler = errorHandler;
    }
}

This means that whenever creating a new Plugin object, you must initialize it with your success and error callbacks. When the call to the native layer succeeds or fails, your handler will get executed. If you require a new callback to be executed, create a new object. Plugin objects extend AWPlugin and are listed below, under the subcategory Plugin.

For example:

var camera = new Appworks.AWCamera(onSuccess, onFail);

function onSuccess(data) {
    console.log(data);
    // do something with data
}

function onFail(err) {
    console.log(err);
}

camera.takePicture();

Note: if you are using angularJS, $scope.$apply() calls will need to be made in your callbacks to ensure that scope variables and the DOM get updated.

AWAuth

* available on desktop

The Auth plugin allows you to seamlessly authenticate against your backend. Useful for refreshing tokens and gaining access rights to make api calls against the gateway.

Methods:

authenticate

authenticate(force?:boolean)

Makes a call against the gateway /auth endpoint. Returns the response to the callback registered upon creation of the instance

force: when a truthy value is passed, the client will force a reauthentication by the user.

Example:

var auth = new Appworks.Auth(
    function (data) {
        // got the response, now make backend api calls
        var response = data.data;
        $.ajax({
            method: 'POST',
            url: response.gatewayUrl + '/v1/content/nodes/1234/children',
            headers: { otcsticket: response.addtl.otcsticket },
            data: { foo: bar }
        });
    },
    function (err) {
        // could not complete authentication request
        console.log(err);
    }
);

$('#click-me').click(function () {
    auth.authenticate();
});

getAuthResponse

Marked for depreciation
Use authenticate(boolean?), which will get the auth object if the session is valid, 
else it will refresh the auth object and return the new auth object.

getAuthResponse()

Returns the auth response to the callback registered upon creation of the instance without sending a reauthentication request.

Example:

var auth = new Appworks.Auth(
    function (data) {
        // got the response, now make backend api calls
        var response = data.data;
        $.ajax({
            method: 'POST',
            url: response.gatewayUrl + '/v1/content/nodes/1234/children',
            headers: { otcsticket: response.addtl.otcsticket },
            data: { foo: bar }
        });
    },
    function (err) {
        // could not complete authentication request
        console.log(err);
    }
);

$('#click-me').click(function () {
    auth.getAuthResponse();
});

gateway

gateway(successHandler: any, errorHandler?: any)

Returns the url of the gateway to the successHandler passed in.

online

online(successHandler: any, errorHandler?: any)

Returns a boolean value based on the current network connection, visibility of the gateway and if the user has signed in online (not with offline pin)

Example:

var auth = new Appworks.Auth();
var weAreOnline = false;

$('#click-me').click(function () {
    auth.online(function(status) {
      // Will return true if the device is connected to a network/data, the gateway is responsive to us, and the user is not logged in with the offline pin.
      // Otherwise this will return false.
      weAreOnline = status;
    }, function(error) {
      // Error function calls in the event an error.
      console.log(error);
    });
});

otdsssoticket

otdsssoticket(successHandler: any, errorHandler?: any)

Added so that clients connected to an OAuth2 based gateway are able to specifically request an OTDS SSO Ticket for legacy systems.

If the property "otdsticket" is not in the auth object returned in Auth.authenticate(boolean?), then you are using an OAuth2 setup.

Request an OTDS SSO Ticket by calling this function. It will return the ticket in this functions successHandler, and it will then be in available in the Auth.authenticate(boolean?) response for the life of the OAuth token.

Upon expiry of the OAuth2 session, a new OTDS SSO Ticket must be requested.

Example

function getOtdsSsoTicket() {
  // Create the Auth instance as normal
  var auth = new Appworks.Auth(function(response){}, function(error){});

  // Call otdsssoticket with a success handler and an error handler
  auth.otdsssoticket(function(ticket) {
    // "ticket" is the OTDS SSO Ticket
    console.log("Got Ticket: " + ticket);
  }, function(error) {
    console.log("Error: " + error);
  });
}

Non OAuth2 systems can still use this method, it will simply return the current OTDS SSO Ticket available from Auth.authenticate(boolean?).

AWWebView

* available on desktop The web view plugin allows you to open links via the in-app browser. This is great for giving your app a native feel when opening external links. On Desktop, this plugin allows you to open urls either in the system browser, or a new BrowserWindow.

Note: on Desktop, addEventListener and removeEventListener methods may only be used on BrowserWindow instances opened with the target _self.

Methods:

open

url:string, target?:string, options?: string):InAppBrowser

Opens the in-app browser with the url provided.

url: the URL to load
target: The target in which to load the URL. Defaults to '_self'
options: options for the in-app browser. Defaults to 'location=yes'. The options string must not contain any blank space, and each feature's name/value pairs must be separated by a comma. Feature names are case insensitive.

addEventListener

type: string, callback: (event: InAppBrowserEvent) => void

Add an event listener to the browser window opened with open

type: the event type
callback: a function that will get called when the event with the provided type is emitted

removeEventListener

type: string, callback: (event: InAppBrowserEvent) => void

Remove an event listener from the browser window opened with open

type: the event type
callback: a function that will get called when the event with the provided type is emitted

show

Show a browser window opened with the open method

close

Close a browser window opened with the open method

executeScript

script: string, callback: (result: any) => void

Execute javascript on the browser window opened with open

script: the script to execute. must be a javascript string.
callback: a function that will get called when the script is executed

Note: this feature is disabled on Desktop

insertCSS

css: string, callback: (result: any) => void

Insert CSS on the browser window opened with open

css: the css to execute. must be a string
callback: a function that will get called when the script is executed

Refer to https://cordova.apache.org/docs/en/latest/reference/cordova-plugin-inappbrowser/ for more documentation

On Desktop, refer to https://github.com/electron/electron/blob/master/docs/api/browser-window.md#instance-events for a full list of all events available to BrowserWindow instances.

Example:

export class MyWebview {

  alertContent: string;
  ref: any;

  openInExternal() {
    const webview = new AWWebView();
    const url = 'https://www.nytimes.com/';
    this.ref = webview.open(url, '_blank');
    this.alertContent = 'You opened a link!';
    this.ref.addEventListener('close', () => {
      this.alertContent = 'You closed the webview!';
    });
  }

  openInInternal() {
    const webview = new AWWebView();
    const url = 'https://www.nytimes.com/';
    this.ref = webview.open(url, '_self');
    this.alertContent = 'You opened a link!';
    this.ref.addEventListener('close', () => {
        this.alertContent = 'You closed the webview!';
    });
  }

  openMinimized() {
    const webview = new AWWebView();
    const url = 'https://www.nytimes.com/';
    this.ref = webview.open(url, '_self', {show: false});
    this.alertContent = 'You opened a browser window that is "closed"';
  }

  showMinimized() {
    if (this.ref) {
      this.ref.show();
    }
  }

  executeScript() {
    if (this.ref) {
      const script = `alert('You executed javascript inside a browser window!')`;
      this.ref.executeScript(script, () => {
        this.alertContent = 'You executed a script!';
      });
    }
  }

  insertCSS() {
    if (this.ref) {
      const css = `* { color: red !important; }`;
      this.ref.insertCSS(css, () => {
        this.alertContent = 'You inserted CSS';
      });
    }
  }
}

AWAppManager

The AppManager plugin allows you to close the current app webview, get the current app name, version and whether it is the first run.

Methods:

closeActiveApp

closeActiveApp()

Closes the currently active app.

Example:

var appManager = new Appworks.AWAppManager(
    function () {
        // success
    },
    function (err) {
        // could not complete request
        console.log(err);
    }
);

$('#click-me').click(function () {
    appManager.closeActiveApp();
});

getAppName

getAppName()

Gets the name of the current active app.

Example:

var appManager = new Appworks.AWAppManager(
    function (appName) {
        console.log("This apps name is: " + appName);
    },
    function (err) {
        // could not retrieve app name
        console.log(err);
    }
);

$('#click-me').click(function () {
    appManager.getAppName();
});

getAppVersion

getAppVersion()

Get the version of the current app

Example:

function getAppVersion() {
  var appManager = new Appworks.AWAppManager();
    appManager.getAppVersion(function (version) {
      console.log(version);
  }, function(error) {
      console.log(error);
  });
}

isFirstRun

isFirstRun()

Determine whether this particular app is running for the first time. Take this opportunity to display an intro carousel or other welcome dialogs.

Example:

function isFirstRun() {
  var appManager = new Appworks.AWAppManager();
    appManager.isFirstRun(function (isFirstRun) {
      if(isFirstRun) {
        console.log('This is the first run of this app');
        // perform first run methods
      } else {
        console.log('This app has run before');
        // perform normal run methods
      }
  }, function(error) {
      console.log(error);
  });
}

setAppHasRun

setAppHasRun()

Tell the AppWorks container that this apps first run has been handled, so that subsequent runs are not incorrectly marked as first run.

Example:

function setAppHasRun() {
  var appManager = new Appworks.AWAppManager();
    appManager.setAppHasRun(function () {
      console.log('setAppHasRun was successful');
  }, function(error) {
      console.log(error);
  });
}

AWComponent

Open, close, list, check components and listen for app close event

Methods:

open

open(successHandler: any, errorHandler?: any, args?: any[])

Open a component

list

list(successHandler: any, errorHandler?: any, args?: any[])

Return a list of all installed components

check

check(successHandler: any, errorHandler?: any, args?: any[])

Check if a component is installed

close

close(successHandler: any, errorHandler?: any, args?: any[])

Close the current component

registerAppClose

registerAppClose(successHandler: any)

Helps the micro app to register itself to listen for app close event.

closeApp

closeApp()

Used to close the Desktop client after performing operations.

Example:

// javascript code example

var awComponent = new Appworks.Component();
function onClose() {
console.log(`close event from callback 1 is called`);
setTimeout(()=>{
    awComponent.closeApp();
},3000); 
}
awComponent.registerAppClose(onClose);

// TypeScript code example
const onClose = () => {
    console.log('Appwork Closed');
    setTimeout(() => {
     alert("Appwork Closed");
     appWorks.closeApp();
    }, 1000);
}

const onError = (error) => {
    this.notify.error('Appwork', error)
}

const appWorks = new AWComponent(null, onError);

appWorks.registerAppClose(onClose);

Finder

The Finder plugin allows you to browse and open files stored on the device inside of the OpenText Mobile container. Files browsing can be done directly inside of your app. Files can be opened in third party iOS apps installed on the device.

Methods:

open

open(path: string, filename: string)

open a file in another iOS app installed on the device

path: the path to the file you would like to open
filename: the name of the file you would like to open

openDirect

openDirect(filename: string)

open a file in another iOS app installed on the device

filename: the name of the file you would like to open at the application root

share(filename: string)

Share a file to an another app such as an email client

filename: the filepath of the file you would like to open at the application root

list

list(path: string)

show the contents of a directory within the OpenText Mobile app container

path: the name of the directory you would like to see the contents of

Example:

var openFile = function (filename) {
    var finder = new Appworks.Finder(showFile, showFileError),

    function showFile(data) {
        console.log(data);
    }

    function showFileError(err) {
        console.log(err);
    }

    finder.open('/', filename);
};

var listDirectory = function (path) {
    var finder = new Appworks.Finder(showContents, showDirectoryError);

    function showContents(directory) {
        console.log(directory);
        // returns an array containing each item in the directory specified by @path

        // try to open file now
        openFile('/', directory[1].filename);
    }

    function showDirectoryError(err) {
        console.log(err);
    }

    finder.list('/');
};

listDirectory();

FileChooser

The FileChooser plugin allows you to select and upload files from the device file system. Android only.

Methods:

selectAndUpload

selectAndUpload(action: string)

select a file and upload

action: the action

AWFileSystem

* available on desktop

The AWFileSystem plugin allows AppWorks Desktop hosted apps to interact with the underlying desktop host. Specifically to make use of the OS file system operations, and also some of the native file browsing dialogs (Windows Explorer, OSX Finder, etc.).

Please note this plugin is only usable in the desktop environment, the plugin methods will throw an error if usage outside of this context is detected. Use of relative paths with this plugin's methods is not advised, and paths beginning with a slash on Windows will assume that they begin at the root drive of the hosts file system. Absolute paths can be retrieved via the AWFileSystem dialog methods, namely showSaveDialog, showDirSelector, and showFileSelector.

Methods:

getPath

    getPath(name: string, successCallback: (result: string), errorCallback?: (result: Error))

Retrieve the full path of a well-known location via a special name.

name: an alias for a well-known disk location

A String path value will be passed to the callback if the alias is recognised, else the error callback will be fired.

You can request the following paths by the name:

home User's home directory.
appData Per-user application data directory, which by default points to:
- %APPDATA% on Windows
- $XDG_CONFIG_HOME or ~/.config on Linux
- ~/Library/Application Support on macOS
userData The directory for storing your app's configuration files, which by default it is the appData directory appended with your app's name.
temp Temporary directory.
desktop The current user's Desktop directory.
documents Directory for a user's "My Documents".
downloads Directory for a user's downloads.
music Directory for a user's music.
pictures Directory for a user's pictures.
videos Directory for a user's videos.

exists

    exists(path: string, successCallback: (result: boolean), errorCallback?: (result: Error))

Determine if the path provided refers to an existing file or directory. Relative paths should not be used.

path: a file path

A boolean value will be passed to the callback if the path does exist, else the error callback will be fired.

isDir

    isDir(path: string, successCallback: (result: boolean), errorCallback?: (result: Error))

Determine if the path provided refers to a directory, as opposed to a file. Relative paths should not be used.

path: a file path

A boolean value will be passed to the callback if the path does refer to an existing directory, else the error callback will be fired.

createFile

    createFile(path: string, successCallback: (result: boolean), errorCallback?: (result: Error), data?: string, append?: boolean)

Create or append to a file at the provided path. A file extension must be provided (e.g. ../myNewImage.jpg). Any extra directories specified in the path that do not currently exist will be created for you.

If data is supplied it will be written to the file, please ensure the file extension is of suitable format to accept String data. If data is not supplied then a new empty file will be created, the file should not currently exist. Use of relative paths will result in an error being thrown.

path: a new file path that has a non empty file extension
data: text data to be written to the new file (optional)
append: should we append to the file if it already exists or overwrite it? (optional)

A boolean value will be passed to the callback if the file/directory was created, else the error callback will be fired.

readFile

    readFile(path: string, successCallback: (result: boolean), errorCallback?: (result: Error))

Read the contents of a text based (UTF-8) file into a String and return it.

Use of relative paths will result in an error being thrown.

path: path of the file to open

A String value will be passed to the callback if the file at the supplied path could be read, else the error callback will be fired.

createDirectory

    createDirectory(path: string, successCallback: (result: boolean), errorCallback?: (result: Error))

Create a new directory at the provided path. The provided path may contain a trailing slash (both ../myDir/ and ../myDir are valid). Any extra directories specified in the path that do not currently exist will be created for you. This method does not support overwriting existing directories. Use of relative paths will result in an error being thrown.

path: a new directory path that may end with a trailing slash

A boolean value will be passed to the callback if the file/directory was created, else the error callback will be fired.

copy

    open(from: string, to: string, successCallback: (result: boolean), errorCallback?: (result: Error))

Copy a file from one location to another. The supplied source and destination paths must be non-empty and contain file extensions. The source path has to refer to an existing file, and any directories in the 'to' path that do not exist will be created as part of the copy operation. Use of relative paths will result in an error being thrown.

from: source file path
to: destination file path

A boolean value will be passed to the callback if the file was successfully copied, else the error callback will be fired.

open

    open(path: string, successCallback: (result: boolean), errorCallback?: (result: Error))

Open a file using the host OS. If the file extension of the existing file is known then the corresponding host application will open, else you will be prompted to choose an application. Relative paths should not be used.

path: a file path

A boolean value will be passed to the callback if the OS managed to open the file, else the error callback will be fired.

reveal

    reveal(path: string, successCallback: (result: boolean), errorCallback?: (result: Error))

Open the OS file browser at the supplied file path. Relative paths should not be used.

path: a file path

A boolean value will be passed to the callback if the OS managed to open the file browser at the supplied location, else the error callback will be fired. Relative paths should not be used.

updateLastModifiedDate

    updateLastModifiedDate(path: string, date: Date, successCallback: (result: boolean) => void, errorCallback?: (result: Error) => void ): void

Update the last modified date of the file specified in the supplied path Relative paths should not be used.

path: a file path
date: date using which last modified date need to be updated

getDetails

    getDetails(path: string, successCallback: (result: FileDetails), errorCallback?: (result: Error))

Retrieve the details of a specific file/directory at the supplied path. Relative paths should not be used.

path: a file path

A FileDetails object will be passed to the callback if the path exists, else the error callback will be fired.

listDirContents

    listDirContents(path: string, successCallback: (result: FileDetails[]), errorCallback?: (result: Error))

List the contents of the directory at the supplied path. Relative paths should not be used.

path: a file path

An array of FileDetails objects will be passed to the callback if the path exists and is a directory, else the error callback will be fired.

showSaveDialog

    showSaveDialog(opts: SaveDialogOptions, successCallback: (result: string), errorCallback?: (result: Error))

Show the OS 'Save As' file browser, only permitting selection of a single file. A new file name is usually entered otherwise we will overwrite the existing file at the provided path (provide the correct permissions are in place)

options: SaveDialogOptions save dialog options

The full path of the file indicated in the OS file browser will be returned to the callback on pressing the dialog confirmation button.

showDirSelector

    showDirSelector(opts: FileDialogOptions, successCallback: (result: string[]), errorCallback?: (result: Error))

Show the OS file selection browser, only allowing the selection of directories.

opts: FileDialogOptions file browser dialog options

The full path to the selected directory will be returned to the callback on pressing the dialog confirmation button.

showFileSelector

    showFileSelector(opts: FileDialogOptions, successCallback: (result: string[]), errorCallback?: (result: Error))

Show the OS file selection browser, allowing the selection of files only. Multiple files can be selected at once as specified in the options.

opts: FileDialogOptions file browser dialog options

An array of the selected file paths will be returned to the callback on pressing the dialog confirmation button.

Objects:

These objects are defined as part of the AWFileSystem module.

FileDetails

Basic file details resolved by the host OS.

name: file name with extension
path: full path to the file
isDirectory: is this a directory or file?
checksum: MD5 hash checksum of the file (files only)
modified: last modified time in millis (since epoch)

FileFilter

A filter that can be applied within a file browser to limit the types of file that are visible

name: the name of the filter as it appears in the file browser
extensions: an array of file extensions without wildcards or dots (e.g. 'png' is good but '.png' and '.png' are bad) to show all files, use the '' wildcard (no other wildcard is supported)

SaveDialogOptions

Options to configure the 'Save As' dialog.

title: custom title for the dialog
defaultPath: the path at which to open the dialog
buttonLabel: custom label for the confirmation button, when left empty the default label will be used
filters: an array of FileFilter objects

FileDialogOptions

Options to configure the file browser dialog

defaultPath: the file path at which the dialog should be opened
multiSelections: enable multiple file selection
filters: an array of FileFilter objects

AWHeaderBar

The AWHeaderBar plugin allows you to hide or show the client header bar, update the text, and/or hide or show a back button.

Methods:

setHeader

setHeader(config: any)

update the header bar with options

config: a configuration object with the following parameters
title: the title of the header
backButtonVisible: boolean flag to hide/show the back button

getHeader

getHeader()

get the current configuration of the header

Example:

var setHeader = function () {
    var header = new Appworks.AWHeaderBar(headerWasSet, failed),

    function headerWasSet(config) {
        // returns an object containing the current header bar configuration
        console.log(config);
        // just to demonstrate a callback
        getHeader();
    }

    function failed(err) {
        console.log(err);
    }

    header.setHeader({
        title: 'My New Title',
        backButtonVisible: true
    });
};

var getHeader = function () {
    var header = new Appworks.AWHeaderBar(gotHeader, failed);

    function gotHeader(header) {
        // returns an object containing the current header bar configuration
        console.log(header);
    }

    function failed(err) {
        console.log(err);
    }

    header.getHeader();
};

// update the header bar
setHeader();

setHeaderButtons

setHeaderButtons(callback: Function, config: any)

Set the header buttons to specified images and indicate if their event handler is custom

config: an array of objects. The properties of each object must contains:
button: The identifier of the button. You can use the AWHeaderBar.ButtonName enumerator for this.
image: The identifier of the image. You can use the AWHeaderBar.ButtonImage enumerator for this.
function: custom|default - Indicate to AppWorks whether AppWorks will handle the tap event (default) or your app will (custom)

Example:

var self = this;

function initHeaderButtons() {
    self.header = new Appworks.AWHeaderBar(null, failFn);
    setHeaderButtons();
}

// Tell the client to set the header buttons according to the apps needs
function setHeaderButtons() {
  // Button definitions
  var RightButtonOne = {
      "button": AWHeaderBar.ButtonName.RightOne, // Identifiy the button using an enumerator
      "image": AWHeaderBar.ButtonImage.Dots, // Use an image specified by an enumerator
      "function" : "custom" // Inform the client this will be handled in the app
    };

  var RightButtonTwo = {
      "button": AWHeaderBar.ButtonName.RightTwo,
      "image": AWHeaderBar.ButtonImage.Search,
      "function" : "custom"
    };

  var LeftButtonOne = {
      "button": AWHeaderBar.ButtonName.LeftOne,
      "image": AWHeaderBar.ButtonImage.Back,
      "function" : "custom"
    };

  var LeftButtonTwo = {
      "button": AWHeaderBar.ButtonName.LeftTwo,
      "function" : "default" // Inform the client this button is to be handled by the client. The image will revert to default.
    };

  var buttons = [LeftButtonOne, RightButtonOne, RightButtonTwo];
  header.setHeaderButtons(headerButtonCallback, buttons);
}

// Tell the client to set each button to their default icons and functions
function resetHeaderButtons() {
  var RightButtonOne = {
      "button": header.ButtonName.RightOne,
      "function" : "default" // Inform the client this button is to be handled by the client. The image will revert to default.
    };

  var RightButtonTwo = {
      "button": header.ButtonName.RightTwo,
      "function" : "default" // Inform the client this button is to be handled by the client. The image will revert to default.
    };

  var LeftButtonOne = {
      "button": header.ButtonName.LeftOne,
      "function" : "default" // Inform the client this button is to be handled by the client. The image will revert to default.
    };

  var LeftButtonTwo = {
      "button": header.ButtonName.LeftTwo,
      "function" : "default" // Inform the client this button is to be handled by the client. The image will revert to default.
    };

  var buttons = [LeftButtonOne, LeftButtonTwo, RightButtonOne, RightButtonTwo];
  header.setHeaderButtons(headerButtonCallback, buttons);
}

// Callback function called when a button is tapped
function headerButtonCallback(button){
  if(button == header.ButtonName.RightOne) {
    rightButtonOneFunction();
  }

  if(button == header.ButtonName.RightTwo) {
    rightButtonTwoFunction();
  }

  if(button == header.ButtonName.LeftOne) {
    leftButtonOneFunction();
  }
}

function failFn(err) {
    // called when the header bar fails to set the buttons
    console.log(err);
}

// Execute the function to initialize the header buttons
initHeaderButtons();

maskHeader

maskHeader(shouldMaskHeader: any)

shouldMaskHeader: A boolean value, true to mask false to unmask
Add an overlay to the native header.
The buttons underneath are not usable when when the overlay is visible.

Example:

document.addEventListener("deviceready", onDeviceReady, false);

var self = this;

function onDeviceReady() {
  app();
}

function app() {
    self.header = new Appworks.AWHeaderBar();
}

// Invoke the mask header plugin
// Pass in a boolean (true to mask, false to unmask)
function maskHeader(shouldMaskHeader) {
  header.maskHeader(shouldMaskHeader);
}

ButtonName enumerator

ButtonName.LeftOne: The left most button, normally the hamburger menu icon
ButtonName.LeftTwo: The second left button, no default use.
ButtonName.RightOne: The right most button, normally the app switcher icon in the multi app client
ButtonName.RightTwo: The second right button, no default use for apps, but the settings icon on the app library page in the multi app client

ButtonImage enumerator

ButtonImage.Back: Same image as the back icon. Can be used here as an alternative.
ButtonImage.Settings: A settings cog-wheel icon
ButtonImage.None: Hides the button
ButtonImage.Dots: Three dots stacked vertically icon
ButtonImage.Search: Magnifying glass icon

AWMenu desktop only

available on Desktop The AWMenu plugin allows you to set and action items in the Desktop native dropdown menu.

Methods:

setMenu

    setMenu(sections: MenuSection[])

sections: MenuSection objects to add to native menu

Pass in a number of MenuSection objects to be added to the native menu. Each MenuSection object contains a number of MenuItem objects.

MenuSection

export interface MenuSection {
    /**
     * the title of the section
     */
    subhead: string;
    /**
     * the items to add to this section
     */
    items: MenuItem[];
}

MenuItem

export interface MenuItem {
    /**
     * the title text to use for the menu item
     */
    title: string;
    /**
     * the callback to invoke when the user taps the menu item
     */
    action: any;
    /**
     * is the menu item visible?
     */
    visible: boolean;
    /**
     * does the menu item have a badge? e.g. Notifications (1)
     */
    hasBadge: boolean;
}

Example

addItems() {
    const menu = new AWMenu(null, (err) => {
      console.error(err);
    });
    const menuSections = [
        {
            subhead: 'Breakfast',
            items: [
                 {
                     title: 'Steak & Eggs',
                     action: () => {
                         alert('You chose Steak & Eggs. Please watch your cholesterol levels.');
                     },
                     visible: true,
                     hasBadge: true
                 },
                 {
                     title: 'Donuts',
                     action: () => {
                         alert('You chose Donuts. Yummy, but gym time is required');
                     },
                     visible: true,
                     hasBadge: true
                 },
            ]
        },
        {
            subhead: 'Dinner',
            items: [
                {
                    title: 'Smoked black cod and escarole salad',
                    action: () => {
                        alert('Isn\'t this on the menu at Chez Panisse?');
                    },
                    visible: true,
                    hasBadge: false
                },
                {
                    title: 'Cheeseburger, Fries, and a Beer',
                    action: () => {
                        alert('Why not');
                    },
                    visible: true,
                    hasBadge: true
                }
            ]
        }
    ];
    menu.setMenu(menuSections).then(() => {
      alert(`Successfully added ${menuSections.length} sections to menu`);
    });
  }

AWMobileFileSystem mobile only

The AWMobileFileSystem plugin allows you to interact with the file system within the appworks mobile client.

You are able to perform file transfer requests such as upload and download, open and share files, and also copy, move, rename and delete files.

Each method has a shared boolean parameter, indicating whether the file location you are targeting is in the documents directory (shared) or file provider storage directory (non shared).

Shared (true) means to share the file with other apps in the appworks container

Shared (false) means to store privately in your apps file provider storage location. This can still be accessed via the file provider and open in methods.

list

list returns a list of files in a given directory relative to the shared/non shared directory

list(directory: string, shared: boolean, success: any, error: any)

directory: the directory relative to the shared/non shared directory
shared: source relative to shared or non shared
success: callback called returning a list of file objects
error: callback called if there is a client side error

File I/O Methods:

exists

exists allows you check check if a file exists at a given directory

exists(source: string, shared: boolean, success: any, error: any)

source: the filepath relative to the shared/non shared directory
shared: source relative to shared or non shared
success: callback called if the file exists
error: callback called if the file does not exist

rename

rename allows you rename a file

rename(source: string, destination: string, shared: boolean, success: any, error: any)

source: the source filepath relative to the shared/non shared directory
destination: the destination filepath relative to the shared/non shared directory
shared: source relative to shared or non shared
success: callback called if the file was renamed successfully
error: callback called if the file was not renamed

copy

copy allows you copy a file

copy(source: string, sourceShared: boolean, destination: string, desintationShared: boolean, success: any, error: any)

source: the source filepath relative to the shared/non shared directory
source shared: source relative to shared or non shared
destination: the destination filepath relative to the shared/non shared directory
destination shared: destination relative to shared or non shared
success: callback called if the file was copied successfully
error: callback called if the file was not copied

move

move allows you move a file

move(source: string, sourceShared: boolean, destination: string, desintationShared: boolean, success: any, error: any)

source: the source filepath relative to the shared/non shared directory
source shared: source relative to shared or non shared
destination: the destination filepath relative to the shared/non shared directory
destination shared: destination relative to shared or non shared
success: callback called if the file was moved successfully
error: callback called if the file was not moved

remove

remove allows you remove/delete a file

remove(source: string, shared: boolean, success: any, error: any)

source: the filepath relative to the shared/non shared directory
shared: source relative to shared or non shared
success: callback called if the file is removed
error: callback called if the file is not removed

File Import Methods:

listImports

listImports returns a list of files in your apps import directory

listImports(success: any, error: any)

success: callback called returning a list of file objects
error: callback called if there is a client side error

moveImport

moveImport allows you move a file from the imports directory to a directory of your choosing

moveImport(source: string, destination: string, desintationShared: boolean, success: any, error: any)

source: the source filename in the imports directory
destination: the destination filepath relative to the shared/non shared directory
destination shared: destination relative to shared or non shared
success: callback called if the file was moved successfully
error: callback called if the file was not moved

File Open Methods:

open

open allows you open the file in a third party app

open(source: string, shared: boolean, success: any, error: any)

source: the filepath relative to the shared/non shared directory
shared: source relative to shared or non shared
success: callback called if the file opens successfully
error: callback called if the file was not opened

share allows you open the file in a third party app, much the same as open, but Android handles this slighty different, warranting a second method

share(source: string, shared: boolean, success: any, error: any)

source: the filepath relative to the shared/non shared directory
shared: source relative to shared or non shared
success: callback called if the file opens successfully
error: callback called if the file was not opened

quicklook

quicklook allows you open the file in iOS using the QuickLook framework with MS office documents and PDFs supported, on Android, you can only use this with PDFs

quicklook(source: string, shared: boolean, success: any, error: any)

source: the filepath relative to the shared/non shared directory
shared: source relative to shared or non shared
success: callback called if the file opens successfully
error: callback called if the file was not opened

File Transfer Methods:

download

download allows you to download a file from a URL to a destination filepath

download(source: string, destination: string, headers: any, shared: boolean, success: any, error: any)

source: the URL of the file to be downloaded
destination: the destination filepath relative to the shared/non shared directory
headers: any additional headers besides the standard auth tokens automatically injected
shared: destination relative to shared or non shared
success: callback called if the file downloaded successfully
error: callback called if the file was not downloaded

upload

upload allows you to upload a file to a URL

upload(source: string, destination: string, fileParameterName: string, formData: any, headers: any, shared: boolean, success: any, error: any)

source: the source filepath relative to the shared/non shared directory
destination: the destination URL
fileParameterName: the file parameter name used to identify the file in the request
formData: a json object of the form data to be added to the request
headers: any additional headers besides the standard auth tokens automatically injected
shared: source relative to shared or non shared
success: callback called if the file uploaded successfully
error: callback called if the file was not uploaded

AWMenu mobile only

The AWMenu features available on Android and iOS

Methods:

showMenu

    showMenu(shouldShowMenu: boolean)

shouldShowMenu: Set to true to show the menu, set to false to hide the menu, however it's likely only a true value will ever be needed.

This will open (or close) the native side menu.

AWPage

The AWPage plugin allows you to set the URL of page to an external URL (such as http://www.google.com). This allows the web app to launch a new webView with a specified URL in the current context of the view.

Methods:

setPageUrl

setPageUrl(url: string)

Pass in a URL as a string, starting with http(s):// and a webview will overlay the current webview with that URL. For security reasons no appworks functionality will be available from this URL.

Example:

  var page = new Appworks.AWPage();
  var url = "http://www.opentext.com/"
  var awPage = new Appworks.AWPage();
  page.setPageUrl(url);

openModalAppWebView

openModalAppWebView(url: string, title: string)

Open a modal webview of a html file in your app which is appworks enabled with query params such as modal.html?myproperty=myvalue
This cannot be an external webpage
url: the filename and querystring to be opened
title: the title to be displayed in the header

Example:

  var page = new Appworks.AWPage();
  var url = "modal.html" + "?property=demonstration";
  var title = "My Page Title";
  var closeTitle = "Done";
  page.openModalAppWebView(url, title, closeTitle);

setActionButtonCallback

setActionButtonCallback(callback: any)

Execute a javascript function in your app when the action button is tapped
callback: The callback to run when the action button is tapped.

closeModalAppWebView

closeModalAppWebView()

Used by the ModalAppWebView which has just popped open. This allows the modal to close itself.

openModalExternalWebView

openModalExternalWebView(url: string, title: string, closeText: string, options?: object)

This will open an external webview which is not appworks enabled. Use case: opening your companies website within the app.
url: the web URL to be opened
title: the title to be displayed in the header
closeText: the title to be displayed on the close button
options: (optional) a JSON object with a header property and JSON object value to be applied to the web request

Example:

  var page = new Appworks.AWPage();
  var url = "http://mywebsite.com/mypage";
  var title = "My Web Page";
  var closeTitle = "Dismiss";

  var headers = {};
      headers["myKey"] = "myValue";

  var options = {"headers" : headers};

  page.openModalExternalWebView(url, title, closeTitle, options);

AWLauncher

The AWLauncher plugin provides the URL used to open the client in the event it was opened via a custom URL scheme, with the url appended as the launchUrl parameter, e.g. x-otm://?launchUrl=http%3A%2F%2Fmurdoch.opentext.com%2Fnode%2F200 The launchUrl content must be URL encoded.

If your client and domain are setup to use this functionality, then your client will open when you tap on a corresponding link from another app on your device.

This plugin allows your app to get this URL and also clear it to prevent it from being accessed subsequently.

Methods:

getLaunchURL(successHandler: any, errorHandler: any)

successHandler will return the url as a string if one is set
errorHandler will return a string if no url is set

clearLaunchURL()

No parameters, this will simply set the launch URL to null prevent any further access.

Example:

  self.launcher = new Appworks.AWLauncher();
  
  // Retrieve the launch URL
  launcher.getLaunchURL(function(url) {
    // Success, a launch url is set
    alert(url);
  }, function(error) {
    // Error, no launch url is set
    alert(error);
  });

  // Clears the launch URL
  launcher.clearLaunchURL();

QRReader

The QRReader plugin allows you to scan a QR code using the device camera. You can also scan a barcode.

Methods:

scan

scan()

Opens the device camera to scan a QR code. When the QR code is recognized, it is processed automatically. returns the data encoded by the QR code to the callback initialized upon instance creation.

Example:

var scanQRCode = function () {
    var qrScanner = new Appworks.QRReader(onScan, onScanErr),
        qrScanResult;

    function onScan(data) {
        qrScanResult = data;
    }

    function onScanErr(err) {
        console.log(err);
    }

    qrScanner.scan();
};

barcode

barcode()

Opens the device camera to scan a single barcode or multiple barcodes. The contents of the barcode is returned in a string array. You can provide 4 parameters, multiple, timeout, finishTitle and cancelTitle

Example:

var multiple = true; // If true, scan barcodes until users taps finish. If false, scan a single barcode and finish automatically. (Defaults to false if not provided)
var timeout = 30; // The number of seconds of idle (no barcode scan) before automatically finishing. (defaults to 30 if not provided)
var finishTitle = 'All Done'; // A custom title for the finish button (defaults to "Finished" if not provided)
var cancelTitle = 'End Scanning'; // A custom title for the cancel button (defaults to "Cancel" if not provided)
scanBarcode(multiple, timeout, finishTitle, cancelTitle);

// .....

function scanBarcode(multiple, timeout, finishTitle, cancelTitle) {
  var reader = new Appworks.QRReader(
    function(result) {
      // here, result is a string array, e.g. ['barcode1','barcode2','barcode3']
      console.log(result);
    },
    function(error) {
      // here, error is a string
      console.log(error);
    });

  reader.barcode(multiple, timeout, finishTitle, cancelTitle);
}

Camera

Access the device camera to take photos, or select photos from the device gallery.

Methods:

takePicture

takePicture(options?: any)

use the device camera to take a photo. returns the uri specified by options - default is the native uri to the location on the device.

options: a CameraOptions object. See apache cordova documentation

openGallery

openGallery(options?: any)

open the device gallery to select a photo. returns the uri specified by options - default is the native uri to the location on the device.

options: a CameraOptions object. See apache cordova documentation

SecureStorage

The SecureStorage Plugin allows you to store and retrieve files on the device using AES 256-bit encryption.

Methods:

store

store(url: string, filename: string, options?: any)

store a file securely.

url: the url of the server to download the file from.
filename: the path to the file to be stored. may be a directory structure.
options: optional options to pass with your request. currently supports headers.

Example:

var self = this;

function storeFile() {

    var storage = new Appworks.SecureStorage(setFile, errorHandler);
    self.imgSrc = null;
    self.loading = true;

    function setFile(file) {
        self.storedFile = file.nativeURL;
        stopLoading();
    }

    function stopLoading() {
        console.log('AWJS: File downloaded successfully.');
        self.loading = false;
    }

    storage.store('http://thecatapi.com/api/images/get', 'file.jpg');
}

retrieve

retrieve(filename: string, options?: any)

filename: the name of the file to be retrieved. may be a directory structure. note this is not the nativeURL, but the same path that was supplied to store().
options: optional options to pass with your request.

Example:

var self = this;
function getFile() {
    var storage = new Appworks.SecureStorage(showImage, errorHandler);

    function showImage(file) {
        self.storedFile = file.nativeURL;
        self.showStoredFileAsImage = true;
    }

    storage.retrieve('file.jpg');
};

function errorHandler(err) {
    console.log(err);
}

remove

remove(target: string)

target: the name of the file to be removed. may be a directory structure. note this is not the nativeURL, but the same path that was supplied to store().

Example:

function removeFile() {
    var storage = new Appworks.SecureStorage(success, errorHandler);
    storage.remove('file.jpg');
}

function success() {
    alert('success');
}

function errorHandler(err) {
    console.log(err);
}

fileExistsAtPath

fileExistsAtPath(target: string)

check if a file exists

target: the name of the file to check for. may be a directory structure. note this is not the nativeURL, but the same path that was supplied to store().

Example:

function fileExists() {
    var storage = new Appworks.SecureStorage(success, errorHandler);
    storage.fileExistsAtPath('file.jpg');
}

function success(doesFileExist) {
    alert(doesFileExist); // true or false
}

function errorHandler(err) {
    console.log(err);
}

onprogress

onprogress=

bind a progress function to be passed progress events while the request is being downloaded when store() is called.

AWFileTransfer

* available on desktop

The File Transfer plugin allows you to upload and download files to and from the device. Additionally, it allows you to download files to a shared container where they may be accessed by third party applications installed on the device.

Methods:

download

download(url: string, target: string, options?: any, shared?: boolean)

download a file from a remote url and store it on the device

url: the url of the server to download the file from
target: the name of the path including the filename where you would like the file to be stored.
options: an optional options object. currently supports headers only.
shared: a boolean flag. when set, the file will be downloaded to a shared container where it may be accessed by third party applications

This method passes a FileEntry object to your success callback. See Apache Cordova Documentation for more information.

Example:

var self = this;
function downloadFile () {
    var fileTransfer = new Appworks.AWFileTransfer(showFile, errorHandler);

    function showFile(file) {
        console.log(file);
        self.downloadedFile = file.nativeURL;
    }

    fileTransfer.progressHandler(function (progress) {
        console.log(progress);
    });

    fileTransfer.download('http://thecatapi.com/api/images/get', 'file.jpg');
};

upload

upload(source: string, url: string, options?: any, shared: boolean)

upload a file from the device to another location

source: the name of the path including the filename where the file is stored
url: the url of the server to upload the file to
options: an optional options object.
shared: a boolean flag. when set, the file will be uploaded from a shared container where it may be accessed by third party applications

This method passes a FileUploadResult object to your success callback. See Apache Cordova Documentation for more information.

Example:

var self = this;
function uploadFile () {
    var fileTransfer = new Appworks.AWFileTransfer(showFile, errorHandler);

    function showFile(file) {
        console.log(file);
        self.uploadedFile = file.nativeURL;
    }

    fileTransfer.upload('file.jpg', 'http://thecatapi.com/api/images/get');
};

progressHandler

progressHandler(callback: (data: any) => void)

define a callback to be executed whenever upload or download progress is made

callback: a function to be executed during upload or download. passed a ProgressEvent object.

abort

abort()

abort the current transfer.

AWMedia

The AWMedia plugin provides the ability to record and play back audio files on a device.

var media = new Appworks.AWMedia('path-to-src.mp3', audioEnded, errorHandler, statusChanged);

function audioEnded() {
    console.log('audio ended');
}

function errorHandler(err) {
    console.log(err);
}

function statusChanged(status) {
    console.log(status);
}

media.play();

Methods:

getCurrentPosition: Returns the current position within an audio file.
getDuration: Returns the duration of an audio file.
play: Start or resume playing an audio file.
pause: Pause playback of an audio file.
release: Releases the underlying operating system's audio resources.
seekTo: Moves the position within the audio file.
setVolume: Set the volume for audio playback.
startRecord: Start recording an audio file.
stopRecord: Stop recording an audio file.
stop: Stop playing an audio file

Parameters:

src: A URI containing the audio content
mediaStatus: (Optional) The callback that executes to indicate status changes. (Function)

See the Apache Cordova Github for in depth documentation, device specific quirks, and more.

AWMediaCapture

The AWMediaCapture plugin provides access to the device's audio, image, and video capture capabilities.

Methods:

captureImage
captureVideo

Objects:

Capture
CaptureAudioOptions
CaptureVideoOptions
CaptureCallback
CaptureErrorCB
ConfigurationData
MediaFile
MediaFileData

Properties:

supportedAudioModes: The audio recording formats supported by the device. (ConfigurationData[])
supportedImageModes: The recording image sizes and formats supported by the device. (ConfigurationData[])
supportedVideoModes: The recording video resolutions and formats supported by the device. (ConfigurationData[])

See the Apache Cordova Github for in depth documentation, device specific quirks, and more.

AWAccelerometer

The AWAccelerometer plugin provides access to the device's accelerometer. The accelerometer is a motion sensor that detects the change (delta) in movement relative to the current device orientation, in three dimensions along the x, y, and z axis.

Methods:

getCurrentAcceleration

getCurrentAcceleration()

Get the current acceleration along the x, y, and z axes.

Example:

// onSuccess Callback
// This method accepts an Acceleration object, which contains the current acceleration data
//
var onSuccess = function(position) {
     alert('Acceleration X: ' + acceleration.x + '\n' +
              'Acceleration Y: ' + acceleration.y + '\n' +
              'Acceleration Z: ' + acceleration.z + '\n' +
              'Timestamp: '      + acceleration.timestamp + '\n');
};

function onError(error) {
    alert('code: '    + error.code    + '\n' +
          'message: ' + error.message + '\n');
}

var accelerometer = new Appworks.AWAccelerometer(onSuccess, onError);
accelerometer.getCurrentAcceleration();

watchAcceleration

watchAcceleration(options?: any) => watchId: number

Retrieves the device's current Acceleration at a regular interval, executing the successHandler callback function each time. Specify the interval in milliseconds via the accelerometerOptions object's frequency parameter.

options - An object with the following optional keys:
- period: requested period of calls to successHandler with acceleration data in Milliseconds. (Number) (Default: 10000)

returns a watchId that references the watch acceleration interval function. This value should be used with clearWatch to cancel watching for changes in acceleration.

Example:

function onSuccess(acceleration) {
    alert('Acceleration X: ' + acceleration.x + '\n' +
          'Acceleration Y: ' + acceleration.y + '\n' +
          'Acceleration Z: ' + acceleration.z + '\n' +
          'Timestamp: '      + acceleration.timestamp + '\n');
}

function onError() {
    alert('onError!');
}

var accelerometer = new Appworks.AWAccelerometer(onSuccess, onError);
var watchID = accelerometer.watchAcceleration({ period: 30000 });

clearWatch

clearWatch(watchId: number)

Stop watching for changes to the acceleration referenced by the watchId parameter.

Example:

var accelerometer = new Appworks.AWAccelerometer(onSuccess, onError);

var watchId = accelerometer.watchAcceleration();

// .. later on

accelerometer.clearWatch(watchId);

AWCompass

The AWCompass plugin provides access to the device's compass. The compass is a sensor that detects the direction or heading that the device is pointed, typically from the top of the device. It measures the heading in degrees from 0 to 359.99, where 0 is north.

Methods:

getCurrentHeading

getCurrentHeading()

Get the current compass heading. The compass heading is returned via a CompassHeading object using the successHandler callback function.

Example:

function onSuccess(heading) {
    alert('Heading: ' + heading.magneticHeading);
};

function onError(error) {
    alert('CompassError: ' + error.code);
};

var compass = new Appworks.AWCompass(onSuccess, onError);
compass.getCurrentHeading();

watchHeading

watchAcceleration(options?: any) => watchId: number

Gets the device's current heading at a regular interval. Each time the heading is retrieved, the successHandler callback function is executed.

options - An object with the following optional keys: - frequency: How often to retrieve the compass heading in milliseconds. (Number) (Default: 100) - filter: The change in degrees required to initiate a watchHeading success callback. When this value is set, frequency is ignored. (Number)

returns a watchId that references the watch heading interval function. This value should be used with clearWatch to cancel watching for changes in heading.

Example:

function onSuccess(heading) {
    var element = document.getElementById('heading');
    element.innerHTML = 'Heading: ' + heading.magneticHeading;
};

function onError(compassError) {
    alert('Compass error: ' + compassError.code);
};

var options = {
    frequency: 3000
}; // Update every 3 seconds

var compass = new Appworks.AWCompass(onSuccess, onError);
var

@types/cordova lodash

@everything-registry/sub-chunk-1158 @zalastax/nolb-appw

10 months ago

5 years ago

5 years ago

6 years ago

6 years ago