Working with forms

Working with forms

About this document

This document provides an introduction to the basics of web forms and howthey are handled in Django. For a more detailed look at specific areas ofthe forms API, see The Forms API, Form fields, andForm and field validation.

Unless you’re planning to build websites and applications that do nothing butpublish content, and don’t accept input from your visitors, you’re going toneed to understand and use forms.

Django provides a range of tools and libraries to help you build forms toaccept input from site visitors, and then process and respond to the input.

HTML forms

In HTML, a form is a collection of elements inside <form>…</form> thatallow a visitor to do things like enter text, select options, manipulateobjects or controls, and so on, and then send that information back to theserver.

Some of these form interface elements - text input or checkboxes - are builtinto HTML itself. Others are much more complex; an interface that pops up adate picker or allows you to move a slider or manipulate controls willtypically use JavaScript and CSS as well as HTML form <input> elements toachieve these effects.

As well as its <input> elements, a form must specify two things:

where: the URL to which the data corresponding to the user’s input shouldbe returned
how: the HTTP method the data should be returned byAs an example, the login form for the Django admin contains several<input> elements: one of type="text" for the username, one oftype="password" for the password, and one of type="submit" for the“Log in” button. It also contains some hidden text fields that the userdoesn’t see, which Django uses to determine what to do next.

It also tells the browser that the form data should be sent to the URLspecified in the <form>’s action attribute - /admin/ - and that itshould be sent using the HTTP mechanism specified by the method attribute -post.

When the <input type="submit" value="Log in"> element is triggered, thedata is returned to /admin/.

GET and POST

GET and POST are the only HTTP methods to use when dealing with forms.

Django’s login form is returned using the POST method, in which the browserbundles up the form data, encodes it for transmission, sends it to the server,and then receives back its response.

GET, by contrast, bundles the submitted data into a string, and uses thisto compose a URL. The URL contains the address where the data must be sent, aswell as the data keys and values. You can see this in action if you do a searchin the Django documentation, which will produce a URL of the formhttps://docs.djangoproject.com/search/?q=forms&release=1.

GET and POST are typically used for different purposes.

Any request that could be used to change the state of the system - for example,a request that makes changes in the database - should use POST. GETshould be used only for requests that do not affect the state of the system.

GET would also be unsuitable for a password form, because the passwordwould appear in the URL, and thus, also in browser history and server logs,all in plain text. Neither would it be suitable for large quantities of data,or for binary data, such as an image. A Web application that uses GETrequests for admin forms is a security risk: it can be easy for an attacker tomimic a form’s request to gain access to sensitive parts of the system.POST, coupled with other protections like Django’s CSRF protection offers more control over access.

On the other hand, GET is suitable for things like a web search form,because the URLs that represent a GET request can easily be bookmarked,shared, or resubmitted.

Django’s role in forms

Handling forms is a complex business. Consider Django’s admin, where numerousitems of data of several different types may need to be prepared for display ina form, rendered as HTML, edited using a convenient interface, returned to theserver, validated and cleaned up, and then saved or passed on for furtherprocessing.

Django’s form functionality can simplify and automate vast portions of thiswork, and can also do it more securely than most programmers would be able todo in code they wrote themselves.

Django handles three distinct parts of the work involved in forms:

preparing and restructuring data to make it ready for rendering
creating HTML forms for the data
receiving and processing submitted forms and data from the clientIt is possible to write code that does all of this manually, but Django cantake care of it all for you.

Forms in Django

We’ve described HTML forms briefly, but an HTML <form> is just one part ofthe machinery required.

In the context of a Web application, ‘form’ might refer to that HTML<form>, or to the Django Form that produces it, or to thestructured data returned when it is submitted, or to the end-to-end workingcollection of these parts.

The Django Form class

At the heart of this system of components is Django’s Form class. Inmuch the same way that a Django model describes the logical structure of anobject, its behavior, and the way its parts are represented to us, aForm class describes a form and determines how it works and appears.

