newforms¶

Processing input data with a Form¶

When a form is given valid input data, the successfully validated form data will be in the form.cleanedData object. This data will have been converted into JavaScript types for you, where necessary.

In the above example, ccMyself will be a boolean value. Likewise, fields such as IntegerField and DateField convert values to a JavaScript Number and Date, respectively.

Displaying a Form¶

Rather than newforms providing its own custom React components, Form objects create ReactElement objects to be included in the render() of a React component.

A form also only outputs its own fields; it’s up to you to provide the surrounding <form> element, submit buttons etc:

render: function() {
  return <form action="/contact" method="POST" onSubmit={this.onSubmit}>
    {this.state.form.asDiv()}
    <div>
      <input type="submit" value="Submit"/>{' '}
      <input type="button" value="Cancel" onClick={this.onCancel}/>
    </div>
  </form>
}

form.asDiv() will output the form with each form field and accompanying label wrapped in a <div>. Here’s the output for our example component:

<form action="/contact" method="POST">
  <div><label for="id_subject">Subject:</label> <input maxlength="100" type="text" name="subject" id="id_subject"></div>
  <div><label for="id_message">Message:</label> <input type="text" name="message" id="id_message"></div>
  <div><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender"></div>
  <div><label for="id_ccMyself">Cc myself:</label> <input type="checkbox" name="ccMyself" id="id_ccMyself"></div>
  <div><input type="submit" value="Submit"> <input type="button" value="Cancel"></div>
</form>

Note that each form field has an id attribute set to id_<field-name>, which is referenced by the accompanying label tag. You can customise the way in which labels and ids are generated.

You can also use form.asTable() to output table rows (you’ll need to provide your own <table> and <tbody>) and form.asUl() to output list items. Forms also have a default form.render() method which calls form.asTable().

Form 'auto' validation¶

When you pass an onChange callback to a form, its validation setting is automatically implied to be 'auto':

var form = new SignupForm({onChange: this.onFormChange})

When the form’s validation mode is 'auto':

• Text fields are validated using the onChange and onBlur events, with a debounce delay of 369ms applied to onChange between the last change being made and validation being performed.
• Other fields are validated as soon as the user interacts with them.

'auto' example form¶

Let’s use a standard signup form as an example:

var SignupForm = forms.Form.extend({
  email: forms.EmailField()
, password: forms.CharField({widget: forms.PasswordInput})
, confirm: forms.CharField({label: 'Confirm password', widget: forms.PasswordInput})
, terms: forms.BooleanField({
    label: 'I have read and agree to the Terms and Conditions'
  , errorMessages: {required: 'You must accept the terms to continue'}
  })

, clean: function() {
    if (this.cleanedData.password && this.cleanedData.confirm &&
        this.cleanedData.password != this.cleanedData.confirm) {
      throw forms.ValidationError('Passwords do not match.')
    }
  }
})

Note that this form defines a clean() function for cross-field validation. In addition to validating the field which just changed, user input will also trigger form-wide validation by calling clean(). This function must always be written defensively regardless of whether full or partial validation is being run, as it can’t assume that any of the cleanedData it validates against will be present due to the possibility of missing or invalid user input.

'manual'¶

This is the default option, which disables interactive validation.

You’re only likely to need to use this if you’re opting specific fields out of form-wide interactive validation.

validation object¶

Interactive validation can be specified as an object with the following properties:

on

The name of the default event to use to trigger validation on text input fields. This can be specified with or without an 'on' prefix. If validation should be triggerd by multiple events, their names can be passed as a space-delimited string or a list of strings.

For example, given validation: {on: 'blur'}, text input validation will be performed when the input loses focus after editing.

onChangeDelay

A delay, in milliseconds, to be used to debounce performing of validation when using the onChange event, to give the user time to enter input without distracting them with error messages or other disply changes around the input while they’re still typing.

'auto'¶

The behaviour of 'auto' validation is documented above. It’s equivalent to passing:

validation: {on: 'blur change', onChangeDelay: 369}

Any event name¶

If you pass any other string as the validation argument, it will be assumed to be an event name, so the following lines are equivalent:

validation: 'blur'
validation: {on: 'blur'}

controlled example Form¶

An example of reusing the same controlled Form to edit a bunch of different objects which have the same fields.

First, define a form:

var PersonForm = forms.Form.extend({
  name: forms.CharField({maxLength: 100}),
  age: forms.IntegerField({minValue: 0, maxValue: 115}),
  bio: forms.CharField({widget: forms.Textarea})
})

When creating the form in our example React component, we’re passing controlled: true:

getInitialState: function() {
  return {
    form: new PersonForm({
      controlled: true
    , onChange: this.forceUpdate.bind(this)
    })
  , editing: null
  , people: [/* ... */]
  }
}

To update what’s displayed in the form, we have a handleEdit function in our React component which is calling form.reset() to put the form back into its initial state, with new initial data:

handleEdit: function(personIndex) {
  this.state.form.reset(this.state.people[personIndex])
  this.setState({editing: personIndex})
}

form.isInitialRender¶

If you need to distinguish between the type of rendering behaviour a form instance will exhibit, check the value of the form’s form.isInitialRender property:

var f = new ContactForm()
print(f.isInitialRender)
// => true
f = new ContactForm({data: {subject: 'hello'}})
print(f.isInitialRender)
// => false

A form given an empty data object will still be considered to have user input and will trigger validation when rendered:

var f = new ContactForm({data: {}})
print(f.isInitialRender)
// => false

Server or standalone validation¶

The primary task of a Form object is to validate data. With a bound Form instance, call the BaseForm#isValid() method to run validation and return a boolean designating whether the data was valid:

var data = {
  subject: 'hello'
, message: 'Hi there'
, sender: 'foo@example.com'
, ccMyself: true
}
var f = new ContactForm({data: data})
print(f.isValid())
// => true

Let’s try with some invalid data. In this case, subject is blank (an error, because all fields are required by default) and sender is not a valid email address:

var data = {
  subject: 'hello',
, message: 'Hi there'
, sender: 'invalid email address'
, ccMyself: true
}
var f = new ContactForm({data: data})
print(f.isValid())
// => false

form.errors() returns an ErrorObject() containing error messages:

f.errors().asText()
/* =>
* subject
  * This field is required.
* sender
  * Enter a valid email address.
*/

You can access form.errors() without having to call Form.isValid() first. The form’s data will be validated the first time you either call form.isValid() or form.errors().

The validation routines will only get called once for a given set of data, regardless of how many times you call form.isValid() or form.errors(). This means that if validation has side effects, those side effects will only be triggered once per set of input data.

