Unless you’re planning to build websites and applications that do nothing but\npublish content, and don’t accept input from your visitors, you’re going to\nneed to understand and use forms.
\nDjango provides a range of tools and libraries to help you build forms to\naccept input from site visitors, and then process and respond to the input.
\nIn HTML, a form is a collection of elements inside <form>...</form> that\nallow a visitor to do things like enter text, select options, manipulate\nobjects or controls, and so on, and then send that information back to the\nserver.
Some of these form interface elements - text input or checkboxes - are built\ninto HTML itself. Others are much more complex; an interface that pops up a\ndate picker or allows you to move a slider or manipulate controls will\ntypically use JavaScript and CSS as well as HTML form <input> elements to\nachieve 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 should\nbe returned
how: the HTTP method the data should be returned by
As an example, the login form for the Django admin contains several\n<input> elements: one of type="text" for the username, one of\ntype="password" for the password, and one of type="submit" for the\n«Log in» button. It also contains some hidden text fields that the user\ndoesn’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 URL\nspecified in the <form>’s action attribute - /admin/ - and that it\nshould be sent using the HTTP mechanism specified by the method attribute -\npost.
When the <input type="submit" value="Log in"> element is triggered, the\ndata is returned to /admin/.
GET and POSTLink to this heading#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 browser\nbundles up the form data, encodes it for transmission, sends it to the server,\nand then receives back its response.
GET, by contrast, bundles the submitted data into a string, and uses this\nto compose a URL. The URL contains the address where the data must be sent, as\nwell as the data keys and values. You can see this in action if you do a search\nin the Django documentation, which will produce a URL of the form\nhttps://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,\na request that makes changes in the database - should use POST. GET\nshould 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 password\nwould appear in the URL, and thus, also in browser history and server logs,\nall in plain text. Neither would it be suitable for large quantities of data,\nor for binary data, such as an image. A web application that uses GET\nrequests for admin forms is a security risk: it can be easy for an attacker to\nmimic a form’s request to gain access to sensitive parts of the system.\nPOST, 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,\nbecause the URLs that represent a GET request can easily be bookmarked,\nshared, or resubmitted.
Handling forms is a complex business. Consider Django’s admin, where numerous\nitems of data of several different types may need to be prepared for display in\na form, rendered as HTML, edited using a convenient interface, returned to the\nserver, validated and cleaned up, and then saved or passed on for further\nprocessing.
\nDjango’s form functionality can simplify and automate vast portions of this\nwork, and can also do it more securely than most programmers would be able to\ndo in code they wrote themselves.
\nDjango handles three distinct parts of the work involved in forms:
\npreparing and restructuring data to make it ready for rendering
creating HTML forms for the data
receiving and processing submitted forms and data from the client
It is possible to write code that does all of this manually, but Django can\ntake care of it all for you.
\nWe’ve described HTML forms briefly, but an HTML <form> is just one part of\nthe machinery required.
In the context of a web application, “form” might refer to that HTML\n<form>, or to the Django Form that produces it, or to the\nstructured data returned when it is submitted, or to the end-to-end working\ncollection of these parts.
Form classLink to this heading#At the heart of this system of components is Django’s Form class. In\nmuch the same way that a Django model describes the logical structure of an\nobject, its behavior, and the way its parts are represented to us, a\nForm 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 form\nclass’s fields map to HTML form <input> elements. (A ModelForm\nmaps a model class’s fields to HTML form <input> elements via a\nForm; this is what the Django admin is based upon.)
A form’s fields are themselves classes; they manage form data and perform\nvalidation when a form is submitted. A DateField and a\nFileField handle very different kinds of data and have to do\ndifferent things with it.
A form field is represented to a user in the browser as an HTML «widget» - a\npiece of user interface machinery. Each field type has an appropriate default\nWidget class, but these can be overridden as\nrequired.
\nWhen rendering an object in Django, we generally:
\nget 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 variables
Rendering a form in a template involves nearly the same work as rendering any\nother kind of object, but there are some key differences.
\nIn the case of a model instance that contained no data, it would rarely if ever\nbe useful to do anything with it in a template. On the other hand, it makes\nperfect sense to render an unpopulated form - that’s what we do when we want\nthe user to populate it.
\nSo when we handle a model instance in a view, we typically retrieve it from the\ndatabase. When we’re dealing with a form we typically instantiate it in the\nview.
\nWhen we instantiate a form, we can opt to leave it empty or prepopulate it, for\nexample with:
\ndata 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 it\npossible for users not just to read a website, but to send information back\nto it too.
\nSuppose you want to create a simple form on your website, in order to obtain\nthe user’s name. You’d need something like this in your template:
\n<form action="/your-name/" method="post">\n <label for="your_name">Your name: </label>\n <input id="your_name" type="text" name="your_name" value="{{ current_name }}">\n <input type="submit" value="OK">\n</form>\nThis tells the browser to return the form data to the URL /your-name/, using\nthe POST method. It will display a text field, labeled «Your name:», and a\nbutton marked «OK». If the template context contains a current_name\nvariable, that will be used to pre-fill the your_name field.
You’ll need a view that renders the template containing the HTML form, and\nthat can supply the current_name field as appropriate.
When the form is submitted, the POST request which is sent to the server\nwill contain the form data.
Now you’ll also need a view corresponding to that /your-name/ URL which will\nfind 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 or\nhundreds of fields, many of which might need to be prepopulated, and we might\nexpect the user to work through the edit-submit cycle several times before\nconcluding the operation.
\nWe might require some validation to occur in the browser, even before the form\nis submitted; we might want to use much more complex fields, that allow the\nuser to do things like pick dates from a calendar and so on.
\nAt this point it’s much easier to get Django to do most of this work for us.
\nForm classLink to this heading#We already know what we want our HTML form to look like. Our starting point for\nit in Django is this:
\nforms.pyfrom django import forms\n\nclass NameForm(forms.Form):\n your_name = forms.CharField(label='Your name', max_length=100)\nThis defines a Form class with a single field (your_name). We’ve\napplied a human-friendly label to the field, which will appear in the\n<label> when it’s rendered (although in this case, the label\nwe specified is actually the same one that would be generated automatically if\nwe had omitted it).
The field’s maximum allowable length is defined by\nmax_length. This does two things. It puts a\nmaxlength="100" on the HTML <input> (so the browser should prevent the\nuser from entering more than that number of characters in the first place). It\nalso means that when Django receives the form back from the browser, it will\nvalidate the length of the data.
A Form instance has an is_valid() method, which runs\nvalidation routines for all its fields. When this method is called, if all\nfields 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:
\n<label for="your_name">Your name: </label>\n<input id="your_name" type="text" name="your_name" maxlength="100" required>\nNote that it does not include the <form> tags, or a submit button.\nWe’ll have to provide those ourselves in the template.
Form data sent back to a Django website is processed by a view, generally the\nsame view which published the form. This allows us to reuse some of the same\nlogic.
\nTo handle the form we need to instantiate it in the view for the URL where we\nwant it to be published:
\nviews.pyfrom django.http import HttpResponseRedirect\nfrom django.shortcuts import render\n\nfrom .forms import NameForm\n\ndef get_name(request):\n # if this is a POST request we need to process the form data\n if request.method == 'POST':\n # create a form instance and populate it with data from the request:\n form = NameForm(request.POST)\n # check whether it's valid:\n if form.is_valid():\n # process the data in form.cleaned_data as required\n # ...\n # redirect to a new URL:\n return HttpResponseRedirect('/thanks/')\n\n # if a GET (or any other method) we'll create a blank form\n else:\n form = NameForm()\n\n return render(request, 'name.html', {'form': form})\nIf we arrive at this view with a GET request, it will create an empty form\ninstance and place it in the template context to be rendered. This is what we\ncan expect to happen the first time we visit the URL.
If the form is submitted using a POST request, the view will once again\ncreate a form instance and populate it with data from the request: form =\nNameForm(request.POST) This is called «binding data to the form» (it is now\na bound form).
We call the form’s is_valid() method; if it’s not True, we go back to\nthe template with the form. This time the form is no longer empty (unbound)\nso the HTML form will be populated with the data previously submitted, where it\ncan be edited and corrected as required.
If is_valid() is True, we’ll now be able to find all the validated form\ndata in its cleaned_data attribute. We can use this data to update the\ndatabase or do other processing before sending an HTTP redirect to the browser\ntelling it where to go next.
We don’t need to do much in our name.html template:
<form action="/your-name/" method="post">\n {% csrf_token %}\n {{ form }}\n <input type="submit" value="Submit">\n</form>\nAll the form’s fields and their attributes will be unpacked into HTML markup\nfrom that {{ form }} by Django’s template language.
We now have a working web form, described by a Django Form, processed\nby a view, and rendered as an HTML <form>.
That’s all you need to get started, but the forms framework puts a lot more at\nyour fingertips. Once you understand the basics of the process described above,\nyou should be prepared to understand other features of the forms system and\nready to learn a bit more about the underlying machinery.
\nForm classesLink to this heading#All form classes are created as subclasses of either django.forms.Form\nor django.forms.ModelForm. You can think of ModelForm as a\nsubclass of Form. Form and ModelForm actually inherit common\nfunctionality from a (private) BaseForm class, but this implementation\ndetail is rarely important.
The distinction between Bound and unbound forms is important:
\nAn unbound form has no data associated with it. When rendered to the user,\nit will be empty or will contain default values.
A bound form has submitted data, and hence can be used to tell if that data\nis valid. If an invalid bound form is rendered, it can include inline error\nmessages telling the user what data to correct.
The form’s is_bound attribute will tell you whether a form has\ndata bound to it or not.
Consider a more useful form than our minimal example above, which we could use\nto implement «contact me» functionality on a personal website:
\nforms.pyfrom django import forms\n\nclass ContactForm(forms.Form):\n subject = forms.CharField(max_length=100)\n message = forms.CharField(widget=forms.Textarea)\n sender = forms.EmailField()\n cc_myself = forms.BooleanField(required=False)\nOur earlier form used a single field, your_name, a CharField. In\nthis case, our form has four fields: subject, message, sender and\ncc_myself. CharField, EmailField and\nBooleanField are just three of the available field types; a full list\ncan be found in Form fields.
Each form field has a corresponding Widget class,\nwhich in turn corresponds to an HTML form widget such as <input\ntype="text">.
In most cases, the field will have a sensible default widget. For example, by\ndefault, a CharField will have a TextInput widget, that\nproduces an <input type="text"> in the HTML. If you needed <textarea>\ninstead, you’d specify the appropriate widget when defining your form field,\nas we have done for the message field.
Whatever the data submitted with a form, once it has been successfully\nvalidated by calling is_valid() (and is_valid() has returned True),\nthe validated form data will be in the form.cleaned_data dictionary. This\ndata will have been nicely converted into Python types for you.
In the contact form example above, cc_myself will be a boolean value.\nLikewise, fields such as IntegerField and FloatField convert\nvalues to a Python int and float respectively.
Here’s how the form data could be processed in the view that handles this form:
\nviews.pyfrom django.core.mail import send_mail\n\nif form.is_valid():\n subject = form.cleaned_data['subject']\n message = form.cleaned_data['message']\n sender = form.cleaned_data['sender']\n cc_myself = form.cleaned_data['cc_myself']\n\n recipients = ['info@example.com']\n if cc_myself:\n recipients.append(sender)\n\n send_mail(subject, message, sender, recipients)\n return HttpResponseRedirect('/thanks/')\nSome field types need some extra handling. For example, files that are uploaded\nusing a form need to be handled differently (they can be retrieved from\nrequest.FILES, rather than request.POST). For details of how to handle\nfile uploads with your form, see Binding uploaded files to a form.
All you need to do to get your form into a template is to place the form\ninstance into the template context. So if your form is called form in the\ncontext, {{ form }} will render its <label> and <input> elements\nappropriately.
The HTML output when rendering a form is itself generated via a template. You\ncan control this by creating an appropriate template file and setting a custom\nFORM_RENDERER to use that\nform_template_name site-wide. You\ncan also customize per-form by overriding the form’s\ntemplate_name attribute to render the form using the\ncustom template, or by passing the template name directly to\nForm.render().
The example below will result in {{ form }} being rendered as the output of\nthe form_snippet.html template.
In your templates:
\n# In your template:\n{{ form }}\n\n# In form_snippet.html:\n{% for field in form %}\n <div class="fieldWrapper">\n {{ field.errors }}\n {{ field.label_tag }} {{ field }}\n </div>\n{% endfor %}\nThen you can configure the FORM_RENDERER setting:
settings.pyfrom django.forms.renderers import TemplatesSetting\n\nclass CustomFormRenderer(TemplatesSetting):\n form_template_name = "form_snippet.html"\n\nFORM_RENDERER = "project.settings.CustomFormRenderer"\n… or for a single form:
\nclass MyForm(forms.Form):\n template_name = "form_snippet.html"\n ...\n… or for a single render of a form instance, passing in the template name to\nthe Form.render(). Here’s an example of this being used in a view:
def index(request):\n form = MyForm()\n rendered_form = form.render("form_snippet.html")\n context = {'form': rendered_form}\n return render(request, 'index.html', context)\nSee Outputting forms as HTML for more details.
\n\n\nThere are other output options though for the <label>/<input> pairs:
{{ form.as_div }} will render them wrapped in <div> tags.
{{ form.as_table }} will render them as table cells wrapped in <tr>\ntags.
{{ 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>\nelements yourself.
Here’s the output of {{ form.as_p }} for our ContactForm instance:
<p><label for="id_subject">Subject:</label>\n <input id="id_subject" type="text" name="subject" maxlength="100" required></p>\n<p><label for="id_message">Message:</label>\n <textarea name="message" id="id_message" required></textarea></p>\n<p><label for="id_sender">Sender:</label>\n <input type="email" name="sender" id="id_sender" required></p>\n<p><label for="id_cc_myself">Cc myself:</label>\n <input type="checkbox" name="cc_myself" id="id_cc_myself"></p>\nNote that each form field has an ID attribute set to id_<field-name>, which\nis referenced by the accompanying label tag. This is important in ensuring that\nforms are accessible to assistive technology such as screen reader software.\nYou can also customize the way in which labels and ids are generated.
See Outputting forms as HTML for more on this.
\nWe don’t have to let Django unpack the form’s fields; we can do it manually if\nwe like (allowing us to reorder the fields, for example). Each field is\navailable as an attribute of the form using {{ form.name_of_field }}, and\nin a Django template, will be rendered appropriately. For example:
{{ form.non_field_errors }}\n<div class="fieldWrapper">\n {{ form.subject.errors }}\n <label for="{{ form.subject.id_for_label }}">Email subject:</label>\n {{ form.subject }}\n</div>\n<div class="fieldWrapper">\n {{ form.message.errors }}\n <label for="{{ form.message.id_for_label }}">Your message:</label>\n {{ form.message }}\n</div>\n<div class="fieldWrapper">\n {{ form.sender.errors }}\n <label for="{{ form.sender.id_for_label }}">Your email address:</label>\n {{ form.sender }}\n</div>\n<div class="fieldWrapper">\n {{ form.cc_myself.errors }}\n <label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>\n {{ form.cc_myself }}\n</div>\nComplete <label> elements can also be generated using the\nlabel_tag(). For example:
<div class="fieldWrapper">\n {{ form.subject.errors }}\n {{ form.subject.label_tag }}\n {{ form.subject }}\n</div>\nThe price of this flexibility is a bit more work. Until now we haven’t had to\nworry about how to display form errors, because that’s taken care of for us. In\nthis example we have had to make sure we take care of any errors for each field\nand any errors for the form as a whole. Note {{ form.non_field_errors }} at\nthe 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,\nrendered as an unordered list. This might look like:
<ul class="errorlist">\n <li>Sender is required.</li>\n</ul>\nThe list has a CSS class of errorlist to allow you to style its appearance.\nIf you wish to further customize the display of errors you can do so by looping\nover them:
{% if form.subject.errors %}\n <ol>\n {% for error in form.subject.errors %}\n <li><strong>{{ error|escape }}</strong></li>\n {% endfor %}\n </ol>\n{% endif %}\nNon-field errors (and/or hidden field errors that are rendered at the top of\nthe form when using helpers like form.as_p()) will be rendered with an\nadditional class of nonfield to help distinguish them from field-specific\nerrors. For example, {{ form.non_field_errors }} would look like:
<ul class="errorlist nonfield">\n <li>Generic validation error</li>\n</ul>\nSee The Forms API for more on errors, styling, and working with form\nattributes in templates.
\nIf you’re using the same HTML for each of your form fields, you can reduce\nduplicate code by looping through each field in turn using a {% for %}\nloop:
{% for field in form %}\n <div class="fieldWrapper">\n {{ field.errors }}\n {{ field.label_tag }} {{ field }}\n {% if field.help_text %}\n <p class="help">{{ field.help_text|safe }}</p>\n {% endif %}\n </div>\n{% endfor %}\nUseful attributes on {{ field }} include:
{{ field.errors }}Outputs a <ul class="errorlist"> containing any validation errors\ncorresponding to this field. You can customize the presentation of\nthe errors with a {% for error in field.errors %} loop. In this\ncase, each object in the loop is a string containing the error message.
{{ field.field }}The Field instance from the form class that\nthis BoundField wraps. You can use it to access\nField attributes, e.g.\n{{ char_field.field.max_length }}.
{{ field.help_text }}Any help text that has been associated with the field.
\n{{ field.html_name }}The name of the field that will be used in the input element’s name\nfield. This takes the form prefix into account, if it has been set.
\n{{ field.id_for_label }}The ID that will be used for this field (id_email in the example\nabove). If you are constructing the label manually, you may want to use\nthis in lieu of label_tag. It’s also useful, for example, if you have\nsome inline JavaScript and want to avoid hardcoding the field’s ID.
{{ field.is_hidden }}This attribute is True if the form field is a hidden field and\nFalse otherwise. It’s not particularly useful as a template\nvariable, but could be useful in conditional tests such as:
{% if field.is_hidden %}\n {# Do something special #}\n{% endif %}\n{{ 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. This\nincludes the form’s label_suffix. For example,\nthe default label_suffix is a colon:
<label for="id_email">Email address:</label>\n{{ field.legend_tag }}
\n\n\nSimilar to
\nfield.label_tagbut uses a<legend>tag in place of\n<label>, for widgets with multiple inputs wrapped in a<fieldset>.
{{ field.use_fieldset }}
\n\n\nThis attribute is
\nTrueif the form field’s widget contains multiple\ninputs that should be semantically grouped in a<fieldset>with a\n<legend>to improve accessibility. An example use in a template:
{% if field.use_fieldset %}\n <fieldset>\n {% if field.label %}{{ field.legend_tag }}{% endif %}\n{% else %}\n {% if field.label %}{{ field.label_tag }}{% endif %}\n{% endif %}\n{{ field }}\n{% if field.use_fieldset %}</fieldset>{% endif %}\n{{ field.value }}The value of the field. e.g someone@example.com.
This covers the basics, but forms can do a whole lot more:
\nMedia class)\n