In a similar way that a model class’s fields map to database fields, a formclass’s fields map to HTML form <input> elements. (A ModelFormmaps a model class’s fields to HTML form <input> elements via aForm; this is what the Django admin is based upon.)

A form’s fields are themselves classes; they manage form data and performvalidation when a form is submitted. A DateField and aFileField handle very different kinds of data and have to dodifferent things with it.

A form field is represented to a user in the browser as an HTML “widget” - apiece of user interface machinery. Each field type has an appropriate defaultWidget class, but these can be overridden asrequired.

Instantiating, processing, and rendering forms

When rendering an object in Django, we generally:

get hold of it in the view (fetch it from the database, for example)
pass it to the template context
expand it to HTML markup using template variablesRendering a form in a template involves nearly the same work as rendering anyother kind of object, but there are some key differences.

In the case of a model instance that contained no data, it would rarely if everbe useful to do anything with it in a template. On the other hand, it makesperfect sense to render an unpopulated form - that’s what we do when we wantthe user to populate it.

So when we handle a model instance in a view, we typically retrieve it from thedatabase. When we’re dealing with a form we typically instantiate it in theview.

When we instantiate a form, we can opt to leave it empty or pre-populate it, forexample with:

data from a saved model instance (as in the case of admin forms for editing)
data that we have collated from other sources
data received from a previous HTML form submissionThe last of these cases is the most interesting, because it’s what makes itpossible for users not just to read a website, but to send information backto it too.

Building a form

The work that needs to be done

Suppose you want to create a simple form on your website, in order to obtainthe user’s name. You’d need something like this in your template:

<form action="/your-name/" method="post">
    <label for="your_name">Your name: </label>
    <input id="your_name" type="text" name="your_name" value="{{ current_name }}">
    <input type="submit" value="OK">
</form>

This tells the browser to return the form data to the URL /your-name/, usingthe POST method. It will display a text field, labeled “Your name:”, and abutton marked “OK”. If the template context contains a current_namevariable, that will be used to pre-fill the your_name field.

You’ll need a view that renders the template containing the HTML form, andthat can supply the current_name field as appropriate.

When the form is submitted, the POST request which is sent to the serverwill contain the form data.

Now you’ll also need a view corresponding to that /your-name/ URL which willfind the appropriate key/value pairs in the request, and then process them.

This is a very simple form. In practice, a form might contain dozens orhundreds of fields, many of which might need to be pre-populated, and we mightexpect the user to work through the edit-submit cycle several times beforeconcluding the operation.

We might require some validation to occur in the browser, even before the formis submitted; we might want to use much more complex fields, that allow theuser to do things like pick dates from a calendar and so on.

At this point it’s much easier to get Django to do most of this work for us.

Building a form in Django

The Form class

We already know what we want our HTML form to look like. Our starting point forit in Django is this:

forms.py

from django import forms
 
class NameForm(forms.Form):
    your_name = forms.CharField(label='Your name', max_length=100)

This defines a Form class with a single field (your_name). We’veapplied a human-friendly label to the field, which will appear in the<label> when it’s rendered (although in this case, the labelwe specified is actually the same one that would be generated automatically ifwe had omitted it).

The field’s maximum allowable length is defined bymax_length. This does two things. It puts amaxlength="100" on the HTML <input> (so the browser should prevent theuser from entering more than that number of characters in the first place). Italso means that when Django receives the form back from the browser, it willvalidate the length of the data.

A Form instance has an is_valid() method, which runsvalidation routines for all its fields. When this method is called, if allfields contain valid data, it will:

return True
place the form’s data in its cleaned_data attribute.The whole form, when rendered for the first time, will look like:

<label for="your_name">Your name: </label>
<input id="your_name" type="text" name="your_name" maxlength="100" required>

Note that it does not include the <form> tags, or a submit button.We’ll have to provide those ourselves in the template.

The view

Form data sent back to a Django website is processed by a view, generally thesame view which published the form. This allows us to reuse some of the samelogic.

To handle the form we need to instantiate it in the view for the URL where wewant it to be published:

views.py

from django.http import HttpResponseRedirect
from django.shortcuts import render
 
