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
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
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
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
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
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 Attributes Description
entity string

the entity of the objects to retrieve

constraints Array.<Object>

an array of constraints to filter returned records.

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

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

Parameters:
Name Type Attributes Description
args Object
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

handle which can be passed to unsubscribe to remove the subscription

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
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
count number

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

Object

# ReferencesSpec

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

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

Array.<Array.<string>>

# SortSpec

Specifies how the result set must be sorted.

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

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