GET andPOST¶

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

Django’s login form is returned using thePOST 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 andPOST 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 usePOST.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 usesGETrequests 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’sCSRF 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 aGET request can easily be bookmarked,shared, or resubmitted.

The DjangoForm class¶

At the heart of this system of components is Django’sForm 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. (AModelFormmaps 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. ADateField 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:

1. get hold of it in the view (fetch it from the database, for example)
2. pass it to the template context
3. expand it to HTML markup using template variables

Rendering 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 submission

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

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:

<formaction="/your-name/"method="post"><labelfor="your_name">Your name:</label><inputid="your_name"type="text"name="your_name"value="{{current_name}}"><inputtype="submit"value="OK"></form>

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

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

When the form is submitted, thePOST 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¶

fromdjangoimportformsclassNameForm(forms.Form):your_name=forms.CharField(label='Your name',max_length=100)

<labelfor="your_name">Your name:</label><inputid="your_name"type="text"name="your_name"maxlength="100"required/>

fromdjango.shortcutsimportrenderfromdjango.httpimportHttpResponseRedirectfrom.formsimportNameFormdefget_name(request):# if this is a POST request we need to process the form dataifrequest.method=='POST':# create a form instance and populate it with data from the request:form=NameForm(request.POST)# check whether it's valid:ifform.is_valid():# process the data in form.cleaned_data as required# ...# redirect to a new URL:returnHttpResponseRedirect('/thanks/')# if a GET (or any other method) we'll create a blank formelse:form=NameForm()returnrender(request,'name.html',{'form':form})

<formaction="/your-name/"method="post">{%csrf_token%}{{form}}<inputtype="submit"value="Submit"/></form>

Models and Forms

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

Bound and unbound form instances¶

The distinction betweenBound 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’sis_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:

fromdjangoimportformsclassContactForm(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, aCharField. 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 inForm fields.

fromdjango.core.mailimportsend_mailifform.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']ifcc_myself:recipients.append(sender)send_mail(subject,message,sender,recipients)returnHttpResponseRedirect('/thanks/')

Form rendering options¶

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

Note that you’ll have to provide the surrounding<table> or<ul>elements yourself.

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

<p><labelfor="id_subject">Subject:</label><inputid="id_subject"type="text"name="subject"maxlength="100"required/></p><p><labelfor="id_message">Message:</label><textareaname="message"id="id_message"required></textarea></p><p><labelfor="id_sender">Sender:</label><inputtype="email"name="sender"id="id_sender"required/></p><p><labelfor="id_cc_myself">Cc myself:</label><inputtype="checkbox"name="cc_myself"id="id_cc_myself"/></p>

Note that each form field has an ID attribute set toid_<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 alsocustomize the way in which labels and ids are generated.

SeeOutputting 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}}<divclass="fieldWrapper">{{form.subject.errors}}<labelfor="{{form.subject.id_for_label}}">Email subject:</label>{{form.subject}}</div><divclass="fieldWrapper">{{form.message.errors}}<labelfor="{{form.message.id_for_label}}">Your message:</label>{{form.message}}</div><divclass="fieldWrapper">{{form.sender.errors}}<labelfor="{{form.sender.id_for_label}}">Your email address:</label>{{form.sender}}</div><divclass="fieldWrapper">{{form.cc_myself.errors}}<labelfor="{{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:

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

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

{%ifform.subject.errors%}<ol>{%forerrorinform.subject.errors%}<li><strong>{{error|escape}}</strong></li>{%endfor%}</ol>{%endif%}

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

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:

{%forfieldinform%}<divclass="fieldWrapper">{{field.errors}}{{field.label_tag}}{{field}}{%iffield.help_text%}<pclass="help">{{field.help_text|safe}}</p>{%endif%}</div>{%endfor%}

Useful attributes on{{field}} include:

{{field.label}}

The label of the field, e.g.Emailaddress.

{{field.label_tag}}

The field’s label wrapped in the appropriate HTML<label> tag. Thisincludes the form’slabel_suffix. For example,the defaultlabel_suffix is a colon:

<labelfor="id_email">Emailaddress:</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 oflabel_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.gsomeone@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<ulclass="errorlist"> containing any validation errorscorresponding to this field. You can customize the presentation ofthe errors with a{%forerrorinfield.errors%} loop. In thiscase, each object in the loop is a simple string containing the errormessage.

{{field.is_hidden}}

This attribute isTrue 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:

{%iffield.is_hidden%}{# Do something special #}{%endif%}

{{field.field}}

TheField instance from the form class thatthisBoundField wraps. You can use it to accessField attributes, e.g.{{char_field.field.max_length}}.

{# Include the hidden fields #}{%forhiddeninform.hidden_fields%}{{hidden}}{%endfor%}{# Include the visible fields #}{%forfieldinform.visible_fields%}<divclass="fieldWrapper">{{field.errors}}{{field.label_tag}}{{field}}</div>{%endfor%}

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 theinclude tag to reuse it in other templates:

# In your form template:{%include"form_snippet.html"%}# In form_snippet.html:{%forfieldinform%}<divclass="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 thewith argument of theincludetag:

{%include"form_snippet.html"withform=comment_form%}

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

• Formsets
  • Using initial data with a formset
  • Limiting the maximum number of forms
  • Formset validation
  • Validating the number of forms in a formset
  • Dealing with ordering and deletion of forms
  • Adding additional fields to a formset
  • Passing custom parameters to formset forms
  • Using a formset in views and templates
• Creating forms from models
  • ModelForm
  • Model formsets
  • Inline formsets
• Form Assets (theMedia class)
  • Assets as a static definition
  • Media as a dynamic property
  • Paths in asset definitions
  • Media objects
  • Media on Forms

See also

The Forms Reference

Covers the full API reference, including form fields, form widgets,and form and field validation.