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¶

Newforms provides a React component which implements default rendering of Form objects.

This only provides rendering of the form’s 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}>
    <forms.RenderForm form={ContactForm}/>
    <div>
      <input type="submit" value="Submit"/>{' '}
      <input type="button" value="Cancel" onClick={this.onCancel}/>
    </div>
  </form>
}

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

<form action="/contact" method="POST">
  <div>
    <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>
  <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 customise the output of RenderForm by passing certain props or a child React component. See the documentation for custom rendering for more info.

You can also completely customise form display using rendering helpers for each field.

Form options¶

If form construction options are passed as props to RenderForm, they will be passed on to the Form constructor when creating an instance.

For example, if you need to display more than one of the same Form, you need to specify a prefix to give them a unique namespace, so pass a prefix prop like so:

var ParentForm = forms.Form.extend({
  name: forms.CharField(),
  dob: forms.DateField({label: 'Date of birth'})
})

<fieldset>
  <legend>Parent 1</legend>
  <RenderForm form={ParentForm} prefix="parent1"/>
</fieldset>
<fieldset>
  <legend>Parent 2</legend>
  <RenderForm form={ParentForm} prefix="parent2"/>
</fieldset>

Getting the Form instance¶

When passing RenderForm a Form constructor, give it a ref prop so you can use its getForm() method to access the Form instance it manages for you.

For example, when handling submission of a form:

render: function() {
  return <form onSubmit={this._onSubmit}>
    <forms.RenderForm form={MyForm} ref="myForm"/>
    <button>Submit</button>
  </form>
},

_onSubmit: function(e) {
  e.preventDefault()
  var form = this.refs.form.getForm()
  var isValid = form.validate()
  if (isValid) {
    // ..
  }
}

Other rendering scenarios¶

For the sake of being a complete default rendering implementation, RenderForm also handles some less common scenarios:

• Displaying error messages related to hidden fields.
• Rendering hidden fields.
• Displaying a progress indicator if the form has asynchronous whole-form validation pending completion.

RenderForm props¶

form

type:	Form or Function (a Form constructor)

The Form to be rendered – can be a constructor or an instance.

If you pass a Form constructor, the component will instantiate it for you. Form construction options may also be passed to RenderForm as additional props.

If you pass a Form instance, make sure you set up its onChange() in such a way that it will also re-render the <RenderForm/> component when the form changes.

component

type:	ReactCompositeComponent or String (an HTML tag name)

The component used to wrap all the form’s rows – defaults to 'div'.

className

type:	String

If provided, this prop will be passed to the wrapper component containing all the form’s rows.

row

type:	ReactCompositeComponent

The component used to render each form row – defaults to FormRow.

rowComponent

type:	ReactCompositeComponent or String (an HTML tag name)

The tag name or component used to wrap each form row. Defaults to 'div'.

This is passed as a component prop to the component in the row prop.

progress

type:	ReactCompositeComponent or Function

Used to render what’s displayed if the form has an async clean() method which is pending completion.

This will also be passed to the component in the row prop when rendering.

Form construction options

All the options which be passed when instantiating a Form can be passed as props to RenderForm for use when you pass a Form constructor as the form prop.

RenderForm methods¶

getForm()

Returns the Form instance being rendered by the component.

FormRow props¶

content

type:	Any

If given, will be used for the entire contents of the row.

bf

type:	BoundField()

If given and content is not given, this Field rendering helper will be used to create contents for a Field row.

component

type:	ReactCompositeComponent or String (an HTML tag name)

The component used to wrap the row contents. Defaults to 'div'.

className

type:	String

If provided, this prop will be passed to the wrapper component for the row.

hidden

type:	Boolean

If true, the row container ReactElement will be given a display: none style – defaults to false.

progress

type:	ReactCompositeComponent or Function

Used to render what’s displayed if the form has async clean<Field>() method which is pending completion.

RenderFormSet props¶

form

type:	Function (a Form constructor)

If you pass a Form constructor, the component will instantiate a FormSet for you.

FormSet constructor options may be passed as additional props to RenderFormSet.

