Documentation
Tutorials
Form messages Widget Lifecycle

Class

mxui/lib/form/_FormBase

mxui/lib/form/_FormBase()

Constructor

# new mxui/lib/form/_FormBase()

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

This class contains the functionality shared between all Form types. This means that all of the following applies to _WidgetBase#mxform.

Members

HTMLElement

# static readonly domNode

The form's document node.

string

# static readonly id

Unique id of the form.

string

# static readonly path

Path to the form, e.g. MyFirstModule/EmployeeOverview_mobile.page.xml.

string

# static readonly title

Title of the form, as defined in the Modeler.

Methods

# callRecursive(method, …args)

Invoke a function on all direct child widgets.

Parameters:
Name Type Attributes Description
method string

method to invoke on all top level children
args * <repeatable>

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

# close()

Close the form. For popup forms this implies closing the popup and hence destroying all widgets placed in it, while for content pages "closing" means navigating back to the previous page.

Example
mx.ui.openForm("MyFirstModule/Puppies.page.xml", {
    location: "popup",
    callback(form) {
        form.close();
    }
});

# commit(function, error)

Shortcut for calling mxui/lib/form/_FormBase#publish with the commit message.

Parameters:
Name Type Description
function mxui/lib/form/_FormBase~SuccessCallback

to call after all listeners have finished
error mxui/lib/form/_FormBase~ErrorCallback

function to call in case of an error

# getChildren(nested) → {Array.<dijit._WidgetBase>}

Retrieve child widgets of the form.

Parameters:
Name Type Description
nested boolean

retrieve all children recursively if true, only direct children otherwise

child widgets of the form

Array.<dijit._WidgetBase>
Example
mx.ui.openForm("MyFirstModule/Puppies.page.xml", {
    location: "popup",
    callback(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) → {mxui/lib/form/_FormBase~ListenHandle}

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

message to listen to
callback mxui/lib/form/_FormBase~ListenCallback

function to call when the message is broadcast
Tutorials:

handle that can be used to remove the subscription using mxui/lib/form/_FormBase#unlisten

mxui/lib/form/_FormBase~ListenHandle
Example
l = form.listen("submit", function(callback, error) {
    try {
        validateStuff();
        callback();
    } catch (e) {
        error(e);
    }
});

# 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

message to publish
callback mxui/lib/form/_FormBase~SuccessCallback

function to call after all listeners have finished
error mxui/lib/form/_FormBase~ErrorCallback

function to call in case of an error
Tutorials:
Example
form.publish("commit", function() {
    console.log("Called all listeners for the 'commit' message.");
}, function(e) {
    console.log("Something went wrong during commit:", e.message);
});

# rollback(function, error)

Shortcut for calling mxui/lib/form/_FormBase#publish with the rollback message.

Parameters:
Name Type Description
function mxui/lib/form/_FormBase~SuccessCallback

to call after all listeners have finished
error mxui/lib/form/_FormBase~ErrorCallback

function to call in case of an error

# unlisten(handle)

Unregister a listener.

Parameters:
Name Type Description
handle mxui/lib/form/_FormBase~ListenHandle

of the listener to unregister
Tutorials:
Example
l = form.listen("rollback", function(callback, error) {
    rollbackStuff();
});

form.unlisten(l);

# validate(function, error)

Shortcut for calling mxui/lib/form/_FormBase#publish with the validate message.

Parameters:
Name Type Description
function mxui/lib/form/_FormBase~SuccessCallback

to call after all listeners have finished
error mxui/lib/form/_FormBase~ErrorCallback

function to call in case of an error

Type Definitions

# ErrorCallback(error)

Function to call when a listener encounters an error.

Parameters:
Name Type Description
error Error

error object indicating the reason of the error

# ListenCallback(callback, error)

Callback for handling a message that the form listens to.

Parameters:
Name Type Description
callback mxui/lib/form/_FormBase~SuccessCallback
error mxui/lib/form/_FormBase~ErrorCallback

# ListenHandle

Handle of a listener.

# SuccessCallback()

Function to call when a listener finishes successfully.

Events

# onNavigation

Called after the form is loaded and is going to be shown to the user. This event indicates that properties of the form, for example title, have been updated, and all widgets are done loading.

Note that for content forms, onNavigation is triggered after every page navigation. Which means that a widget can receive multiple events during its lifetime if it is placed on the layout.

This method is intended to be used as shown in the example.

Since:
  • 6.7.0
Example
this.connect(this.mxform, "onNavigation", function() {
  // custom logic
});