Django Forms

Start with this basic Form subclass, which we’ll call ContactForm:

from django import newforms as forms

class ContactForm(forms.Form):
subject = forms.CharField(max_length=100)
message = forms.CharField()
sender = forms.EmailField()
cc_myself = forms.BooleanField(required=False)

A form is composed of Field objects.

Creating Form instances

A Form instance is either bound to a set of data, or unbound.

* If it’s bound to a set of data, it’s capable of validating that data and rendering the form as HTML with the data displayed in the HTML.
* If it’s unbound, it cannot do validation but it can still render the blank form as HTML.

To create an unbound Form instance, simply instantiate the class:

>>> f = ContactForm()

To bind data to a form, pass the data as a dictionary as the first parameter to your Form class constructor:

>>> data = {'subject': 'hello',
... 'message': 'Hi there',
... 'sender': 'foo@example.com',
... 'cc_myself': True}
>>> f = ContactForm(data)

In this dictionary, the keys are the field names, which correspond to the attributes in your Form class. The values are the data you’re trying to validate. These will usually be strings, but there’s no requirement that they be strings; the type of data you pass depends on the Field, as we’ll see in a moment.

If you need to distinguish between bound and unbound form instances at runtime, check the value of the form’s is_bound attribute:

>>> f = ContactForm()
>>> f.is_bound
False
>>> f = ContactForm({'subject': 'hello'})
>>> f.is_bound
True

Note that passing an empty dictionary creates a bound form with empty data:

>>> f = ContactForm({})
>>> f.is_bound
True

If you have a bound Form instance and want to change the data somehow, or if you want to bind an unbound Form instance to some data, create another Form instance. There is no way to change data in a Form instance. Once a Form instance has been created, you should consider its data immutable, whether it has data or not.


1) The primary task of a Form object is to validate data. With a bound Form instance, call the is_valid() method to run validation and return a boolean designating whether the data was valid:
2) Each Field in a Form class is responsible not only for validating data, but also for “cleaning” it — normalizing it to a consistent format.

f.errors
In this dictionary, the keys are the field names, and the values are lists of Unicode strings representing the error messages. The error messages are stored in lists because a field can have multiple error messages.

f.cleaned_data
If your data does not validate, your Form instance will not have a cleaned_data attribute:

cleaned_data will always only contain a key for fields defined in the Form, even if you pass extra data when you define the Form. In this example, we pass a bunch of extra fields to the ContactForm constructor, but cleaned_data contains only the form’s fields:

print f

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

The validation routines will only get called once, regardless of how many times you access errors or call is_valid()

Each field type has a default HTML representation. CharField and EmailField are represented by an . BooleanField is represented by an . Note these are merely sensible defaults; you can specify which HTML to use for a given field by using widgets

Use the auto_id argument to the Form constructor to control the label and id behavior. This argument must be True, False or a string.
If auto_id is False, then the form output will not include tags nor id attributes: f = ContactForm(auto_id=False)

To reorder the HTML output, just change the order in which those fields are listed in the class.

By default, forms use django.newforms.util.ErrorList to format validation errors. If you’d like to use an alternate class for displaying errors, you can pass that in at construction time:

>>> from django.newforms.util import ErrorList
>>> class DivErrorList(ErrorList):
... def __unicode__(self):
... return self.as_divs()
... def as_divs(self):
... if not self: return u''
... return u'

%s

' % ''.join([u'

%s

' % e for e in self])
>>> f = ContactForm(data, auto_id=False, error_class=DivErrorList)

>>> str(f['subject'])
''
>>> unicode(f['subject'])
u''

For a field’s list of errors, access the field’s errors attribute. This is a list-like object that is displayed as an HTML

when printed:


Subclassing forms

If you have multiple Form classes that share fields, you can use subclassing to remove redundancy.

When you subclass a custom Form class, the resulting subclass will include all fields of the parent class(es), followed by the fields you define in the subclass.