Note

When a form prop is passed, use of the formset prop changes. If also provided, it must be a FormSet constructor to be extended from.

formset

type:	FormSet or Function (a FormSet constructor)

The FormSet to be rendered – can be a constructor or an instance.

If you pass a FormSet constructor, the component will instantiate it for you. FormSet construction options may also be passed to RenderFormSet as additional props.

If you pass a FormSet instance, make sure you set up its onChange() in such a way that it will also re-render the <RenderFormSet/> component when one of its forms changes.

component

type:	ReactCompositeComponent or String (an HTML tag name)

The component used to wrap the formset’s contents. Defaults to 'div'.

className

type:	String

If provided, this prop will be passed to the wrapper component for the formset.

formComponent

type:	ReactCompositeComponent or String (an HTML tag name)

The component used to wrap each form. Defaults to 'div'.

This is passed as a component prop to RenderForm.

row & rowComponent

These are as defined above for RenderForm, which they are passed to.

progress

type:	ReactCompositeComponent or Function

Used to render what’s displayed if the formset has an async clean() method which is pending completion.

This will also be passed to RenderForm.

useManagementForm

type:	Boolean If true, hidden fields from the FormSet’s management form will be rendered. Defaults to false. These fields are usually only required if you will be performing a regular form submission which will be processed by newforms on the server.

RenderFormSet methods¶

getFormset()

Returns the FormSet instance being rendered by the component.

noValidate¶

Some newforms Widgets render HTML5 input types which, by default, perform their own validation.

When you’re using newforms with React for interactive validation, this can give your forms an inconsistent feeling as the native inputs have their own way of presenting validation errors. Consider adding a noValidate prop to your <form> to disable native validation if this starts to feel like an issue:

<form onSubmit={this.handleSubmit} noValidate>

If you’re creating an isomorphic application, you might want to conditionally use noValidate so there’s some validation while the page is still initially loading, or for scenarios when JavaScript isn’t available on the client:

getInitialState() {
  return {client: false}
},

componentDidMount() {
  this.setState({client: true})
},

render() {
  return <form onSubmit={this.handleSubmit} noValidate={this.state.client}>
    ...

Form 'auto' validation¶

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

When the 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 input 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 cross-field 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 Form#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 event-based 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 Form#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.

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
• requiredCssClass – applied to form rows for required fields
• optionalCssClass – applied to form rows for optional fields
• errorCssClass – applied to form rows for fields which have errors
• validCssClass – applied to form rows for fields which have a corresponding value present in cleanedData
• pendingCssClass – applied to form rows for fields which have a pending asynchronous valdation.

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',
  requiredCssClass: 'required',
  optionalCssClass: 'optional',
  errorCssClass: 'error',
  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(<RenderForm form={f}/>))