Client validation¶

On the client-side, the user’s input is held in form DOM inputs, not a tidy JavaScript object as in the above examples (whereas if you’re handling a request on the server, the request body serves this purpose).

Regardless of whether or not you’re using interactive validation, the form’s input data will be updated as the user fills it in. To force the form to fully validate, call form.validate():

// Form creation in a React component's getInitialState()
var form = new ContactForm()

// Validation in an onSubmit event handler
var isValid = this.state.form.validate()

form.setData()¶

To replace a Form’s entire input data with a new set, use form.setData().

This will also trigger validation – updating form.errors() and form.cleanedData, and returning the result of form.isValid():

var f = new ContactForm()
// ...user inputs data...
var data = {
  subject: 'hello'
, message: 'Hi there'
, sender: 'foo@example.com'
, ccMyself: true
}
var isValid = f.setData(data)
print(f.isInitialRender)
// => false
print(isValid)
// => true

form.updateData()¶

To partially update a Form’s input data, use form.updateData().

This will trigger validation of the fields for which new input data has been given, and also any form-wide validation if configured.

It doesn’t return the result of the validation it triggers, since the validity of a subset of fields doesn’t tell you whether or not the entire form is valid.

If you’re peforming partial updates of user input (which is the case if individual fields are being validated onChange) and need to check if the entire form is valid without triggering validation errors on fields the user may not have reached yet, use BaseForm#isComplete():

var f = new ContactForm()
f.updateData({subject: 'hello'})
print(f.isComplete())
// => false
f.updateData({message: 'Hi there'})
print(f.isComplete())
// => false
f.updateData({sender: 'foo@example.com'})
print(f.isComplete())
// => true

Note that form.isComplete() returns true once all required fields have valid input data.

asDiv()¶

asDiv() renders the form as a series of <div> tags, with each <div> containing one field:

var f = new ContactForm()
print(reactHTML(f.asDiv()))
/* =>
<div><label for="id_subject">Subject:</label><span> </span><input maxlength="100" type="text" name="subject" id="id_subject"></div>
<div><label for="id_message">Message:</label><span> </span><input type="text" name="message" id="id_message"></div>
<div><label for="id_sender">Sender:</label><span> </span><input type="email" name="sender" id="id_sender"></div>
<div><label for="id_ccMyself">Cc myself:</label><span> </span><input type="checkbox" name="ccMyself" id="id_ccMyself"></div>
*/

asUl()¶

asUl() renders the form as a series of <li> tags, with each <li> containing one field:

var f = new ContactForm()
print(reactHTML(f.asUl()))
/* =>
<li><label for="id_subject">Subject:</label><span> </span><input maxlength="100" type="text" name="subject" id="id_subject"></li>
<li><label for="id_message">Message:</label><span> </span><input type="text" name="message" id="id_message"></li>
<li><label for="id_sender">Sender:</label><span> </span><input type="email" name="sender" id="id_sender"></li>
<li><label for="id_ccMyself">Cc myself:</label><span> </span><input type="checkbox" name="ccMyself" id="id_ccMyself"></li>
*/

Styling form rows¶

When defining a Form, there are a few hooks you can use to add class attributes to form rows in the default rendering:

• rowCssClass – applied to every form row
• errorCssClass – applied to form rows of fields which have errors
• requiredCssClass – applied to form rows for required fields
• validCssClass – applied to form rows for fields which have a corresponding value present in cleanedData

To use these hooks, ensure your form has them as prototype or instance properties, e.g. to set them up as protoype properties:

var ContactForm = forms.Form.extend({
  rowCssClass: 'row'
, errorCssClass: 'error'
, requiredCssClass: 'required'
, validCssClass: 'valid'
// ...and the rest of your fields here
})

Once you’ve done that, the generated markup will look something like:

var data = {
  subject: 'hello'
, message: 'Hi there'
, sender: ''
, ccMyself: true
}
var f = new ContactForm({data: data})
print(reactHTML(f.render()))
/* =>
<tr class="row valid required"><th><label for="id_subject">Subject:</label> ...
<tr class="row valid required"><th><label for="id_message">Message:</label> ...
<tr class="row error required"><th><label for="id_sender">Sender:</label> ...
<tr class="row valid"><th><label for="id_ccMyself">Cc myself:</label> ...
*/

The className string generated for each field when you configure the available CSS properties is also available for use in custom rendering, via a BoundField’s cssClasses() method.

Configuring form elements’ HTML id attributes and <label> tags¶

By default, the form rendering methods include:

• HTML id attributes on the form elements.
• The corresponding <label> tags around the labels. An HTML <label> tag designates which label text is associated with which form element. This small enhancement makes forms more usable and more accessible to assistive devices. It’s always a good idea to use <label> tags.

The id attribute values are generated by prepending id_ to the form field names. This behavior is configurable, though, if you want to change the id convention or remove HTML id attributes and <label> tags entirely.

Use the autoId argument to the Form constructor to control the id and label behavior. This argument must be true, false or a string.

If autoId is false, then the form output will include neither <label> tags nor id attributes:

var f = new ContactForm({autoId: false})
print(reactHTML(f.asTable()))
/* =>
<tr><th>Subject:</th><td><input maxlength="100" type="text" name="subject"></td></tr>
<tr><th>Message:</th><td><input type="text" name="message"></td></tr>
<tr><th>Sender:</th><td><input type="email" name="sender"></td></tr>
<tr><th>Cc myself:</th><td><input type="checkbox" name="ccMyself"></td></tr>
*/
print(reactHTML(f.asUl()))
/* =>
<li><span>Subject:</span><span> </span><input maxlength="100" type="text" name="subject"></li>
<li><span>Message:</span><span> </span><input type="text" name="message"></li>
<li><span>Sender:</span><span> </span><input type="email" name="sender"></li>
<li><span>Cc myself:</span><span> </span><input type="checkbox" name="ccMyself"></li>
*/
print(reactHTML(f.asDiv()))
/* =>
<div><span>Subject:</span><span> </span><input maxlength="100" type="text" name="subject"></div>
<div><span>Message:</span><span> </span><input type="text" name="message"></div>
<div><span>Sender:</span><span> </span><input type="email" name="sender"></div>
<div><span>Cc myself:</span><span> </span><input type="checkbox" name="ccMyself"></div>"
*/

If autoId is set to true, then the form output will include <label> tags and will simply use the field name as its id for each form field:

