Namespace: data

mx. data

Retrieve and manipulate MxObjects.

Methods

(static) action(params)

Executes a Microflow. Note that this method is not supported in offline apps.

The params.params.applyto parameter indicates which objects are passed to the Microflow as input.

Name Description
none don’t pass any objects to the Microflow
selection pass the objects with the given GUIDs
set pass the objects matching the given XPath query
Parameters:
Name Type Description
params Object
Properties
Name Type Description
params.actionname string

name of the Microflow to invoke
params.applyto "none" | "set" | "selection"

to what to apply the Microflow
params.guids Array.<GUID>

the GUIDs to apply the Microflow to
params.xpath string

The root entity for an XPath query. The Microflow will be applied to the matching objects.
params.constraints string

the constraints for the xpath parameter
params.sort mx.data~SortSpec

sorting of XPath query results before feeding them to the Microflow
context mendix/lib/MxContext

the context for the Microflow
origin mxui/lib/form/_FormBase

the page on which instructions returned by the server ('close form' in particular) can be executed
async boolean

whether the Microflow should be executed asynchronously. Note that the result of an asynchronous microflow is not returned.
callback mx.data~ActionSuccessCallback

function to handle the result when successful
error mx.data~ActionErrorCallback

function to handle errors
onValidation mx.data~ActionValidationCallback

function to handle validation feedback
Examples

Calling a simple Microflow, not expecting any entities

mx.data.action({
    params: {
        actionname: "MyFirstModule.PetCat"
    },
    origin: this.mxform,
    callback: function(obj) {
        // no MxObject expected
        alert("Just petted the cat a little");
    },
    error: function(error) {
        alert(error.message);
    },
    onValidation: function(validations) {
        alert("There were " + validation.length + " validation errors");
    }
});

Calling a Microflow expecting a list of entities, using an XPath query

mx.data.action({
    params: {
        applyto: "set",
        actionname: "MyFirstModule.GetFavoriteFood",
        xpath: "//MyFirstModule.Cat",
        constraints: "[id=281530811285515 or id=281530811285506]"
    },
    origin: this.mxform,
    callback: function(obj) {
        // expect single MxObject
        alert(obj.get("manufacturer"));
    },
    error: function(error) {
        alert(error.message);
    }
});

Performing the same request, but now using a list of `GUIDs`

mx.data.action({
    params: {
        applyto: "selection"
        actionname: "MyFirstModule.GetFavoriteFood",
        guids: [ "281530811285515", "281530811285506"]
    },
    origin: this.mxform,
    callback: function(obj) {
        // expect single MxObject
        alert(obj.get("manufacturer"));
    },
    error: function(error) {
        alert(error.message);
    }
});

Showing a progress bar while calling a microflow

var progressId = window.mx.ui.showProgress("Progress msg", true);
mx.data.action({
    params: {
        actionname: "MyFirstModule.PetCat"
    },
    origin: this.mxform,
    callback: function(obj) {
        // no MxObject expected
        alert("Just petted the cat a little");
        window.mx.ui.hideProgress(progressId);
    },
    error: function(error) {
        alert(error.message);
        window.mx.ui.hideProgress(progressId);
    },
    onValidation: function(validations) {
        alert("There were " + validation.length + " validation errors");
    }
});

(static) callNanoflow(params)

Executes a Nanoflow.

Parameters:
Name Type Description
params Object
Properties
Name Type Description
nanoflow Object

Nanoflow definition to execute, this value is exported to the property defined in the custom widget. This value may change, so it should not be tampered.
context mendix/lib/MxContext

the context for the Nanoflow
origin mxui/lib/form/_FormBase

the page on which instructions ('close form' in particular) can be executed
callback mx.data~ActionSuccessCallback

function to handle the result when successful
error mx.data~ActionErrorCallback

function to handle errors
Example

Calling a simple Nanoflow

mx.data.callNanoflow({
    nanoflow: this.propertyWithNanoflow,
    origin: this.mxform,
    context: this.mxcontext,
    callback: function(result) {
        alert("Nanoflow completed with result " + result);
    },
    error: function(error) {
        alert(error.message);
    }
});

