mxui.lib.Form

Forms are the client implementation of the Mendix Pages concept. They can be shown in content or as a (modal) popup.

Properties

id

The unique id for the form (not unique between instances of the same form), e.g. “54015330-4ce4-4346-8d0a-1ff92bfb5c99”.

path

The path to the form, e.g. “MyFirstModule/EmployeeOverview_mobile.mxf”

title

The title of the form, as defined in the Modeler.

context

The current context of the form.

domNode

A reference to the form’s DOM node.

Methods

startup(callback)

This method is called to startup the form, and parse widgets in it.

Parameters

Name	Type	Description
callback	Function	Called when all widgets in the form have been loaded.

Example

mx.ui.getForm("MyFirstModule/Puppies.mxf", {
    callback: function(form) {
        form.startup(function() {
            console.log("Widgets done parsing");
        });
    }
});

getChildren(nested)

Retrieve child widgets of the form.

Parameters

Name	Type	Description
nested	Boolean	Whether to only retrieve direct children, or all children recursively.

mx.ui.openForm("MyFirstModule/Puppies.mxf", {
    location: "popup",
    callback: function(form) {
        // List all direct child widgets in the popup.
        console.log(form.getChildren());

        // List all child widgets in the popup.
        console.log(form.getChildren(true));
    }
});

listen(message, callback)

Register a listener to a given message. A listener receives two parameters: callback and error. callback should be called on success, error on failure. Listeners are called in reverse order of which they were registered.

Parameters

Name	Type	Description
message	String	The message to listen to.
callback	Function	Function to call when the message is published.

Returns

Type	Description
Object	The handle to remove the subscription with.

Example

l = form.listen("validate", function(callback, error) {
    try {
        validateStuff();
        callback();
    } catch (err) {
        error();
    }
});

unlisten(handle)

Unregister a listener.

Parameters

Name	Type	Description
handle	Object	The handle of the listener to unregister.

Example

l = form.listen("rollback", function(callback, error) {
    rollbackStuff();
});

form.unlisten(l);

applyContext(context, callback)

Apply a context to the the form.

Parameters

Name	Type	Description
context	MxContext	The context to apply.
callback	Function	Function to call when finished. It is run in the form’s scope.

Example

// Passing a new, empty context to a form.
form.applyContext(new mendix.lib.MxContext(), function() {
    console.log("Done applying context to the widget.");
});

callRecursive(method, param…)

This method is called to invoke a function on all direct child widgets.

Parameters

Name	Type	Description
method	String	Method to invoke on all top widgets.
param…	Mixed	Parameters to call the method with.

Example

// Disable all child widgets of the form (you would normally use .enable() for this).
form.callRecursive("set", "disabled", true);

publish(message, callback, error)

Publish a message throughout the form, calling all listeners for it. Listeners are called in reverse order of which they were registered.

Parameters

Name	Type	Description
message	String	The message to publish.
callback	Function	Function to call after all listeners have been called.
error	Function	Function to call in case of an error.

Example

form.publish("save", function() {
    console.log("Called all listeners for the 'save' message.");
}, function(err) {
    console.log("Something went wrong during save:", e.message);
});

suspend()

Set the suspended attribute to true for each child widget of the form.

resume()

Set the suspended attribute to false for each child widget of the form.

enable()

Set the disabled attribute to false for each child widget of the form.

disable()

Set the disabled attribute to true for each child widget of the form.

validate(callback, error)

Shortcut for calling publish with the validate message.

Parameters

Name	Type	Description
callback	Function	Function to call after all listeners have been called.
error	Function	Function to calll in case of an error.

save(callback, error)

Shortcut for calling publish with the save message.

Parameters

Name	Type	Description
callback	Function	Function to call after all listeners have been called.
error	Function	Function to calll in case of an error.

commit(callback, error)

Shortcut for calling publish with the commit message.

Parameters

Name	Type	Description
callback	Function	Function to call after all listeners have been called.
error	Function	Function to calll in case of an error.

rollback(callback, error)

Shortcut for calling publish with the rollback message.

Parameters

Name	Type	Description
callback	Function	Function to call after all listeners have been called.
error	Function	Function to calll in case of an error.

destroy()

Destroy the form and its contents.

form.destroy(); // Free any resources associated with the widget.

Messages

Messages are used within the client to trigger and handle specific events on forms. You can listen to messages and publish them.

validate

Let the form validate itself, e.g. run client side validations of an object.

save

Let the form save itself, e.g. change object values in the runtime or set references in an object.

When saving fails, this is passed as an error. This might happen when a server side validation fails, a connection error occurs, etc. In order to distinguish between validation and other errors you can check the error using instanceof:

form.publish("save", function() {
    console.log("Form validated fine!");
}, function(err) {
    if (err instanceof mendix.lib.ValidationError) {
        console.log("Validation failed");
    } else {
        console.log("Some other error occured");
    }
});

commit

Let the form commit itself, e.g. commit an object in the runtime.

rollback

Let the form rollback itself, e.g. rollback an object in the runtime.

Events

These methods are intended to be connected to using dojo.connect.

onBeforeShow()

Called before the form is shown.

onBeforeHide()

Called before the form is hidden.

onAfterShow()

Called after the form is shown.

onAfterHide()

Called after the form is hidden.