2008-08-23 22:25:40 +00:00
|
|
|
|
==================
|
|
|
|
|
Working with forms
|
|
|
|
|
==================
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
.. currentmodule:: django.forms
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
.. admonition:: About this document
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
This document provides an introduction to the basics of web forms and how
|
|
|
|
|
they are handled in Django. For a more detailed look at specific areas of
|
|
|
|
|
the forms API, see :doc:`/ref/forms/api`, :doc:`/ref/forms/fields`, and
|
2010-10-10 07:08:35 +00:00
|
|
|
|
:doc:`/ref/forms/validation`.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
Unless you're planning to build Web sites and applications that do nothing but
|
2014-06-08 18:30:52 +00:00
|
|
|
|
publish content, and don't accept input from your visitors, you're going to
|
|
|
|
|
need to understand and use forms.
|
|
|
|
|
|
|
|
|
|
Django provides a range of tools and libraries to help you build forms to
|
2014-06-25 16:23:04 +00:00
|
|
|
|
accept input from site visitors, and then process and respond to the input.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
HTML forms
|
|
|
|
|
==========
|
|
|
|
|
|
|
|
|
|
In HTML, a form is a collection of elements inside ``<form>...</form>`` that
|
|
|
|
|
allow a visitor to do things like enter text, select options, manipulate
|
|
|
|
|
objects or controls, and so on, and then send that information back to the
|
|
|
|
|
server.
|
|
|
|
|
|
|
|
|
|
Some of these form interface elements - text input or checkboxes - are fairly
|
2015-05-10 03:18:56 +00:00
|
|
|
|
simple and are built into HTML itself. Others are much more complex; an
|
|
|
|
|
interface that pops up a date picker or allows you to move a slider or
|
|
|
|
|
manipulate controls will typically use JavaScript and CSS as well as HTML form
|
|
|
|
|
``<input>`` elements to achieve these effects.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
be returned
|
|
|
|
|
|
|
|
|
|
* *how*: the HTTP method the data should be returned by
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
As an example, the login form for the Django admin contains several
|
|
|
|
|
``<input>`` elements: one of ``type="text"`` for the username, one of
|
|
|
|
|
``type="password"`` for the password, and one of ``type="submit"`` for the
|
|
|
|
|
"Log in" button. It also contains some hidden text fields that the user
|
|
|
|
|
doesn't see, which Django uses to determine what to do next.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
It also tells the browser that the form data should be sent to the URL
|
|
|
|
|
specified in the ``<form>``’s ``action`` attribute - ``/admin/`` - and that it
|
|
|
|
|
should be sent using the HTTP mechanism specified by the ``method`` attribute -
|
|
|
|
|
``post``.
|
|
|
|
|
|
|
|
|
|
When the ``<input type="submit" value="Log in">`` element is triggered, the
|
2014-06-25 16:23:04 +00:00
|
|
|
|
data is returned to ``/admin/``.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
``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 browser
|
2015-05-10 03:18:56 +00:00
|
|
|
|
bundles up the form data, encodes it for transmission, sends it to the server,
|
|
|
|
|
and then receives back its response.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
``GET``, by contrast, bundles the submitted data into a string, and uses this
|
|
|
|
|
to compose a URL. The URL contains the address where the data must be sent, as
|
2014-06-08 18:30:52 +00:00
|
|
|
|
well as the data keys and values. You can see this in action if you do a search
|
|
|
|
|
in the Django documentation, which will produce a URL of the form
|
|
|
|
|
``https://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``. ``GET``
|
|
|
|
|
should 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
|
2014-06-25 16:23:04 +00:00
|
|
|
|
would 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 ``GET``
|
2014-06-08 18:30:52 +00:00
|
|
|
|
requests for admin forms is a security risk: it can be easy for an attacker to
|
|
|
|
|
mimic a form's request to gain access to sensitive parts of the system.
|
2014-06-25 15:15:20 +00:00
|
|
|
|
``POST``, coupled with other protections like Django's :doc:`CSRF protection
|
2014-10-31 22:39:46 +00:00
|
|
|
|
</ref/csrf/>` offers more control over access.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
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 numerous
|
2014-06-25 16:23:04 +00:00
|
|
|
|
items of data of several different types may need to be prepared for display in
|
2014-06-08 18:30:52 +00:00
|
|
|
|
a form, rendered as HTML, edited using a convenient interface, returned to the
|
|
|
|
|
server, validated and cleaned up, and then saved or passed on for further
|
|
|
|
|
processing.
|
|
|
|
|
|
|
|
|
|
Django's form functionality can simplify and automate vast portions of this
|
2014-06-25 16:23:04 +00:00
|
|
|
|
work, and can also do it more securely than most programmers would be able to
|
|
|
|
|
do in code they wrote themselves.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
Django handles three distinct parts of the work involved in forms:
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
2015-05-10 03:18:56 +00:00
|
|
|
|
* preparing and restructuring data to make it ready for rendering
|
2014-06-08 18:30:52 +00:00
|
|
|
|
* creating HTML forms for the data
|
|
|
|
|
* receiving and processing submitted forms and data from the client
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
It is *possible* to write code that does all of this manually, but Django can
|
2014-06-08 18:30:52 +00:00
|
|
|
|
take care of it all for you.
|
|
|
|
|
|
|
|
|
|
Forms in Django
|
|
|
|
|
===============
|
|
|
|
|
|
|
|
|
|
We've described HTML forms briefly, but an HTML ``<form>`` is just one part of
|
|
|
|
|
the machinery required.
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
In the context of a Web application, 'form' might refer to that HTML
|
2014-06-08 18:30:52 +00:00
|
|
|
|
``<form>``, or to the Django :class:`Form` that produces it, or to the
|
|
|
|
|
structured data returned when it is submitted, or to the end-to-end working
|
|
|
|
|
collection of these parts.
|
|
|
|
|
|
|
|
|
|
The Django :class:`Form` class
|
|
|
|
|
------------------------------
|
|
|
|
|
|
|
|
|
|
At the heart of this system of components is Django's :class:`Form` class. In
|
|
|
|
|
much the same way that a Django model describes the logical structure of an
|
|
|
|
|
object, its behavior, and the way its parts are represented to us, a
|
|
|
|
|
:class:`Form` 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
|
|
|
|
|
class's fields map to HTML form ``<input>`` elements. (A :class:`ModelForm`
|
|
|
|
|
maps a model class's fields to HTML form ``<input>`` elements via a
|
|
|
|
|
:class:`Form`; this is what the Django admin is based upon.)
|
|
|
|
|
|
|
|
|
|
A form's fields are themselves classes; they manage form data and perform
|
2014-06-25 16:23:04 +00:00
|
|
|
|
validation when a form is submitted. A :class:`DateField` and a
|
|
|
|
|
:class:`FileField` handle very different kinds of data and have to do
|
|
|
|
|
different things with it.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
2015-05-10 03:18:56 +00:00
|
|
|
|
A form field is represented to a user in the browser as an HTML "widget" - a
|
2014-06-08 18:30:52 +00:00
|
|
|
|
piece of user interface machinery. Each field type has an appropriate default
|
|
|
|
|
:doc:`Widget class </ref/forms/widgets/>`, but these can be overridden as
|
|
|
|
|
required.
|
|
|
|
|
|
|
|
|
|
Instantiating, processing, and rendering forms
|
|
|
|
|
----------------------------------------------
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
When rendering an object in Django, we generally:
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
2014-12-17 13:01:19 +00:00
|
|
|
|
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
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
Rendering a form in a template involves nearly the same work as rendering any
|
|
|
|
|
other kind of object, but there are some key differences.
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
In the case of a model instance that contained no data, it would rarely if ever
|
2015-05-10 03:18:56 +00:00
|
|
|
|
be useful to do anything with it in a template. On the other hand, it makes
|
2014-06-08 18:30:52 +00:00
|
|
|
|
perfect sense to render an unpopulated form - that's what we do when we want
|
|
|
|
|
the user to populate it.
|
2008-09-09 01:54:20 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
So when we handle a model instance in a view, we typically retrieve it from the
|
|
|
|
|
database. When we're dealing with a form we typically instantiate it in the
|
2014-06-08 18:30:52 +00:00
|
|
|
|
view.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
When we instantiate a form, we can opt to leave it empty or pre-populate it, for
|
|
|
|
|
example with:
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
* 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
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
The last of these cases is the most interesting, because it's what makes it
|
2014-06-25 16:23:04 +00:00
|
|
|
|
possible for users not just to read a Web site, but to send information back
|
|
|
|
|
to it too.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Building a form
|
|
|
|
|
===============
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
The work that needs to be done
|
|
|
|
|
------------------------------
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
Suppose you want to create a simple form on your Web site, in order to obtain
|
|
|
|
|
the user's name. You'd need something like this in your template:
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
.. code-block:: html+django
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
<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/``, using
|
|
|
|
|
the ``POST`` method. It will display a text field, labeled "Your name:", and a
|
|
|
|
|
button marked "OK". If the template context contains a ``current_name``
|
|
|
|
|
variable, 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
|
|
|
|
|
that can supply the ``current_name`` field as appropriate.
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
When the form is submitted, the ``POST`` request which is sent to the server
|
|
|
|
|
will contain the form data.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
Now you'll also need a view corresponding to that ``/your-name/`` URL which will
|
2014-06-25 16:23:04 +00:00
|
|
|
|
find the appropriate key/value pairs in the request, and then process them.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
This is a very simple form. In practice, a form might contain dozens or
|
|
|
|
|
hundreds of fields, many of which might need to be pre-populated, and we might
|
|
|
|
|
expect the user to work through the edit-submit cycle several times before
|
|
|
|
|
concluding the operation.
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
We might require some validation to occur in the browser, even before the form
|
|
|
|
|
is submitted; we might want to use much more complex fields, that allow the
|
2014-06-25 16:23:04 +00:00
|
|
|
|
user to do things like pick dates from a calendar and so on.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
At this point it's much easier to get Django to do most of this work for us.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Building a form in Django
|
|
|
|
|
-------------------------
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
The :class:`Form` class
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
We already know what we want our HTML form to look like. Our starting point for
|
2015-04-06 05:43:37 +00:00
|
|
|
|
it in Django is this:
|
|
|
|
|
|
|
|
|
|
.. snippet::
|
|
|
|
|
:filename: forms.py
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
from django import forms
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
class NameForm(forms.Form):
|
|
|
|
|
your_name = forms.CharField(label='Your name', max_length=100)
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
This defines a :class:`Form` class with a single field (``your_name``). We've
|
2014-06-25 16:23:04 +00:00
|
|
|
|
applied a human-friendly label to the field, which will appear in the
|
2014-06-08 18:30:52 +00:00
|
|
|
|
``<label>`` when it's rendered (although in this case, the :attr:`~Field.label`
|
|
|
|
|
we specified is actually the same one that would be generated automatically if
|
|
|
|
|
we had omitted it).
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
The field's maximum allowable length is defined by
|
|
|
|
|
:attr:`~CharField.max_length`. This does two things. It puts a
|
|
|
|
|
``maxlength="100"`` on the HTML ``<input>`` (so the browser should prevent the
|
2014-06-25 16:23:04 +00:00
|
|
|
|
user from entering more than that number of characters in the first place). It
|
|
|
|
|
also means that when Django receives the form back from the browser, it will
|
|
|
|
|
validate the length of the data.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
A :class:`Form` instance has an :meth:`~Form.is_valid()` method, which runs
|
|
|
|
|
validation routines for all its fields. When this method is called, if all
|
|
|
|
|
fields contain valid data, it will:
|
|
|
|
|
|
|
|
|
|
* return ``True``
|
|
|
|
|
* place the form's data in its :attr:`~Form.cleaned_data` attribute.
|
|
|
|
|
|
|
|
|
|
The whole form, when rendered for the first time, will look like:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
|
|
|
|
|
|
|
|
|
<label for="your_name">Your name: </label>
|
|
|
|
|
<input id="your_name" type="text" name="your_name" maxlength="100">
|
|
|
|
|
|
|
|
|
|
Note that it **does not** include the ``<form>`` tags, or a submit button.
|
|
|
|
|
We'll have to provide those ourselves in the template.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2012-06-11 08:34:00 +00:00
|
|
|
|
.. _using-a-form-in-a-view:
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
The view
|
|
|
|
|
^^^^^^^^
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
Form data sent back to a Django Web site is processed by a view, generally the
|
|
|
|
|
same view which published the form. This allows us to reuse some of the same
|
2014-06-08 18:30:52 +00:00
|
|
|
|
logic.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
To handle the form we need to instantiate it in the view for the URL where we
|
2015-04-06 05:43:37 +00:00
|
|
|
|
want it to be published:
|
|
|
|
|
|
|
|
|
|
.. snippet::
|
|
|
|
|
:filename: views.py
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
from django.shortcuts import render
|
|
|
|
|
from django.http import HttpResponseRedirect
|
|
|
|
|
|
2015-04-06 05:43:37 +00:00
|
|
|
|
from .forms import NameForm
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
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 form
|
|
|
|
|
instance and place it in the template context to be rendered. This is what we
|
|
|
|
|
can expect to happen the first time we visit the URL.
|
|
|
|
|
|
|
|
|
|
If the form is submitted using a ``POST`` request, the view will once again
|
|
|
|
|
create a form instance and populate it with data from the request: ``form =
|
2014-06-25 16:23:04 +00:00
|
|
|
|
NameForm(request.POST)`` This is called "binding data to the form" (it is now
|
2014-06-08 18:30:52 +00:00
|
|
|
|
a *bound* form).
|
|
|
|
|
|
|
|
|
|
We call the form's ``is_valid()`` method; if it's not ``True``, we go back to
|
|
|
|
|
the 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 it
|
|
|
|
|
can be edited and corrected as required.
|
|
|
|
|
|
|
|
|
|
If ``is_valid()`` is ``True``, we'll now be able to find all the validated form
|
2014-06-25 16:23:04 +00:00
|
|
|
|
data in its ``cleaned_data`` attribute. We can use this data to update the
|
2014-06-08 18:30:52 +00:00
|
|
|
|
database or do other processing before sending an HTTP redirect to the browser
|
|
|
|
|
telling it where to go next.
|
|
|
|
|
|
|
|
|
|
.. _topics-forms-index-basic-form-template:
|
|
|
|
|
|
|
|
|
|
The template
|
|
|
|
|
^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
We don't need to do much in our ``name.html`` template. The simplest example
|
|
|
|
|
is:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
|
|
|
|
|
|
|
|
|
<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 markup
|
|
|
|
|
from that ``{{ form }}`` by Django's template language.
|
|
|
|
|
|
|
|
|
|
.. admonition:: Forms and Cross Site Request Forgery protection
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
Django ships with an easy-to-use :doc:`protection against Cross Site Request
|
2014-10-31 22:39:46 +00:00
|
|
|
|
Forgeries </ref/csrf>`. When submitting a form via ``POST`` with
|
2014-06-25 16:23:04 +00:00
|
|
|
|
CSRF protection enabled you must use the :ttag:`csrf_token` template tag
|
|
|
|
|
as in the preceding example. However, since CSRF protection is not
|
|
|
|
|
directly tied to forms in templates, this tag is omitted from the
|
|
|
|
|
following examples in this document.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
2014-08-23 08:27:33 +00:00
|
|
|
|
.. admonition:: HTML5 input types and browser validation
|
|
|
|
|
|
|
|
|
|
If your form includes a :class:`~django.forms.URLField`, an
|
|
|
|
|
:class:`~django.forms.EmailField` or any integer field type, Django will
|
|
|
|
|
use the ``url``, ``email`` and ``number`` HTML5 input types. By default,
|
|
|
|
|
browsers may apply their own validation on these fields, which may be
|
|
|
|
|
stricter than Django's validation. If you would like to disable this
|
|
|
|
|
behavior, set the `novalidate` attribute on the ``form`` tag, or specify
|
|
|
|
|
a different widget on the field, like :class:`TextInput`.
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
We now have a working web form, described by a Django :class:`Form`, processed
|
|
|
|
|
by 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
|
|
|
|
|
your fingertips. Once you understand the basics of the process described above,
|
2015-05-10 03:18:56 +00:00
|
|
|
|
you should be prepared to understand other features of the forms system and
|
|
|
|
|
ready to learn a bit more about the underlying machinery.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
More about Django :class:`Form` classes
|
|
|
|
|
=======================================
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
All form classes are created as subclasses of :class:`django.forms.Form`,
|
|
|
|
|
including the :doc:`ModelForm </topics/forms/modelforms>`, which you encounter
|
|
|
|
|
in Django's admin.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
.. admonition:: Models and Forms
|
|
|
|
|
|
|
|
|
|
In fact if your form is going to be used to directly add or edit a Django
|
|
|
|
|
model, a :doc:`ModelForm </topics/forms/modelforms>` can save you a great
|
|
|
|
|
deal of time, effort, and code, because it will build a form, along with the
|
|
|
|
|
appropriate fields and their attributes, from a ``Model`` class.
|
|
|
|
|
|
|
|
|
|
Bound and unbound form instances
|
|
|
|
|
--------------------------------
|
2012-06-07 18:06:47 +00:00
|
|
|
|
|
|
|
|
|
The distinction between :ref:`ref-forms-api-bound-unbound` 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 data
|
|
|
|
|
is valid. If an invalid bound form is rendered, it can include inline error
|
|
|
|
|
messages telling the user what data to correct.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2015-01-06 07:56:53 +00:00
|
|
|
|
The form's :attr:`~Form.is_bound` attribute will tell you whether a form has
|
|
|
|
|
data bound to it or not.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
More on fields
|
|
|
|
|
--------------
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
Consider a more useful form than our minimal example above, which we could use
|
2015-04-06 05:43:37 +00:00
|
|
|
|
to implement "contact me" functionality on a personal Web site:
|
|
|
|
|
|
|
|
|
|
.. snippet::
|
|
|
|
|
:filename: forms.py
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
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)
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
Our earlier form used a single field, ``your_name``, a :class:`CharField`. In
|
|
|
|
|
this case, our form has four fields: ``subject``, ``message``, ``sender`` and
|
2014-06-08 18:30:52 +00:00
|
|
|
|
``cc_myself``. :class:`CharField`, :class:`EmailField` and
|
|
|
|
|
:class:`BooleanField` are just three of the available field types; a full list
|
|
|
|
|
can be found in :doc:`/ref/forms/fields`.
|
2009-05-24 06:46:02 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Widgets
|
|
|
|
|
^^^^^^^
|
2009-05-24 06:46:02 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Each form field has a corresponding :doc:`Widget class </ref/forms/widgets/>`,
|
|
|
|
|
which in turn corresponds to an HTML form widget such as ``<input
|
|
|
|
|
type="text">``.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
In most cases, the field will have a sensible default widget. For example, by
|
2014-06-25 16:23:04 +00:00
|
|
|
|
default, a :class:`CharField` will have a :class:`TextInput` widget, that
|
2014-09-25 13:09:12 +00:00
|
|
|
|
produces 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.
|
2014-06-08 18:30:52 +00:00
|
|
|
|
|
|
|
|
|
Field data
|
|
|
|
|
^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
Whatever the data submitted with a form, once it has been successfully
|
|
|
|
|
validated by calling ``is_valid()`` (and ``is_valid()`` has returned ``True``),
|
|
|
|
|
the validated form data will be in the ``form.cleaned_data`` dictionary. This
|
2014-06-25 16:23:04 +00:00
|
|
|
|
data will have been nicely converted into Python types for you.
|
2012-06-07 19:07:43 +00:00
|
|
|
|
|
|
|
|
|
.. note::
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
You can still access the unvalidated data directly from ``request.POST`` at
|
|
|
|
|
this point, but the validated data is better.
|
2012-06-07 19:07:43 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
In the contact form example above, ``cc_myself`` will be a boolean value.
|
|
|
|
|
Likewise, fields such as :class:`IntegerField` and :class:`FloatField` convert
|
|
|
|
|
values to a Python ``int`` and ``float`` respectively.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2015-04-06 05:43:37 +00:00
|
|
|
|
Here's how the form data could be processed in the view that handles this form:
|
|
|
|
|
|
|
|
|
|
.. snippet::
|
|
|
|
|
:filename: views.py
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
from django.core.mail import send_mail
|
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
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']
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
recipients = ['info@example.com']
|
|
|
|
|
if cc_myself:
|
|
|
|
|
recipients.append(sender)
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
send_mail(subject, message, sender, recipients)
|
2014-06-08 18:30:52 +00:00
|
|
|
|
return HttpResponseRedirect('/thanks/')
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2012-06-07 19:07:43 +00:00
|
|
|
|
.. tip::
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
For more on sending email from Django, see :doc:`/topics/email`.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Some field types need some extra handling. For example, files that are uploaded
|
|
|
|
|
using a form need to be handled differently (they can be retrieved from
|
|
|
|
|
``request.FILES``, rather than ``request.POST``). For details of how to handle
|
|
|
|
|
file uploads with your form, see :ref:`binding-uploaded-files`.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Working with form templates
|
|
|
|
|
===========================
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
All you need to do to get your form into a template is to place the form
|
|
|
|
|
instance into the template context. So if your form is called ``form`` in the
|
|
|
|
|
context, ``{{ form }}`` will render its ``<label>`` and ``<input>`` elements
|
|
|
|
|
appropriately.
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Form rendering options
|
|
|
|
|
----------------------
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
.. admonition:: Additional form template furniture
|
2013-01-23 09:42:34 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
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 provide
|
|
|
|
|
these yourself.
|
2013-01-23 09:42:34 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
There are other output options though for the ``<label>``/``<input>`` pairs:
|
2011-02-07 22:52:39 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
* ``{{ 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.
|
2011-02-07 22:52:39 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Here's the output of ``{{ form.as_p }}`` for our ``ContactForm`` instance:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
<p><label for="id_subject">Subject:</label>
|
|
|
|
|
<input id="id_subject" type="text" name="subject" maxlength="100" /></p>
|
|
|
|
|
<p><label for="id_message">Message:</label>
|
|
|
|
|
<input type="text" name="message" id="id_message" /></p>
|
|
|
|
|
<p><label for="id_sender">Sender:</label>
|
|
|
|
|
<input type="email" name="sender" id="id_sender" /></p>
|
|
|
|
|
<p><label for="id_cc_myself">Cc myself:</label>
|
|
|
|
|
<input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Note that each form field has an ID attribute set to ``id_<field-name>``, which
|
2014-06-25 16:23:04 +00:00
|
|
|
|
is referenced by the accompanying label tag. This is important in ensuring that
|
|
|
|
|
forms are accessible to assistive technology such as screen reader software.
|
|
|
|
|
You can also :ref:`customize the way in which labels and ids are generated
|
2008-08-23 22:25:40 +00:00
|
|
|
|
<ref-forms-api-configuring-label>`.
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
See :ref:`ref-forms-api-outputting-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 if
|
|
|
|
|
we like (allowing us to reorder the fields, for example). Each field is
|
|
|
|
|
available as an attribute of the form using ``{{ form.name_of_field }}``, and
|
|
|
|
|
in a Django template, will be rendered appropriately. For example:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
|
|
|
|
|
|
|
|
|
{{ form.non_field_errors }}
|
|
|
|
|
<div class="fieldWrapper">
|
|
|
|
|
{{ form.subject.errors }}
|
2014-11-15 12:29:16 +00:00
|
|
|
|
<label for="{{ form.subject.id_for_label }}">Email subject:</label>
|
2014-06-08 18:30:52 +00:00
|
|
|
|
{{ form.subject }}
|
|
|
|
|
</div>
|
|
|
|
|
<div class="fieldWrapper">
|
|
|
|
|
{{ form.message.errors }}
|
2014-11-15 12:29:16 +00:00
|
|
|
|
<label for="{{ form.message.id_for_label }}">Your message:</label>
|
2014-06-08 18:30:52 +00:00
|
|
|
|
{{ form.message }}
|
|
|
|
|
</div>
|
|
|
|
|
<div class="fieldWrapper">
|
|
|
|
|
{{ form.sender.errors }}
|
2014-11-15 12:29:16 +00:00
|
|
|
|
<label for="{{ form.sender.id_for_label }}">Your email address:</label>
|
2014-06-08 18:30:52 +00:00
|
|
|
|
{{ form.sender }}
|
|
|
|
|
</div>
|
|
|
|
|
<div class="fieldWrapper">
|
|
|
|
|
{{ form.cc_myself.errors }}
|
2014-11-15 12:29:16 +00:00
|
|
|
|
<label for="{{ form.cc_myself.id_for_label }}">CC yourself?</label>
|
2014-06-08 18:30:52 +00:00
|
|
|
|
{{ form.cc_myself }}
|
|
|
|
|
</div>
|
|
|
|
|
|
2015-05-10 03:18:56 +00:00
|
|
|
|
Complete ``<label>`` elements can also be generated using the
|
2014-11-15 12:29:16 +00:00
|
|
|
|
:meth:`~django.forms.BoundField.label_tag`. For example:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
|
|
|
|
|
|
|
|
|
<div class="fieldWrapper">
|
|
|
|
|
{{ form.subject.errors }}
|
|
|
|
|
{{ form.subject.label_tag }}
|
|
|
|
|
{{ form.subject }}
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
Rendering form error messages
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
Of course, the price of this flexibility is more work. Until now we haven't had
|
2014-06-08 18:30:52 +00:00
|
|
|
|
to 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 each
|
|
|
|
|
field 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:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
<ul class="errorlist">
|
|
|
|
|
<li>Sender is required.</li>
|
|
|
|
|
</ul>
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
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 looping
|
2014-06-08 18:30:52 +00:00
|
|
|
|
over them:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
{% if form.subject.errors %}
|
|
|
|
|
<ol>
|
2008-11-21 16:25:05 +00:00
|
|
|
|
{% for error in form.subject.errors %}
|
2008-08-23 22:25:40 +00:00
|
|
|
|
<li><strong>{{ error|escape }}</strong></li>
|
|
|
|
|
{% endfor %}
|
|
|
|
|
</ol>
|
|
|
|
|
{% endif %}
|
2008-09-14 23:55:09 +00:00
|
|
|
|
|
2014-04-15 03:58:51 +00:00
|
|
|
|
Non-field errors (and/or hidden field errors that are rendered at the top of
|
|
|
|
|
the form when using helpers like ``form.as_p()``) will be rendered with an
|
|
|
|
|
additional class of ``nonfield`` to help distinguish them from field-specific
|
2014-06-08 18:30:52 +00:00
|
|
|
|
errors. For example, ``{{ form.non_field_errors }}`` would look like:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
2014-04-15 03:58:51 +00:00
|
|
|
|
|
|
|
|
|
<ul class="errorlist nonfield">
|
|
|
|
|
<li>Generic validation error</li>
|
|
|
|
|
</ul>
|
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
See :doc:`/ref/forms/api` for more on errors, styling, and working with form
|
|
|
|
|
attributes in templates.
|
|
|
|
|
|
2008-09-14 23:55:09 +00:00
|
|
|
|
Looping over the form's fields
|
|
|
|
|
------------------------------
|
|
|
|
|
|
2008-10-09 09:19:47 +00:00
|
|
|
|
If you're using the same HTML for each of your form fields, you can reduce
|
|
|
|
|
duplicate code by looping through each field in turn using a ``{% for %}``
|
2014-06-08 18:30:52 +00:00
|
|
|
|
loop:
|
2008-09-14 23:55:09 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
.. code-block:: html+django
|
|
|
|
|
|
|
|
|
|
{% for field in form %}
|
|
|
|
|
<div class="fieldWrapper">
|
|
|
|
|
{{ field.errors }}
|
|
|
|
|
{{ field.label_tag }} {{ field }}
|
2015-10-02 14:56:25 +00:00
|
|
|
|
{% if field.help_text %}
|
|
|
|
|
<p class="help">{{ field.help_text|safe }}</p>
|
|
|
|
|
{% endif %}
|
2014-06-08 18:30:52 +00:00
|
|
|
|
</div>
|
|
|
|
|
{% endfor %}
|
|
|
|
|
|
|
|
|
|
Useful attributes on ``{{ field }}`` include:
|
2008-09-14 23:55:09 +00:00
|
|
|
|
|
2011-10-14 00:12:01 +00:00
|
|
|
|
``{{ field.label }}``
|
|
|
|
|
The label of the field, e.g. ``Email address``.
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2011-10-14 00:12:01 +00:00
|
|
|
|
``{{ field.label_tag }}``
|
2014-03-24 15:42:56 +00:00
|
|
|
|
The field's label wrapped in the appropriate HTML ``<label>`` tag. This
|
|
|
|
|
includes the form's :attr:`~django.forms.Form.label_suffix`. For example,
|
|
|
|
|
the default ``label_suffix`` is a colon::
|
2012-06-08 13:32:35 +00:00
|
|
|
|
|
2014-03-24 15:42:56 +00:00
|
|
|
|
<label for="id_email">Email address:</label>
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2013-10-14 20:16:49 +00:00
|
|
|
|
``{{ field.id_for_label }}``
|
|
|
|
|
The ID that will be used for this field (``id_email`` in the example
|
2014-06-25 16:23:04 +00:00
|
|
|
|
above). If you are constructing the label manually, you may want to use
|
|
|
|
|
this in lieu of ``label_tag``. It's also useful, for example, if you have
|
2013-10-14 20:16:49 +00:00
|
|
|
|
some inline JavaScript and want to avoid hardcoding the field's ID.
|
|
|
|
|
|
2012-06-07 18:06:47 +00:00
|
|
|
|
``{{ field.value }}``
|
2014-06-08 18:30:52 +00:00
|
|
|
|
The value of the field. e.g ``someone@example.com``.
|
2011-11-21 23:33:39 +00:00
|
|
|
|
|
2011-10-14 00:12:01 +00:00
|
|
|
|
``{{ field.html_name }}``
|
|
|
|
|
The name of the field that will be used in the input element's name
|
|
|
|
|
field. This takes the form prefix into account, if it has been set.
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2011-10-14 00:12:01 +00:00
|
|
|
|
``{{ field.help_text }}``
|
|
|
|
|
Any help text that has been associated with the field.
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2011-10-14 00:12:01 +00:00
|
|
|
|
``{{ field.errors }}``
|
|
|
|
|
Outputs a ``<ul class="errorlist">`` containing any validation errors
|
|
|
|
|
corresponding to this field. You can customize the presentation of
|
|
|
|
|
the errors with a ``{% for error in field.errors %}`` loop. In this
|
|
|
|
|
case, each object in the loop is a simple string containing the error
|
|
|
|
|
message.
|
2008-09-15 00:13:25 +00:00
|
|
|
|
|
2013-02-02 13:34:42 +00:00
|
|
|
|
``{{ field.is_hidden }}``
|
2011-10-14 00:12:01 +00:00
|
|
|
|
This attribute is ``True`` if the form field is a hidden field and
|
|
|
|
|
``False`` otherwise. It's not particularly useful as a template
|
2014-06-08 18:30:52 +00:00
|
|
|
|
variable, but could be useful in conditional tests such as:
|
|
|
|
|
|
|
|
|
|
.. code-block:: html+django
|
2008-12-05 04:22:00 +00:00
|
|
|
|
|
2014-06-25 16:23:04 +00:00
|
|
|
|
{% if field.is_hidden %}
|
|
|
|
|
{# Do something special #}
|
|
|
|
|
{% endif %}
|
2008-12-05 04:22:00 +00:00
|
|
|
|
|
2013-02-02 13:34:42 +00:00
|
|
|
|
``{{ field.field }}``
|
|
|
|
|
The :class:`~django.forms.Field` instance from the form class that
|
|
|
|
|
this :class:`~django.forms.BoundField` wraps. You can use it to access
|
2014-06-25 16:23:04 +00:00
|
|
|
|
:class:`~django.forms.Field` attributes, e.g.
|
2013-02-02 13:34:42 +00:00
|
|
|
|
``{{ char_field.field.max_length }}``.
|
|
|
|
|
|
2015-08-10 11:23:24 +00:00
|
|
|
|
.. seealso::
|
|
|
|
|
|
|
|
|
|
For a complete list of attributes and methods, see
|
|
|
|
|
:class:`~django.forms.BoundField`.
|
|
|
|
|
|
2008-12-05 04:22:00 +00:00
|
|
|
|
Looping over hidden and visible fields
|
2014-06-08 18:30:52 +00:00
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
2008-12-05 04:22:00 +00:00
|
|
|
|
|
2008-12-08 04:07:42 +00:00
|
|
|
|
If you're manually laying out a form in a template, as opposed to relying on
|
|
|
|
|
Django's default form layout, you might want to treat ``<input type="hidden">``
|
2014-06-08 18:30:52 +00:00
|
|
|
|
fields differently from non-hidden fields. For example, because hidden fields
|
2008-12-08 04:07:42 +00:00
|
|
|
|
don't display anything, putting error messages "next to" the field could cause
|
|
|
|
|
confusion for your users -- so errors for those fields should be handled
|
|
|
|
|
differently.
|
2008-12-05 04:22:00 +00:00
|
|
|
|
|
|
|
|
|
Django provides two methods on a form that allow you to loop over the hidden
|
|
|
|
|
and visible fields independently: ``hidden_fields()`` and
|
2008-12-08 04:07:42 +00:00
|
|
|
|
``visible_fields()``. Here's a modification of an earlier example that uses
|
2014-06-08 18:30:52 +00:00
|
|
|
|
these two methods:
|
2008-12-05 04:22:00 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
.. code-block:: html+django
|
|
|
|
|
|
|
|
|
|
{# 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 %}
|
2008-12-05 04:22:00 +00:00
|
|
|
|
|
|
|
|
|
This example does not handle any errors in the hidden fields. Usually, an
|
|
|
|
|
error in a hidden field is a sign of form tampering, since normal form
|
|
|
|
|
interaction won't alter them. However, you could easily insert some error
|
2008-12-08 04:07:42 +00:00
|
|
|
|
displays for those form errors, as well.
|
2008-12-05 04:22:00 +00:00
|
|
|
|
|
2008-09-15 09:30:05 +00:00
|
|
|
|
Reusable form templates
|
|
|
|
|
-----------------------
|
|
|
|
|
|
2008-09-16 05:31:00 +00:00
|
|
|
|
If your site uses the same rendering logic for forms in multiple places, you
|
|
|
|
|
can reduce duplication by saving the form's loop in a standalone template and
|
2014-06-08 18:30:52 +00:00
|
|
|
|
using the :ttag:`include` tag to reuse it in other templates:
|
2008-09-15 09:30:05 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
.. code-block:: html+django
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
# In your form template:
|
|
|
|
|
{% include "form_snippet.html" %}
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
# In form_snippet.html:
|
2008-09-15 09:30:05 +00:00
|
|
|
|
{% for field in form %}
|
|
|
|
|
<div class="fieldWrapper">
|
|
|
|
|
{{ field.errors }}
|
2012-06-08 13:32:35 +00:00
|
|
|
|
{{ field.label_tag }} {{ field }}
|
2008-09-15 09:30:05 +00:00
|
|
|
|
</div>
|
|
|
|
|
{% endfor %}
|
|
|
|
|
|
2008-09-16 05:22:08 +00:00
|
|
|
|
If the form object passed to a template has a different name within the
|
2010-12-18 02:50:26 +00:00
|
|
|
|
context, you can alias it using the ``with`` argument of the :ttag:`include`
|
2014-06-08 18:30:52 +00:00
|
|
|
|
tag:
|
2008-09-15 09:30:05 +00:00
|
|
|
|
|
2014-06-08 18:30:52 +00:00
|
|
|
|
.. code-block:: html+django
|
|
|
|
|
|
|
|
|
|
{% include "form_snippet.html" with form=comment_form %}
|
2008-09-15 09:30:05 +00:00
|
|
|
|
|
2008-09-16 05:31:00 +00:00
|
|
|
|
If you find yourself doing this often, you might consider creating a custom
|
|
|
|
|
:ref:`inclusion tag<howto-custom-template-tags-inclusion-tags>`.
|
2008-09-15 15:44:59 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
Further topics
|
|
|
|
|
==============
|
|
|
|
|
|
|
|
|
|
This covers the basics, but forms can do a whole lot more:
|
|
|
|
|
|
|
|
|
|
.. toctree::
|
2010-10-10 07:08:35 +00:00
|
|
|
|
:maxdepth: 2
|
2008-08-23 22:25:40 +00:00
|
|
|
|
|
|
|
|
|
formsets
|
2011-02-07 23:39:29 +00:00
|
|
|
|
modelforms
|
2008-08-23 22:25:40 +00:00
|
|
|
|
media
|
2008-09-16 05:22:08 +00:00
|
|
|
|
|
2008-08-23 22:25:40 +00:00
|
|
|
|
.. seealso::
|
|
|
|
|
|
2010-10-10 07:08:35 +00:00
|
|
|
|
:doc:`The Forms Reference </ref/forms/index>`
|
2010-12-26 21:50:16 +00:00
|
|
|
|
Covers the full API reference, including form fields, form widgets,
|
2010-10-10 07:08:35 +00:00
|
|
|
|
and form and field validation.
|