(static) commit(args, scope)

Commits an MxObject.

When there are changes, these will automatically be sent to the Runtime.

Parameters:
Name Type Description
args Object
Properties
Name Type Description
mxobj mendix/lib/MxObject

MxObject to save changes for
mxobjs Array.<mendix/lib/MxObject>

MxObjects to save changes for
callback mx.data~CommitSuccessCallback

function to handle the result when successful
error mx.data~CommitErrorCallback

function to handle errors
onValidation mx.data~CommitValidationCallback

function to handle validation feedback
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.commit({
    mxobj: obj,
    callback: function() {
        console.log("Object committed");
    },
    error: function(e) {
        console.error("Could not commit object:", e);
    }
});

(static) create(args, scope)

Creates an MxObject.

Parameters:
Name Type Description
args Object
Properties
Name Type Description
entity string

entity to create an instance of
callback mx.data~CreateSuccessCallback

function to handle the result when successful
error mx.data~CreateErrorCallback

function to handle errors
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.create({
    entity: "MyFirstModule.Cat",
    callback: function(obj) {
        console.log("Object created on server");
    },
    error: function(e) {
        console.error("Could not commit object:", e);
    }
});

(static) get(args, scopenullable)

Retrieves MxObjects from the Runtime (in online apps) or from the local database (in offline apps). Note that not every parameter is supported in offline apps.

Only one of the guid / guids / xpath / microflow parameters should be set.

Parameters:
Name Type Attributes Description
args Object
Properties
Name Type Attributes Description
guid GUID

GUID of the object to retrieve
guids Array.<GUID>

GUIDS of the objects to retrieve
xpath string

XPath query to retrieve (not supported offline)
microflow string

a Microflow to fetch objects from (not supported offline)
path string

Path (reference name) to the desired object, relative to the object referenced by guid. E.g. MyFirstModule.Child_Parent.
callback mx.data~GetSuccessCallback

function to handle the result
error mx.data~GetErrorCallback <nullable>

function to handle errors
count boolean <nullable>

whether a count of the entire set should be returned
filter.attributes Array.<string> <nullable>

if provided, only the given attributes will be fetched
filter.offset number <nullable>

index from where to start in the set
filter.sort mx.data~SortSpec <nullable>

specifies how the result set should be sorted
filter.amount number <nullable>

maximum number of objects to fetch
filter.distinct boolean <nullable>

only fetch distinct objects
filter.references Object.<string, mx.data~ReferencesSpec> <nullable>

If provided, the given references, specified as keys of args.filter.references, will be pre-fetched within the same request. Pre-fetched objects will be accessible via mxobj.getChildren. Supported only for retrieval through XPath.
scope Object <nullable>

scope in which the error and callback handler are invoked
Examples
mx.data.get({
    guids: [ "123456", "456789" ],
    callback: function(objs) {
        console.log("Received " + objs.length + " MxObjects");
    }
});
mx.data.get({
    guid: "123456",
    callback: function(obj) {
        console.log("Received MxObject with GUID " + obj.getGuid());
    }
});
mx.data.get({
    xpath: "//System.User",
    callback: function(objs) {
        console.log("Received " + objs.length + " MxObjects");
    }
});
mx.data.get({
    xpath: "//System.User",
    filter: {
        sort: [["Name", "asc"]],
        offset: 0,
        amount: 10
    },
    callback: function(objs) {
        console.log("Received " + objs.length + " MxObjects");
    }
});

(static) getOffline(entity, constraints, filter, callback, error)

Retrieve MxObjects from the local database. Note that this method is not supported in online apps.

Parameters:
Name Type Description
entity string

the entity of the objects to retrieve
constraints Array.<Object>

an array of constraints to filter returned records.

Properties
Name Type Attributes Description
operator string

the operator to constrain with. One of equals, lessThan, lessThanOrEquals, greaterThan, greaterThanOrEquals, contains, and, or.
attribute string <nullable>

the attribute (or reference) to constrain on Should be omitted for and and or operators.
value string | number

