Creating a widget with full dojox.form.manager support

As a part of our Free Dojo Support initiative, we received the following question from Pong about how to add dojox.form.manager support to a custom widget:

The Question

“I would like to create a custom form widget which is a combination of dijit.form.Select and a dijit.form.ValidationTextBox.

Since this is not a standard dijit.form elements so it won’t benefit from the dojox.form.manager function like disable(), setFormValues(), observer etc..

So how can I create a custom form widget with fully support of dojox.form.manager”

Thanks for writing, Pong! Before we dive in, we would note that the description of your widget — “a combination of dijit.form.Select and a dijit.form.ValidationTextBox” — sounds much like what dijit.form.FilteringSelect already does. dijit.form.FilteringSelect will already work with dojox.form.Manager; it may be worth a look if you haven’t tried it yet.
You can see both widgets in action in this trivial dojox.form.Manager example.

However, since you have created your own widget already, let’s look at what dojox.form.Manager requires of a widget in order to manage it.

First and most importantly, dojox.form.Manager only aggregates and tracks widgets which inherit dijit.form._FormWidget. Therefore, you will want your widget to extend off of it, like so:

dojo.declare("my.CustomFormWidget", dijit.form._FormWidget, {
    /* implementation here */
});

To briefly explain, dijit.form._FormWidget is what Dijit’s form widgets commonly use to wrap a regular DOM input element in a widget. Of particular importance is the focusNode attach point, which normally points to the actual input node being wrapped.

There is also a further extension of dijit.form._FormWidget called dijit.form._FormValueWidget, which provides additional base functionality, primarily for setting/retrieving values. dijit.form.Select and dijit.form.FilteringSelect both inherit this.

You may be able to find some useful information on these base classes in the API documentation, but for purposes of extending, it may be best to look at the source to see how they really work.

It’s worth noting that these base classes provide default implementations of a few other APIs which dojox.form.Manager also calls, though you may wish to provide your own implementations more appropriate to your use case.

Let’s take a look at what those APIs are:

onChange: this is what the manager connects observers to. (implemented by _FormWidget)
disabled getter/setter: used by the manager for enabling/disabling fields. The disabled state is also checked when validating the form, since disabled fields aren’t submitted. (implemented by _FormWidget)
value getter/setter: used by the manager for inspecting form fields and setting their values. (implemented by _FormValueWidget)
reset: called on each widget when the form is told to reset. (implemented by _FormValueWidget)

The following two validation methods are also called by the manager; however, they are not implemented in the _FormWidget base classes. dijit.form.ValidationTextBox (which dijit.form.FilteringSelect inherits) contains an implementation that might be useful for reference.

isValid: Returns true if the widget is in a valid state. The manager delegates to this method on each widget when its own isValid method is called, e.g. when the form is submitted.
validate: Whereas isValid simply reports whether the widget is in a valid state, validate also performs any necessary updates to the UI to reflect this state. Generally, it works by calling isValid, performing UI update logic based on the result, then returning that result. The manager delegates to this method from its own validate method.

We hope this information aids you in your customization efforts! Happy coding!