Namespace: data

mx. data

Retrieve and manipulate MxObjects.

Methods

(static) action(params)

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
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
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.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]",
        origin: this.mxform
    },
    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"],
        origin: this.mxform
    },
    callback: function(obj) {
        // expect single MxObject
        alert(obj.get("manufacturer"));
    },
    error: function(error) {
        alert(error.description);
    }
}, this);

(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.log("Error occurred attempting to commit: " + 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.log("an error occured: " + e);
    }
});

(static) createXPathString(args)

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

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

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

context on which the query constrains
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(args, scope)

Retrieves MxObjects from the Runtime.

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

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

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

GUIDS of the objects to retrieve
xpath string

XPath query to retrieve
microflow string

a Microflow to fetch objects from
noCache boolean

whether the client cache should be used
count boolean

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

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

function to handle the result
error mx.data~GetErrorCallback

function to handle errors
filter.attributes Array.<string>

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

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

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

maximum number of objects to fetch
filter.distinct boolean

distinct objects on an attribute
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(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.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(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.log("Error occured attempting to rollback: " + e);
    }
});

(static) save(args, scope)

Save an MxObject

This has become a no-op: changes are now automatically sent with calls to mx.data.commit, mx.data.rollback, mx.data.action and mx.data.saveDocument.

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

MxObject to save changes for
callback mx.data~SaveSuccessCallback

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

function to handle errors
scope Object

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

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

Save a document file.

Parameters:
Name Type Description
guid GUID

GUID of the MxObject to associate the file with.
name 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 Description
guid GUID

GUID to subscribe to
entity string

entity to subscribe to
attr string

attribute to subscribe to
val boolean

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

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

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

SaveErrorCallback(error)

Error callback for mx.data.save

Parameters:
Name Type Description
error Error

error describing the failure of the request
Deprecated:
  • since version 6.7

SaveSuccessCallback()

Success callback for mx.data.save

Deprecated:
  • since version 6.7

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