an argument for the constraints's operator. Should be omitted for and and or operators.
negate boolean <nullable>

if true, return the objects not matching the constraint. Should be omitted for and and or operators.
constraints Array.<Object> <nullable>

nested constraints to combine with given operator. Should only be used with and and or operators.
filter Object

sorting and paging options additionally limiting what objects to retrieve

Properties
Name Type Attributes Description
offset number <nullable>

index from where to start in the results
limit number <nullable>

maximum number of objects in the result
sort mx.data~SortSpec <nullable>

specifies how the result set should be sorted
callback mx.data~GetOfflineSuccessCallback

function to handle the result
error mx.data~GetOfflineErrorCallback

function to handle errors
Examples
mx.data.getOffline("MyFirstModule.Pet", [], {}, function(mxobjs, count) {
  console.log("There are " + count + " pets");
});
mx.data.getOffline("MyFirstModule.Pet", [{
  attribute: "MyFirstModule.Pet_Person",
  operator: "equals",
  value: "1234" // the guid of the owner, which is a Person entity
}], {}, function(mxobjs, count) {
  console.log("There are " + count + " pets referring to owner 1234");
});
mx.data.getOffline("MyFirstModule.Pet", [{
  operator: "or",
  constraints: [{
        attribute: "Name",
        operator: "equals",
        value: "ed"
     }, {
        attribute: "Name",
        operator: "equals",
        value: "jack"
     }]
  }], {}, function(mxobjs, count) {
  console.log("There are " + count + " pets whose name is either 'ed' or 'jack'");
});
mx.data.getOffline("MyFirstModule.Pet", [{
  attribute: "Name",
  operator: "contains",
  value: "ed"
}, {
  attribute: "Age",
  operator: "greaterThan",
  value: 2
}], {
  offset: 15,
  limit: 5,
  sort: [["Name", "asc"], ["Age", "desc"]]
}, function(mxobjs, count) {
  console.log("Pets that matched your filter: " + mxobjs.length);
  console.log("Pets that matched your query: " + count);
}, function(e) {
  console.error("Could not retrieve slice:", e);
});

(static) remove(args, scope)

Removes MxObjects.

Only one of args.guid or args.guids should be set.

Parameters:
Name Type Description
args Object
Properties
Name Type Description
guid GUID

GUID of MxObject to remove
guids Array.<GUID>

GUIDs of MxObjects to remove
callback mx.data~RemoveSuccessCallback

function to handle the result when successful
error mx.data~RemoveErrorCallback

function to handle errors
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.remove({
    guid: "123456",
    callback: function() {
        console.log("Object removed");
    },
    error: function(e) {
        console.error("Could not remove object:", e);
    }
});

mx.data.remove({
    guids: [ "123456", "45678" ],
    callback: function() {
        console.log("Objects removed");
    },
    error: function(e) {
        console.log("Could not remove objects:", e);
    }
});

(static) rollback(args, scope)

Rollbacks an MxObject.

Parameters:
Name Type Description
args Object
Properties
Name Type Description
mxobj mendix/lib/MxObject

MxObject to rollback changes for
mxobjs Array.<mendix/lib/MxObject>

MxObjects to rollback changes for
callback mx.data~RollbackSuccessCallback

function to handle the result when successful
error mx.data~RollbackErrorCallback

function to handle errors
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.rollback({
    mxobj: obj,
    callback: function() {
        console.log("The object was rollbacked");
    },
    error: function(e) {
        console.error("Could not rollback object:", e);
    }
});

(static) saveDocument(guid, fileName, params, blob, callback, error)

Save a document file.

Parameters:
Name Type Description
guid GUID

GUID of the MxObject to associate the file with.
fileName string

file name to store the file with. If null, it will be derived from the blob parameter. For File blobs (e.g. those retrieved from an <input type='file'>) this is the name of the file, for Blob objects it is blob.
params Object

additional parameters when saving the file. These depend on the type of document to upload. For images, width and height specify the width and height of the thumbnail that will be generated for the image.
blob

Blob containing the file data.
callback mx.data~SaveDocumentSuccessCallback

success handler.
error mx.data~SaveDocumentErrorCallback

error handler.
Example
var fileBlob = document.querySelector("input[type=file]").files[0];
mx.data.saveDocument("123456", "Bunnies.jpg", { width: 180, height: 180 }, fileBlob, function() {
  // success
}, function(e) {
  console.error(e);
});

(static) subscribe(args) → {mx.data~SubscribeHandle}

Registers a callback to be invoked on changes in an MxObject, an attribute of a MxObject, any changes to MxObjects of a specific entity or validations errors in a specific MxObject.

In a widget it is highly recommended to use mxui/widget/_WidgetBase#subscribe instead, which makes sure the subscription is automatically removed when the widget is destroyed.

Parameters:
Name Type Description
args Object
Properties
Name Type Attributes Description
guid GUID <nullable>

GUID to subscribe to
entity string <nullable>

entity to subscribe to
attr string <nullable>

attribute to subscribe to
val boolean <nullable>

subscribe to a validation on an MxObject
callback mx.data~SubscribeEntityCallback | mx.data~SubscribeObjectCallback | mx.data~SubscribeAttributeCallback | mx.data~SubscribeValidationCallback

function to invoke when an update is available
Returns:

handle which can be passed to unsubscribe to remove the subscription

Type
mx.data~SubscribeHandle
Examples
// Subscribe to all changes in an MxObject
var subscription = mx.data.subscribe({
    guid: "123213",
    callback: function(guid) {
        console.log("Object with guid " + guid + " changed");
    }
});

mx.data.unsubscribe(subscription);
// Subscribe to changes in a specific attribute of an MxObject
var subscription = mx.data.subscribe({
    guid: "123213",
    attr: "Name",
    callback: function(guid, attr, value) {
        console.log("Object with guid " + guid + " had its attribute " +
                    attr + " change to " + value);
    }
});

mx.data.unsubscribe(subscription);
// Subscribe to validations of an MxObject
var subscription = mx.data.subscribe({
    guid: "123213",
    val: true,
    callback: function(validations) {
        var reason = validations[0].getReasonByAttribute("MyAttribute");
        console.log("Reason for validation error on attribute MyAttribute: " + reason);
    }
});

mx.data.unsubscribe(subscription);
// Subscribe to changes in a class
var subscription = mx.data.subscribe({
    entity: "System.User",
    callback: function(entity) {
        console.log("Update on entity " + entity);
    }
});

mx.data.unsubscribe(subscription);

(static) unsubscribe(handle)

Unregisters a callback registered through mx.data~subscribe.

Unregistering callbacks when they are no longer needed is important to prevent memory leaks.

Parameters:
Name Type Description
handle mx.data~SubscribeHandle

handle previously returned by a call to mx.data~subscribe
Example
// First subscribe:
var subscription = mx.data.subscribe({
    entity: "System.User",
    callback: function(entity) {
        console.log("Received update for entity " + entity);
    }
});

// And then unsubscribe:
mx.data.unsubscribe(subscription);

(static) update(args)

Calls listeners to changes in a MxObject, an attribute of a MxObject or any changes to MxObjects of a entity.

Parameters:
Name Type Description
args Object
Properties
Name Type Description
guid GUID

GUID to invoke the update for
entity string

entity to invoke the update for
attr string

attribute to invoke the update for
callback mx.data~UpdateCallback

function to be called after all invocations have been done
Examples
// Trigger object subscriptions
mx.data.update({
    guid: "123213"
});
// Trigger attribute subscriptions
mx.data.update({
    guid: "123213",
    attr: "Name"
});
// Trigger entity subscriptions
mx.data.update({
    entity: "System.User",
});

Type Definitions

ActionErrorCallback(errornullable)

Error callback for mx.data.action

Parameters:
Name Type Attributes Description
error Error <nullable>

error describing the failure of the request

ActionSuccessCallback(value)

Success callback for mx.data.action

Parameters:
Name Type Description
value mendix/lib/MxObject | Array.<mendix/lib/MxObject> | boolean | number | string

ActionValidationCallback(validations)

Validation callback for mx.data.action