var f = new ContactForm({autoId: false})
print(reactHTML(f.asTable()))
/* =>
<tr><th><label for="subject">Subject:</label></th><td><input maxlength="100" type="text" name="subject" id="subject"></td></tr>
<tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message"></td></tr>
<tr><th><label for="sender">Sender:</label></th><td><input type="email" name="sender" id="sender"></td></tr>
<tr><th><label for="ccMyself">Cc myself:</label></th><td><input type="checkbox" name="ccMyself" id="ccMyself"></td></tr>
*/
print(reactHTML(f.asUl()))
/* =>
<li><label for="subject">Subject:</label><span> </span><input maxlength="100" type="text" name="subject" id="subject"></li>
<li><label for="message">Message:</label><span> </span><input type="text" name="message" id="message"></li>
<li><label for="sender">Sender:</label><span> </span><input type="email" name="sender" id="sender"></li>
<li><label for="ccMyself">Cc myself:</label><span> </span><input type="checkbox" name="ccMyself" id="ccMyself"></li>
*/
print(reactHTML(f.asDiv()))
/* =>
<div><label for="subject">Subject:</label><span> </span><input maxlength="100" type="text" name="subject" id="subject"></div>
<div><label for="message">Message:</label><span> </span><input type="text" name="message" id="message"></div>
<div><label for="sender">Sender:</label><span> </span><input type="email" name="sender" id="sender"></div>
<div><label for="ccMyself">Cc myself:</label><span> </span><input type="checkbox" name="ccMyself" id="ccMyself"></div>
*/

If autoId is set to a string containing a '{name}' format placeholder, then the form output will include <label> tags, and will generate id attributes based on the format string:

var f = new ContactForm({autoId: 'id_for_{name}'})
print(reactHTML(f.asTable()))
/* =>
<tr><th><label for="id_for_subject">Subject:</label></th><td><input maxlength="100" type="text" name="subject" id="id_for_subject"></td></tr>\
<tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message"></td></tr>\
<tr><th><label for="id_for_sender">Sender:</label></th><td><input type="email" name="sender" id="id_for_sender"></td></tr>\
<tr><th><label for="id_for_ccMyself">Cc myself:</label></th><td><input type="checkbox" name="ccMyself" id="id_for_ccMyself"></td></tr>",
*/
print(reactHTML(f.asUl()))
/* =>
<li><label for="id_for_subject">Subject:</label><span> </span><input maxlength="100" type="text" name="subject" id="id_for_subject"></li>\
<li><label for="id_for_message">Message:</label><span> </span><input type="text" name="message" id="id_for_message"></li>\
<li><label for="id_for_sender">Sender:</label><span> </span><input type="email" name="sender" id="id_for_sender"></li>\
<li><label for="id_for_ccMyself">Cc myself:</label><span> </span><input type="checkbox" name="ccMyself" id="id_for_ccMyself"></li>",
*/
print(reactHTML(f.asDiv()))
/* =>
<div><label for="id_for_subject">Subject:</label><span> </span><input maxlength="100" type="text" name="subject" id="id_for_subject"></div>\
<div><label for="id_for_message">Message:</label><span> </span><input type="text" name="message" id="id_for_message"></div>\
<div><label for="id_for_sender">Sender:</label><span> </span><input type="email" name="sender" id="id_for_sender"></div>\
<div><label for="id_for_ccMyself">Cc myself:</label><span> </span><input type="checkbox" name="ccMyself" id="id_for_ccMyself"></div>",
*/

By default, autoId is set to the string 'id_{name}'.

It’s possible to customise the suffix character appended to generated labels (default: ':'), or omit it entirely, using the labelSuffix parameter:

var f = new ContactForm({autoId: 'id_for_{name}', labelSuffix: ''})
print(reactHTML(f.asUl()))
/* =>
<li><label for="id_for_subject">Subject</label><span> </span><input maxlength="100" type="text" name="subject" id="id_for_subject"></li>
<li><label for="id_for_message">Message</label><span> </span><input type="text" name="message" id="id_for_message"></li>
<li><label for="id_for_sender">Sender</label><span> </span><input type="email" name="sender" id="id_for_sender"></li>
<li><label for="id_for_ccMyself">Cc myself</label><span> </span><input type="checkbox" name="ccMyself" id="id_for_ccMyself"></li>
*/
f = new ContactForm({autoId: 'id_for_{name}', labelSuffix: ' ->'})
print(reactHTML(f.asUl()))
/* =>
<li><label for="id_for_subject">Subject -&gt;</label><span> </span><input maxlength="100" type="text" name="subject" id="id_for_subject"></li>
<li><label for="id_for_message">Message -&gt;</label><span> </span><input type="text" name="message" id="id_for_message"></li>
<li><label for="id_for_sender">Sender -&gt;</label><span> </span><input type="email" name="sender" id="id_for_sender"></li>
<li><label for="id_for_ccMyself">Cc myself -&gt;</label><span> </span><input type="checkbox" name="ccMyself" id="id_for_ccMyself"></li>
*/

Note that the label suffix is added only if the last character of the label isn’t a punctuation character.

You can also customise the labelSuffix on a per-field basis using the labelSuffix argument to BoundField#labelTag().

Notes on field ordering¶

In the asDiv(), asUl() and asTable() shortcuts, the fields are displayed in the order in which you define them in your form. For example, in the ContactForm example, the fields are defined in the order subject, message, sender, ccMyself. To reorder the HTML output, just change the order in which those fields are listed in the class.

How errors are displayed¶

If you render a bound Form object, the act of rendering will automatically run the form’s validation if it hasn’t already happened, and the HTML output will include the validation errors as a <ul class="errorlist"> near the field:

var data = {
  subject: ''
, message: 'Hi there'
, sender: 'invalid email address'
, ccMyself: true
}
var f = new ContactForm({data: data})
print(reactHTML(f.asTable()))
/* =>
<tr><th><label for="id_subject">Subject:</label></th><td><ul class="errorlist"><li>This field is required.</li></ul><input maxlength="100" type="text" name="subject" id="id_subject"></td></tr>
<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there"></td></tr>
<tr><th><label for="id_sender">Sender:</label></th><td><ul class="errorlist"><li>Enter a valid email address.</li></ul><input type="email" name="sender" id="id_sender" value="invalid email address"></td></tr>
<tr><th><label for="id_ccMyself">Cc myself:</label></th><td><input type="checkbox" name="ccMyself" id="id_ccMyself" checked></td></tr>
*/
print(reactHTML(f.asUl()))
/* =>
<li><ul class="errorlist"><li>This field is required.</li></ul><label for="id_subject">Subject:</label><span> </span><input maxlength="100" type="text" name="subject" id="id_subject"></li>
<li><label for="id_message">Message:</label><span> </span><input type="text" name="message" id="id_message" value="Hi there"></li>
<li><ul class="errorlist"><li>Enter a valid email address.</li></ul><label for="id_sender">Sender:</label><span> </span><input type="email" name="sender" id="id_sender" value="invalid email address"></li>
<li><label for="id_ccMyself">Cc myself:</label><span> </span><input type="checkbox" name="ccMyself" id="id_ccMyself" checked></li>
*/
print(reactHTML(f.asDiv()))
/* =>
<div><ul class="errorlist"><li>This field is required.</li></ul><label for="id_subject">Subject:</label><span> </span><input maxlength="100" type="text" name="subject" id="id_subject"></div>
<div><label for="id_message">Message:</label><span> </span><input type="text" name="message" id="id_message" value="Hi there"></div>
<div><ul class="errorlist"><li>Enter a valid email address.</li></ul><label for="id_sender">Sender:</label><span> </span><input type="email" name="sender" id="id_sender" value="invalid email address"></div>
<div><label for="id_ccMyself">Cc myself:</label><span> </span><input type="checkbox" name="ccMyself" id="id_ccMyself" checked></div>
*/