from .forms import NameForm
 
def get_name(request):
    # if this is a POST request we need to process the form data
    if request.method == 'POST':
        # create a form instance and populate it with data from the request:
        form = NameForm(request.POST)
        # check whether it's valid:
        if form.is_valid():
            # process the data in form.cleaned_data as required
            # ...
            # redirect to a new URL:
            return HttpResponseRedirect('/thanks/')
 
    # if a GET (or any other method) we'll create a blank form
    else:
        form = NameForm()
 
    return render(request, 'name.html', {'form': form})

If we arrive at this view with a GET request, it will create an empty forminstance and place it in the template context to be rendered. This is what wecan expect to happen the first time we visit the URL.

If the form is submitted using a POST request, the view will once againcreate a form instance and populate it with data from the request: form =NameForm(request.POST) This is called “binding data to the form” (it is nowa bound form).

We call the form’s isvalid() method; if it’s not True, we go back tothe template with the form. This time the form is no longer empty (_unbound)so the HTML form will be populated with the data previously submitted, where itcan be edited and corrected as required.

If is_valid() is True, we’ll now be able to find all the validated formdata in its cleaned_data attribute. We can use this data to update thedatabase or do other processing before sending an HTTP redirect to the browsertelling it where to go next.

The template

We don’t need to do much in our name.html template:

<form action="/your-name/" method="post">
    {% csrf_token %}
    {{ form }}
    <input type="submit" value="Submit">
</form>

All the form’s fields and their attributes will be unpacked into HTML markupfrom that {{ form }} by Django’s template language.

Forms and Cross Site Request Forgery protection

Django ships with an easy-to-use protection against Cross Site RequestForgeries. When submitting a form via POST withCSRF protection enabled you must use the csrf_token template tagas in the preceding example. However, since CSRF protection is notdirectly tied to forms in templates, this tag is omitted from thefollowing examples in this document.

HTML5 input types and browser validation

If your form includes a URLField, anEmailField or any integer field type, Django willuse the url, email and number HTML5 input types. By default,browsers may apply their own validation on these fields, which may bestricter than Django’s validation. If you would like to disable thisbehavior, set the novalidate attribute on the form tag, or specifya different widget on the field, like TextInput.

We now have a working web form, described by a Django Form, processedby a view, and rendered as an HTML <form>.

That’s all you need to get started, but the forms framework puts a lot more atyour fingertips. Once you understand the basics of the process described above,you should be prepared to understand other features of the forms system andready to learn a bit more about the underlying machinery.

More about Django Form classes

All form classes are created as subclasses of either django.forms.Formor django.forms.ModelForm. You can think of ModelForm as asubclass of Form. Form and ModelForm actually inherit commonfunctionality from a (private) BaseForm class, but this implementationdetail is rarely important.

Models and Forms

In fact if your form is going to be used to directly add or edit a Djangomodel, a ModelForm can save you a greatdeal of time, effort, and code, because it will build a form, along with theappropriate fields and their attributes, from a Model class.

Bound and unbound form instances

The distinction between Bound and unbound forms is important:

An unbound form has no data associated with it. When rendered to the user,it will be empty or will contain default values.
A bound form has submitted data, and hence can be used to tell if that datais valid. If an invalid bound form is rendered, it can include inline errormessages telling the user what data to correct.The form’s is_bound attribute will tell you whether a form hasdata bound to it or not.

More on fields

Consider a more useful form than our minimal example above, which we could useto implement “contact me” functionality on a personal website:

forms.py

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

Our earlier form used a single field, your_name, a CharField. Inthis case, our form has four fields: subject, message, sender andcc_myself. CharField, EmailField andBooleanField are just three of the available field types; a full listcan be found in Form fields.

Widgets

Each form field has a corresponding Widget class,which in turn corresponds to an HTML form widget such as <inputtype="text">.

In most cases, the field will have a sensible default widget. For example, bydefault, a CharField will have a TextInput widget, thatproduces an <input type="text"> in the HTML. If you needed <textarea>instead, you’d specify the appropriate widget when defining your form field,as we have done for the message field.