Parameters:
Name Type Description
validations Array.<mendix/lib/ObjectValidation>

validations received for the request

CommitErrorCallback(error)

Error callback for mx.data.commit

Parameters:
Name Type Description
error Error

Error describing the failure of the request.

CommitSuccessCallback()

Success callback for mx.data.commit

CommitValidationCallback(validations)

Validation callback for mx.data.commit

Parameters:
Name Type Description
validations Array.<mendix/lib/ObjectValidation>

validations received for the request

CreateErrorCallback(error)

Error callback for mx.data.create

Parameters:
Name Type Description
error Error

error describing the failure of the request

CreateSuccessCallback(created)

Success callback for mx.data.create

Parameters:
Name Type Description
created mendix/lib/MxObject

object

GetBacktrackConstraintsCallback(xpath, allMatched)

Callback to handle the result of mx.data.getBacktrackConstraints.

Parameters:
Name Type Description
xpath string

generated XPath query
allMatched boolean

indicates whether all backtracking constraints could be matched

GetErrorCallback(error)

Error callback for mx.data.get

Parameters:
Name Type Description
error Error

error describing the failure of the request

GetOfflineErrorCallback(error)

Error callback for mx.data.getOffline

Parameters:
Name Type Description
error Error

error describing the failure of the request

GetOfflineSuccessCallback(objs, count)

Success callback for mx.data.getOffline

Parameters:
Name Type Description
objs Array.<mendix/lib/MxObject>

the requested objects
count number

the total number of matching objects before filtering

GetSuccessCallback(objs, extra)

Success callback for mx.data.get

Parameters:
Name Type Description
objs mendix/lib/MxObject | Array.<mendix/lib/MxObject>

either a single MxObject or an array of `MxObjects, depending on the original request.
extra
Properties
Name Type Description
count number

when a count was requested, the total number of matching objects before filtering

ReferencesSpec

Specifies how objects associated with the requested one must be fetched.

Type:
  • Object
Properties:
Name Type Attributes Description
attributes Array.<string> <nullable>

if provided, only the given attributes of an objects will be fetched
amount number <nullable>

maximum number of objects to fetch
sort mx.data~SortSpec <nullable>

specifies how the result set should be sorted

RemoveErrorCallback(error)

Error callback for mx.data.remove

Parameters:
Name Type Description
error Error

error describing the failure of the request

RemoveSuccessCallback()

Success callback for mx.data.remove

RollbackErrorCallback(error)

Error callback for mx.data.rollback

Parameters:
Name Type Description
error Error

error describing the failure of the request

RollbackSuccessCallback()

Success callback for mx.data.rollback

SaveDocumentErrorCallback(error)

Error callback for mx.data.rollback

Parameters:
Name Type Description
error Error

error describing the failure

SaveDocumentSuccessCallback()

Success callback for mx.data.saveDocument

SortSpec

Specifies how the result set must be sorted.

Consists of ordered pairs of an attribute name and a string "asc" or "desc".

Type:
  • Array.<Array.<string>>
Example
[ [ "LastName", "asc" ], [ "FirstName", "asc" ] ]

SubscribeAttributeCallback(guid, attribute, value)

Callback to register for attribute changes

Parameters:
Name Type Description
guid GUID

GUID of the changed object
attribute string

attribute that was changed
value *

new value of the attribute

SubscribeEntityCallback(entity)

Callback to register for entity changes

Parameters:
Name Type Description
entity string

SubscribeHandle

Handle to a subscription

SubscribeObjectCallback(`GUID`)

Callback to register for object changes

Parameters:
Name Type Description
`GUID` GUID

of the changed object.

SubscribeValidationCallback(validations)

Callback to register for object validations

Parameters:
Name Type Description
validations Array.<mendix/lib/ObjectValidation>

validations for the object

UpdateCallback()

Callback called after invocations by mx.data~update are done

ValidateErrorCallback(error)

Error callback for mx.data.validate

Parameters:
Name Type Description
error Error

Error describing the failure of the request.

ValidateSuccessCallback()

Success callback for mx.data.validate