Namespace: data

mx. data

Retrieve and manipulate MxObjects.

Methods

(static) action()

Executes a Microflow.

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
selectionset pass the objects matching the given XPath query

If params.params.applyto is selectionset, params.params.gridid is set and the corresponding grid is single selection, only the first queried object is considered.

Parameters:
Name Type Description
params.params.actionname string

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

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

the GUIDs to apply the Microflow to
params.params.xpath string

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

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

sorting of XPath query results before feeding them to the Microflow
params.params.gridid string

the grid ID of the data grid which is providing the selection information
params.context mendix/lib/MxContext

the context for the Microflow
params.store.caller mxui/mixin/_Scriptable

the caller instance, on which server instructions can be executed
params.async boolean

whether the Microflow should be executed asynchronously
params.callback mx.data~ActionSuccessCallback

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

function to handle errors
params.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"
    },
    callback: function(obj) {
        // no MxObject expected
        alert("Just petted the cat a little");
    },
    error: function(error) {
        alert(error.description);
    },
    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]",
    },
    callback: function(obj) {
        // expect single MxObject
        alert(obj.get("manufacturer"));
    },
    error: function(error) {
        alert(error.description);
    }
}, this);

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

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

(static) commit(scope)

Commits an MxObject.

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

Parameters:
Name Type Description
args.mxobj mendix/lib/MxObject

MxObject to save changes for
args.callback mx.data~CommitSuccessCallback

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

function to handle errors
args.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.log("Error occurred attempting to commit: " + e);
    }
});

(static) create(scope)

Creates an MxObject.

Parameters:
Name Type Description
args.entity string

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

function to handle the result when successful
args.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.log("an error occured: " + e);
    }
});

(static) createXPathString()

Creates an XPath query matching a context’s entities and constraints with respect to an entity.

Parameters:
Name Type Description
args.entity string

entity to create an XPath query for
args.context mendix/lib/MxContext

context on which the query constrains
args.callback mx.data~CreateXPathStringCallback

function to handle the result
Example
mx.data.createXPathString({
    entity: "System.User",
    context: someContext,
    callback: function(xpath, allMatched) {
        if (allMatched) {
            console.log("All backtracking constraints were met, xpath is: " + xpath);
        } else {
            console.log("Some backtracking constraints could not be met");
        }
    }
});

(static) get(scope)

Retrieves MxObjects from the Runtime.

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

Parameters:
Name Type Description
args.guid GUID

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

GUIDS of the objects to retrieve
args.xpath string

XPath query to retrieve
args.microflow string

a Microflow to fetch objects from
args.noCache boolean

whether the client cache should be used
args.count boolean

whether a count of the entire set should be returned
args.path string

Path to the desired object, relative to the object referenced by guid. Format is: Entity/Reference/Entity.
args.callback mx.data~GetSuccessCallback

function to handle the result
args.error mx.data~GetErrorCallback

function to handle errors
args.filter.id SchemaID

schema-id
args.filter.attributes Array.<string>

if given, only given attributes will be fetched
args.filter.offset number

index from where to start in the set
args.filter.sort SortSpec

attribute and sort order pairs on which to sort the objects on
args.filter.amount number

maximum number of objects to fetch
args.filter.distinct boolean

distinct objects on an attribute
args.filter.references Object

key-value pairs of reference name and options
scope Object

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) getBacktrackConstraints(metaobj, context, callback)

Creates an XPath constraint matching the constraints of context leading to the object tracked by context.

Parameters:
Name Type Description
metaobj mendix/lib/MxMetaObject

ignored; only for backwards compatibility
context mendix/lib/MxContext

context on which the query constrains
callback mx.data~GetBacktrackConstraintsCallback

function to handle the result
Example
mx.data.getBacktrackConstraints(null, someContext, function(xpath, allMatched) {
    if (allMatched) {
        console.log("All backtracking constraints were met, xpath is: " + xpath);
    } else {
        console.log("Some backtracking constraints could not be met");
    }
});

(static) release(objs)

Informs the Runtime that the client is no longer interested in an object.

If the object is not persistable, this may cause the object being removed from the Runtime cache.

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

one or more MxObjects to release
Examples
mx.data.release(obj) // releases a single object
mx.data.release([obj1, obj2]) // releases two objects

(static) remove(scope)

Removes MxObjects.

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

Parameters:
Name Type Description
args.guid GUID

GUID of MxObject to remove
args.guids Array.<GUID>

GUIDs of MxObjects to remove
args.callback mx.data~RemoveSuccessCallback

function to handle the result when successful
args.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.log("Error occurred attempting to remove object " + e);
    }
});

mx.data.remove({
    guids: [ "123456", "45678" ],
    callback: function() {
        console.log("Objects removed");
    },
    error: function(e) {
        console.log("Error occurred attempting to remove objects " + e);
    }
});

(static) rollback(scope)

Rollbacks an MxObject.

Parameters:
Name Type Description
args.mxobj mendix/lib/MxObject

MxObject to rollback changes for
args.callback mx.data~RollbackSuccessCallback

function to handle the result when successful
args.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.log("Error occured attempting to rollback: " + e);
    }
});

(static) save(scope)

Saves an MxObject.

Parameters:
Name Type Description
args.mxobj mendix/lib/MxObject

MxObject to save changes for
args.callback mx.data~SaveSuccessCallback

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

function to handle errors
scope Object

scope in which the error and callback handler are invoked
Example
mx.data.save({
    mxobj: obj,
    callback: function() {
        console.log("Object saved");
    }
});

(static) subscribe() → {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.guid GUID

GUID to subscribe to
args.entity string

entity to subscribe to
args.attr string

attribute to subscribe to
args.val boolean

subscribe to a validation on an MxObject
args.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()

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.guid GUID

GUID to invoke the update for
args.entity string

entity to invoke the update for
args.attr string

attribute to invoke the update for
args.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, ioArgs)

Success callback for mx.data.action

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

HTTP status code of the request

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

CreateXPathStringCallback(xpath, allMatched)

Callback to handle the result of mx.data.createXPathString

Parameters:
Name Type Description
xpath string

generated XPath query
allMatched boolean

indicates whether all backtracking constraints could be matched

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

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

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

SaveErrorCallback(error)

Error callback for mx.data.save

Parameters:
Name Type Description
error Error

error describing the failure of the request

SaveSuccessCallback()

Success callback for mx.data.save

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