Field data

Whatever the data submitted with a form, once it has been successfullyvalidated by calling is_valid() (and is_valid() has returned True),the validated form data will be in the form.cleaned_data dictionary. Thisdata will have been nicely converted into Python types for you.

Note

You can still access the unvalidated data directly from request.POST atthis point, but the validated data is better.

In the contact form example above, cc_myself will be a boolean value.Likewise, fields such as IntegerField and FloatField convertvalues to a Python int and float respectively.

Here’s how the form data could be processed in the view that handles this form:

views.py

from django.core.mail import send_mail
 
if form.is_valid():
    subject = form.cleaned_data['subject']
    message = form.cleaned_data['message']
    sender = form.cleaned_data['sender']
    cc_myself = form.cleaned_data['cc_myself']
 
    recipients = ['info@example.com']
    if cc_myself:
        recipients.append(sender)
 
    send_mail(subject, message, sender, recipients)
    return HttpResponseRedirect('/thanks/')

Tip

For more on sending email from Django, see Sending email.

Some field types need some extra handling. For example, files that are uploadedusing a form need to be handled differently (they can be retrieved fromrequest.FILES, rather than request.POST). For details of how to handlefile uploads with your form, see Binding uploaded files to a form.

Working with form templates

All you need to do to get your form into a template is to place the forminstance into the template context. So if your form is called form in thecontext, {{ form }} will render its <label> and <input> elementsappropriately.

Form rendering options

Additional form template furniture

Don’t forget that a form’s output does not include the surrounding<form> tags, or the form’s submit control. You will have to providethese yourself.

There are other output options though for the <label>/<input> pairs:

{{ form.as_table }} will render them as table cells wrapped in <tr>tags
{{ form.as_p }} will render them wrapped in <p> tags
{{ form.as_ul }} will render them wrapped in <li> tagsNote that you’ll have to provide the surrounding <table> or <ul>elements yourself.

Here’s the output of {{ form.as_p }} for our ContactForm instance:

<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>
    <textarea name="message" id="id_message" required></textarea></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>

Note that each form field has an ID attribute set to id_<field-name>, whichis referenced by the accompanying label tag. This is important in ensuring thatforms are accessible to assistive technology such as screen reader software.You can also customize the way in which labels and ids are generated.

See Outputting forms as HTML for more on this.

Rendering fields manually

We don’t have to let Django unpack the form’s fields; we can do it manually ifwe like (allowing us to reorder the fields, for example). Each field isavailable as an attribute of the form using {{ form.name_of_field }}, andin a Django template, will be rendered appropriately. For example:

{{ form.non_field_errors }}
<div class="fieldWrapper">
    {{ form.subject.errors }}
    <label for="{{ form.subject.id_for_label }}">Email subject:</label>
    {{ form.subject }}
</div>
<div class="fieldWrapper">
    {{ form.message.errors }}
    <label for="{{ form.message.id_for_label }}">Your message:</label>
    {{ form.message }}
</div>
<div class="fieldWrapper">
    {{ form.sender.errors }}
    <label for="{{ form.sender.id_for_label }}">Your email address:</label>
    {{ form.sender }}
</div>
<div class="fieldWrapper">
    {{ form.cc_myself.errors }}
    <label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>
    {{ form.cc_myself }}
</div>

Complete <label> elements can also be generated using thelabel_tag(). For example:

<div class="fieldWrapper">
    {{ form.subject.errors }}
    {{ form.subject.label_tag }}
    {{ form.subject }}
</div>

Rendering form error messages

Of course, the price of this flexibility is more work. Until now we haven’t hadto worry about how to display form errors, because that’s taken care of for us.In this example we have had to make sure we take care of any errors for eachfield and any errors for the form as a whole. Note {{ form.non_field_errors}} at the top of the form and the template lookup for errors on each field.

Using {{ form.name_of_field.errors }} displays a list of form errors,rendered as an unordered list. This might look like:

<ul class="errorlist">
    <li>Sender is required.</li>
</ul>

