/docs/topics/forms/index.txt

  1==================
  2Working with forms
  3==================
  4
  5.. admonition:: About this document
  6
  7    This document provides an introduction to Django's form handling features.
  8    For a more detailed look at specific areas of the forms API, see
  9    :doc:`/ref/forms/api`, :doc:`/ref/forms/fields`, and
 10    :doc:`/ref/forms/validation`.
 11
 12.. highlightlang:: html+django
 13
 14``django.forms`` is Django's form-handling library.
 15
 16While it is possible to process form submissions just using Django's
 17:class:`~django.http.HttpRequest` class, using the form library takes care of a
 18number of common form-related tasks. Using it, you can:
 19
 20    1. Display an HTML form with automatically generated form widgets.
 21    2. Check submitted data against a set of validation rules.
 22    3. Redisplay a form in the case of validation errors.
 23    4. Convert submitted form data to the relevant Python data types.
 24
 25Overview
 26========
 27
 28The library deals with these concepts:
 29
 30.. glossary::
 31
 32    Widget
 33        A class that corresponds to an HTML form widget, e.g.
 34        ``<input type="text">`` or ``<textarea>``. This handles rendering of the
 35        widget as HTML.
 36
 37    Field
 38        A class that is responsible for doing validation, e.g.
 39        an ``EmailField`` that makes sure its data is a valid e-mail address.
 40
 41    Form
 42        A collection of fields that knows how to validate itself and
 43        display itself as HTML.
 44
 45    Form Media
 46        The CSS and JavaScript resources that are required to render a form.
 47
 48The library is decoupled from the other Django components, such as the database
 49layer, views and templates. It relies only on Django settings, a couple of
 50``django.utils`` helper functions and Django's internationalization hooks (but
 51you're not required to be using internationalization features to use this
 52library).
 53
 54Form objects
 55============
 56
 57A Form object encapsulates a sequence of form fields and a collection of
 58validation rules that must be fulfilled in order for the form to be accepted.
 59Form classes are created as subclasses of ``django.forms.Form`` and
 60make use of a declarative style that you'll be familiar with if you've used
 61Django's database models.
 62
 63For example, consider a form used to implement "contact me" functionality on a
 64personal Web site:
 65
 66.. code-block:: python
 67
 68    from django import forms
 69
 70    class ContactForm(forms.Form):
 71        subject = forms.CharField(max_length=100)
 72        message = forms.CharField()
 73        sender = forms.EmailField()
 74        cc_myself = forms.BooleanField(required=False)
 75
 76A form is composed of ``Field`` objects. In this case, our form has four
 77fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. ``CharField``,
 78``EmailField`` and ``BooleanField`` are just three of the available field types;
 79a full list can be found in :doc:`/ref/forms/fields`.
 80
 81If your form is going to be used to directly add or edit a Django model, you can
 82use a :doc:`ModelForm </topics/forms/modelforms>` to avoid duplicating your model
 83description.
 84
 85Using a form in a view
 86----------------------
 87
 88The standard pattern for processing a form in a view looks like this:
 89
 90.. code-block:: python
 91
 92   def contact(request):
 93       if request.method == 'POST': # If the form has been submitted...
 94           form = ContactForm(request.POST) # A form bound to the POST data
 95           if form.is_valid(): # All validation rules pass
 96               # Process the data in form.cleaned_data
 97               # ...
 98               return HttpResponseRedirect('/thanks/') # Redirect after POST
 99       else:
