mendix.sys.Data

The mendix.sys.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.guids¹	Array	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²	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.store.caller	Scriptable	The caller instance, on which server instructions can be executed.
params.context¹	MxContext	The context for the Microflow.
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.

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

² 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 a widget 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.

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.

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.

Examples

mx.data.commit({
    mxobj    : obj,
    callback : function() {
        console.log("Object committed");
    },
    error : function(err) {
        console.log("Error occurred attempting to commit " + err);
    }
});

rollback(args, scope)

This method is called to rollback 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.

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(err) {
        console.log("Error occurred attempting to remove object " + err);
    }
});

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

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 : cb // # GUID
      });

    //
    // Subscribe to changes in a specific attribute of an MxObject
    //

    mx.data.subscribe({
        guid     : 123213,
        attr     : 'Name',
        callback : cb // # GUID
      });

    //
    // Subscribe to validations of an MxObject
    //

    mx.data.subscribe({
        guid     : 123213,
        val      : true,
        callback : cb // # GUID
      });

    //
    // Subscribe to changes in a class
    //

    mx.data.subscribe({
        class     : 'System.User',
        callback : cb
      });

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

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

createXPathString(args)

This method is called to create a XPath query, based on an entity and a MxContext.

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	String	The function to handle the result.
args.error	String	The function to handle errors.

getBacktrackConstraints(metaobj, context, callback)

This method is called to create XPath constraints, based on an MxMetaObject and a MxContext.

Parameters

Name	Type	Description
metaobj	MxMetaObject	The MxMetaObject of the entity.
context	MxContext	The context on which the constraints constrain.
callback	String	The function to handle the result.

startup(callback)

This method is called to startup the subsystem.

Parameters

Name	Type	Description
callback	Function	The function to be called when startup is finished.

shutdown()

This method is called to shutdown the subsystem.

isLoaded()

This method is called to check whether the subsystem has been started.

Returns

Type	Description
Boolean	`true` if the subsystem has been started.

Mendix Client 4 API Documentation

Menu

mendix.sys.Data

Methods

get(args, scope)

Parameters

Returns

Examples

action(params)

Parameters

Microflow parameters

Examples

release(objs)

Parameters

create(args, scope)

Parameters

save(args, scope)

Parameters

Examples

commit(args, scope)

Parameters

Examples

rollback(args, scope)

Parameters

remove(args, scope)

Parameters

Examples

subscribe(args)

Parameters

Returns

Examples

unsubscribe(args)

Parameters

update(args)

Parameters

createXPathString(args)

Parameters

getBacktrackConstraints(metaobj, context, callback)

Parameters

startup(callback)

Parameters

shutdown()

isLoaded()

Returns