Customising the error list format¶

By default, forms use ErrorList() to format validation errors. You can pass an alternate constructor for displaying errors at form construction time:

var DivErrorList = forms.ErrorList.extend({
  render: function() {
    return React.createElemenr('div', {className: 'errorlist'}
    , this.messages().map(function(error) {
        return React.createElemenr('div', null, error)
      })
    )
  }
})
f = new ContactForm({data: data, errorConstructor: DivErrorList, autoId: false})
print(reactHTML(f.asDiv()))
/* =>
<div><div class="errorlist"><div>This field is required.</div></div><span>Subject:</span><span> </span><input maxlength="100" type="text" name="subject"></div>
<div><span>Message:</span><span> </span><input type="text" name="message" value="Hi there"></div>
<div><div class="errorlist"><div>Enter a valid email address.</div></div><span>Sender:</span><span> </span><input type="email" name="sender" value="invalid email address"></div>
<div><span>Cc myself:</span><span> </span><input type="checkbox" name="ccMyself" checked></div>
*/

More granular output¶

The asDiv(), asUl() and asTable() methods are simply shortcuts for lazy developers – they’re not the only way a form object can be displayed.

To retrieve a single BoundField(), use the BaseForm#boundField() method on your form, passing the field’s name:

var form = new ContactForm()
print(reactHTML(form.boundField('subject').render()))
// => <input maxlength="100\ type="text" name="subject\" id="id_subject">

To retrieve all BoundField objects, call BaseForm#boundFields():

var form = new ContactForm()
form.boundFields().forEach(function(bf) {
  print(reactHTML(bf.render()))
})
/* =>
<input maxlength="100" type="text" name="subject" id="id_subject">
<input type="text" name="message" id="id_message">
<input type="email" name="sender" id="id_sender">
<input type="checkbox" name="ccMyself" id="id_ccMyself">"
*/

The field-specific output honours the form object’s autoId setting:

var f = new ContactForm({autoId: false})
print(reactHTML(f.boundField('message').render()))
// => <input type="text" name="message">
f = new ContactForm({autoId: 'id_{name}'})
print(reactHTML(f.boundField('message').render()))
// => <input type="text" name="message" id="id_message">

boundField.errors() returns an object which renders as a <ul class="errorlist">:

var data = {subject: 'hi', message: '', sender: '', ccMyself: ''}
var f = new ContactForm({data: data, autoId: false})
var bf = f.boundField('message')
print(reactHTML(bf.render()))
// => <input type="text" name="message">
print(bf.errors().messages())
// => ["This field is required."]
print(reactHTML(bf.errors().render())
// => <ul class="errorlist"><li>This field is required.</li></ul>
bf = f.boundField('subject')
print(bf.errors().messages())
// => []
print(reactHTML(bf.errors().render()))
// =>

To separately render the label tag of a form field, you can call its BoundField#labelTag() method:

var f = new ContactForm()
print(reactHTML(f.boundField('message').labelTag()))
// => <label for="id_message">Message:</label>

If you’re manually rendering a field, you can access configured CSS classes using the cssClasses method:

var f = new ContactForm()#
f.requiredCssClass = 'required'
print(f.boundField('message').cssClasses())
// => required

Additional classes can be provided as an argument:

print(f.boundField('message').cssClasses('foo bar'))
// => foo bar required

boundField.value() returns the raw value of the field as it would be rendered by a Widget():

var initial = {subject: 'welcome'}
var data = {subject: 'hi'}
var unboundForm = new ContactForm({initial: initial})
var boundForm = new ContactForm({data: data, initial: initial})
print(unboundForm.boundField('subject').value())
// => welcome
print(boundForm.boundField('subject').value())
// => hi

boundField.idForLabel() returns the id of the field. For example, if you are manually constructing a label in JSX:

<label htmlFor={form.boundField('myField').idForLabel()}>...<label>

Testing for multipart forms¶

If you’re writing reusable views or templates, you may not know ahead of time whether your form is a multipart form or not. The isMultipart() method tells you whether the form requires multipart encoding for submission:

var f = new ContactFormWithMugshot()
print(f.isMultipart())
// => true

Here’s an example of how you might use this in a React component render() method with JSX:

<form enctype={form.isMultipart() && 'multipart/form-data'} method="POST" action="/foo">
  {form.asDiv()}
</form>

required¶

By default, each Field assumes the value is required, so if you pass an empty value – undefined, null or the empty string ('') – then clean() will throw a ValidationError.

To specify that a field is not required, pass required: false to the Field constructor:

var f = forms.CharField({required: false})

If a Field has required: false and you pass clean() an empty value, then clean() will return a normalised empty value rather than throwing a ValidationError. For CharField, this will be an empty string. For another Field type, it might be null (This varies from field to field.).

label¶

The label argument lets you specify the “human-friendly” label for this field. This is used when the Field is displayed in a Form.

initial¶

The initial argument lets you specify the initial value to use when rendering this Field in an unbound Form.

To specify dynamic initial data, see the initial option.

widget¶

The widget argument lets you specify a Widget to use when rendering this Field. You can pass either an instance or a Widget constructor. See Widgets for more information.

helpText¶

The helpText argument lets you specify descriptive text for this Field. If you provide helpText, it will be displayed next to the Field when the Field is rendered by one of the convenience Form methods (e.g., asUJl()).

errorMessages¶

The errorMessages argument lets you override the default messages that the field will throw. Pass in an object with properties matching the error messages you want to override. For example, here is the default error message:

var generic = forms.CharField()
try {
  generic.clean('')
}
catch (e) {
  print(e.messages())
}
// => ["This field is required."]

And here is a custom error message:

var name = forms.CharField({errorMessages: {required: 'Please enter your name.'}})
try {
  name.clean('')
}
catch (e) {
  print(e.messages())
}
// => ["Please enter your name."]

The error message codes used by fields are defined below.

validators¶

The validators argument lets you provide a list of additional validation functions for this field.

BooleanField()¶

• Default widget: CheckboxInput()
• Empty value: false
• Normalises to: A JavaScript true or false value.
• Validates that the value is true (e.g. the check box is checked) if the field has required: true.
• Error message keys: required

Note

Since all Field types have required: true by default, the validation condition here is important. If you want to include a boolean in your form that can be either true or false (e.g. a checked or unchecked checkbox), you must remember to pass in required: false when creating the BooleanField.

CharField()¶

• Default widget: TextInput()
• Empty value: '' (an empty string)
• Normalises to: A string.
• Validates maxLength or minLength, if they are provided. Otherwise, all inputs are valid.
• Error message keys: required, maxLength, minLength

Has two optional arguments for validation:

• maxLength
• minLength

If provided, these arguments ensure that the string is at most or at least the given length.

ChoiceField()¶

• Default widget: Select()
• Empty value: '' (an empty string)
• Normalises to: A string.
• Validates that the given value exists in the list of choices.
• Error message keys: required, invalidChoice

The invalidChoice error message may contain {value}, which will be replaced with the selected choice.

Takes one extra argument:

• choices

  A list of pairs (2 item lists) to use as choices for this field. See Providing choices for more details.

TypedChoiceField()¶

Just like a ChoiceField(), except TypedChoiceField() takes two extra arguments, coerce and emptyValue.

• Default widget: Select()
• Empty value: Whatever you’ve given as emptyValue
• Normalises to: A value of the type provided by the coerce argument.
• Validates that the given value exists in the list of choices and can be coerced.
• Error message keys: required, invalidChoice

Takes extra arguments:

• coerce

  A function that takes one argument and returns a coerced value. Examples include the built-in Number, Boolean and other types. Defaults to an identity function. Note that coercion happens after input validation, so it is possible to coerce to a value not present in choices.

• emptyValue

  The value to use to represent “empty.” Defaults to the empty string; null is another common choice here. Note that this value will not be coerced by the function given in the coerce argument, so choose it accordingly.

DateField()¶

• Default widget: DateInput()
• Empty value: null
• Normalises to: A JavaScript Date object, with its time fields set to zero.
• Validates that the given value is either a Date, or string formatted in a particular date format.
• Error message keys: required, invalid

Takes one optional argument:

• inputFormats

  A list of format strings used to attempt to convert a string to a valid Date object.

If no inputFormats argument is provided, the default input formats are:

[
  '%Y-%m-%d'              // '2006-10-25'
, '%m/%d/%Y', '%m/%d/%y'  // '10/25/2006', '10/25/06'
, '%b %d %Y', '%b %d, %Y' // 'Oct 25 2006', 'Oct 25, 2006'
, '%d %b %Y', '%d %b, %Y' // '25 Oct 2006', '25 Oct, 2006'
, '%B %d %Y', '%B %d, %Y' // 'October 25 2006', 'October 25, 2006'
, '%d %B %Y', '%d %B, %Y' // '25 October 2006', '25 October, 2006'
]

DateTimeField()¶

• Default widget: DateTimeInput()
• Empty value: null
• Normalises to: A JavaScript Date object.
• Validates that the given value is either a Date or string formatted in a particular datetime format.
• Error message keys: required, invalid

Takes one optional argument:

• inputFormats

  A list of format strings used to attempt to convert a string to a valid Date object.

If no inputFormats argument is provided, the default input formats are:

[
  '%Y-%m-%d %H:%M:%S' // '2006-10-25 14:30:59'
, '%Y-%m-%d %H:%M'    // '2006-10-25 14:30'
, '%Y-%m-%d'          // '2006-10-25'
, '%m/%d/%Y %H:%M:%S' // '10/25/2006 14:30:59'
, '%m/%d/%Y %H:%M'    // '10/25/2006 14:30'
, '%m/%d/%Y'          // '10/25/2006'
, '%m/%d/%y %H:%M:%S' // '10/25/06 14:30:59'
, '%m/%d/%y %H:%M'    // '10/25/06 14:30'
, '%m/%d/%y'          // '10/25/06'
]

DecimalField()¶

• Default widget: NumberInput().
• Empty value: null
• Normalises to: A string (since JavaScript doesn’t have built-in Decimal type).
• Validates that the given value is a decimal. Leading and trailing whitespace is ignored.
• Error message keys: required, invalid, maxValue, minValue, maxDigits, maxDecimalPlaces, maxWholeDigits

The maxValue and minValue error messages may contain {limitValue}, which will be substituted by the appropriate limit.

Similarly, the maxDigits, maxDecimalPlaces and maxWholeDigits error messages may contain {max}.

Takes four optional arguments:

• maxValue

• minValue

  These control the range of values permitted in the field.

• maxDigits

  The maximum number of digits (those before the decimal point plus those after the decimal point, with leading zeros stripped) permitted in the value.

• decimalDlaces

  The maximum number of decimal places permitted.

EmailField()¶

• Default widget: EmailInput()
• Empty value: '' (an empty string)
• Normalises to: A string.
• Validates that the given value is a valid email address, using a moderately complex regular expression.
• Error message keys: required, invalid

Has two optional arguments for validation, maxLength and minLength. If provided, these arguments ensure that the string is at most or at least the given length.

FileField()¶

• Default widget: ClearableFileInput()
• Empty value: null
• Normalises to: The given object in files - this field just validates what’s there and leaves the rest up to you.
• Can validate that non-empty file data has been bound to the form.
• Error message keys: required, invalid, missing, empty, maxLength

Has two optional arguments for validation, maxLength and allowEmptyFile. If provided, these ensure that the file name is at most the given length, and that validation will succeed even if the file content is empty.

When you use a FileField in a form, you must also remember to bind the file data to the form.

The maxLength error refers to the length of the filename. In the error message for that key, {max} will be replaced with the maximum filename length and {length} will be replaced with the current filename length.

FilePathField()¶

• Default widget: Select()
• Empty value: null
• Normalises to: A string
• Validates that the selected choice exists in the list of choices.
• Error message keys: required, invalidChoice

The field allows choosing from files inside a certain directory. It takes three extra arguments; only path is required:

• path

  The absolute path to the directory whose contents you want listed. This directory must exist.

• recursive

  If false (the default) only the direct contents of path will be offered as choices. If true, the directory will be descended into recursively and all descendants will be listed as choices.

• match

  A regular expression pattern; only files with names matching this expression will be allowed as choices.

• allowFiles

  Optional. Either true or false. Default is true. Specifies whether files in the specified location should be included. Either this or allowFolders must be true.

• allowFolders

  Optional. Either true or false. Default is false. Specifies whether folders in the specified location should be included. Either this or allowFiles must be true.

FloatField()¶

• Default widget: NumberInput().
• Empty value: null
• Normalises to: A JavaScript Number.
• Validates that the given value is a float. Leading and trailing whitespace is allowed.
• Error message keys: required, invalid, maxValue, minValue

Takes two optional arguments for validation, maxValue and minValue. These control the range of values permitted in the field.

ImageField()¶

• Default widget: ClearableFileInput()
• Empty value: null
• Normalises to: The given object in files - this field just validates what’s there and leaves the rest up to you.
• Validates that file data has been bound to the form, and that the file is of an image format.
• Error message keys: required, invalid, missing, empty, invalidImage

Note

Server-side image validation isn’t implemented yet.

When you use a ImageField in a form, you must also remember to bind the file data to the form.

IntegerField()¶

• Default widget: NumberInput().
• Empty value: null
• Normalises to: A JavaScript Number.
• Validates that the given value is an integer. Leading and trailing whitespace is allowed.
• Error message keys: required, invalid, maxValue, minValue

The maxValue and minValue error messages may contain {limitValue}, which will be substituted by the appropriate limit.

Takes two optional arguments for validation:

• maxValue

• minValue

  These control the range of values permitted in the field.

IPAddressField()¶

Deprecated since version 0.5: This field has been deprecated in favour of GenericIPAddressField().

• Default widget: TextInput()
• Empty value: '' (an empty string)
• Normalises to: A string.
• Validates that the given value is a valid IPv4 address, using a regular expression.
• Error message keys: required, invalid

GenericIPAddressField()¶

A field containing either an IPv4 or an IPv6 address.

• Default widget: TextInput()
• Empty value: '' (an empty string)
• Normalises to: A string. IPv6 addresses are normalised as described below.
• Validates that the given value is a valid IP address.
• Error message keys: required, invalid

The IPv6 address normalisation follows RFC 4291 section 2.2, including using the IPv4 format suggested in paragraph 3 of that section, like ::ffff:192.0.2.0. For example, 2001:0::0:01 would be normalised to 2001::1, and ::ffff:0a0a:0a0a to ::ffff:10.10.10.10. All characters are converted to lowercase.

Takes two optional arguments:

• protocol

  Limits valid inputs to the specified protocol. Accepted values are both (default), ipv4 or ipv6. Matching is case insensitive.

• unpackIPv4

  Unpacks IPv4 mapped addresses like ::ffff:192.0.2.1. If this option is enabled that address would be unpacked to 192.0.2.1. Default is disabled. Can only be used when protocol is set to 'both'.

MultipleChoiceField()¶

• Default widget: SelectMultiple()
• Empty value: [] (an empty list)
• Normalises to: A list of strings.
• Validates that every value in the given list of values exists in the list of choices.
• Error message keys: required, invalidChoice, invalidList

The invalidChoice error message may contain {value}, which will be replaced with the selected choice.

Takes one extra required argument, choices, as for ChoiceField.

TypedMultipleChoiceField()¶

Just like a MultipleChoiceField(), except TypedMultipleChoiceField() takes two extra arguments, coerce and emptyValue.

• Default widget: SelectMultiple()
• Empty value: Whatever you’ve given as emptyValue
• Normalises to: A list of values of the type provided by the coerce argument.
• Validates that the given values exists in the list of choices and can be coerced.
• Error message keys: required, invalidChoice

The invalidChoice error message may contain {value}, which will be replaced with the selected choice.

Takes two extra arguments, coerce and emptyValue, as for TypedChoiceField.

NullBooleanField()¶

• Default widget: NullBooleanSelect()
• Empty value: null
• Normalises to: A JavaScript true, false or null value.
• Validates nothing (i.e., it never raises a ValidationError).

RegexField()¶

• Default widget: TextInput()
• Empty value: '' (an empty string)
• Normalises to: A string.
• Validates that the given value matches against a certain regular expression.
• Error message keys: required, invalid

Takes one required argument:

• regex

  A regular expression specified either as a string or a compiled regular expression object.

Also takes maxLength and minLength, which work just as they do for CharField.

SlugField()¶

• Default widget: TextInput()
• Empty value: '' (an empty string)
• Normalises to: A string.
• Validates that the given value contains only letters, numbers, underscores, and hyphens.
• Error messages: required, invalid

TimeField()¶

• Default widget: TextInput()
• Empty value: null
• Normalises to: A JavaScript Date object, with its date fields set to 1900-01-01.
• Validates that the given value is either a Date or string formatted in a particular time format.
• Error message keys: required, invalid

Takes one optional argument:

• inputFormats

  A list of format strings used to attempt to convert a string to a valid Date object.

If no inputFormats argument is provided, the default input formats are:

[
  '%H:%M:%S' // '14:30:59'
, '%H:%M'    // '14:30'
]

URLField()¶

• Default widget: URLInput()
• Empty value: '' (an empty string)
• Normalises to: A string.
• Validates that the given value is a valid URL.
• Error message keys: required, invalid

Takes the following optional arguments:

• maxLength
• minLength

These are the same as CharField.maxLength and CharField.minLength.

ComboField()¶

• Default widget: TextInput()
• Empty value: '' (an empty string)
• Normalises to: A string.
• Validates that the given value against each of the fields specified as an argument to the ComboField.
• Error message keys: required, invalid

Takes one extra argument:

• fields

  The list of fields that should be used to validate the field’s value (in the order in which they are provided):

  var f = forms.ComboField({fields: [
    forms.CharField({maxLength: 20})
  , forms.EmailField()
  ]})
  print(f.clean('test@example.com'))
  // => test@example.com
  try {
    f.clean('longemailaddress@example.com')
  }
  catch (e) {
    print(e.messages())
  }
  // => ['Ensure this value has at most 20 characters (it has 28).']
  

MultiValueField()¶

• Default widget: TextInput()
• Empty value: '' (an empty string)
• Normalises to: the type returned by the compress method of the field.
• Validates that the given value against each of the fields specified as an argument to the MultiValueField.
• Error message keys: required, invalid, incomplete

Aggregates the logic of multiple fields that together produce a single value.

This field is abstract and must be extended. In contrast with the single-value fields, fields which extend js:class:MultiValueField must not implement BaseField#clean() but instead - implement compress().

Takes one extra argument:

• fields

  A list of fields whose values are cleaned and subsequently combined into a single value. Each value of the field is cleaned by the corresponding field in fields – the first value is cleaned by the first field, the second value is cleaned by the second field, etc. Once all fields are cleaned, the list of clean values is combined into a single value by compress().

Also takes one extra optional argument:

• requireAllFields

  New in version 0.5.

  Defaults to true, in which case a required validation error will be raised if no value is supplied for any field.

  When set to false, the Field.required attribute can be set to false for individual fields to make them optional. If no value is supplied for a required field, an incomplete validation error will be raised.

  A default incomplete error message can be defined on the MultiValueField(), or different messages can be defined on each individual field. For example:

  var RegexValidator = forms.validators.RegexValidator
  var PhoneField = forms.MultiValueField.extend({
    constructor: function(kwargs) {
      kwargs = kwargs || {}
       // Define one message for all fields
      kwargs.errorMessages = {
        incomplete: 'Enter a country code and phone number.'
      }
      // Or define a different message for each field
      kwargs.fields = [
        forms.CharField({errorMessages: {incomplete: 'Enter a country code.'}, validators: [
          RegexValidator({regex: /^\d+$/, message: 'Enter a valid country code.'})
        ]})
      , forms.CharField({errorMessages: {incomplete: 'Enter a phone number.'}, validators: [
          RegexValidator({regex: /^\d+$/, message: 'Enter a valid phone number.'})
        ]})
      , forms.CharField({required: false, validators: [
          RegexValidator({regex: /^\d+$/, message: 'Enter a valid extension.'})
        ]})
      ]
      PhoneField.__super__.constructor.call(this, kwargs)
    }
  })
  

• MultiValueField.widget

  Must extend MultiWidget(). Default value is TextInput(), which probably is not very useful in this case. Have a nice day :)

