About this document

This document covers the gritty details of Django’s forms API. You shouldread theintroduction to working with formsfirst.

Bound and unbound forms¶

AForm instance is eitherbound to a set of data, orunbound.

• If it’sbound to a set of data, it’s capable of validating that dataand rendering the form as HTML with the data displayed in the HTML.
• If it’sunbound, it cannot do validation (because there’s no data tovalidate!), but it can still render the blank form as HTML.

classForm[source]¶

To create an unboundForm instance, simply instantiate the class:

>>>f=ContactForm()

To bind data to a form, pass the data as a dictionary as the first parameter toyourForm 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 theattributes in yourForm class. The values are the data you’re trying tovalidate. These will usually be strings, but there’s no requirement that they bestrings; the type of data you pass depends on theField, as we’ll seein a moment.

Form.is_bound¶

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

>>>f=ContactForm()>>>f.is_boundFalse>>>f=ContactForm({'subject':'hello'})>>>f.is_boundTrue

Note that passing an empty dictionary creates abound form with empty data:

>>>f=ContactForm({})>>>f.is_boundTrue

If you have a boundForm instance and want to change the data somehow,or if you want to bind an unboundForm instance to some data, createanotherForm instance. There is no way to change data in aForm instance. Once aForm instance has been created, youshould consider its data immutable, whether it has data or not.

Using forms to validate data¶

Form.clean()¶

Implement aclean() method on yourForm when you must add customvalidation for fields that are interdependent. SeeCleaning and validating fields that depend on each other for example usage.

Form.is_valid()¶

The primary task of aForm object is to validate data. With a boundForm instance, call theis_valid() method to run validationand return a boolean designating whether the data was valid:

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

Let’s try with some invalid data. In this case,subject is blank (an error,because all fields are required by default) andsender is not a validemail address:

>>>data={'subject':'',...'message':'Hi there',...'sender':'invalid email address',...'cc_myself':True}>>>f=ContactForm(data)>>>f.is_valid()False

Form.errors¶

Access theerrors attribute to get a dictionary of errormessages:

>>>f.errors{'sender': ['Enter a valid email address.'], 'subject': ['This field is required.']}

In this dictionary, the keys are the field names, and the values are lists ofUnicode strings representing the error messages. The error messages are storedin lists because a field can have multiple error messages.

You can accesserrors without having to callis_valid() first. The form’s data will be validated the first timeeither you callis_valid() or accesserrors.

The validation routines will only get called once, regardless of how many timesyou accesserrors or callis_valid(). This means thatif validation has side effects, those side effects will only be triggered once.

Form.errors.as_data()¶

Returns adict that maps fields to their originalValidationErrorinstances.

>>>f.errors.as_data(){'sender': [ValidationError(['Enter a valid email address.'])],'subject': [ValidationError(['This field is required.'])]}

Use this method anytime you need to identify an error by itscode. Thisenables things like rewriting the error’s message or writing custom logic in aview when a given error is present. It can also be used to serialize the errorsin a custom format (e.g. XML); for instance,as_json()relies onas_data().

The need for theas_data() method is due to backwards compatibility.PreviouslyValidationError instances were lost as soon as theirrendered error messages were added to theForm.errors dictionary.IdeallyForm.errors would have storedValidationError instancesand methods with anas_ prefix could render them, but it had to be donethe other way around in order not to break code that expects rendered errormessages inForm.errors.

Form.errors.as_json(escape_html=False)¶

Returns the errors serialized as JSON.

>>>f.errors.as_json(){"sender": [{"message": "Enter a valid email address.", "code": "invalid"}],"subject": [{"message": "This field is required.", "code": "required"}]}

By default,as_json() does not escape its output. If you are using it forsomething like AJAX requests to a form view where the client interprets theresponse and inserts errors into the page, you’ll want to be sure to escape theresults on the client-side to avoid the possibility of a cross-site scriptingattack. It’s trivial to do so using a JavaScript library like jQuery - simplyuse$(el).text(errorText) rather than.html().

If for some reason you don’t want to use client-side escaping, you can alsosetescape_html=True and error messages will be escaped so you can use themdirectly in HTML.

Form.add_error(field,error)¶

This method allows adding errors to specific fields from within theForm.clean() method, or from outside the form altogether; for instancefrom a view.

Thefield argument is the name of the field to which the errorsshould be added. If its value isNone the error will be treated asa non-field error as returned byForm.non_field_errors().

Theerror argument can be a simple string, or preferably an instance ofValidationError. SeeRaising ValidationError for best practiceswhen defining form errors.

Note thatForm.add_error() automatically removes the relevant field fromcleaned_data.

Form.has_error(field,code=None)¶

This method returns a boolean designating whether a field has an error witha specific errorcode. Ifcode isNone, it will returnTrueif the field contains any errors at all.

To check for non-field errors useNON_FIELD_ERRORS as thefield parameter.

Form.non_field_errors()¶

This method returns the list of errors fromForm.errors that aren’t associated with a particular field.This includesValidationErrors that are raised inForm.clean() and errors added usingForm.add_error(None,"...").

>>>f=ContactForm()>>>f.is_valid()False>>>f.errors{}

Dynamic initial values¶

Form.initial¶

Useinitial to declare the initial value of form fields atruntime. For example, you might want to fill in ausername field with theusername of the current session.

To accomplish this, use theinitial argument to aForm.This argument, if given, should be a dictionary mapping field names to initialvalues. Only include the fields for which you’re specifying an initial value;it’s not necessary to include every field in your form. For example:

>>>f=ContactForm(initial={'subject':'Hi there!'})

These values are only displayed for unbound forms, and they’re not used asfallback values if a particular value isn’t provided.

If aField definesinitialand youincludeinitial when instantiating theForm, then the latterinitial will have precedence. In this example,initial is provided bothat the field level and at the form instance level, and the latter getsprecedence:

>>>fromdjangoimportforms>>>classCommentForm(forms.Form):...name=forms.CharField(initial='class')...url=forms.URLField()...comment=forms.CharField()>>>f=CommentForm(initial={'name':'instance'},auto_id=False)>>>print(f)<tr><th>Name:</th><td><input type="text" name="name" value="instance" required /></td></tr><tr><th>Url:</th><td><input type="url" name="url" required /></td></tr><tr><th>Comment:</th><td><input type="text" name="comment" required /></td></tr>

Checking which form data has changed¶

Form.has_changed()¶

Use thehas_changed() method on yourForm when you need to check if theform data has been changed from the initial data.

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

When the form is submitted, we reconstruct it and provide the original dataso that the comparison can be done:

>>>f=ContactForm(request.POST,initial=data)>>>f.has_changed()

has_changed() will beTrue if the data fromrequest.POST differsfrom what was provided ininitial orFalse otherwise. Theresult is computed by callingField.has_changed() for each field in theform.

Form.changed_data¶

Thechanged_data attribute returns a list of the names of the fields whosevalues in the form’s bound data (usuallyrequest.POST) differ from what wasprovided ininitial. It returns an empty list if no data differs.

>>>f=ContactForm(request.POST,initial=data)>>>iff.has_changed():...print("The following fields changed:%s"%", ".join(f.changed_data))

Accessing the fields from the form¶

Form.fields¶

You can access the fields ofForm instance from itsfieldsattribute:

>>>forrowinf.fields.values():print(row)...<django.forms.fields.CharField object at 0x7ffaac632510><django.forms.fields.URLField object at 0x7ffaac632f90><django.forms.fields.CharField object at 0x7ffaac3aa050>>>>f.fields['name']<django.forms.fields.CharField object at 0x7ffaac6324d0>

You can alter the field ofForm instance to change the way it ispresented in the form:

>>>f.as_table().split('\n')[0]'<tr><th>Name:</th><td><input name="name" type="text" value="instance" required /></td></tr>'>>>f.fields['name'].label="Username">>>f.as_table().split('\n')[0]'<tr><th>Username:</th><td><input name="name" type="text" value="instance" required /></td></tr>'

Beware not to alter thebase_fields attribute because this modificationwill influence all subsequentContactForm instances within the same Pythonprocess:

>>>f.base_fields['name'].label="Username">>>another_f=CommentForm(auto_id=False)>>>another_f.as_table().split('\n')[0]'<tr><th>Username:</th><td><input name="name" type="text" value="class" required /></td></tr>'

Accessing “clean” data¶

Form.cleaned_data¶

Each field in aForm class is responsible not only for validatingdata, but also for “cleaning” it – normalizing it to a consistent format. Thisis a nice feature, because it allows data for a particular field to be input ina variety of ways, always resulting in consistent output.

For example,DateField normalizes input into aPythondatetime.date object. Regardless of whether you pass it a string inthe format'1994-07-15', adatetime.date object, or a number of otherformats,DateField will always normalize it to adatetime.date objectas long as it’s valid.

Once you’ve created aForm instance with a set of data and validatedit, you can access the clean data via itscleaned_data attribute:

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

Note that any text-based field – such asCharField orEmailField –always cleans the input into a Unicode string. We’ll cover the encodingimplications later in this document.

If your data doesnot validate, thecleaned_data dictionary containsonly the valid fields:

>>>data={'subject':'',...'message':'Hi there',...'sender':'invalid email address',...'cc_myself':True}>>>f=ContactForm(data)>>>f.is_valid()False>>>f.cleaned_data{'cc_myself': True, 'message': 'Hi there'}

cleaned_data will alwaysonly contain a key for fields defined in theForm, even if you pass extra data when you define theForm. In thisexample, we pass a bunch of extra fields to theContactForm constructor,butcleaned_data contains only the form’s fields:

>>>data={'subject':'hello',...'message':'Hi there',...'sender':'foo@example.com',...'cc_myself':True,...'extra_field_1':'foo',...'extra_field_2':'bar',...'extra_field_3':'baz'}>>>f=ContactForm(data)>>>f.is_valid()True>>>f.cleaned_data# Doesn't contain extra_field_1, etc.{'cc_myself': True, 'message': 'Hi there', 'sender': 'foo@example.com', 'subject': 'hello'}

When theForm is valid,cleaned_data will include a key and value forall its fields, even if the data didn’t include a value for some optionalfields. In this example, the data dictionary doesn’t include a value for thenick_name field, butcleaned_data includes it, with an empty value:

>>>fromdjangoimportforms>>>classOptionalPersonForm(forms.Form):...first_name=forms.CharField()...last_name=forms.CharField()...nick_name=forms.CharField(required=False)>>>data={'first_name':'John','last_name':'Lennon'}>>>f=OptionalPersonForm(data)>>>f.is_valid()True>>>f.cleaned_data{'nick_name': '', 'first_name': 'John', 'last_name': 'Lennon'}

In this above example, thecleaned_data value fornick_name is set to anempty string, becausenick_name isCharField, andCharFields treatempty values as an empty string. Each field type knows what its “blank” valueis – e.g., forDateField, it’sNone instead of the empty string. Forfull details on each field’s behavior in this case, see the “Empty value” notefor each field in the “Built-inField classes” section below.

You can write code to perform validation for particular form fields (based ontheir name) or for the form as a whole (considering combinations of variousfields). More information about this is inForm and field validation.

Outputting forms as HTML¶

The second task of aForm object is to render itself as HTML. To do so,simplyprint it:

>>>f=ContactForm()>>>print(f)<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr><tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr><tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr><tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>

If the form is bound to data, the HTML output will include that dataappropriately. For example, if a field is represented by an<inputtype="text">, the data will be in thevalue attribute. If afield is represented by an<inputtype="checkbox">, then that HTML willincludechecked="checked" if appropriate:

>>>data={'subject':'hello',...'message':'Hi there',...'sender':'foo@example.com',...'cc_myself':True}>>>f=ContactForm(data)>>>print(f)<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" required /></td></tr><tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" required /></td></tr><tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" value="foo@example.com" required /></td></tr><tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked="checked" /></td></tr>

This default output is a two-column HTML table, with a<tr> for each field.Notice the following:

• For flexibility, the output doesnot include the<table> and</table> tags, nor does it include the<form> and</form>tags or an<inputtype="submit"> tag. It’s your job to do that.
• Each field type has a default HTML representation.CharField isrepresented by an<inputtype="text"> andEmailField by an<inputtype="email">.BooleanField is represented by an<inputtype="checkbox">. Notethese are merely sensible defaults; you can specify which HTML to use fora given field by using widgets, which we’ll explain shortly.
• The HTMLname for each tag is taken directly from its attribute namein theContactForm class.
• The text label for each field – e.g.'Subject:','Message:' and'Ccmyself:' is generated from the field name by converting allunderscores to spaces and upper-casing the first letter. Again, notethese are merely sensible defaults; you can also specify labels manually.
• Each text label is surrounded in an HTML<label> tag, which pointsto the appropriate form field via itsid. Itsid, in turn, isgenerated by prepending'id_' to the field name. Theidattributes and<label> tags are included in the output by default, tofollow best practices, but you can change that behavior.

Although<table> output is the default output style when youprint aform, other output styles are available. Each style is available as a method ona form object, and each rendering method returns a Unicode object.

>>>f=ContactForm()>>>f.as_p()'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" required /></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>'>>>print(f.as_p())<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></p><p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></p><p><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></p><p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>

>>>f=ContactForm()>>>f.as_ul()'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></li>\n<li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>'>>>print(f.as_ul())<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" required /></li><li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" required /></li><li><label for="id_sender">Sender:</label> <input type="email" name="sender" id="id_sender" required /></li><li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>

>>>f=ContactForm()>>>f.as_table()'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>'>>>print(f)<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" required /></td></tr><tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" required /></td></tr><tr><th><label for="id_sender">Sender:</label></th><td><input type="email" name="sender" id="id_sender" required /></td></tr><tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>

fromdjangoimportformsclassContactForm(forms.Form):error_css_class='error'required_css_class='required'# ... and the rest of your fields here

>>>f=ContactForm(data)>>>print(f.as_table())<tr class="required"><th><label class="required" for="id_subject">Subject:</label>    ...<tr class="required"><th><label class="required" for="id_message">Message:</label>    ...<tr class="required error"><th><label class="required" for="id_sender">Sender:</label>      ...<tr><th><label for="id_cc_myself">Cc myself:<label> ...>>>f['subject'].label_tag()<label class="required" for="id_subject">Subject:</label>>>>f['subject'].label_tag(attrs={'class':'foo'})<label for="id_subject" class="foo required">Subject:</label>

>>>f=ContactForm(auto_id=False)>>>print(f.as_table())<tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" required /></td></tr><tr><th>Message:</th><td><input type="text" name="message" required /></td></tr><tr><th>Sender:</th><td><input type="email" name="sender" required /></td></tr><tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>>>>print(f.as_ul())<li>Subject: <input type="text" name="subject" maxlength="100" required /></li><li>Message: <input type="text" name="message" required /></li><li>Sender: <input type="email" name="sender" required /></li><li>Cc myself: <input type="checkbox" name="cc_myself" /></li>>>>print(f.as_p())<p>Subject: <input type="text" name="subject" maxlength="100" required /></p><p>Message: <input type="text" name="message" required /></p><p>Sender: <input type="email" name="sender" required /></p><p>Cc myself: <input type="checkbox" name="cc_myself" /></p>

>>>f=ContactForm(auto_id=True)>>>print(f.as_table())<tr><th><label for="subject">Subject:</label></th><td><input id="subject" type="text" name="subject" maxlength="100" required /></td></tr><tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" required /></td></tr><tr><th><label for="sender">Sender:</label></th><td><input type="email" name="sender" id="sender" required /></td></tr><tr><th><label for="cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="cc_myself" /></td></tr>>>>print(f.as_ul())<li><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" required /></li><li><label for="message">Message:</label> <input type="text" name="message" id="message" required /></li><li><label for="sender">Sender:</label> <input type="email" name="sender" id="sender" required /></li><li><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></li>>>>print(f.as_p())<p><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" required /></p><p><label for="message">Message:</label> <input type="text" name="message" id="message" required /></p><p><label for="sender">Sender:</label> <input type="email" name="sender" id="sender" required /></p><p><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></p>

>>>f=ContactForm(auto_id='id_for_%s')>>>print(f.as_table())<tr><th><label for="id_for_subject">Subject:</label></th><td><input id="id_for_subject" type="text" name="subject" maxlength="100" required /></td></tr><tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message" required /></td></tr><tr><th><label for="id_for_sender">Sender:</label></th><td><input type="email" name="sender" id="id_for_sender" required /></td></tr><tr><th><label for="id_for_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></td></tr>>>>print(f.as_ul())<li><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" required /></li><li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" required /></li><li><label for="id_for_sender">Sender:</label> <input type="email" name="sender" id="id_for_sender" required /></li><li><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>>>>print(f.as_p())<p><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" required /></p><p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" required /></p><p><label for="id_for_sender">Sender:</label> <input type="email" name="sender" id="id_for_sender" required /></p><p><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></p>

>>>f=ContactForm(auto_id='id_for_%s',label_suffix='')>>>print(f.as_ul())<li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" required /></li><li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" required /></li><li><label for="id_for_sender">Sender</label> <input type="email" name="sender" id="id_for_sender" required /></li><li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>>>>f=ContactForm(auto_id='id_for_%s',label_suffix=' ->')>>>print(f.as_ul())<li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" required /></li><li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" required /></li><li><label for="id_for_sender">Sender -></label> <input type="email" name="sender" id="id_for_sender" required /></li><li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>

>>>data={'subject':'',...'message':'Hi there',...'sender':'invalid email address',...'cc_myself':True}>>>f=ContactForm(data,auto_id=False)>>>print(f.as_table())<tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" required /></td></tr><tr><th>Message:</th><td><input type="text" name="message" value="Hi there" required /></td></tr><tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid email address.</li></ul><input type="email" name="sender" value="invalid email address" required /></td></tr><tr><th>Cc myself:</th><td><input checked="checked" type="checkbox" name="cc_myself" /></td></tr>>>>print(f.as_ul())<li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" required /></li><li>Message: <input type="text" name="message" value="Hi there" required /></li><li><ul class="errorlist"><li>Enter a valid email address.</li></ul>Sender: <input type="email" name="sender" value="invalid email address" required /></li><li>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></li>>>>print(f.as_p())<p><ul class="errorlist"><li>This field is required.</li></ul></p><p>Subject: <input type="text" name="subject" maxlength="100" required /></p><p>Message: <input type="text" name="message" value="Hi there" required /></p><p><ul class="errorlist"><li>Enter a valid email address.</li></ul></p><p>Sender: <input type="email" name="sender" value="invalid email address" required /></p><p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>

>>>fromdjango.forms.utilsimportErrorList>>>classDivErrorList(ErrorList):...def__str__(self):# __unicode__ on Python 2...returnself.as_divs()...defas_divs(self):...ifnotself:return''...return'<div class="errorlist">%s</div>'%''.join(['<div class="error">%s</div>'%eforeinself])>>>f=ContactForm(data,auto_id=False,error_class=DivErrorList)>>>f.as_p()<div class="errorlist"><div class="error">This field is required.</div></div><p>Subject: <input type="text" name="subject" maxlength="100" required /></p><p>Message: <input type="text" name="message" value="Hi there" required /></p><div class="errorlist"><div class="error">Enter a valid email address.</div></div><p>Sender: <input type="email" name="sender" value="invalid email address" required /></p><p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>

More granular output¶

Theas_p(),as_ul(), andas_table() methods are simply shortcuts –they’re not the only way a form object can be displayed.

classBoundField[source]¶

Used to display HTML or access attributes for a single field of aForm instance.

The__str__() (__unicode__ on Python 2) method of thisobject displays the HTML for this field.

To retrieve a singleBoundField, use dictionary lookup syntax on your formusing the field’s name as the key:

>>>form=ContactForm()>>>print(form['subject'])<input id="id_subject" type="text" name="subject" maxlength="100" required />

To retrieve allBoundField objects, iterate the form:

>>>form=ContactForm()>>>forboundfieldinform:print(boundfield)<input id="id_subject" type="text" name="subject" maxlength="100" required /><input type="text" name="message" id="id_message" required /><input type="email" name="sender" id="id_sender" required /><input type="checkbox" name="cc_myself" id="id_cc_myself" />

The field-specific output honors the form object’sauto_id setting:

>>>f=ContactForm(auto_id=False)>>>print(f['message'])<input type="text" name="message" required />>>>f=ContactForm(auto_id='id_%s')>>>print(f['message'])<input type="text" name="message" id="id_message" required />

CustomizingBoundField¶

If you need to access some additional information about a form field in atemplate and using a subclass ofField isn’tsufficient, consider also customizingBoundField.

A custom form field can overrideget_bound_field():

Field.get_bound_field(form,field_name)[source]¶

Takes an instance ofForm and the name of the field.The return value will be used when accessing the field in a template. Mostlikely it will be an instance of a subclass ofBoundField.

If you have aGPSCoordinatesField, for example, and want to be able toaccess additional information about the coordinates in a template, this couldbe implemented as follows:

classGPSCoordinatesBoundField(BoundField):@propertydefcountry(self):"""        Return the country the coordinates lie in or None if it can't be        determined.        """value=self.value()ifvalue:returnget_country_from_coordinates(value)else:returnNoneclassGPSCoordinatesField(Field):defget_bound_field(self,form,field_name):returnGPSCoordinatesBoundField(form,self,field_name)

Now you can access the country in a template with{{form.coordinates.country}}.

Binding uploaded files to a form¶

Dealing with forms that haveFileField andImageField fieldsis a little more complicated than a normal form.

Firstly, in order to upload files, you’ll need to make sure that your<form> element correctly defines theenctype as"multipart/form-data":

<formenctype="multipart/form-data"method="post"action="/foo/">

Secondly, when you use the form, you need to bind the file data. Filedata is handled separately to normal form data, so when your formcontains aFileField andImageField, you will need to specifya second argument when you bind your form. So if we extend ourContactForm to include anImageField calledmugshot, weneed to bind the file data containing the mugshot image:

# Bound form with an image field>>>fromdjango.core.files.uploadedfileimportSimpleUploadedFile>>>data={'subject':'hello',...'message':'Hi there',...'sender':'foo@example.com',...'cc_myself':True}>>>file_data={'mugshot':SimpleUploadedFile('face.jpg',<filedata>)}>>>f=ContactFormWithMugshot(data,file_data)

In practice, you will usually specifyrequest.FILES as the sourceof file data (just like you userequest.POST as the source ofform data):

# Bound form with an image field, data from the request>>>f=ContactFormWithMugshot(request.POST,request.FILES)

Constructing an unbound form is the same as always – just omit bothform dataand file data:

# Unbound form with an image field>>>f=ContactFormWithMugshot()

>>>f=ContactFormWithMugshot()>>>f.is_multipart()True

{%ifform.is_multipart%}<formenctype="multipart/form-data"method="post"action="/foo/">{%else%}<formmethod="post"action="/foo/">{%endif%}{{form}}</form>

Subclassing forms¶

If you have multipleForm classes that share fields, you can usesubclassing to remove redundancy.

When you subclass a customForm class, the resulting subclass willinclude all fields of the parent class(es), followed by the fields you definein the subclass.

In this example,ContactFormWithPriority contains all the fields fromContactForm, plus an additional field,priority. TheContactFormfields are ordered first:

>>>classContactFormWithPriority(ContactForm):...priority=forms.CharField()>>>f=ContactFormWithPriority(auto_id=False)>>>print(f.as_ul())<li>Subject: <input type="text" name="subject" maxlength="100" required /></li><li>Message: <input type="text" name="message" required /></li><li>Sender: <input type="email" name="sender" required /></li><li>Cc myself: <input type="checkbox" name="cc_myself" /></li><li>Priority: <input type="text" name="priority" required /></li>

It’s possible to subclass multiple forms, treating forms as mixins. In thisexample,BeatleForm subclasses bothPersonForm andInstrumentForm(in that order), and its field list includes the fields from the parentclasses:

>>>fromdjangoimportforms>>>classPersonForm(forms.Form):...first_name=forms.CharField()...last_name=forms.CharField()>>>classInstrumentForm(forms.Form):...instrument=forms.CharField()>>>classBeatleForm(InstrumentForm,PersonForm):...haircut_type=forms.CharField()>>>b=BeatleForm(auto_id=False)>>>print(b.as_ul())<li>First name: <input type="text" name="first_name" required /></li><li>Last name: <input type="text" name="last_name" required /></li><li>Instrument: <input type="text" name="instrument" required /></li><li>Haircut type: <input type="text" name="haircut_type" required /></li>

It’s possible to declaratively remove aField inherited from a parent classby setting the name of the field toNone on the subclass. For example:

>>>fromdjangoimportforms>>>classParentForm(forms.Form):...name=forms.CharField()...age=forms.IntegerField()>>>classChildForm(ParentForm):...name=None>>>ChildForm().fields.keys()...['age']

Prefixes for forms¶

Form.prefix¶

You can put several Django forms inside one<form> tag. To give eachForm its own namespace, use theprefix keyword argument:

>>>mother=PersonForm(prefix="mother")>>>father=PersonForm(prefix="father")>>>print(mother.as_ul())<li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" required /></li><li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" required /></li>>>>print(father.as_ul())<li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" required /></li><li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" required /></li>

The prefix can also be specified on the form class:

>>>classPersonForm(forms.Form):.........prefix='person'