Mendix Client 5 API Documentation

Menu

mx.data

The mx.data subsystem provides an API to retrieve and manipulate MxObjects.

Methods

get(args, scope)

This method is called to retrieve MxObjects from the Runtime.

Parameters

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

Name Type Description
args.guid Number The GUID of the object to retrieve.
args.guids Array The GUIDS of the objects to retrieve.
args.xpath String The XPath query to retrieve.
args.microflow Boolean A microflow to fetch objects from.
args.callback Function Function to handle the result.
args.error Function Function to handle errors.
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.filter.id String Schema-id.
args.filter.attributes Array If given, only given attributes will be fetched.
args.filter.offset Number Index from where to start in the set.
args.filter.sort Array 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.

Returns

If one GUID is requested:

Type Description
MxObject The requested MxObject

else:

Type Description
Array Array with requested objects

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");
    }
});

action(params)

Execute a Microflow.

Parameters

Name Type Description
params.params.actionname String Name of the Microflow to invoke. (required)
params.params.applyto String To what to apply the Microflow. Can be one of “none”, “set”, “selection” or “selectionset”. “none” is the default.
params.params.guids1 Array The GUIDs to apply the Microflow to.
params.params.xpath1 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.sort2 Array 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.context1 MxContext The context for the Microflow.
params.store.caller Scriptable The caller instance, on which server instructions can be executed.
params.async Boolean Whether the Microflow should be executed asynchronously. Defaults to false.
params.callback Function Function to handle the result when successful. It should take two parameters, value and ioArgs. value contains the result of the Microflow. ioArgs contains additional information about the request (see also the documentation of the handle parameter of dojo.xhrGet).
params.error Function Function to handle errors. It should take a single parameter, error, which is set to undefined when the server cannot be accessed, or an Object describing the error.
params.onValidation Function Function to handle validation feedback. It should take a single parameter, validations, which will be set to an array of ObjectValidation objects.

1 One of either the guids or xpath parameters is required.

2 Required when using an XPath query to specify Microflow parameters.

Microflow parameters

The 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 gridid is set, and the corresponding grid is single selection, only the first queried object is considered.

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);

release(objs)

This method is called to inform 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 MxObject or Array of MxObjects The MxObjects to release.

Examples

mx.data.release(obj)
// releases a single object

mx.data.release([obj1, obj2])
// releases two objects

create(args, scope)

This method is called to create a MxObject.

Parameters

Name Type Description
args.entity String Entity to create an instance of.
args.callback Function Function to handle the result.
args.error Function 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);
    }
});

save(args, scope)

This method is called to save a MxObject.

Parameters

Name Type Description
args.mxobj MxObject MxObject to save changes for.
args.callback Function Function to handle the result.
args.error Function Function to handle errors.
scope Object Scope in which the error and callback handler are invoked.

Examples

mx.data.save({
    mxobj    : obj,
    callback : function() {
        console.log("Object saved");
    }
});

commit(args, scope)

This method is called to commit a MxObject. When there are changes, these will automatically be sent to the Runtime.

Parameters

Name Type Description
args.mxobj MxObject MxObject to save changes for.
args.callback Function Function to handle the result.
args.error Function Function to handle errors.
args.onValidation Function Function to handle validation feedback.
args.standalone Boolean Whether other changes may be sent along.
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);
    }
});

rollback(args, scope)

This method is called to rollback a MxObject.

Parameters

Name Type Description
args.mxobj MxObject MxObject to rollback changes for.
args.callback Function Function to handle the result.
args.error Function 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);
    }
});

remove(args, scope)

This method is called to remove MxObjects. Only one of the guid / guids parameters should be set.

Parameters

Name Type Description
args.guid Number GUID of MxObject to remove.
args.guids Array GUIDS of MxObjects to remove.
args.callback Function Function to handle the result.
args.error Function Function to handle errors.
scope Object Scope in which the error and callback handler are invoked.

Examples

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);
    }
});

subscribe(args)

This method is called to register a callback to be invoked on changes in a specific MxObject, an attribute of a specific MxObject or any changes to MxObjects of a specific entity. Widgets inherit a method from Widget, this.connect() which automatically sets up an unsubscription function to be run on Widget teardown.

Parameters

Name Type Description
args.guid Number The GUID to subscribe to
args.entity String The entity to subscribe to
args.attr String The attribute to subscribe to
args.callback Function The callback to invoke when an update is available

Returns

Type Description
Object Handler which can be passed to unsubscribe to remove the subscription

Examples

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

// Subscribe to changes in a specific attribute of an MxObject
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);
    }
});

// Subscribe to validations of an MxObject
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);
    }
});

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

unsubscribe(args)

This method is called to unregister a callback to be invoked on changes in a specific MxObject, an attribute of a specific MxObject or any changes to MxObjects of a specific entity. Unregistering callbacks when they are no longer needed is important to prevent memory leaks. Widgets inherit a method from Widget, this.connect() which automatically sets up an unsubscription function to be run on Widget teardown.

Parameters

Name Type Description
args Object Handler which should be the return value of a subscribe call

Example

// First subscribe:
var sub = mx.data.subscribe({
    class    : "System.User",
    callback : function(entity) {
        console.log("Received update for entity " + entity);
    }

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

update(args)

This method is called to call listeners to changes in a specific MxObject, an attribute of a specific MxObject or any changes to MxObjects of a specific entity.

Parameters

Name Type Description
args.guid Number The GUID to subscribe to
args.entity String The entity to subscribe to
args.attr String The attribute to subscribe to
args.callback Function The callback to invoke when an update is available

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",
});

createXPathString(args)

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

Parameters

Name Type Description
args.entity String The entity to create an XPath query for.
args.context MxContext The context on which the query constrains.
args.callback Function The function to handle the result, taking two parameters: xpath, a string containing the generated query. allMatched, a boolean indicating whether all backtracking constraints could be matched.

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");
        }
    }
});

getBacktrackConstraints(metaobj, context, callback)

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

Parameters

Name Type Description
metaobj MxMetaObject Ignored; only for backwards compatibility.
context MxContext The context on which the the query constrains.
callback Function The function to handle the result, taking two parameters: xpath, a string containing the generated query. allMatched, a boolean indicating whether all backtracking constraints could be matched.

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");
    }
});