• compress(dataList)

  Takes a list of valid values and returns a “compressed” version of those values – in a single value. For example, SplitDateTimeField() is a combines a time field and a date field into a Date object.

  This method must be implemented in the Field extending MultiValueField.

SplitDateTimeField()¶

• Default widget: SplitDateTimeWidget()
• Empty value: null
• Normalises to: A JavaScript datetime.datetime object.
• Validates that the given value is a datetime.datetime or string formatted in a particular datetime format.
• Error message keys: required, invalid, invalidDate, invalidTime

Takes two optional arguments:

• inputDateFormats

  A list of format strings used to attempt to convert a string to a valid Date object with its time fields set to zero.

If no inputDateFormats argument is provided, the default input formats for DateField are used.

• inputTimeFormats

  A list of format strings used to attempt to convert a string to a valid Date object with its date fields set to 1900-01-01.

If no inputTimeFormats argument is provided, the default input formats for TimeField are used.

Creating custom fields¶

If the built-in Field objects don’t meet your needs, you can easily create custom Fields. To do this, just .extend() Field. Its only requirements are that it implement a clean() method and that its constructor() accepts the core arguments mentioned above (required, label, initial, widget, helpText) in an argument object.

Throwing multiple errors¶

If you detect multiple errors during a cleaning method and wish to signal all of them to the form submitter, it is possible to pass a list of errors to the ValidationError constructor.

