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 |
Properties
|
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);
}
});
(static) callNanoflow(params)
Executes a Nanoflow.
Parameters:
Name | Type | Description | ||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
params |
Object |
Properties
|
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 |
Properties
|
||||||||||||||||||
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 |
Properties
|
||||||||||||
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 |
Properties
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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) 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 |
- Deprecated:
- since version 7.0.
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) 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 | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
entity |
string | the entity of the objects to retrieve |
||||||||||||||||||||||||
constraints |
Array.<Object> | an array of constraints to filter returned records. Properties
|
||||||||||||||||||||||||
filter |
Object | sorting and paging options additionally limiting what objects to retrieve Properties
|
||||||||||||||||||||||||
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) 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
|
- Deprecated:
- since version 7.0. Mendix objects don't have to be released anymore. A Mendix object is kept in cache as long as there is a subscription to it.
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
|
|||||||||||||||
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 |
Properties
|
|||||||||||||||
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) 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
|
||||||||||||
scope |
Object | scope in which the error and callback handler are invoked |
- Deprecated:
- since version 6.8, use
mx.data.commit
andmx.data.action
instead
- since version 6.8, use
Example
mx.data.save({
mxobj: obj,
callback: function() {
console.log("ok");
}
});
(static) saveDocument(guid, fileName, params, blob, callback, error)
Save a document file.
Parameters:
Name | Type | Description |
---|---|---|
guid |
GUID |
|
fileName |
string | file name to store the file with. If |
params |
Object | additional parameters when saving the file. These depend on the
type of document to upload. For images, |
blob |
|
|
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
|
Returns:
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
|
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
|
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 |
||||||
extra |
Properties
|
ReferencesSpec
Specifies how objects associated with the requested one must be fetched.
Type:
- Object
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
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
SortSpec
Specifies how the result set must be sorted.
Consists of ordered pairs of an attribute name and a string "asc"
or "desc"
.
Type:
- Array.<Array.<string>>
Example
[ [ "LastName", "asc" ], [ "FirstName", "asc" ] ]
SubscribeAttributeCallback(guid, attribute, value)
Callback to register for attribute changes
Parameters:
Name | Type | Description |
---|---|---|
guid |
GUID |
|
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