Dojo: The Definitive Guide

Form

Although form dijits can be wrapped in an HTML form tag, the dijit.form.Form dijit provides some additional conveniences that are quite useful. This section rounds off the chapter by reviewing ordinary HTML forms and then reviews the specific features provided by dijit.form.Form. A common source of confusion to many Dijit newcomers is that they expect Dijit to do something directly that already works just fine via ordinary HTML. Recall that a significant part of Dojo's design philosophy is to not reinvent aspects of web technologies that already work; rather, Dojo supplements and augments as needed where web technology is lacking or not standardized.

HTML Form Tag Synopsis

dijit.form.Form respects the standard form attributes as defined in the HTML 4.01 specification. All attribute values are assumed to be wrapped in quotes as string values, although DOM events such as onclick entail explicitly denoting that a script action is expected, like onclick="javascript:someScriptAction( )" or onclick="javascript:return someValidationAction( )". For mouse events, a "left-click" action is assumed.

Form

The Form dijit itself supplements the standard HTML form attribute by providing several methods that may be called to manipulate it directly, and one extension point that is called internally in response to a user action. Table 13-16 lists the key aspects of Form.

Table 13-16. Form methods and extension points

Name	Category	Comment
getValues( )	Method	Returns a JSON structure providing named key/value pairs for the form.
isValid( )	Method	Returns true if each enabled value in the form returns true for its isValid method.
setValues (/*Object*/values)	Method	Provides a concise way of setting all values in the form at one time via a JSON structure where each key in the structure is a named form field.
submit( )	Method	Used to programmatically submit the form.
reset()	Method	Systematically calls reset( ) on each contained dijit in the form to reset its value.
onSubmit( )	Extension point	Called internally when the submit( ) method is executed. This extension point is intended to provide a way of canceling the form submission if it returns false. By default, it returns the value from isValid( ).
validate( )	Method	Returns true if the form is valid, which is the same as isValid, but also highlights any form dijits that are valid and calls focus( ) on the first invalid dijit that is contained in the form.

Wrapping up the entire form into a dijit.form.Form is just like replacing any other element with the corresponding dijit, as shown in Example 13-17.

Example 13-17. Typical Form usage

<form id="registration_form" dojoType="dijit.form.Form">

  <!-- form elements go here -->

  <!-- override extension points as usual...-->

  <script type="dojo/method" event="onSubmit" args="evt">
    //return false if form should not be submitted. By default
    //onSubmit returns isValid(  ) for the dijit.form.Form
  </script>
</form>