It’s recommended to pass a list of ValidationError instances with codes and params but a list of strings will also work:

throw forms.ValidationError([
  forms.ValidationError('Error 1', {code: 'error1'})
, forms.ValidationError('Error 2', {code: 'error2'})
])

throw forms.ValidationError(['Error 1', 'Error 2'])

Using validators¶

Fields support use of utility functions known as validators. A validator is a function that takes a value and returns nothing if the value is valid, or thriws a ValidationError() if not. These can be passed to a field’s constructor, via the field’s validators argument, or defined on the field’s prototype as a defaultValidators property.

Let’s have a look at a basic implementation of newforms’ SlugField:

var MySlugField = forms.CharField.extend({
  defaultValidators: [forms.validators.validateSlug]
})

As you can see, a basic SlugField is just a CharField with a customised validator that validates that submitted text obeys some character usage rules. This can also be done on field definition so:

var field = new MySlugField()

is equivalent to:

var field = forms.CharField({validators: [forms.validators.validateSlug]})

Common cases such as validating against an email or a regular expression can be handled using existing validators available in newforms. For example, validateSlug() is a function created by passing a slug-matching RegExp to the RegexValidator() function factory.

Form field default cleaning¶

Let’s firstly create a custom form field that validates its input is a string containing comma-separated email addresses:

var MultiEmailField = forms.Field.extend({
  /** Normalise data to a list of strings. */
  toJavaScript: function(value) {
    // Return an empty list if no input was given
    if (this.isEmptyValue(value)) {
      return []
    }
    return value.split(/, ?/g)
  }

  /** Check if value consists only of valid emails. */
, validate: function(value) {
    // Use the parent's handling of required fields, etc.
    MultiEmailField.__super__.validate.call(this, value)
    value.map(forms.validators.validateEmail)
  }
})

Let’s create a simple ContactForm to demonstrate how you’d use this field:

var ContactForm = forms.Form.extend({
  subject: forms.CharField({maxLength: 100})
, message: forms.CharField()
, sender: forms.EmailField()
, recipients: new MultiEmailField()
, ccMyself: forms.BooleanField({required: false})
})

Cleaning a specific field attribute¶

Suppose that in our ContactForm, we want to make sure that the recipients field always contains the address "fred@example.com". This is validation that is specific to our form, so we don’t want to put it into the general MultiEmailField. Instead, we write a cleaning function that operates on the recipients field, like so:

var ContactForm = forms.Form.extend({
  // Everything as before
  // ...

, cleanRecipients: function() {
    var recipients = this.cleanedData.recipients
    if (recipients.indexOf('fred@example.com') == -1) {
      throw forms.ValidationError('You have forgotten about Fred!')
    }

    // Returning the cleaned data is optional - if anything is returned,
    // cleanedData will be updated with the new value.
    return recipients
  }
}

If you return anything from a custom field cleaning function, the form’s cleanedData for the field will be updated with the returned value.

Cleaning and validating fields that depend on each other¶

var ContactForm = forms.Form.extend({
  // Everything as before
  // ...

, clean: function() {
    var cleanedData = ContactForm.__super__.clean.call(this)
    var ccMyself = cleanedData.ccMyself
    var subject = cleanedData.subject

    if (ccMyself && subject) {
      // Only do something if both fields are valid so far
      if (subject.indexOf('help') == -1) {
        throw forms.ValidationError(
          "Did not send for 'help' in the subject despite CC'ing yourself.")
      }
    }
  }
}

var ContactForm = forms.Form.extend({
  // Everything as before
  // ...

, clean: function() {
    var cleanedData = ContactForm.__super__.clean.call(this)
    var ccMyself = cleanedData.ccMyself
    var subject = cleanedData.subject

    if (ccMyself && subject && subject.indexOf('help') == -1) {
      var message = "Must put 'help' in subject when cc'ing yourself."
      this.addError('ccMyself', message)
      this.addError('subject', message)
    }
  }
}

var PersonForm = forms.Form.extend({
  firstName: forms.CharField({required: false, maxLength: 50}),
  lastName: forms.CharField({required: false, maxLength: 50}),
  jobTitle: forms.CharField({required: false, maxLength: 100}),
  organisation : forms.CharField({required: false}),

  clean: ['firstName', 'lastName', function() {
     if (!this.cleanedData.firstName && !this.cleanedData.lastName) {
       throw forms.ValidationError('A first name or last name is required.')
     }
  }]
})

Styling widget instances¶

If you want to make one widget instance look different from another, you will need to specify additional attributes at the time when the widget object is instantiated and assigned to a form field (and perhaps add some rules to your CSS files).

For example, take the following simple form:

var CommentForm = forms.Form.extend({
  name: forms.CharField()
, url: forms.URLField()
, comment: forms.CharField()
})

This form will include three default TextInput() widgets, with default rendering – no CSS class, no extra attributes. This means that the input boxes provided for each widget will be rendered exactly the same:

var f = new CommentForm({autoId: false})
print(reactHTML(f.asTable()))
/* =>
<tr><th>Name:</th><td><input type="text" name="name"></td></tr>
<tr><th>Url:</th><td><input type="url" name="url"></td></tr>
<tr><th>Comment:</th><td><input type="text" name="comment"></td></tr>
*/

On a real Web page, you probably don’t want every widget to look the same. You might want a larger input element for the comment, and you might want the ‘name’ widget to have some special CSS class. It is also possible to specify the ‘type’ attribute to take advantage of the new HTML5 input types. To do this, you use the Widget.attrs argument when creating the widget:

var CommentForm = forms.Form.extend({
  name: forms.CharField({
    widget: forms.TextInput({attrs: {className: 'special'}})
  })
, url: forms.URLField()
, comment: forms.CharField({widget: forms.TextInput({attrs: {size: '40'}})
})

The extra attributes will then be included in the rendered output:

var f = new CommentForm({autoId: false})
print(reactHTML(f.asTable()))
/* =>
<tr><th>Name:</th><td><input class="special" type="text" name="name"></td></tr>
<tr><th>Url:</th><td><input type="url" name="url"></td></tr>
<tr><th>Comment:</th><td><input size="40" type="text" name="comment"></td></tr>
*/

You can also set the HTML id using Widget.attrs.

Widget()¶

This abstract widget cannot be rendered, but provides the basic attribute Widget.attrs. You may also implement or override the render() method on custom widgets.

widget.attrs

An object containing HTML attributes to be set on the rendered widget:

var name = forms.TextInput({attrs: {size:10, title: 'Your name'}})
print(reactHTML(name.render('name', 'A name')))
// => <input size="10" title="Your name" type="text" name="name" value="A name">"

Key Widget methods are:

Widget#render()

Returns a ReactElement representation of the widget. This method must be implemented by extending widgets, or an Error will be thrown.

The ‘value’ given is not guaranteed to be valid input, therefore extending widgets should program defensively.

Widget#valueFromData()

Given an object containing input data and this widget’s name, returns the value of this widget. Returns null if a value wasn’t provided.

MultiWidget()¶

A widget that is composed of multiple widgets. MultiWidget() works hand in hand with the MultiValueField().

MultiWidget has one required argument:

MultiWidget.widgets

A list containing the widgets needed.

And one required method:

MultiWidget#decompress()

This method takes a single “compressed” value from the field and returns a list of “decompressed” values. The input value can be assumed valid, but not necessarily non-empty.

This method must be implemented by the widgets extending MultiWidget, and since the value may be empty, the implementation must be defensive.

The rationale behind “decompression” is that it is necessary to “split” the combined value of the form field into the values for each widget.

An example of this is how SplitDateTimeWidget() turns a Date value into a list with date and time split into two separate values.

Tip

Note that MultiValueField() has a complementary method MultiValueField#compress() with the opposite responsibility - to combine cleaned values of all member fields into one.

Other methods that may be useful to implement include:

MultiWidget#render()

The value argument must be handled differently in this method then in Widget#render() because it has to figure out how to split a single value for display in multiple widgets.

The value argument used when rendering can be one of two things:

• A list.
• A single value (e.g., a string) that is the “compressed” representation of a list of values.

If value is a list, the output of MultiWidget#render() will be a concatenation of rendered child widgets. If value is not a list, it will first be processed by the method MultiWidget#decompress() to create the list and then rendered.

When render() runs, each value in the list is rendered with the corresponding widget – the first value is rendered in the first widget, the second value is rendered in the second widget, etc.

Unlike in the single value widgets, render() doesn’t have to be implemented by extending widgets.

MultiWidget#formatOutput()

Given a list of rendered widgets (as ReactElement objects), returns the list or a ReactElement object containing the widgets. This hook allows you to lay out the widgets any way you’d like.

Here’s an example widget which extends MultiWidget() to display a date with the day, month, and year in different select boxes. This widget is intended to be used with a DateField() rather than a MultiValueField(), so we’ve implemented Widget#valueFromData():

var DateSelectorWidget = forms.MultiWidget.extend({
  constructor: function(kwargs) {
    kwargs = extend({attrs: {}}, kwargs)
    widgets = [
      forms.Select({choices: range(1, 32), attrs: kwargs.attrs})
    , forms.Select({choices: range(1, 13), attrs: kwargs.attrs})
    , forms.Select({choices: range(2012, 2017), attrs: kwargs.attrs})
    ]
    forms.MultiWidget.call(this, widgets, kwargs)
  }

, decompress: function(value) {
    if (value instanceof Date) {
      return [value.getDate(),
              value.getMonth() + 1, // Make month 1-based for display
              value.getFullYear()]
    }
    return [null, null, null]
  }

, formatOutput: function(renderedWidgets) {
    return React.createElement('div', null, renderedWidgets)
  }

, valueFromData: function(data, files, name) {
    var parts = this.widgets.map(function(widget, i) {
      return widget.valueFromData(data, files, name + '_' + i)
    })
    parts.reverse() // [d, m, y] => [y, m, d]
    return parts.join('-')
  }
})