100           form = ContactForm() # An unbound form
101
102       return render_to_response('contact.html', {
103           'form': form,
104       })
105
106
107There are three code paths here:
108
109    1. If the form has not been submitted, an unbound instance of ContactForm is
110       created and passed to the template.
111    2. If the form has been submitted, a bound instance of the form is created
112       using ``request.POST``. If the submitted data is valid, it is processed
113       and the user is re-directed to a "thanks" page.
114    3. If the form has been submitted but is invalid, the bound form instance is
115       passed on to the template.
116
117The distinction between **bound** and **unbound** forms is important. An unbound
118form does not have any data associated with it; when rendered to the user, it
119will be empty or will contain default values. A bound form does have submitted
120data, and hence can be used to tell if that data is valid. If an invalid bound
121form is rendered it can include inline error messages telling the user where
122they went wrong.
123
124See :ref:`ref-forms-api-bound-unbound` for further information on the
125differences between bound and unbound forms.
126
127Handling file uploads with a form
128---------------------------------
129
130To see how to handle file uploads with your form see
131:ref:`binding-uploaded-files` for more information.
132
133Processing the data from a form
134-------------------------------
135
136Once ``is_valid()`` returns ``True``, you can process the form submission safe
137in the knowledge that it conforms to the validation rules defined by your form.
138While you could access ``request.POST`` directly at this point, it is better to
139access ``form.cleaned_data``. This data has not only been validated but will
140also be converted in to the relevant Python types for you. In the above example,
141``cc_myself`` will be a boolean value. Likewise, fields such as ``IntegerField``
142and ``FloatField`` convert values to a Python int and float respectively. Note
143that read-only fields are not available in ``form.cleaned_data`` (and setting
144a value in a custom ``clean()`` method won't have any effect) because these
145fields are displayed as text rather than as input elements, and thus are not
146posted back to the server.
147
148Extending the above example, here's how the form data could be processed:
149
150.. code-block:: python
151
152    if form.is_valid():
153        subject = form.cleaned_data['subject']
154        message = form.cleaned_data['message']
155        sender = form.cleaned_data['sender']
156        cc_myself = form.cleaned_data['cc_myself']
157
158        recipients = ['info@example.com']
159        if cc_myself:
160            recipients.append(sender)
161
162        from django.core.mail import send_mail
163        send_mail(subject, message, sender, recipients)
164        return HttpResponseRedirect('/thanks/') # Redirect after POST
165
166For more on sending e-mail from Django, see :doc:`/topics/email`.
167
168Displaying a form using a template
169----------------------------------
170
171Forms are designed to work with the Django template language. In the above
172example, we passed our ``ContactForm`` instance to the template using the
173context variable ``form``. Here's a simple example template::
174
175    <form action="/contact/" method="post">{% csrf_token %}
176    {{ form.as_p }}
177    <input type="submit" value="Submit" />
178    </form>
179
180The form only outputs its own fields; it is up to you to provide the surrounding
181``<form>`` tags and the submit button.
182
183.. admonition:: Forms and Cross Site Request Forgery protection
184
185   Django ships with an easy-to-use :doc:`protection against Cross Site Request
186   Forgeries </ref/contrib/csrf>`. When submitting a form via POST with
187   CSRF protection enabled you must use the :ttag:`csrf_token` template tag
188   as in the preceding example. However, since CSRF protection is not
189   directly tied to forms in templates, this tag is omitted from the
190   following examples in this document.
191
192``form.as_p`` will output the form with each form field and accompanying label
193wrapped in a paragraph. Here's the output for our example template::
194
195   <form action="/contact/" method="post">
196   <p><label for="id_subject">Subject:</label>
197       <input id="id_subject" type="text" name="subject" maxlength="100" /></p>
198   <p><label for="id_message">Message:</label>
199       <input type="text" name="message" id="id_message" /></p>
200   <p><label for="id_sender">Sender:</label>
201       <input type="text" name="sender" id="id_sender" /></p>
202   <p><label for="id_cc_myself">Cc myself:</label>
203       <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>
204   <input type="submit" value="Submit" />
205   </form>
206
207Note that each form field has an ID attribute set to ``id_<field-name>``, which
208is referenced by the accompanying label tag. This is important for ensuring
209forms are accessible to assistive technology such as screen reader software. You
210can also :ref:`customize the way in which labels and ids are generated
211<ref-forms-api-configuring-label>`.
212
213You can also use ``form.as_table`` to output table rows (you'll need to provide
214your own ``<table>`` tags) and ``form.as_ul`` to output list items.
215
216Customizing the form template
217-----------------------------
218
219If the default generated HTML is not to your taste, you can completely customize
220the way a form is presented using the Django template language. Extending the
221above example::
222
223    <form action="/contact/" method="post">
224        {{ form.non_field_errors }}
225        <div class="fieldWrapper">
226            {{ form.subject.errors }}
227            <label for="id_subject">E-mail subject:</label>
228            {{ form.subject }}
229        </div>
230        <div class="fieldWrapper">
231            {{ form.message.errors }}
232            <label for="id_message">Your message:</label>
233            {{ form.message }}
234        </div>
235        <div class="fieldWrapper">
236            {{ form.sender.errors }}
237            <label for="id_sender">Your email address:</label>
238            {{ form.sender }}
239        </div>
240        <div class="fieldWrapper">
241            {{ form.cc_myself.errors }}
242            <label for="id_cc_myself">CC yourself?</label>
243            {{ form.cc_myself }}
244        </div>
245        <p><input type="submit" value="Send message" /></p>
246    </form>
247
248Each named form-field can be output to the template using
249``{{ form.name_of_field }}``, which will produce the HTML needed to display the
250form widget. Using ``{{ form.name_of_field.errors }}`` displays a list of form
251errors, rendered as an unordered list. This might look like::
252
253   <ul class="errorlist">
254       <li>Sender is required.</li>
255   </ul>
256
257The list has a CSS class of ``errorlist`` to allow you to style its appearance.
258If you wish to further customize the display of errors you can do so by looping
259over them::
260
261    {% if form.subject.errors %}
262        <ol>
263        {% for error in form.subject.errors %}
264            <li><strong>{{ error|escape }}</strong></li>
265        {% endfor %}
266        </ol>
267    {% endif %}
268
269Looping over the form's fields
270------------------------------
271
272If you're using the same HTML for each of your form fields, you can reduce
273duplicate code by looping through each field in turn using a ``{% for %}``
274loop::
275
276    <form action="/contact/" method="post">
277        {% for field in form %}
278            <div class="fieldWrapper">
279                {{ field.errors }}
280                {{ field.label_tag }}: {{ field }}
281            </div>
282        {% endfor %}
283        <p><input type="submit" value="Send message" /></p>
284    </form>
285
286Within this loop, ``{{ field }}`` is an instance of :class:`BoundField`.
287``BoundField`` also has the following attributes, which can be useful in your
288templates:
289
290    ``{{ field.label }}``
291        The label of the field, e.g. ``E-mail address``.
292
293    ``{{ field.label_tag }}``
294        The field's label wrapped in the appropriate HTML ``<label>`` tag,
295        e.g. ``<label for="id_email">E-mail address</label>``
296
297    ``{{ field.html_name }}``
298        The name of the field that will be used in the input element's name
299        field. This takes the form prefix into account, if it has been set.
300
301    ``{{ field.help_text }}``
302        Any help text that has been associated with the field.
303
304    ``{{ field.errors }}``
305        Outputs a ``<ul class="errorlist">`` containing any validation errors
306        corresponding to this field. You can customize the presentation of
307        the errors with a ``{% for error in field.errors %}`` loop. In this
308        case, each object in the loop is a simple string containing the error
309        message.
310
311    ``field.is_hidden``
312        This attribute is ``True`` if the form field is a hidden field and
313        ``False`` otherwise. It's not particularly useful as a template
314        variable, but could be useful in conditional tests such as::
315
316            {% if field.is_hidden %}
317               {# Do something special #}
318            {% endif %}
319
320Looping over hidden and visible fields
321~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
322
323If you're manually laying out a form in a template, as opposed to relying on
324Django's default form layout, you might want to treat ``<input type="hidden">``
325fields differently than non-hidden fields. For example, because hidden fields
326don't display anything, putting error messages "next to" the field could cause
327confusion for your users -- so errors for those fields should be handled
328differently.
329
330Django provides two methods on a form that allow you to loop over the hidden
331and visible fields independently: ``hidden_fields()`` and
332``visible_fields()``. Here's a modification of an earlier example that uses
333these two methods::
334
335    <form action="/contact/" method="post">
336        {% for field in form.visible_fields %}
337            <div class="fieldWrapper">
338
339                {# Include the hidden fields in the form #}
340                {% if forloop.first %}
341                    {% for hidden in form.hidden_fields %}
342                    {{ hidden }}
343                    {% endfor %}
344                {% endif %}
345
346                {{ field.errors }}
347                {{ field.label_tag }}: {{ field }}
348            </div>
349        {% endfor %}
350        <p><input type="submit" value="Send message" /></p>
351    </form>
352
353This example does not handle any errors in the hidden fields. Usually, an
354error in a hidden field is a sign of form tampering, since normal form
355interaction won't alter them. However, you could easily insert some error
356displays for those form errors, as well.
357
358Reusable form templates
359-----------------------
360
361If your site uses the same rendering logic for forms in multiple places, you
362can reduce duplication by saving the form's loop in a standalone template and
363using the :ttag:`include` tag to reuse it in other templates::
364
365    <form action="/contact/" method="post">
366        {% include "form_snippet.html" %}
367        <p><input type="submit" value="Send message" /></p>
368    </form>
369
370    # In form_snippet.html:
371
372    {% for field in form %}
373        <div class="fieldWrapper">
374            {{ field.errors }}
375            {{ field.label_tag }}: {{ field }}
376        </div>
377    {% endfor %}
378
379If the form object passed to a template has a different name within the
380context, you can alias it using the ``with`` argument of the :ttag:`include`
381tag::
382
383    <form action="/comments/add/" method="post">
384        {% include "form_snippet.html" with form=comment_form %}
385        <p><input type="submit" value="Submit comment" /></p>
386    </form>
387
388If you find yourself doing this often, you might consider creating a custom
389:ref:`inclusion tag<howto-custom-template-tags-inclusion-tags>`.
390
391Further topics
392==============
393
394This covers the basics, but forms can do a whole lot more:
395
396.. toctree::
397   :maxdepth: 2
398
399   formsets
400   modelforms
401   media
402
403.. seealso::
404
405    :doc:`The Forms Reference </ref/forms/index>`
406        Covers the full API reference, including form fields, form widgets,
407        and form and field validation.