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 subclass 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

MultipleHiddenInput ​Unit test

FileInput ​Unit test

Textarea ​Unit test

CheckboxInput ​Unit test

Select ​Unit test

NullBooleanSelect ​Unit test

SelectMultiple ​Unit test

RadioSelect ​Unit test

CheckboxSelectMultiple ​Unit test

Multi ​Unit test

SplitDateTime ​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

FloatField ​Unit test

DecimalField ​Unit test

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

Arguments:

• min_length -- Minimum length
• max_length -- Maximum length
• verify_exists -- Defaults to False. If True, verifies that the URL is live on the Internet and doesn't return a 404 or 500

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

SplitDateTimeField ​Unit test

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.