In this example, ContactFormWithPriority contains all the fields from ContactForm, plus an additional field, priority. The ContactForm fields are ordered first:

>>> class ContactFormWithPriority(ContactForm):
... priority = forms.CharField()
>>> f = ContactFormWithPriority(auto_id=False)

It’s possible to subclass multiple forms, treating forms as “mix-ins.” In this example, BeatleForm subclasses both PersonForm and InstrumentForm (in that order), and its field list includes the fields from the parent classes:

>>> class PersonForm(Form):
... first_name = CharField()
... last_name = CharField()
>>> class InstrumentForm(Form):
... instrument = CharField()
>>> class BeatleForm(PersonForm, InstrumentForm):
... haircut_type = CharField()
>>> b = BeatleForm(auto_id=False)

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.

As explained in “Outputting forms as HTML” above, the default label for a Field is generated from the field name by converting all underscores to spaces and upper-casing the first letter. Specify label if that default behavior doesn’t result in an adequate label.

The error_messages argument lets you override the default messages that the field will raise. Pass in a dictionary with keys matching the error messages you want to override.
name = forms.CharField(error_messages={'required': 'Please enter your name'})

In general, any cleaning method can raise ValidationError if there is a problem with the data it is processing, passing the relevant error message to the ValidationError constructor. If no ValidationError is raised, the method should return the cleaned (normalised) data as a Python object.

A widget is Django’s representation of a HTML input element. The widget handles the rendering of the HTML, and the extraction of data from a GET/POST dictionary that corresponds to the widget.

Django provides a representation of all the basic HTML widgets, plus some commonly used groups of widgets:
Whenever you specify a field on a form, Django will use a default widget that is appropriate to the type of data that is to be displayed.

However, if you want to use a different widget for a field, you can - just use the ‘widget’ argument on the field definition. For example:

class CommentForm(forms.Form):
name = forms.CharField()
url = forms.URLField()
comment = forms.CharField(widget=forms.Textarea)

This would specify a form with a comment that uses a larger Textarea widget, rather than the default TextInput widget

If you want to make one widget look different to another, you need to specify additional attributes for each widget. When you specify a widget, you can provide a list of attributes that will be added to the rendered HTML for the widget.

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

Django will then include the extra attributes in the rendered output:


Custom Widgets

When you start to write a lot of forms, you will probably find that you will reuse certain sets of widget attributes over and over again. Rather than repeat these attribute definitions every time you need them, Django allows you to capture those definitions as a custom widget.

For example, if you find that you are including a lot of comment fields on forms, you could capture the idea of a TextInput with a specific size attribute as a custom extension to the TextInput widget:

class CommentWidget(forms.TextInput):
def __init__(self, *args, **kwargs):
kwargs.setdefault('attrs',{}).update({'size': '40'})
super(CommentWidget, self).__init__(*args, **kwargs)

Then you can use this widget in your forms:

class CommentForm(forms.Form):
name = forms.CharField()
url = forms.URLField()
comment = forms.CharField(widget=CommentWidget)

You can even customize your custom widget, in the same way as you would any other widget. Adding a once-off class to your CommentWidget is as simple as adding an attribute definition:

class CommentForm(forms.Form):
name = forms.CharField(max_length=20)
url = forms.URLField()
comment = forms.CharField(
widget=CommentWidget(attrs={'class': 'special'}))

Django also makes it easy to specify a custom field type that uses your custom widget. For example, you could define a customized field type for comments by defining:

class CommentInput(forms.CharField):
widget = CommentWidget

You can then use this field whenever you have a form that requires a comment:

class CommentForm(forms.Form):
name = forms.CharField()
url = forms.URLField()
comment = CommentInput()



initial

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

The use-case for this is when you want to display an “empty” form in which a field is initialized to a particular value.

The widget argument lets you specify a Widget class to use when rendering this Field.