Client Builder Reference Guide

This is a “Reference Guide” for the classes that make up the Client Builder API. The User’s Guide may be found here.

Client

This section describes the functions and properties of the “Client” object. There is always a single “Client” object available that represents the running Client; it is usually accessible through the “client” argument to event handlers.

confirmCustom()

Pop up a “Confirmation” Dialog offering 1 or 2 choices.

Pop up a dialog which offers 0, 1 or 2 choices plus a “Cancel” button.

confirmCustom(msg: string, choice1Label: string, choice2Label: string, callback: Function)

The dialog is modal; the user must click one of the buttons to dismiss it (at which point the callback function will be called).

Here is an example showing how confirmCustom() might be used:

//
//  This function is called when the user clicks the 'makeAChoice' button.
//
function Client_Start_makeAChoice_onClick(client,page,extra)
{
    client.confirmCustom("Make a choice","Yes","No",function(clicked)
    {
        //
        //  "clicked" will have a value of "Yes", "No" or "Cancel" depending on which 
        //  button in the dialog was clicked.
        //
        console.log(clicked);    
    }
);

createResponseObject()

Create a “response object” from the contents of the current Page

createResponseObject(submitValue:number):any

This method generates a “response object” by collecting data from all the ControlWidgets on the current Page. In addition it will automatically add some properties to give context:

This method returns null if the response object is not created, usually because a required ControlWidget has not been given a value.

data

“client.data” refers to the “global” DataObject

data: DataObject

You can always reach the DataObject for the Client using “client.data”.

errorDialog()

Pop up an “Error” Dialog with the supplied message.

errorDialog(msg: string):void

The dialog is modal; the user must click “OK” to dismiss it.

getDataStreamByName()

Get a DataStream by name

getDataStreamByName(name: string): DataStream

Returns “null” if the DataStream is not defined.

getDataStreamByUUID()

Get a DataStream by UUID

getDataStreamByUUID(uuid: string): DataStream

Returns “null” if the DataStream is not defined.

getCurrentPage()

Get the current Page

getCurrentPage():Page

getUsername()

Get the currently authenticated username

getUsername():string

getWidget()

Get a Widget by name

getWidget(name: string): Widget

All Widgets have a unique name, so you can use the name to look up the Widget (even if it lives on another page).

goToPage()

goToPage(pageName: string, parameters: any): string

infoDialog()

Pop up an “Info” Dialog with the supplied message.

infoDialog(msg: string, title: string):void

The dialog is modal; the user must click “OK” to dismiss it.

modifyTimedQuery()

Modify the configuration of a “Timed Query” DataStream at runtime

modifyTimedQuery(datastream:DataStream, parameters:TimedQueryParameters):void

You must use either getDataStreamByName() or getDataStreamByUUID() to look up the DataStream to be modified. The properties of the TimedQueryParameters object should be set to indicate the changes you wish to make:

class TimedQueryParameters
{
    public typeName:string;
    public updateIntervalInSeconds:number;
    public groupByPropertyName:string;
    public maximumRecordsReturned:number;
    public sortByPropertyName:string;
    public sortDescending:boolean;
    public whereClause:object;
}

You should only specify those properties whose values you wish to change; all un-specified parameters will be left as they are.

For example, inside an event handler you might change the behavior of a timed query DataStream like this:

    var ds = client.getDataStreamByName("MyTimedQueryDataStream");
    var p = new TimedQueryParameters();

    p.whereClause = {
        salary: {
            "$gte": 100000
        }
    };

    client.modifyTimedQuery(ds,p);

If the modifyTimedQuery() is successful the new query will be re-run immediately and the delay timer will be reset.

showHttpErrors()

Pop up a Dialog that reports an error from an Http request

showHttpErrors(errors:any,cause:string):void

For example, your Http request might look like this:

    http.select(queryParameters,function(response)
    {
        //
        //  At this point "response" is an array containing the objects returned for the "select"
        //
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing a select on 'MyType'");
    });

returnToCallingPage()

Return to the calling Page

returnToCallingPage(parameters: any): string

This is a NOP if you are currently on the “Start” Page.

sendClientEvent()

Fire a “client event” to trigger a DataStream

sendClientEvent(dataStreamName: string, dataObject: any): void

More details may be found in the User’s Guide here and here.

terminate()

Terminate the current Client

terminate(withResponse:boolean = false): void

The effect of doing a “terminate” depends on how the Client was launched, but it generally means “go back to where you where before the Client started”.

uploadDocument()

Upload a file selected by the user to a Vantiq Document.

This function causes the browser to pop up a “file selection dialog” which prompts the user to select a single file that should be uploaded to a “document”. A second popup dialog will prompt for the “name” that should be given to the document.

uploadDocument(callback: Function)
//
//  This function is called when the user clicks the 'Button5' button. (Note
//  that 'this' points to the button itself.)
//
function Client_Start_Button5_onClick(client,page,extra)
{
    //
    //  "status" contains either "success" or "error".
    //  "detail" contains either the name of the saved document (if "status" == "success") or an
    //  error message (if "status" == "error").
    //
    client.uploadDocument(function(status, detail)
    {
        if (status == "success")
        {
            console.log("File has been uploaded to document '" + detail + "'");
        }
        else
        {
            console.log("Upload failed with error: " + detail);
        }     
    });
};

getLocation()

Retrieve the latitude/longitude coordinates of the device running the client.

This function allows the device to return a JSON object containing ‘latitude’ and ‘longitude’ properties or null if the device’s location cannot be determined or is running on a browser.

getLocation(callback: Function)
client.getLocation(function(location) {
    if (location) {
        console.log("location = " + JSON.stringify(location));
    } else {
        console.log("no location!");
    }
});

DataObject

A description of DataObjects and how they are used can be found here.

This section describes some useful methods defined on all DataObjects.

copyMatchingData(obj:any):void

Copy any properties from the supplied object which are defined in the DataObject

copyMatchingData(obj:any): void

This method can be used to initialize all the properties within a DataObject from a JavaScript object. Any properties defined in the DataObject which are found in the supplied object will be copied. For example:

page.data.MyDataObject.copyMatchingData(myObject);

initializePropertyToDefaultValue(propertyName:string):void

Initialize the indicated property to its default value

initializePropertyToDefaultValue(propertyName:string): void

This method can be used to initialize a single property within a DataObject to its default value. For example:

page.data.MyDataObject.initializePropertyToDefaultValue("myProperty");

page.data.initializePropertyToDefaultValue("anotherProperty");

initializeToDefaultValues():void

Initialize all properties within the DataObject to their default values

initializeToDefaultValues(): void

This method can be used to initialize all the properties defined within a DataObject to their default values. For example:

page.data.MyDataObject.initializeToDefaultValues();

DataStream

A description of DataStreams and their uses can be found here and here.

This section describes the properties defined on the DataStream object; these objects are defined in the Client Builder and may not be changed at runtime.

name:string

The unique name of the DataStream

restart():void

Restart a “Timed Query” DataStream

restart(): void

“Timed Query” Data Streams will wake up at regularly scheduled intervals and re-run their query. You can programmatically cause the timer to pop early, which will re-run the query and schedule the next query after the update interval. This could be used like this:

var ds = client.getDataStreamByName("MyTimedQueryDataStream");
ds.restart();

uuid:string

The UUID of the DataStream

Http

This section describes the methods defined on the Http object; these are used to make an asychronous request to the Vantiq server. In general you instantiate one Http object for every request.

Basic Information

More detailed information on crafting a REST API request can be found in the API Reference Guide.

An Http request to the Vantiq database is always asynchronous and is not complete until it either succeeds or fails, at which time one of the caller-supplied callback functions will be invoked.

A request is “successful” if the Http status code is 200 (really 2xx); the “succeed” callback will be called with a single argument whose meaning depends on the type of operation you requested.

A request has “failed” if the Http status code is something other than 2xx; the “failure” callback will be called with an “error object” produced by the server that contains information about why the failure occurred. In general you will want to call the showHttpErrors method to display the error to the user.

aggregate()

Issue an asynchronous “aggregate” to the Vantiq database

aggregate(pipeline:any[], succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback returns a “response” which contains an array with results of the “aggregate”.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do a "select" on our Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    //
    //  Specify the array of aggregation pipeline operations
    //
    var pipeline = [
                       {"$match":{ "salary": { "$gt":  50000 }}},
                       {"$match":{ "salary": { "$lt":  100000 }}}
                   ];

    //
    //  Execute the asynchronous server request. This expects 3 parameters:
    //
    //  pipeline: An array containing the pipeline operations
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.aggregate(pipeline,function(response)
    {
        //
        //  At this point "response" is an array containing the objects returned for the "select".
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing an aggregation on 'Employee'");
    });

deleteAll()

Issue an asynchronous request to delete all the records of a given Type from the Vantiq database

delete(parameters:any, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback is called but there is nothing meaningful in the “response” object.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do a delete all the records of a Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    //
    //  Execute the asynchronous server request. This expects 3 parameters:
    //
    //  parameters: "null" or an object containing the parameters for this request
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.deleteAll(null,function(response)
    {
        //
        //  The "response" object is meaningless in this case.
        //
        console.log("DELETE ALL SUCCESSFUL");
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Deleting all instances of 'Employee'");
    });

deleteOne()

Issue an asynchronous request to delete a single record from the Vantiq database

deleteOne(resourceId:string, parameters:any, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback is called but there is nothing meaningful in the “response” object. It is important to note that the request will not fail if the record does not exist; in that case the request is a NOP.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do a "deleteOne" on our Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    var theEmployeeId = "59776c4589133374df264357";

    //
    //  Execute the asynchronous server request. This expects 4 parameters:
    //
    //  resourceId: The "_id" of the object being deleted
    //  parameters: "null" or an object containing the parameters for this request
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.deleteOne(TheEmployeeId,null,function(response)
    {
        //
        //  The "response" object is meaningless in this case.
        //
        console.log("DELETE SUCCESSFUL");
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing a delete on a single'Employee'");
    });

execute()

Asynchronously execute a Procedure in the Vantiq database.

execute(procedureArguments:any, procedureName:string, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

You must have called setVantiqUrlForSystemResource() with a “resourceName” of “procedures” for this to work.

If successful the “succeed” callback returns the “return” value of the procedure “response”.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do an "execute" of a Procedure
    //
    http.setVantiqUrlForSystemResource("procedures");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    //
    //  Set the Procedure arguments
    //
    var args = {
        a:1,
        b:2
    };

    //
    //  Execute the asynchronous server request. This expects 4 parameters:
    //
    //  procedureArguments: The procedure arguments.
    //  procedureName: The fully-qualified name of the Procedure.
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.execute(args,"MyService.MyProcedure",function(response)
    {
        //
        //  At this point "response" is results of the Procedure call
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Executing 'MyService.MyProcedure'");
    });

insert()

Issue an asynchronous “insert” to add a single item to the Vantiq database

insert(data:any, parameters:any, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback returns the inserted object in “response”.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do an "insert" on our Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    //
    //  Execute the asynchronous server request. This expects 4 parameters:
    //
    //  data: The object being inserted.
    //  parameters: "null" or an object containing the parameters for this request
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.insert(aNewEmployee,null,function(response)
    {
        //
        //  At this point "response" is the inserted object
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing an insert of a new Employee");
    });

patch()

Issue an asynchronous request to “patch” a record in the Vantiq database

patch(resourceId:string, patchInstructions:any[], parameters:any, succeed:Function, fail:Function):void;

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback returns the updated object in “response”.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do an "update" on our Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    var theEmployeeId = "57e567fe3bdecaa45d7486ba";

    var patchInstructions = [
        {
            op: "replace",
            path: "/salary",
            value: 100000
        }
    ];

    //
    //  Execute the asynchronous server request. This expects 4 parameters:
    //
    //  data: The object being inserted.
    //  parameters: "null" or an object containing the parameters for this request
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.patch(theEmployeeId,patchInstructions,null,function(response)
    {
        //
        //  At this point "response" is the updated object
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing a patch of an existing Employee");
    });

publish()

Asynchronously “publish” an event on a “topic” or “source”

publish(data:any, topicOrSource:string, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

You must have called setVantiqUrlForSystemResource() with a “resourceName” of “topics” or “source” for this to work.

If successful the “succeed” callback returns but the “response” object has no meaning.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do an "publish" on a topic
    //
    http.setVantiqUrlForSystemResource("topics");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    //
    //  Execute the asynchronous server request. This expects 4 parameters:
    //
    //  data: The object being inserted.
    //  topicOrSource: The topic or Source name
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.publish(theMessageObject,"/a/b/c/d",function(response)
    {
        //
        //  "response" is meaningless for a "publish"
        //
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing a publish on a topic");
    });

query()

Asynchronously execute a “query” against a Source object

query(parameters:any, resourceId:string, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

You must have called setVantiqUrlForSystemResource() with a “resourceName” of “sources” for this to work.

A “query” will only work on Sources which support them; you need to refer to the documentation of the individual Source type for information on the supported parameters.

If successful the “succeed” callback will provide the results of the query in the “response” variable.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do an "query" of a Source
    //
    http.setVantiqUrlForSystemResource("sources");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    var parameters = {
        path: "/api/getData",
        query: {
            xxx: 100
        }
    };

    //
    //  Execute the asynchronous server request. This expects 4 parameters:
    //
    //  parameters: The parameters for the query
    //  resourceId: The name of the target Source
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.query(parameters,"MySource",function(response)
    {
        //
        //  At this point "response" is results of the query
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Executing a query against a Source'");
    });

select()

Issue an asynchronous “select” to the Vantiq database

select(parameters:any, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback returns a “response” which contains an array with results of the “select”.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do a "select" on our Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    //
    //  Specify the (optional) query parameters
    //
    var parameters = {
        where: {salary:{"$gt":50000}}
    };

    //
    //  Execute the asynchronous server request. This expects 3 parameters:
    //
    //  parameters: "null" or an object containing the parameters for this request
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.select(parameters,function(response)
    {
        //
        //  At this point "response" is an array containing the objects returned for the "select".
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing a select on 'Employee'");
    });

selectOne()

Issue an asynchronous “select” to read a single item from the Vantiq database

selectOne(resourceId:string, parameters:any, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback returns the selected object in “response”. If an object matching the resourceId is not found the request will fail.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do a "selectOne" on our Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    var theEmployeeId = "59776c4589133374df264357";

    //
    //  Execute the asynchronous server request. This expects 4 parameters:
    //
    //  resourceId: The "_id" of the object being loaded
    //  parameters: "null" or an object containing the parameters for this request
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.selectOne(theEmployeeId,null,function(response)
    {
        //
        //  At this point "response" is the object found
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing a select on a single'Employee'");
    });

setVantiqHeaders()

Initialize the Http object with required authentication headers

setVantiqHeaders():any

The method returns an object containing the HTTP headers which will actually be used in the request. The headers will contain the tokens needed to validate your request with the Vantiq server (acquired the last time you logged in.)

You can modify these headers before submitting the request.

setVantiqUrlForResource()

Initialize the Http object with the target database Type name

setVantiqUrlForResource(databaseTypeName:string):string

The method returns the URL which will actually be used in the request, something like:

https://dev.vantiq.com/api/v1/resources/custom/MyType"

setVantiqUrlForSystemResource()

Initialize the Http object with the target system resource name

setVantiqUrlForSystemResource(resourceName:string):string

The method returns the URL which will actually be used in the request, something like:

https://dev.vantiq.com/api/v1/resources/sources"

update()

Issue an asynchronous “update” to update a single existing item in the Vantiq database

update(data:any, resourceId:string, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback returns the updated object in “response”.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do an "update" on our Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    //
    //  Execute the asynchronous server request. This expects 4 parameters:
    //
    //  data: The object being inserted.
    //  parameters: "null" or an object containing the parameters for this request
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.update(updatedEmployeeData,employeeId,function(response)
    {
        //
        //  At this point "response" is the updated object
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing an update of an existing Employee");
    });

upsert()

Issue an asynchronous “upsert” to update or insert an item in the Vantiq database

upsert(data:any, succeed:Function, fail:Function):void

See above for details on the common features of Http requests such as this one.

If successful the “succeed” callback returns the updated or inserted object in “response”.

    //
    //  Create an instance of the Http class to execute our server request
    //
    var http = new Http();

    //
    //  Build the URL needed to do an "upsert" on our Type
    //
    http.setVantiqUrlForResource("Employee");

    //
    //  Add the Authorization header to the request
    //
    http.setVantiqHeaders();

    //
    //  Execute the asynchronous server request. This expects 3 parameters:
    //
    //  data: The object being inserted or updated.
    //  successCallback: A callback function that will be driven when the request completes
    //                   successfully (i.e. a status code of 2XX)
    //  failureCallback: A callback function that will be driven when the request does not complete
    //                   successfully.
    //
    http.upsert(updatedEmployeeData,null,function(response)
    {
        //
        //  At this point "response" is the updated object
        //
        console.log("SUCCESS: " + JSON.stringify(response));
    },
    function(errors)
    {
        //
        //  This call will format the error into a popup dialog
        //
        client.showHttpErrors(errors,"Doing an upsert of an existing Employee");
    });

Page

This section describes the functions and properties of the “Page” object. There is always a “Page” object available that represents each of your Pages at runtime; it is usually accessible through the “page” argument of event handlers.

children

A list of Widgets defined on the Page

children: Widget[]

The Widgets in the array are the “top level” Widgets for the Page; if one of these is a WidgetContainer you can drill into its list of “children” if necessary.

data

“page.data” refers to the DataObject for a particular Page

data: DataObject

In most cases an event handler will pass you a “page” variable that points to the current Page.

Uploader

This section describes the Uploader class which allows you to construct a request to upload specific scalar and media data to the VANTIQ server. Before reading this section you should refer here which explains what the Uploader does and why you might want to use it.

To use the Uploader you must instantiate an instance like this:

var uploader = new Uploader(client);

You then tell the Uploader what the responseObject should contain by calling various methods. When ready you call the “start” method which will begin uploading the data to the server; when the request is done a callback function will be called,

addRequestFor(widgetName:string):boolean

Add request to upload the “media data” from the indicated widget.

uploader.addRequestFor("MyCameraWidget");

The named Widget must be a “media” Widget that captures and uploads binary data (AudioRecorder, Camera, ImageMarkup or VideoRecorder).

addRequestsForClient():boolean

Add request to upload the “media data” from all suitable widgets in the Client

uploader.addRequestsForClient();

This tells the Uploader that you want to upload the contents of all the “media” Widgets in your client (AudioRecorder, Camera, ImageMarkup or VideoRecorder).

addRequestsForCurrentPage():boolean

Add request to upload the “media data” from all suitable widgets on the current Page

uploader.addRequestsForCurrentPage();

addRequestsForPage(pageName:string):boolean

Add request to upload the “media data” from all suitable widgets on the indicated Page

uploader.addRequestsForPage("MyPage");

setResponseObject(responseObject:any=null,responseTopic:string=null):void

Set the “response object” and the “response topic” to be published to the server

var responseObject = {
        "a":1,
        "b":2
    };

uploader.setResponseObject(responseObject,"/the/target/topic");

start(completedFunction:Function):boolean

Start the upload of the requested data and response object

uploader.start(function(theUploader)
    {
        //
        //  Upon completion the Widgets will contain the name of the target Documents where
        //  the media was saved.
        //
        var cameraWidget = client.getWidget("MyCameraWidget");
        client.infoDialog("DocumentName=" + cameraWidget.documentName);
    });

Widget Hierarchy

This section describes the functions and properties of objects in the “Widget” hierarchy.

In general, the list of properties described here should match those that appear on the “property sheet” for each type of Widget.

The Widgets are arranged in a class hierarchy which is shown below; note that only “leaf” classes can be instantiated.


AudioRecorder

WidgetControlWidget → AudioRecorder

This Widget is used to record a short audio clip. The clip may be uploaded into a Document object on the server.

clearUpload()

Reset the recorder to its initial state

clearUpload():void

After a clip has been recorder you can call this method to reset it to “empty”.

documentName:string

The name of the document to which the clip was uploaded

This property is readonly - it will be null until after a clip has been recorded and uploaded at which time it will contain the name of the Document where it was saved.

maxDurationInSeconds:number

The maximum number of seconds which may be recorded

In order to place a limit of the amount of storage used in your mobile device this setting places a limit on how many seconds of audio you may record. (Default - 10 seconds).

maxSizeInK:number

The maximum amount of storage that may be recorded

In order to place a limit of the amount of storage used in your mobile device this setting places a limit on the maximum size of the clip which may be recorded. (Default - 100K).

optional:boolean

Specify whether a clip must be recorded before a default “submit”

placeholder:string

The optional “placeholder” value

Defaults to “Start Audio Recording”.


BaiduMapViewer

WidgetDataStreamWidget → BaiduMapViewer

This Widget shows location points on a map as they arrive from the Data Stream.

Note that the BaiduMapViewer uses Baidu Maps which is only available in China. VANTIQ users outside of China will build their Clients using the DynamicMapViewer which provides the equivalent functionality.

borderThickness:number

The thickness of the border in pixels

dataStreamProperty:string

The property that contains the GeoJSON Location value

This value must the name of a valid property in the DataStream objects that contains the GeoJSON location.

fixedCenter:boolean

Indicate if the map should move when new points arrive

If “fixedCenter” is “true” (the default) the map will center on the first point to arrive and not move again unless the user moves it. If “fixedCenter” is “false” then the map will re-center on each new point as it arrives. Note: to see more than one pin on the map, set the Group By attribute on the data stream used by the map.

labelProperty:string

The property that contains a label for each location

This value must the name of a valid property in the DataStream objects that contains a label for the corresponding point in “dataStreamProperty”.

maptype:string

The map type

This value must be a valid map type, one of “Normal”, “Hybrid” or “Satellite”. (The default is “Normal”.) You should specify this value using one of these three constants:


BarChart

WidgetDataStreamWidget → BarChart

This Widget draws a “bar chart” (where the “histogram” bars grow to the right).

borderThickness:number

The thickness of the border in pixels

displayThreshold:string

Indicate whether a thresholdline will be drawn across the chart at “thresholdValue”

“displayThreshold” may be set to either “Yes” or “No” (the default is “No”). When “Yes” is specified the value of the “thresholdValue” property is used to draw a “threshold line” across the chart at the indicated point.

hasGridLines:boolean

Indicate whether grid lines should be drawn across the chart

thresholdValue:number

The value where the threshold line should be drawn

Ignored unless “displayThreshold” is set to “Yes”.

xAxisProperties:DataStreamListElement[]

The properties to be used for the X-Axis

This value must be an array of DataStreamListElement objects; you instantiate them like this:

var dsle = new DataStreamListElement(propertyName:string, label:string);

where “propertyName” is the name of a valid property in the incoming DataStream objects and “label” is a human-readable to be label to used when drawing the chart.

yAxisProperty:string

The property to be used for the Y-Axis

This value must either be the name of a valid property in the DataStream objects or the special string “-TIMESTAMP-” (which means to use the “arrival time” of the DataStream event).


BarcodeReader

WidgetControlWidget → BarcodeReader

This Widget uses the mobile device’s camera to scan a barcode or QR image and convert it into a string.

defaultValue:string

The default result value

This allows you to supply a default value for the result of the scan.

optional:boolean

Specify whether a clip must be recorded before a default “submit”

placeholder:string

The optional “placeholder” value

Defaults to “Scan Barcode”.


Button

WidgetControlWidget → Button

This is a Button that appears in the main body of a Page. (To put a button in the “Footer” area you must use a FooterButton Widget.)

backgroundColor:string

The color of the Button background

The background color is specified using the standard “#RRGGBB” format. (“#d0d0d0” is the default.)

buttonLabel:string

The text of the Button

buttonLabelColor:string

The color of the Button text

The text color is specified using the standard “#RRGGBB” format. (“#000000” is the default.)

buttonLabelSize:number

The font size of the Button text

The font size is specified in pixels. (“18” is the default.)

buttonLabelStyle:string

The style of the Button text

The style of the text may be specified as one of “plain”, “bold”, “italic” or “bold-italic”. (“plain” is the default.)

glyphIcon:string

Display a Bootstrap Glyphicon to the left of the button text

For a list of valid icons see here. For example you could enter a value from that list such as “glyphicon-asterisk”. The default is “null” which omits the icon.

submitValue:number

A value to identify the button when it is used to submit a default response

For a discussion of how this property is used see Terminating with default Buttons.

On Click Event

This Widget supports an “On Click” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onClick(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


ButtonCluster

WidgetControlWidget → ButtonCluster

This Widget is used to present a list of Buttons in a cluster as a single widget.

enumeratedList:any[]

The button definition list

A ButtonCluster is simply a set of Buttons all grouped together. Each Button needs a separate “label” and a numeric “value” to represent it when clicked. This information is defined in a list like this:

var enumList = [
    {value:1, label:"Red"},
    {value:2, label:"Green"},
    {value:3, label:"Blue"}
];

In this example the user would see 3 Buttons with the labels “Red”, “Green” and “Blue”.

On Click Event

This Widget supports an “On Click” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onClick(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter will contain the “value” for the Button that was clicked.


Camera

WidgetControlWidget → Camera

This Widget is used to capture an image using your mobile device’s camera. The image may be uploaded into a Document object on the server.

clearUpload()

Reset the camera to its initial state

clearUpload():void

After a image has been captured you can call this method to reset it to “empty”.

defaultImageUrl:string

The URL of an image will be the default value for the Camera

This defaults to “null”, but if set if contains a URL pointing to a default image for the Camera.

documentName:string

The name of the document to which the image was uploaded

This property is readonly - it will be null until after an image has been captured and uploaded at which time it will contain the name of the Document where it was saved.

optional:boolean

Specify whether a clip must be recorded before a default “submit”

placeholder:string

The optional “placeholder” value

Defaults to “Take Photo”.


Checkbox

WidgetControlWidget → Checkbox

This Widget is used to enter boolean value as a standard “checkbox”.

checkboxLabel:string

The Checkbox label

This is the text label inside the Checkbox Widget.

dataBinding:string

The name of a Boolean DataObject variable

This Widget can be bound to a DataObject variable of type “Boolean” (e.g. “client.data.myBoolean”). Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


ColumnChart

WidgetDataStreamWidget → ColumnChart

This Widget draws a “bar chart” (where the “histogram” bars grow upwards).

borderThickness:number

The thickness of the border in pixels

displayThreshold:string

Indicate whether a thresholdline will be drawn across the chart at “thresholdValue”

“displayThreshold” may be set to either “Yes” or “No” (the default is “No”). When “Yes” is specified the value of the “thresholdValue” property is used to draw a “threshold line” across the chart at the indicated point.

hasGridLines:boolean

Indicate whether grid lines should be drawn across the chart

thresholdValue:number

The value where the threshold line should be drawn

Ignored unless “displayThreshold” is set to “Yes”.

xAxisProperty:string

The property to be used for the X-Axis

This value must either be the name of a valid property in the DataStream objects or the special string “-TIMESTAMP-” (which means to use the “arrival time” of the DataStream event).

yAxisProperties:DataStreamListElement[]

The properties to be used for the Y-Axis

This value must be an array of DataStreamListElement objects; you instantiate them like this:

var dsle = new DataStreamListElement(propertyName:string, label:string);

where “propertyName” is the name of a valid property in the incoming DataStream objects and “label” is a human-readable to be label to used when drawing the chart.


ControlWidget

Widget → ControlWidget

This is the superclass of all “control” Widgets. It is a non-leaf class and cannot be instantiated.

label:string

The Widget’s label text

All “control” Widgets have an optional label that appears above the main body of the Widget. (This is useful when putting a list of controls into a VerticalLayout.) No label will be shown when the value is null or the empty string.

“label” has a default value of “”.

labelAlign:string

The alignment of the Widget’s label text

The label alignment may specified as one of “center”, “left” or “right”. (“center” is the default.)

labelColor:string

The color of the Widget’s label text

The label color may specified using the standard “#RRGGBB” format. (“#000000” is the default.)

labelSize:number

The font size of the Widget’s label text

The label font size may specified in pixels. (“14” is the default.)

labelStyle:string

The style of the Widget’s label text

The style of the label text may be specified as one of “plain”, “bold”, “italic” or “bold-italic”. (“plain” is the default.)


DashboardViewer

WidgetControlWidget → DashboardViewer

This Widget allows you to launch the Dashboard in another browser tab.

placeholder:string

The text that is displayed next to the icon

By default the placeholder says “View the Dashboard” as a hint to the user, suggesting what will happen if they click the icon button. The “placeholder” property allows you to override that string.

startTab:string

The name of the tab of the Dashboard to display (optional)

If not specified the Dashboard will display the last tab that the user was looking at.


DataStreamWidget

Widget → DataStreamWidget

This is the superclass of all “Data Stream” Widgets. It is a non-leaf class and cannot be instantiated.

A DataStream can be found using either the getDataStreamByName() or getDataStreamByUUID() methods on Client.

These are all the Widgets which inherit from the DataStreamWidget class and can be bound to a DataStream:

dataStreamUUID:string

The UUID of the DataStream to which the Widget is bound

If you have a DataStream object you can get its UUID using “theDataStreamObject.uuid”;


DataTable

WidgetDataStreamWidget → DataTable

This Widget displays a table which contain an array of data rows. Each event from the Data Stream is assumed to carry an array which completely replaces the previous one.

borderThickness:number

The thickness of the border in pixels

columnDescriptors:DataTableColumn[]

An array of objects describing each column

The DataTableColumn object contains these properties which must be set:

cellFontColor:string

The color of the text in table cell

The text color is specified using the standard “#RRGGBB” format. (“#000000” is the default.)

cellFontFace:string

The font family of the text in table cell

The font family of the text is specified using normal CSS conventions. (“inherit” is the default.)

cellFontSize:number

The font size of the text in table cell

The font size is specified in pixels. (“14” is the default.)

cellFontStyle:string

The style of the text in table cell

The style of the text may be specified as one of “plain”, “bold”, “italic” or “bold-italic”. (“plain” is the default.)

headerFontColor:string

The color of the text in table header

The text color is specified using the standard “#RRGGBB” format. (“#000000” is the default.)

headerFontFace:string

The font family of the text in table header

The font family of the text is specified using normal CSS conventions. (“inherit” is the default.)

headerFontSize:number

The font size of the text in table header

The font size is specified in pixels. (“14” is the default.)

headerFontStyle:string

The style of the text in table header

The style of the text may be specified as one of “plain”, “bold”, “italic” or “bold-italic”. (“plain” is the default.)

rowsPerPage:number

The number of rows shown in each “page” of the DataTable

The Data Table only shows “rowsPerPage” rows of data at a time; there is a “paginator” widget shown at the bottom of the table that allows you to page forward and backward through the data.

selectedObjectIndex:number

Index of the currently selected row object in original data set

If you define a “Select” Event handler then the Data Table will support the selection of rows. This property may be used to programmatically get the index of selected row object in original data set. This index starts at 0.

selectedRowIndex:number

Index of the currently selected row on current visible page

If you define a “Select” Event handler then the Data Table will support the selection of rows. This property may be used to programmatically get the the index of selected row on current visible page. This index starts at 0 and is less than rowsPerPage.

selectedRowObject:any

The currently selected row object

If you define either a “Select” or “Deselect” Event handler then the Data Table will support the selection and deselection of rows. This property may be used to programmatically get and set the selected row object.

On Select Event

This Widget supports an “On Select” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onSelect(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains the row object which was selected.

On Deselect Event

This Widget supports an “On Deselect” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onDeselect(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains the row object which was deselected.


Droplist

WidgetControlWidget → Droplist

This Widget is used to enter a value as a standard “dropdown list”.

dataBinding:string

The name of a String, Integer or Real DataObject variable

This Widget can be bound to a DataObject variable of type “String”, “Integer” or “Real” (e.g. “client.data.myInteger”). Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.

enumeratedList:any[]

The Droplist menu definition

When clicked a Droplist presents a menu of choices. Each choice consists of a “label” (the text the user sees) and a “value” (the actual value that is used by the dataBinding). The array must be formed like this:

var enumList = [
    {value:1, label:"One"},
    {value:2, label:"Two"},
    {value:3, label:"Three"}
];

In this example the user would see a dropdown menu with the items “One”, “Two” and “Three”. If the user selected “Two” the bound DataObject variable would be set to the number 2.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


DocumentViewer

WidgetControlWidget → DocumentViewer

This Widget allows you to display a web page or a Vantiq document in another browser tab.

flavor:string

The type of document to be displayed

This property is optional; if supplied it must be one of the following types:

The “vaudio”, “vimage” and “vvideo” flavors are used to listen, view or stream media which have been previously uploaded to a Vantiq document. (This can either be done manually using the Dev Portal or with the Vantiq mobile app).

placeholder:string

The text that is displayed next to the icon

By default the placeholder says “View the Dashboard” as a hint to the user, suggesting what will happen if they click the icon button. The “placeholder” property allows you to override that string.

url:string

The url of the document to display

For the “html” and “pdf” flavors this must be a complete URL. For the other flavors (“vaudio”, “vimage” or “vvideo”) this is a fragment that references a Vantiq document. It will look like:

"rcs/audio/f9ceddab-add2-4b10-a602-65f82cc0a9da.m4a"

DynamicMapViewer

WidgetDataStreamWidget → DynamicMapViewer

This Widget shows location points on a map as they arrive from the Data Stream.

Note that the DynamicMapView uses Google Maps which is not available in China. VANTIQ users in China will build their Clients using the BaiduMapViewer which provides the equivalent functionality.

borderThickness:number

The thickness of the border in pixels

dataStreamProperty:string

The property that contains the GeoJSON Location value

This value must the name of a valid property in the DataStream objects that contains the GeoJSON location.

fixedCenter:boolean

Indicate if the map should move when new points arrive

If “fixedCenter” is “true” (the default) the map will center on the first point to arrive and not move again unless the user moves it. If “fixedCenter” is “false” then the map will re-center on each new point as it arrives. Note: to see more than one pin on the map, set the Group By attribute on the data stream used by the map.

labelProperty:string

The property that contains a label for each location

This value must the name of a valid property in the DataStream objects that contains a label for the corresponding point in “dataStreamProperty”.

maptype:string

The map type

This value must be a valid map type, one of “Roadmap”, “Hybrid”, “Satellite” or “Terrain”. (The default is “Roadmap”.) You should specify this value using one of these four constants:


FloorplanViewer

WidgetDataStreamWidget → FloorplanViewer

This Widget shows location points on a fixed image (floorplan) as they arrive from the Data Stream.

borderThickness:number

The thickness of the border in pixels

dataStreamProperty:string

The property that contains the GeoJSON Location value

This value must the name of a valid property in the DataStream objects that contains the GeoJSON location.

filterObjectString:string

String version on a JSON objects containing filtering information

This property is optional; it is the stringified version of a JSON object which contains information on how to filter the incoming data.

The object should look something like this:

var filterObject = {
    floorNumber: 2
}

This means that the FloorplanViewer will only use location data from data objects which also contain a property called “floorNumber” with a value of “2”. This is useful if you a single Data Stream reporting location data but wish to divide it up into multiple FloorplanViewers which show different floors or areas.

imageHeightInLocationUnits:number

The height of the image

This describes the height of the image in whatever units the Location data uses.

imageWidthInLocationUnits:number

The width of the image

This describes the width of the image in whatever units the Location data uses.

isScaleable:boolean

Indicates whether the image is scaled or shown at its “natural” size

If this property is “false” (the default) the Widget (and the image it contains) are shown at the image’s “natural” size. If “true” then the image is scaled to the Widget’s width (and the height is scaled to maintain the correct aspect ratio).

labelProperty:string

The property that contains a label for each location

This value must the name of a valid property in the DataStream objects that contains a label for the corresponding point in “dataStreamProperty”.


FlowLayout

WidgetWidgetContainer → FlowLayout

This is a “container” widget that arranges its visible children into a “flow” where they arranged left-to-right and top-to-bottom in the same manner that an HTML “div” does. The children are arranged from left-to-right in the order given by the “children” property. (The index of a child within its parent’s “children” array determines its position in the flow.)

The width of a FlowLayout determines where the children “wrap”; the height of a FlowLayout grows as necessary to accommodate its children.


FooterButton

WidgetControlWidget → FooterButton

This is a button that appears in the footer area of a Page. (To put a button in the “main” area you must use a Button Widget.)

buttonLabel:string

The text of the FooterButton

glyphIcon:string

Display a Bootstrap Glyphicon to the left of the button text

For a list of valid icons see here. For example you could enter a value from that list such as “glyphicon-asterisk”. The default is “null” which omits the icon.

submitValue:number

A value to identify the button when it is used to submit a default response

For a discussion of how this property is used see Terminating with default Buttons.

On Click Event

This Widget supports an “On Click” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onClick(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


Gauge

WidgetDataStreamWidget → Gauge

This Widget shows a simple “gauge” that displays a single value from the most recent object from the Data Stream.

There are four property values that define the range bands of the Gauge. For things to make sense the following relationships should be maintained:

minimum < yellowMinimum < redMinimum < maximum

borderThickness:number

The thickness of the border in pixels

dataStreamProperty:string

The property that contains the GeoJSON Location value

This value must the name of a valid property in the DataStream objects that contains the GeoJSON location.

maximum:number

The maximum value displayed by the Gauge

minimum:number

The minimum value displayed by the Gauge

minorTicks:number

The interval at which to draw minor ticks on the Gauge

redMinimum:number

The value at which the Gauge turns red.

yellowMinimum:number

The value at which the Gauge turns yellow


GridLayout

WidgetWidgetContainer → GridLayout

This is a “container” widget that arranges its visible children into a “grid” with a fixed number of rows and columns. (The index of a child within its parent’s “children” array is irrelevant.) A grid “cell” can only contain one child at a time.

You can adjust the number of cells in a GridLayout by changing the “rows” and “columns” property, but any cells which would be “lost” must be empty.

columns:number

The number of columns in the Grid

The number of columns must be a positive integer (default is “2”).

rows:number

The number of rows in the Grid

The number of rows must be a positive integer (default is “2”).


HorizontalLayout

WidgetWidgetContainer → HorizontalLayout

This is a “container” widget that arranges its visible children into a horizontal “stack”. The children are arranged from left-to-right in the order given by the “children” property. (The index of a child within its parent’s “children” array determines its position in the stack.)


ImageMarkup

WidgetControlWidget → ImageMarkup

This Widget is used to show an image to the user which can be “marked up” using some simple drawing tools. The image can come from the camera (so the user can snap a picture and then mark it up) or from an image Document or URL.

clearUpload()

Reset the camera to its initial state

clearUpload():void

After a image has been captured you can call this method to reset it to “empty”.

documentName:string

The name of the document to which the image was uploaded

This property is readonly - it will be null until after an image has been captured and uploaded at which time it will contain the name of the Document where it was saved.

optional:boolean

Specify whether a clip must be recorded before a default “submit”

placeholder:string

The optional “placeholder” value

If “source” has been set to “camera” the placeholder defaults to “Take a photo and mark it up”. Otherwise the default is “Mark up an image”.

source:string

The source of the image to be offered to the user for markup

This may be the string “camera” (if you want the user to snap an image first), the URL of an accessible image from the internet or an image Document in the VANTIQ server. (Image Documents must start with “rcs/image/…”).

The default value is “camera”.


InputDate

WidgetControlWidget → InputDate

This Widget is used to enter or edit only the “date” portion of a DateTime. When clicked the Widget will show an appropriate popup Dialog which will allow the user to enter and edit the bound data.

dataBinding:string

The name of an Object or TypedObject DataObject variable

This Widget can be bound to a DataObject variable of type “DateTime” (e.g. “client.data.myDate”). The DataObject variable may be marked as an array. Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.

defaultValue:any

The default value for the Widget

If the widget is bound to a DataObject then the DataObject’s value overrides this default.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.

InputDateTime

WidgetControlWidget → InputDateTime

This Widget is used to enter or edit DateTime values. When clicked the Widget will show an appropriate popup Dialog which will allow the user to enter and edit the bound data.

dataBinding:string

The name of a DateTime variable

This Widget can be bound to a DataObject variable of type “DateTime” (e.g. “client.data.myDateTime”). Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.

defaultValue:any

The default value for the Widget

If the widget is bound to a DataObject then the DataObject’s value overrides this default.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


ImageViewer

WidgetControlWidget → ImageViewer

This Widget allows you to display an image inside a VerticalLayout at a reduced size. (Its width is sized to the width of its parent and the height is scaled to match). When clicked the image displays at full size inside another browser tab.

url:string

The url of the image to display


InputInteger

WidgetControlWidgetInputNumeric → InputInteger

This Widget is used to input an Integer value.

dataBinding:string

The name of an Integer DataObject variable

This Widget can be bound to a DataObject variable of type “Integer” (e.g. “client.data.myInteger”). Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.


InputNumeric

WidgetControlWidget → InputNumeric

This is the superclass of the two “numeric input” Widgets InputInteger and InputReal. It is a non-leaf class and cannot be instantiated.

defaultValue:number

The default value for the Widget

If the widget is bound to a DataObject then the DataObject’s value overrides this default.

flavor:string

The display style of the input control

When editing or displaying numeric input you can specify the “flavor” of the Widget; this must be either “text” or “slider”.

isReadOnly:boolean

Disables input into the field

maxValue:number

The maximum value when in “slider” mode

Defaults to “100”.

minValue:number

The minimum value when in “slider” mode

Defaults to “0”.

optional:boolean

Specify whether a value must be entered before a default “submit”

placeholder:string

The optional “placeholder” value when in “text” mode

Defaults to “”.

units:string

The optional “units” text label when in “slider” mode

Defaults to “”.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


InputObject

WidgetControlWidget → InputObject

This Widget is used to enter Objects, arrays of Objects, TypedObjects or arrays of TypedObjects. When clicked the Widget will show an appropriate popup Dialog which will allow the user to enter and edit the bound data.

dataBinding:string

The name of an Object or TypedObject DataObject variable

This Widget can be bound to a DataObject variable of type “Object” or “TypedObject” (e.g. “client.data.myObject”). The DataObject variable may be marked as an array. Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.

defaultValue:any

The default value for the Widget

If the widget is bound to a DataObject then the DataObject’s value overrides this default.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


InputReal

WidgetControlWidgetInputNumeric → InputReal

This Widget is used to input a Real value.

dataBinding:string

The name of an Real DataObject variable

This Widget can be bound to a DataObject variable of type “Real” (e.g. “client.data.myReal”). Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.


InputString

WidgetControlWidget → InputString

This Widget is used to enter a String value.

dataBinding:string

The name of a String DataObject variable

This Widget can be bound to a DataObject variable of type “String” (e.g. “client.data.myString”). Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.

defaultValue:string

The default value for the Widget

If the widget is bound to a DataObject then the DataObject’s value overrides this default.

isPassword:boolean

Specify if this is a “password” field (masking the input)

isReadOnly:boolean

Disables input into the field

optional:boolean

Specify whether a value must be entered before a default “submit”

placeholder:string

The optional “placeholder” value

Defaults to “”.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


Label

WidgetControlWidget → Label

This is a special kind of ControlWidget which contains no active Widget but just the “Label” portion. It is intended for use inside a VerticalLayout with other ControlWidgets. In other cases it is more appropriate to use the StaticText Widget.

It differs from SectionLabel in that it has a slightly different appearance making it suitable for labeling a single item rather than an entire “section” in the VerticalLayout.


LineChart

WidgetDataStreamWidget → LineChart

This Widget draws a “line chart”.

borderThickness:number

The thickness of the border in pixels

displayThreshold:string

Indicate whether a thresholdline will be drawn across the chart at “thresholdValue”

“displayThreshold” may be set to either “Yes” or “No” (the default is “No”). When “Yes” is specified the value of the “thresholdValue” property is used to draw a “threshold line” across the chart at the indicated point.

hasGridLines:boolean

Indicate whether grid lines should be drawn across the chart

showArea:boolean

Indicate whether the area should be drawn in under the chart lines

showPoints:boolean

Indicate whether the data points should be draw on the chart lines

thresholdValue:number

The value where the threshold line should be drawn

Ignored unless “displayThreshold” is set to “Yes”.

xAxisProperty:string

The property to be used for the X-Axis

This value must either be the name of a valid property in the DataStream objects or the special string “-TIMESTAMP-” (which means to use the “arrival time” of the DataStream event).

yAxisProperties:DataStreamListElement[]

The properties to be used for the Y-Axis

This value must be an array of DataStreamListElement objects; you instantiate them like this:

var dsle = new DataStreamListElement(propertyName:string, label:string);

where “propertyName” is the name of a valid property in the incoming DataStream objects and “label” is a human-readable to be label to used when drawing the chart.


ListViewer

WidgetDataStreamWidget → ListViewer

This Widget shows a single value from the most recent objects to arrive on the Data Stream. Each display row also includes the time that the row arrived.

borderThickness:number

The thickness of the border in pixels

dataStreamProperty:string

The property within the Data Stream object to display in the list

hasSeparators:boolean

Indicates whether to show separators between the rows

maxRows:number

The maximum number of rows the List Viewer should display


MapViewer

WidgetControlWidget → MapViewer

This Widget is used to launch a map viewer at a specific location. This is different from the functionality provided by DynamicMapViewer and BaiduMapViewer which tracks location data coming in from a DataStream.

Note that this Widget can be used to collect input as well; the user may click on the map to indicate a location which will become the “value” of the Widget when results are sent to the server.

defaultValue:any

The default location for the center of the map

This allows you to supply a default value for the result of the scan. It may be either a GeoJSON POINT object or a simple JSON object with the properties “longitude” and “latitude”.

maptype:string

The map type

This value must be a valid map type, one of “Standard”, “Hybrid” or “Satellite”. (The default is “Standard”.) You should specify this value using one of these three constants:

markers:any[]

An array describing markers which are to appear on the map

Here is an example of an array which describes two markers:

[
   {"label": "Space Mountain", "longitude": -117.917193, "latitude": 33.811379, color:"azure"},
   {"label": "Haunted Mansion", "longitude": -117.922675, "latitude": 33.811530, color:"magenta"}
]

The “color” property is optional and can be one of “azure”, “blue”, “cyan”, “green”, “magenta”, “orange”, “red”:, “rose”, “violet” or “yellow”.

minMapWidthInMeters:number

The minimum map width in meters

optional:boolean

Specify whether a clip must be recorded before a default “submit”

placeholder:string

The optional “placeholder” value

Defaults to “Show Map”.


WidgetControlWidget → MenuButton

This is a Button that has been styled to be suitable for use in the TopBar or SideBar of a Client.

fontColor:string

The color of the Button text

The text color is specified using the standard “#RRGGBB” format. (“#000000” is the default.)

fontSize:number

The font size of the Button text

The font size is specified in pixels. (“18” is the default.)

fontStyle:string

The style of the Button text

The style of the text may be specified as one of “plain”, “bold”, “italic” or “bold-italic”. (“plain” is the default.)

glyphIcon:string

Display a Bootstrap Glyphicon to the left of the button text

For a list of valid icons see here. For example you could enter a value from that list such as “glyphicon-asterisk”. The default is “null” which omits the icon.

text:string

The text of the Button

On Click Event

This Widget supports an “On Click” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onClick(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


MultilineInput

WidgetControlWidget → MultilineInput

This Widget is used to enter a multi-line String value.

dataBinding:string

The name of a String DataObject variable

This Widget can be bound to a DataObject variable of type “String” (e.g. “client.data.myString”). Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.

defaultValue:string

The default value for the Widget

If the widget is bound to a DataObject then the DataObject’s value overrides this default.

isReadOnly:boolean

Disables input into the field

optional:boolean

Specify whether a value must be entered before a default “submit”

placeholder:string

The optional “placeholder” value

Defaults to “”.

rows:number

The number of rows to be displayed.

Defaults to 5.

wordwrap:boolean

Specify whether to wrap text displayed inside the widget.

Defaults to true.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


NumberViewer

WidgetDataStreamWidget → NumberViewer

This Widget shows a simple “infographic” box that displays a single value from the most recent object from the Data Stream.

backgroundColor:string

The background color

The color of the background is specified using the standard “#RRGGBB” format. (“#ff9800” is the default.)

borderThickness:number

The thickness of the border in pixels

dataStreamProperty:string

The property that contains the numeric value

format:string

An optional string to format the number

Some examples of valid format strings are found here.

icon:string

An optional icon to display with the number

This icon string refers to one of the “Font Awesome” icons (such as “fa-circle”).

A full list of possibilities can be found here.

units:string

An optional short string containing the “units” that should be displayed with the number


PieChart

WidgetDataStreamWidget → PieChart

This Widget shows a simple “Pie Chart” by counting up the number of times a certain value appears in the indicated Data Stream object property.

borderThickness:number

The thickness of the border in pixels

dataStreamProperty:string

The property that contains the instances to be counted

For example, the Data Stream property might be “typeOfPet” which would contains such values as “Dog”, “Cat” and “Bird”. The Pie Chart would display the number of times each of those values appear in the incoming data.

showLegend:boolean

Indicates whether to display a legend with the Pie Chart


RadioButtons

WidgetControlWidget → RadioButtons

This Widget is used to enter a value as a standard set of “Radio Buttons” where only one buttons may be selected at a time.

dataBinding:string

The name of a String, Integer or Real DataObject variable

This Widget can be bound to a DataObject variable of type “String”, “Integer” or “Real” (e.g. “client.data.myInteger”). Changes to the DataObject variable will be reflected in the Widget, and changes to the Widget will be used to update the DataObject variable.

enumeratedList:any[]

The RadioButton list definition

RadioButtons present the user with a list of buttons, only one of which may be selected at a time. Each choice consists of a “label” (the text the user sees) and a “value” (the actual value that is used by the dataBinding). The array must be formed like this:

var enumList = [
    {value:1, label:"One"},
    {value:2, label:"Two"},
    {value:3, label:"Three"}
];

In this example the user would see a set of RadioButtons with the labels “One”, “Two” and “Three”. If the user selected “Two” the bound DataObject variable would be set to the number 2.

On Change Event

This Widget supports an “On Change” Event Handler. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onChange(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains no useful information in this case.


VideoRecorder

WidgetControlWidget → VideoRecorder

This Widget is used to record a short video clip. The clip may be uploaded into a Document object on the server.

clearUpload()

Reset the recorder to its initial state

clearUpload():void

After a clip has been recorded you can call this method to reset it to “empty”.

documentName:string

The name of the document to which the clip was uploaded

This property is readonly - it will be null until after a clip has been recorded and uploaded at which time it will contain the name of the Document where it was saved.

maxDurationInSeconds:number

The maximum number of seconds which may be recorded

In order to place a limit of the amount of storage used in your mobile device this setting places a limit on how many seconds of video you may record. (Default - 10 seconds).

maxSizeInK:number

The maximum amount of storage that may be recorded

In order to place a limit of the amount of storage used in your mobile device this setting places a limit on the maximum size of the clip which may be recorded. (Default - 1000K).

optional:boolean

Specify whether a clip must be recorded before a default “submit”

placeholder:string

The optional “placeholder” value

Defaults to “Start Video Recording”.


SectionLabel

WidgetControlWidget → SectionLabel

This is a special kind of ControlWidget which contains no active Widget but just the “Label” portion. It is intended for use inside a VerticalLayout with other ControlWidgets. In other cases it is more appropriate to use the StaticText Widget.

It differs from Label in that it has a slightly different appearance making it suitable for labeling an entire “section” in the VerticalLayout rather than a single item.


StaticHtml

Widget → StaticHtml

This Widget displays a fixed fragment of HTML. It would be useful to display a piece of “rich text” or to embed some kind of HTML media viewer.

Since you can add whatever HTML you like StaticHtml can also be used as the basis for your own custom widgets. As a convenience for this feature you can also associate StaticHtml with a DataStream and then define an “On Data Arrived” event which will be called whenever new data appears. Widgets which are bound to DataStreams are generally subclasses of the DataStreamWidget class; StaticHtml is an exception.

Here are some examples:

<iframe src="//www.youtube.com/embed/Ki_Af_o9Q9s" width="100%" height="100%" frameborder="0" allowfullscreen="allowfullscreen"></iframe>
The quick <span style="color: #993300;">brown</span> <strong><em>fox</em></strong> jumped over the lazy <strong>dog</strong>.

borderThickness:number

The thickness of the border in pixels

dataStreamUUID:string

The UUID of the DataStream to which the Widget is associated

If you have a DataStream object you can get its UUID using “theDataStreamObject.uuid”;

html:string

The HTML to be be displayed

horizontalScrollPolicy:number

Controls the management of horizontal scrollbars on the StaticHtml Widget

The value must be one of StaticHtml.ScrollPolicyNone, StaticHtml.ScrollPolicyAlways or StaticHtml.ScrollPolicyAuto.

verticalScrollPolicy:number

Controls the management of horizontal scrollbars on the StaticHtml Widget

The value must be one of StaticHtml.ScrollPolicyNone, StaticHtml.ScrollPolicyAlways or StaticHtml.ScrollPolicyAuto.

On Data Arrived Event

This Widget supports an “On Data Arrived” Event Handler. This handler will be called whenever new data arrives on the widget’s associated DataStream. The code will be wrapped in a function with a signature of the form:

Client_<page name>_<widget name>_onDataArrived(client,page,extra)

where “client” points to the Client object, “page” points to the current Page and “this” points to the Widget itself.

The “extra” parameter contains the newly arrived data, which will be either an Object or and array of Objects depending on the characteristics of the DataStream.

It is your responsibility to examine this data and extract (and act on) whatever information is appropriate to your custom HTML.

If you need to reference the DataStream object itself you can do it like this:

var theDataStream = client.getDataStreamByUUID(this.dataStreamUUID);

StaticImage

Widget → StaticImage

This Widget displays an loaded from a URL.

isScaleable:boolean

Indicates whether the image is scaled or shown at its “natural” size

If this property is “false” (the default) the Widget (and the image is contains) are shown at the image’s “natural” size. If “true” then the image is scaled to the Widget’s width (and the height is scaled to maintain the correct aspect ratio).

url:string

The URL of the image to be displayed


StaticText

Widget → StaticText

This Widget displays a single list of static text.

fontColor:string

The color of the text

The color of the text is specified using the standard “#RRGGBB” format. (“#000000” is the default.)

fontFamily:string

The font family of the text

The font family of the text is specified using normal CSS conventions. (“Arial,Verdana” is the default.)

fontSize:number

The font size of the text

The font size is specified in pixels. (“20” is the default.)

fontStyle:string

The style of the Widget’s label text

The style of the text is specified as either “normal” or “italic”. (“normal” is the default.)

fontWeight:string

The weight of the Widget’s label text

The weight of the text is specified as either “normal” or “bold”. (“normal” is the default.)

text:string

The text to display


VerticalLayout

WidgetWidgetContainer → VerticalLayout

This is a “container” widget that arranges its visible children into a vertical “stack”. The children are arranged from top-to-bottom in the order given by the “children” property. (The index of a child within its parent’s “children” array determines its position in the stack.)


Widget

This is the superclass of all Widgets which can be displayed in a Client. It is a non-leaf class and cannot be instantiated.

addEventHandler()

Add an event handler to a Widget

addEventHandler(eventName:string, callback:Function)

This is useful if you are dynamically adding Widgets to a Page and you need to add an event handler as well.

    //
    //  Look up an existing container widget to use as a "parent"
    //
    var vc1 = client.getWidget("vc1");

    //
    //  Create a Button and give it a name
    //
    var btn = new Button();
    btn.name = "DynamicButton1";

    //
    //  Add an event handler
    //
    btn.addEventHandler("onClick",function(client,page,extra)
    {
        client.infoDialog("Clicked!","Success");
    });

    //
    //  Add the button to a container so it will become visible and active on the Page
    //
    vc1.addChild(btn);

isContainer:boolean

Is this a container widget? (readonly)

Returns “true” if this Widget is a subclass of WidgetContainer.

isVisible:boolean

Is this widget visible?

By default all Widgets are visible. At runtime you can hide a Widget by setting the value of its “isVisible” property to “true”. When a Widget is invisible it is ignored by its parent when doing layout.

name:string

The name of the Widget.

All Widgets must have a name which uniquely identifies it. A Widget can be found using the getWidget() method on Client.

parent:WidgetContainer

The parent of the Widget (readonly)

All Widgets (except the topmost) have a parent of class WidgetContainer.


WidgetContainer

Widget → WidgetContainer

This is the superclass of all “container” Widgets. It is a non-leaf class and cannot be instantiated.

addChild()

Add a child Widget to a WidgetContainer

addChild(child: Widget, index1: number=-1, index2: number= -2)

GridLayout WidgetContainers arrange their children in a “grid” where each cell is identified by a “row” and “column”. In this case “index1” and “index2” are both required and mean the “row” and “column” of the cell where the child is to be inserted. The cell must be unoccupied or addChild() will throw an exception.

children:Widget[]

The list of “child” Widgets (readonly)

This property contains an array containing all the children of the WidgetContainer.

removeChild()

Remove a child Widget to a WidgetContainer

removeChild(child: Widget)