The list has a CSS class of errorlist to allow you to style its appearance.If you wish to further customize the display of errors you can do so by loopingover them:

{% if form.subject.errors %}
    <ol>
    {% for error in form.subject.errors %}
        <li><strong>{{ error|escape }}</strong></li>
    {% endfor %}
    </ol>
{% endif %}

Non-field errors (and/or hidden field errors that are rendered at the top ofthe form when using helpers like form.as_p()) will be rendered with anadditional class of nonfield to help distinguish them from field-specificerrors. For example, {{ form.non_field_errors }} would look like:

<ul class="errorlist nonfield">
    <li>Generic validation error</li>
</ul>

See The Forms API for more on errors, styling, and working with formattributes in templates.

Looping over the form’s fields

If you’re using the same HTML for each of your form fields, you can reduceduplicate code by looping through each field in turn using a {% for %}loop:

{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
        {% if field.help_text %}
        <p class="help">{{ field.help_text|safe }}</p>
        {% endif %}
    </div>
{% endfor %}

Useful attributes on {{ field }} include:

{{ field.label }}
The label of the field, e.g. Email address.
{{ field.label_tag }}
The field’s label wrapped in the appropriate HTML <label> tag. Thisincludes the form’s label_suffix. For example,the default label_suffix is a colon:

<label for="id_email">Email address:</label>

{{ field.id_for_label }}
The ID that will be used for this field (id_email in the exampleabove). If you are constructing the label manually, you may want to usethis in lieu of label_tag. It’s also useful, for example, if you havesome inline JavaScript and want to avoid hardcoding the field’s ID.
{{ field.value }}
The value of the field. e.g someone@example.com.
{{ field.html_name }}
The name of the field that will be used in the input element’s namefield. This takes the form prefix into account, if it has been set.
{{ field.help_text }}
Any help text that has been associated with the field.
{{ field.errors }}
Outputs a <ul class="errorlist"> containing any validation errorscorresponding to this field. You can customize the presentation ofthe errors with a {% for error in field.errors %} loop. In thiscase, each object in the loop is a string containing the error message.
{{ field.is_hidden }}
This attribute is True if the form field is a hidden field andFalse otherwise. It’s not particularly useful as a templatevariable, but could be useful in conditional tests such as:

{% if field.is_hidden %}
   {# Do something special #}
{% endif %}

{{ field.field }}
The Field instance from the form class thatthis BoundField wraps. You can use it to accessField attributes, e.g.{{ char_field.field.max_length }}.

Looping over hidden and visible fields

If you’re manually laying out a form in a template, as opposed to relying onDjango’s default form layout, you might want to treat <input type="hidden">fields differently from non-hidden fields. For example, because hidden fieldsdon’t display anything, putting error messages “next to” the field could causeconfusion for your users – so errors for those fields should be handleddifferently.

Django provides two methods on a form that allow you to loop over the hiddenand visible fields independently: hidden_fields() andvisible_fields(). Here’s a modification of an earlier example that usesthese two methods:

{# Include the hidden fields #}
{% for hidden in form.hidden_fields %}
{{ hidden }}
{% endfor %}
{# Include the visible fields #}
{% for field in form.visible_fields %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}

This example does not handle any errors in the hidden fields. Usually, anerror in a hidden field is a sign of form tampering, since normal forminteraction won’t alter them. However, you could easily insert some errordisplays for those form errors, as well.

Reusable form templates

If your site uses the same rendering logic for forms in multiple places, youcan reduce duplication by saving the form’s loop in a standalone template andusing the include tag to reuse it in other templates:

# In your form template:
{% include "form_snippet.html" %}
 
# In form_snippet.html:
{% for field in form %}
    <div class="fieldWrapper">
        {{ field.errors }}
        {{ field.label_tag }} {{ field }}
    </div>
{% endfor %}

If the form object passed to a template has a different name within thecontext, you can alias it using the with argument of the includetag:

{% include "form_snippet.html" with form=comment_form %}

If you find yourself doing this often, you might consider creating a custominclusion tag.

Further topics

This covers the basics, but forms can do a whole lot more: