Documentation
Tutorials
Form messages Widget Lifecycle

Class

mxui/widget/_WidgetBase

mxui/widget/_WidgetBase()

This is the object all widgets must inherit of. This inherits from dijit._WidgetBase, which serves as a foundation for all widgets. For more information on Dijit widgets and their lifecycle see the widget lifecycle documentation.

Constructor

# new mxui/widget/_WidgetBase()

Constructs a new _WidgetBase.

Members

boolean

# disabled

Whether the widget is disabled; disabled widgets do not allow editing.

This is a dijit attribute and should be accessed using dijit._WidgetBase's get and set methods.

See:
boolean

# doParse

Whether the widget content should be parsed. If set to false it is responsible for parsing its own content.

mendix/lib/MxContext

# readonly mxcontext

The current context.

mxui/lib/form/_FormBase

# readonly mxform

Reference to the form containing the widget.

string

# readonly mxid

Id of the widget generated by the Modeler. This id is not guaranteed to be unique on the client, as widget can be inside a repeatable widget like a ListView. This id is intended to be used for locating Modeler-generated resources, like templates.

string

# readonly uniqueid

Unique id of the widget generated by the Client. This id is guaranteed to be unique and stable withing the whole application. This id is intended to be used for locating Client-specific resources, like state. Note, that if you are creating a widget programmatically, you must deterministically compute and pass this id to it.

Methods

# addOnDestroy(func)

Adds a function to be called when the widget is destroyed.

Parameters:
Name Type Description
func function

function to be called on destroy
Example
myWidget.addOnDestroy(function() {
    console.log("cleanup widget");
});

# addOnLoad(func)

Adds a function to be called when the widget is loaded.

Parameters:
Name Type Description
func function

function to be called on load
Example
myWidget.addOnLoad(function() {
    console.log("myWidget was loaded");
});

# applyContext(context, callback)

Applies a context to this widget.

Parameters:
Name Type Description
context mendix/lib/MxContext

context to apply
callback mxui/widget/_WidgetBase~ApplyContextCallback

function to be called when finished
Example
define([ "mendix/lib/MxContext" ], function(MxContext) {

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

});

# checkDisabled() → {boolean}

Returns true if the widget is disabled, false otherwise.

returns true if the widget is disabled, false otherwise

boolean

# collect()

Alias of module:mendix/lang.collect, but automatically uses this widget's scope.

# destroy(preserveDom)

Destroys the widget.

Note: do not overwrite this method, use the uninitialize method for cleanup.

Parameters:
Name Type Description
preserveDom boolean

preserves the DOM structure if true, removes the DOM nodes otherwise
Example
myWidget.destroy(); // free any resources associated with this widget

# abstract disable()

Implement this method to do something when the widget is disabled.

# abstract enable()

Implement this method to do something when the widget is enabled.

# getChildren(nested) → {array}

Returns child widgets.

Parameters:
Name Type Description
nested boolean

Whether to only retrieve direct children or all children recursively

child widgets

array

# listen(message, callback) → {Object}

Registers a listener to the form.

Automatically removed when the widget is destroyed.

Parameters:
Name Type Description
message string

type of message to listen for, e.g. "commit"
callback function

function to call on receiving the specified message

form listen handler

Object

# parseContent(node, params) → {Array}

Instantiates all widgets at or under node, passing the given parameters. If the widget’s doparse attribute is false, no widgets are instantiated. Only div nodes are considered.

Parameters:
Name Type Description
node DOMNode

root node to start parsing at
params Object

parameters to be mixed in with each instantiated widget

instantiated widgets

Array

# passContext(widgets, contextnullable, callback)

Passes the context to a list of widgets.

Invokes applyContext on all widgets specified by widgets. If any of the widgets do not implement applyContext (e.g. standard Dijit widgets), context is passed to its separate child widgets.

Parameters:
Name Type Attributes Description
widgets array

list of widgets to apply the context to
context mendix/lib/MxContext <nullable>

context to pass, if not specified the current context will be passed
callback

function to be called when finished

# abstract resize(boxnullable)

Implement this method to re-compute size of your widget in cases it is computed in JavaScript. Note: always prefer to rely on CSS stylesheets for widget layouting instead of doing manual size calculations in your code. Default implementation does nothing except forwarding the call to all child widgets.

Parameters:
Name Type Attributes Description
box Object <nullable>

width and height available to widget to occupy, or undefined if size is not limited.

# sequence()

Alias of module:mendix/lang.sequence, but automatically uses this widget's scope.

# subscribe() → {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.

Under the hood this method calls mx.data.subscribe, but it also checks for redundant subscribes and automatically removes all subscriptions when the widget gets destroyed.

Parameters:
Name Type Description
args.guid GUID

GUID to subscribe to
args.entity string

entity to subscribe to
args.attr string

attribute to subscribe to
args.val boolean

subscribe to a validation on an MxObject
args.callback mx.data~SubscribeEntityCallback | mx.data~SubscribeObjectCallback | mx.data~SubscribeAttributeCallback | mx.data~SubscribeValidationCallback

function to invoke when an update is available

handle which can be passed to unsubscribe to remove the subscription

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

this.unsubscribe(subscription);
// Subscribe to changes in a specific attribute of an MxObject
var subscription = this.subscribe({
    guid: "123213",
    attr: "Name",
    callback: function(guid, attr, value) {
        console.log("Object with guid " + guid + " had its attribute " +
                    attr + " change to " + value);
    }
});

this.unsubscribe(subscription);
// Subscribe to validations of an MxObject
var subscription = this.subscribe({
    guid: "123213",
    val: true,
    callback: function(validations) {
        var reason = validations[0].getReasonByAttribute("MyAttribute");
        console.log("Reason for validation error on attribute MyAttribute: " + reason);
    }
});

this.unsubscribe(subscription);
// Subscribe to changes in a class
var subscription = this.subscribe({
    entity: "System.User",
    callback: function(entity) {
        console.log("Update on entity " + entity);
    }
});

this.unsubscribe(subscription);

# abstract uninitialize()

Implement this method to release any resources claimed by this widget.

# unlisten(handler)

Removes a listener.

Parameters:
Name Type Description
handler Object

handler to remove

# unsubscribe(handler)

Unregisters a callback registered through mxui/widget/_WidgetBase#subscribe.

Unregistering callbacks when they are no longer needed is important to prevent memory leaks.

Parameters:
Name Type Description
handler mx.data~SubscribeHandle

return value of a subscribe call
Example
// First subscribe
var subscription = this.subscribe({
    entity: "System.User",
    callback: function(entity) {
        console.log("Received update for entity " + entity);
    }
});

// And then unsubscribe:
this.unsubscribe(subscription);

# unsubscribeAll()

Unregisters all callbacks registered through mxui/widget/_WidgetBase#subscribe.

Example
// First subscribe
this.subscribe({
    entity: "System.User",
    callback: function(entity) {
        console.log("Received update for entity " + entity);
    }
});

// Another subscribe
this.subscribe({
    guid: "123213",
    callback: function(guid) {
        console.log("Received update for object with guid " + guid);
    }
});

// Remove all subscriptions at once
this.unsubscribeAll();

# abstract update(obj, callback)

Implement this method to handle settting of the current track object in the widget's context.

Parameters:
Name Type Description
obj mendix/lib/MxObject

the current track object, or null if there is none
callback mxui/widget/_WidgetBase~ApplyContextCallback

function to be called when finished

Type Definitions

# ApplyContextCallback()

Callback indicating that an mxui/widget/_WidgetBase#applyContext or mxui/widget/_WidgetBase#update has finished/