NewForms

Since newforms is mostly undocumented at the moment this page summarizes some useful information. This documentation should be considered complementary to the documentation on ​http://www.djangoproject.com/documentation/newforms/. It's mostly information extracted from the ​unit tests for newforms at the moment.

Widgets ​Unit tests

Each Widget class corresponds to an HTML form widget. A Widget knows how to render itself, given a field name and some data. Widgets don't perform validation.

Widget types

List of widget types with their associated unit test for easy lookup.

TextInput ​Unit test

PasswordInput ​Unit test

HiddenInput ​Unit test

FileInput ​Unit test

Textarea ​Unit test

CheckBoxInput ​Unit test

Select ​Unit test

SelectMultiple ​Unit test

RadioSelect ​Unit test

CheckBoxSelectMultiple ​Unit test

Fields

Each Field class does some sort of validation. Each Field has a clean() method, which either raises django.newforms.ValidationError or returns the "clean" data -- usually a Unicode object, but, in some rare cases, a list.

Each Field's init() takes at least these parameters:

• required -- Boolean that specifies whether the field is required. True by default.
  
• widget -- A Widget class, or instance of a Widget class, that should be used for this Field when displaying it. Each Field has a
• default -- Widget that it'll use if you don't specify this. In most cases, the default widget is TextInput.
• label -- A verbose name for this field, for use in displaying this field in a form. By default, Django will use a "pretty" version of the form field name, if the Field is part of a Form.
• initial -- A value to use in this Field's initial display. This value is *not* used as a fallback if data isn't given.

Other than that, the Field subclasses have class-specific options for init(). For example, CharField has a max_length option.

Field types ​Unit tests

List of field types with their associated unit test for easy lookup.

CharField ​Unit test

Arguments:

• max_length -- (optional) Maximum number of characters
• min_length -- (optional) Minimum number of characters

IntegerField ​Unit test

Arguments:

• max_value -- (optional) Maximum value
• min_value -- (optional) Minimum value

DateField ​Unit test

Arguments:

• input_formats -- (optional) A list of strftime() input formats. These will override all other input formats

TimeField ​Unit test

DateTimeField ​Unit test

RegexField ​Unit test

Arguments:

• regex -- The regular expression in compiled or string form that the input should match

EmailField ​Unit test

Arguments:

• min_length -- Minimum length
• max_length -- Maximum length

URLField ​Unit test

BooleanField ​Unit test

Since html forms either return something like 'fieldname=on' in request.POST or request.GET, this value may not be set in form.clean_data.

Arguments:

• None

ChoiceField ​Unit test

Arguments:

• choices -- A list of (key, value) pairs

MultipleChoiceField ​Unit test

Arguments:

• choices -- A list of (key, value) pairs

ComboField ​Unit test

ComboField takes a list of fields that should be used to validate a value, in that order.

Arguments:

• choices -- A list of fields used to validate the input value

Forms ​Unit test

A Form is a collection of Fields. It knows how to validate a set of data and it knows how to render itself in a couple of default ways (e.g., an HTML table).

You can pass it data in init(), as a dictionary, this data will usually come from request.POST or request.GET. The dictionaries passed to form need not be complete, a partial or empty dictionary is valid too. If you don't pass any values to the Form's init(), or if you pass None, the Form won't do any validation. Form.errors will be an empty dictionary *but* Form.is_valid() will return False.