/* =>
<div>
  <div class="row valid required"><label for="id_subject">Subject:</label> ...
  <div class="row valid required"><label for="id_message">Message:</label> ...
  <div class="row error required"><label for="id_sender">Sender:</label> ...
  <div class="row valid optional"><label for="id_ccMyself">Cc myself:</label> ...
</div>
*/

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(<RenderForm form={f}/>))
/* =>
<div>
  <divSubject: <input maxlength="100" type="text" name="subject"></div>
  <divMessage: <input type="text" name="message"></div>
  <divSender: <input type="email" name="sender"></div>
  <divCc myself: <input type="checkbox" name="ccMyself"></div>
</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: true})
print(reactHTML(<RenderForm form={f}/>))
/* =>
<div>
  <div><label for="subject">Subject:</label> <input maxlength="100" type="text" name="subject" id="subject"></div>
  <div><label for="message">Message:</label> <input type="text" name="message" id="message"></div>
  <div><label for="sender">Sender:</label> <input type="email" name="sender" id="sender"></div>
  <div><label for="ccMyself">Cc myself:</label> <input type="checkbox" name="ccMyself" id="ccMyself"></div>
</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(<RenderForm form={f}/>))
/* =>
<div>
  <div><label for="id_for_subject">Subject:</label> <input maxlength="100" type="text" name="subject" id="id_for_subject"></div>
  <div><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message"></div>
  <div><label for="id_for_sender">Sender:</label> <input type="email" name="sender" id="id_for_sender"></div>
  <div><label for="id_for_ccMyself">Cc myself:</label> <input type="checkbox" name="ccMyself" id="id_for_ccMyself"></div>
</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(<RenderForm form={f}/>))
/* =>
<div>
  <div><label for="id_for_subject">Subject</label> <input maxlength="100" type="text" name="subject" id="id_for_subject"></div>
  <div><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message"></div>
  <div><label for="id_for_sender">Sender</label> <input type="email" name="sender" id="id_for_sender"></div>
  <div><label for="id_for_ccMyself">Cc myself</label> <input type="checkbox" name="ccMyself" id="id_for_ccMyself"></div>
</div>
*/

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

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 provided default rendering, 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(<RenderForm form={f}/>))
/* =>
<div>
  <div><ul class="errorlist"><li>This field is required.</li></ul><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" value="Hi there"></div>
  <div><ul class="errorlist"><li>Enter a valid email address.</li></ul><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" value="invalid email address"></div>
  <div><label for="id_ccMyself">Cc myself:</label> <input type="checkbox" name="ccMyself" id="id_ccMyself" checked></div>
</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 <div className="errorlist">
      {this.messages().map(function(error) { return <div>{error}</div> })}
    </div>
  }
})

f = new ContactForm({data: data, errorConstructor: DivErrorList, autoId: false})
print(reactHTML(<RenderForm form={f}/>))
/* =>
<div>
  <div><div class="errorlist"><div>This field is required.</div></div>Subject: <input maxlength="100" type="text" name="subject"></div>
  <div>Message: <input type="text" name="message" value="Hi there"></div>
  <div><div class="errorlist"><div>Enter a valid email address.</div></div>Sender: <input type="email" name="sender" value="invalid email address"></div>
  <div>Cc myself: <input type="checkbox" name="ccMyself" checked></div>
</div>
*/

More granular output¶

To retrieve a single BoundField(), use the Form#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 Form#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>

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 the default rending components.

To render raw HTML in help text, specify it using the React convention for raw HTML, which is as an object with an __html property.

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.

widgetAttrs¶

The widgetAttrs argument lets you specify additional attributes for the field’s Widget without having to specify a new Widget from scratch using the widget argument.

This provides a more convenient way to add attributes like autoFocus, className or data- attributes to the field’s default Widget but has the lowest priority when determining final widget attributes.

For example, you can’t override an Input-based widget’s type attribute using widgetAttrs, as type is set in that widget’s render() method based on the specific widget constructor being used.

However, TextInput() treats the type attribute specially, to allow you to override the rendered type when creating an instance:

TextInput({attrs: {type: 'tel'}})

Or you can extend TextInput to create your own widget constructor:

var TelInput = TextInput.extend({
  inputType: 'tel'
})

Built-in Field type hierarchy¶

• Field
  • BaseTemporalField
    • DateField
    • DateTimeField
    • TimeField
  • BooleanField
    • NullBooleanField
  • CharField
    • EmailField
    • GenericIPAddressField
    • IPAddressField
    • RegexField
    • SlugField
    • URLField
  • ChoiceField
    • FilePathField
    • MultipleChoiceField
      • TypedMultipleChoiceField
    • TypedChoiceField
  • ComboField
  • IntegerField
    • DecimalField
    • FloatField
  • FileField
    • ImageField
    • MultipleFileField
  • MultiValueField
    • SplitDateTimeField

Build-in Fields (A-Z)¶

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:
  • Client: a native File object, when supported by the browser, otherwise the value of the <input type="file">.
  • Server: 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 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.

MultipleFileField()¶

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¶

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 forgot about Fred!')
    }
  }
}

Cleaning and validating fields that depend on each other¶

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

  clean: function() {
    var ccMyself = this.cleanedData.ccMyself
    var subject = this.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 = this.cleanedData.ccMyself
    var subject = this.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)
    }
  }
}