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.
Trueby 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.