PageRenderTime 59ms CodeModel.GetById 30ms app.highlight 6ms RepoModel.GetById 14ms app.codeStats 0ms

/docs/ref/forms/api.txt

https://code.google.com/p/mango-py/
Plain Text | 799 lines | 630 code | 169 blank | 0 comment | 0 complexity | c9016b67da6480ed1d1ba7f645398ded MD5 | raw file
  1=============
  2The Forms API
  3=============
  4
  5.. module:: django.forms.forms
  6
  7.. currentmodule:: django.forms
  8
  9.. admonition:: About this document
 10
 11    This document covers the gritty details of Django's forms API. You should
 12    read the :doc:`introduction to working with forms </topics/forms/index>`
 13    first.
 14
 15.. _ref-forms-api-bound-unbound:
 16
 17Bound and unbound forms
 18-----------------------
 19
 20A :class:`Form` instance is either **bound** to a set of data, or **unbound**.
 21
 22    * If it's **bound** to a set of data, it's capable of validating that data
 23      and rendering the form as HTML with the data displayed in the HTML.
 24
 25    * If it's **unbound**, it cannot do validation (because there's no data to
 26      validate!), but it can still render the blank form as HTML.
 27
 28.. class:: Form
 29
 30To create an unbound :class:`Form` instance, simply instantiate the class::
 31
 32    >>> f = ContactForm()
 33
 34To bind data to a form, pass the data as a dictionary as the first parameter to
 35your :class:`Form` class constructor::
 36
 37    >>> data = {'subject': 'hello',
 38    ...         'message': 'Hi there',
 39    ...         'sender': 'foo@example.com',
 40    ...         'cc_myself': True}
 41    >>> f = ContactForm(data)
 42
 43In this dictionary, the keys are the field names, which correspond to the
 44attributes in your :class:`Form` class. The values are the data you're trying to
 45validate. These will usually be strings, but there's no requirement that they be
 46strings; the type of data you pass depends on the :class:`Field`, as we'll see
 47in a moment.
 48
 49.. attribute:: Form.is_bound
 50
 51If you need to distinguish between bound and unbound form instances at runtime,
 52check the value of the form's :attr:`~Form.is_bound` attribute::
 53
 54    >>> f = ContactForm()
 55    >>> f.is_bound
 56    False
 57    >>> f = ContactForm({'subject': 'hello'})
 58    >>> f.is_bound
 59    True
 60
 61Note that passing an empty dictionary creates a *bound* form with empty data::
 62
 63    >>> f = ContactForm({})
 64    >>> f.is_bound
 65    True
 66
 67If you have a bound :class:`Form` instance and want to change the data somehow,
 68or if you want to bind an unbound :class:`Form` instance to some data, create
 69another :class:`Form` instance. There is no way to change data in a
 70:class:`Form` instance. Once a :class:`Form` instance has been created, you
 71should consider its data immutable, whether it has data or not.
 72
 73Using forms to validate data
 74----------------------------
 75
 76.. method:: Form.is_valid()
 77
 78The primary task of a :class:`Form` object is to validate data. With a bound
 79:class:`Form` instance, call the :meth:`~Form.is_valid` method to run validation
 80and return a boolean designating whether the data was valid::
 81
 82    >>> data = {'subject': 'hello',
 83    ...         'message': 'Hi there',
 84    ...         'sender': 'foo@example.com',
 85    ...         'cc_myself': True}
 86    >>> f = ContactForm(data)
 87    >>> f.is_valid()
 88    True
 89
 90Let's try with some invalid data. In this case, ``subject`` is blank (an error,
 91because all fields are required by default) and ``sender`` is not a valid
 92e-mail address::
 93
 94    >>> data = {'subject': '',
 95    ...         'message': 'Hi there',
 96    ...         'sender': 'invalid e-mail address',
 97    ...         'cc_myself': True}
 98    >>> f = ContactForm(data)
 99    >>> f.is_valid()
100    False
101
102.. attribute:: Form.errors
103
104Access the :attr:`~Form.errors` attribute to get a dictionary of error
105messages::
106
107    >>> f.errors
108    {'sender': [u'Enter a valid e-mail address.'], 'subject': [u'This field is required.']}
109
110In this dictionary, the keys are the field names, and the values are lists of
111Unicode strings representing the error messages. The error messages are stored
112in lists because a field can have multiple error messages.
113
114You can access :attr:`~Form.errors` without having to call
115:meth:`~Form.is_valid` first. The form's data will be validated the first time
116either you call :meth:`~Form.is_valid` or access :attr:`~Form.errors`.
117
118The validation routines will only get called once, regardless of how many times
119you access :attr:`~Form.errors` or call :meth:`~Form.is_valid`. This means that
120if validation has side effects, those side effects will only be triggered once.
121
122Behavior of unbound forms
123~~~~~~~~~~~~~~~~~~~~~~~~~
124
125It's meaningless to validate a form with no data, but, for the record, here's
126what happens with unbound forms::
127
128    >>> f = ContactForm()
129    >>> f.is_valid()
130    False
131    >>> f.errors
132    {}
133
134Dynamic initial values
135----------------------
136
137.. attribute:: Form.initial
138
139Use :attr:`~Form.initial` to declare the initial value of form fields at
140runtime. For example, you might want to fill in a ``username`` field with the
141username of the current session.
142
143To accomplish this, use the :attr:`~Form.initial` argument to a :class:`Form`.
144This argument, if given, should be a dictionary mapping field names to initial
145values. Only include the fields for which you're specifying an initial value;
146it's not necessary to include every field in your form. For example::
147
148    >>> f = ContactForm(initial={'subject': 'Hi there!'})
149
150These values are only displayed for unbound forms, and they're not used as
151fallback values if a particular value isn't provided.
152
153Note that if a :class:`~django.forms.fields.Field` defines
154:attr:`~Form.initial` *and* you include ``initial`` when instantiating the
155``Form``, then the latter ``initial`` will have precedence. In this example,
156``initial`` is provided both at the field level and at the form instance level,
157and the latter gets precedence::
158
159    >>> class CommentForm(forms.Form):
160    ...     name = forms.CharField(initial='class')
161    ...     url = forms.URLField()
162    ...     comment = forms.CharField()
163    >>> f = CommentForm(initial={'name': 'instance'}, auto_id=False)
164    >>> print f
165    <tr><th>Name:</th><td><input type="text" name="name" value="instance" /></td></tr>
166    <tr><th>Url:</th><td><input type="text" name="url" /></td></tr>
167    <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
168
169Accessing "clean" data
170----------------------
171
172.. attribute:: Form.cleaned_data
173
174Each field in a :class:`Form` class is responsible not only for validating
175data, but also for "cleaning" it -- normalizing it to a consistent format. This
176is a nice feature, because it allows data for a particular field to be input in
177a variety of ways, always resulting in consistent output.
178
179For example, :class:`~django.forms.DateField` normalizes input into a
180Python ``datetime.date`` object. Regardless of whether you pass it a string in
181the format ``'1994-07-15'``, a ``datetime.date`` object, or a number of other
182formats, ``DateField`` will always normalize it to a ``datetime.date`` object
183as long as it's valid.
184
185Once you've created a :class:`~Form` instance with a set of data and validated
186it, you can access the clean data via its ``cleaned_data`` attribute::
187
188    >>> data = {'subject': 'hello',
189    ...         'message': 'Hi there',
190    ...         'sender': 'foo@example.com',
191    ...         'cc_myself': True}
192    >>> f = ContactForm(data)
193    >>> f.is_valid()
194    True
195    >>> f.cleaned_data
196    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
197
198Note that any text-based field -- such as ``CharField`` or ``EmailField`` --
199always cleans the input into a Unicode string. We'll cover the encoding
200implications later in this document.
201
202If your data does *not* validate, your ``Form`` instance will not have a
203``cleaned_data`` attribute::
204
205    >>> data = {'subject': '',
206    ...         'message': 'Hi there',
207    ...         'sender': 'invalid e-mail address',
208    ...         'cc_myself': True}
209    >>> f = ContactForm(data)
210    >>> f.is_valid()
211    False
212    >>> f.cleaned_data
213    Traceback (most recent call last):
214    ...
215    AttributeError: 'ContactForm' object has no attribute 'cleaned_data'
216
217``cleaned_data`` will always *only* contain a key for fields defined in the
218``Form``, even if you pass extra data when you define the ``Form``. In this
219example, we pass a bunch of extra fields to the ``ContactForm`` constructor,
220but ``cleaned_data`` contains only the form's fields::
221
222    >>> data = {'subject': 'hello',
223    ...         'message': 'Hi there',
224    ...         'sender': 'foo@example.com',
225    ...         'cc_myself': True,
226    ...         'extra_field_1': 'foo',
227    ...         'extra_field_2': 'bar',
228    ...         'extra_field_3': 'baz'}
229    >>> f = ContactForm(data)
230    >>> f.is_valid()
231    True
232    >>> f.cleaned_data # Doesn't contain extra_field_1, etc.
233    {'cc_myself': True, 'message': u'Hi there', 'sender': u'foo@example.com', 'subject': u'hello'}
234
235``cleaned_data`` will include a key and value for *all* fields defined in the
236``Form``, even if the data didn't include a value for fields that are not
237required. In this example, the data dictionary doesn't include a value for the
238``nick_name`` field, but ``cleaned_data`` includes it, with an empty value::
239
240    >>> class OptionalPersonForm(Form):
241    ...     first_name = CharField()
242    ...     last_name = CharField()
243    ...     nick_name = CharField(required=False)
244    >>> data = {'first_name': u'John', 'last_name': u'Lennon'}
245    >>> f = OptionalPersonForm(data)
246    >>> f.is_valid()
247    True
248    >>> f.cleaned_data
249    {'nick_name': u'', 'first_name': u'John', 'last_name': u'Lennon'}
250
251In this above example, the ``cleaned_data`` value for ``nick_name`` is set to an
252empty string, because ``nick_name`` is ``CharField``, and ``CharField``\s treat
253empty values as an empty string. Each field type knows what its "blank" value
254is -- e.g., for ``DateField``, it's ``None`` instead of the empty string. For
255full details on each field's behavior in this case, see the "Empty value" note
256for each field in the "Built-in ``Field`` classes" section below.
257
258You can write code to perform validation for particular form fields (based on
259their name) or for the form as a whole (considering combinations of various
260fields). More information about this is in :doc:`/ref/forms/validation`.
261
262Outputting forms as HTML
263------------------------
264
265The second task of a ``Form`` object is to render itself as HTML. To do so,
266simply ``print`` it::
267
268    >>> f = ContactForm()
269    >>> print f
270    <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
271    <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
272    <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>
273    <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>
274
275If the form is bound to data, the HTML output will include that data
276appropriately. For example, if a field is represented by an
277``<input type="text">``, the data will be in the ``value`` attribute. If a
278field is represented by an ``<input type="checkbox">``, then that HTML will
279include ``checked="checked"`` if appropriate::
280
281    >>> data = {'subject': 'hello',
282    ...         'message': 'Hi there',
283    ...         'sender': 'foo@example.com',
284    ...         'cc_myself': True}
285    >>> f = ContactForm(data)
286    >>> print f
287    <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" value="hello" /></td></tr>
288    <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" value="Hi there" /></td></tr>
289    <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" value="foo@example.com" /></td></tr>
290    <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" checked="checked" /></td></tr>
291
292This default output is a two-column HTML table, with a ``<tr>`` for each field.
293Notice the following:
294
295    * For flexibility, the output does *not* include the ``<table>`` and
296      ``</table>`` tags, nor does it include the ``<form>`` and ``</form>``
297      tags or an ``<input type="submit">`` tag. It's your job to do that.
298
299    * Each field type has a default HTML representation. ``CharField`` and
300      ``EmailField`` are represented by an ``<input type="text">``.
301      ``BooleanField`` is represented by an ``<input type="checkbox">``. Note
302      these are merely sensible defaults; you can specify which HTML to use for
303      a given field by using widgets, which we'll explain shortly.
304
305    * The HTML ``name`` for each tag is taken directly from its attribute name
306      in the ``ContactForm`` class.
307
308    * The text label for each field -- e.g. ``'Subject:'``, ``'Message:'`` and
309      ``'Cc myself:'`` is generated from the field name by converting all
310      underscores to spaces and upper-casing the first letter. Again, note
311      these are merely sensible defaults; you can also specify labels manually.
312
313    * Each text label is surrounded in an HTML ``<label>`` tag, which points
314      to the appropriate form field via its ``id``. Its ``id``, in turn, is
315      generated by prepending ``'id_'`` to the field name. The ``id``
316      attributes and ``<label>`` tags are included in the output by default, to
317      follow best practices, but you can change that behavior.
318
319Although ``<table>`` output is the default output style when you ``print`` a
320form, other output styles are available. Each style is available as a method on
321a form object, and each rendering method returns a Unicode object.
322
323``as_p()``
324~~~~~~~~~~
325
326.. method:: Form.as_p
327
328    ``as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>``
329    containing one field::
330
331        >>> f = ContactForm()
332        >>> f.as_p()
333        u'<p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>\n<p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>\n<p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p>\n<p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>'
334        >>> print f.as_p()
335        <p><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></p>
336        <p><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></p>
337        <p><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></p>
338        <p><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></p>
339
340``as_ul()``
341~~~~~~~~~~~
342
343.. method:: Form.as_ul
344
345    ``as_ul()`` renders the form as a series of ``<li>`` tags, with each
346    ``<li>`` containing one field. It does *not* include the ``<ul>`` or
347    ``</ul>``, so that you can specify any HTML attributes on the ``<ul>`` for
348    flexibility::
349
350        >>> f = ContactForm()
351        >>> f.as_ul()
352        u'<li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>\n<li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>\n<li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>\n<li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>'
353        >>> print f.as_ul()
354        <li><label for="id_subject">Subject:</label> <input id="id_subject" type="text" name="subject" maxlength="100" /></li>
355        <li><label for="id_message">Message:</label> <input type="text" name="message" id="id_message" /></li>
356        <li><label for="id_sender">Sender:</label> <input type="text" name="sender" id="id_sender" /></li>
357        <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_cc_myself" /></li>
358
359``as_table()``
360~~~~~~~~~~~~~~
361
362.. method:: Form.as_table
363
364    Finally, ``as_table()`` outputs the form as an HTML ``<table>``. This is
365    exactly the same as ``print``. In fact, when you ``print`` a form object,
366    it calls its ``as_table()`` method behind the scenes::
367
368        >>> f = ContactForm()
369        >>> f.as_table()
370        u'<tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>\n<tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>\n<tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>\n<tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>'
371        >>> print f.as_table()
372        <tr><th><label for="id_subject">Subject:</label></th><td><input id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
373        <tr><th><label for="id_message">Message:</label></th><td><input type="text" name="message" id="id_message" /></td></tr>
374        <tr><th><label for="id_sender">Sender:</label></th><td><input type="text" name="sender" id="id_sender" /></td></tr>
375        <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>
376
377Styling required or erroneous form rows
378~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
379
380.. versionadded:: 1.2
381
382It's pretty common to style form rows and fields that are required or have
383errors. For example, you might want to present required form rows in bold and
384highlight errors in red.
385
386The :class:`Form` class has a couple of hooks you can use to add ``class``
387attributes to required rows or to rows with errors: simply set the
388:attr:`Form.error_css_class` and/or :attr:`Form.required_css_class`
389attributes::
390
391    class ContactForm(Form):
392        error_css_class = 'error'
393        required_css_class = 'required'
394
395        # ... and the rest of your fields here
396
397Once you've done that, rows will be given ``"error"`` and/or ``"required"``
398classes, as needed. The HTML will look something like::
399
400    >>> f = ContactForm(data)
401    >>> print f.as_table()
402    <tr class="required"><th><label for="id_subject">Subject:</label>    ...
403    <tr class="required"><th><label for="id_message">Message:</label>    ...
404    <tr class="required error"><th><label for="id_sender">Sender:</label>      ...
405    <tr><th><label for="id_cc_myself">Cc myself:<label> ...
406
407.. _ref-forms-api-configuring-label:
408
409Configuring HTML ``<label>`` tags
410~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
411
412An HTML ``<label>`` tag designates which label text is associated with which
413form element. This small enhancement makes forms more usable and more accessible
414to assistive devices. It's always a good idea to use ``<label>`` tags.
415
416By default, the form rendering methods include HTML ``id`` attributes on the
417form elements and corresponding ``<label>`` tags around the labels. The ``id``
418attribute values are generated by prepending ``id_`` to the form field names.
419This behavior is configurable, though, if you want to change the ``id``
420convention or remove HTML ``id`` attributes and ``<label>`` tags entirely.
421
422Use the ``auto_id`` argument to the ``Form`` constructor to control the label
423and ``id`` behavior. This argument must be ``True``, ``False`` or a string.
424
425If ``auto_id`` is ``False``, then the form output will not include ``<label>``
426tags nor ``id`` attributes::
427
428    >>> f = ContactForm(auto_id=False)
429    >>> print f.as_table()
430    <tr><th>Subject:</th><td><input type="text" name="subject" maxlength="100" /></td></tr>
431    <tr><th>Message:</th><td><input type="text" name="message" /></td></tr>
432    <tr><th>Sender:</th><td><input type="text" name="sender" /></td></tr>
433    <tr><th>Cc myself:</th><td><input type="checkbox" name="cc_myself" /></td></tr>
434    >>> print f.as_ul()
435    <li>Subject: <input type="text" name="subject" maxlength="100" /></li>
436    <li>Message: <input type="text" name="message" /></li>
437    <li>Sender: <input type="text" name="sender" /></li>
438    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
439    >>> print f.as_p()
440    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
441    <p>Message: <input type="text" name="message" /></p>
442    <p>Sender: <input type="text" name="sender" /></p>
443    <p>Cc myself: <input type="checkbox" name="cc_myself" /></p>
444
445If ``auto_id`` is set to ``True``, then the form output *will* include
446``<label>`` tags and will simply use the field name as its ``id`` for each form
447field::
448
449    >>> f = ContactForm(auto_id=True)
450    >>> print f.as_table()
451    <tr><th><label for="subject">Subject:</label></th><td><input id="subject" type="text" name="subject" maxlength="100" /></td></tr>
452    <tr><th><label for="message">Message:</label></th><td><input type="text" name="message" id="message" /></td></tr>
453    <tr><th><label for="sender">Sender:</label></th><td><input type="text" name="sender" id="sender" /></td></tr>
454    <tr><th><label for="cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="cc_myself" /></td></tr>
455    >>> print f.as_ul()
456    <li><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></li>
457    <li><label for="message">Message:</label> <input type="text" name="message" id="message" /></li>
458    <li><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></li>
459    <li><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></li>
460    >>> print f.as_p()
461    <p><label for="subject">Subject:</label> <input id="subject" type="text" name="subject" maxlength="100" /></p>
462    <p><label for="message">Message:</label> <input type="text" name="message" id="message" /></p>
463    <p><label for="sender">Sender:</label> <input type="text" name="sender" id="sender" /></p>
464    <p><label for="cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="cc_myself" /></p>
465
466If ``auto_id`` is set to a string containing the format character ``'%s'``,
467then the form output will include ``<label>`` tags, and will generate ``id``
468attributes based on the format string. For example, for a format string
469``'field_%s'``, a field named ``subject`` will get the ``id`` value
470``'field_subject'``. Continuing our example::
471
472    >>> f = ContactForm(auto_id='id_for_%s')
473    >>> print f.as_table()
474    <tr><th><label for="id_for_subject">Subject:</label></th><td><input id="id_for_subject" type="text" name="subject" maxlength="100" /></td></tr>
475    <tr><th><label for="id_for_message">Message:</label></th><td><input type="text" name="message" id="id_for_message" /></td></tr>
476    <tr><th><label for="id_for_sender">Sender:</label></th><td><input type="text" name="sender" id="id_for_sender" /></td></tr>
477    <tr><th><label for="id_for_cc_myself">Cc myself:</label></th><td><input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></td></tr>
478    >>> print f.as_ul()
479    <li><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
480    <li><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></li>
481    <li><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></li>
482    <li><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
483    >>> print f.as_p()
484    <p><label for="id_for_subject">Subject:</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></p>
485    <p><label for="id_for_message">Message:</label> <input type="text" name="message" id="id_for_message" /></p>
486    <p><label for="id_for_sender">Sender:</label> <input type="text" name="sender" id="id_for_sender" /></p>
487    <p><label for="id_for_cc_myself">Cc myself:</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></p>
488
489If ``auto_id`` is set to any other true value -- such as a string that doesn't
490include ``%s`` -- then the library will act as if ``auto_id`` is ``True``.
491
492By default, ``auto_id`` is set to the string ``'id_%s'``.
493
494Normally, a colon (``:``) will be appended after any label name when a form is
495rendered. It's possible to change the colon to another character, or omit it
496entirely, using the ``label_suffix`` parameter::
497
498    >>> f = ContactForm(auto_id='id_for_%s', label_suffix='')
499    >>> print f.as_ul()
500    <li><label for="id_for_subject">Subject</label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
501    <li><label for="id_for_message">Message</label> <input type="text" name="message" id="id_for_message" /></li>
502    <li><label for="id_for_sender">Sender</label> <input type="text" name="sender" id="id_for_sender" /></li>
503    <li><label for="id_for_cc_myself">Cc myself</label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
504    >>> f = ContactForm(auto_id='id_for_%s', label_suffix=' ->')
505    >>> print f.as_ul()
506    <li><label for="id_for_subject">Subject -></label> <input id="id_for_subject" type="text" name="subject" maxlength="100" /></li>
507    <li><label for="id_for_message">Message -></label> <input type="text" name="message" id="id_for_message" /></li>
508    <li><label for="id_for_sender">Sender -></label> <input type="text" name="sender" id="id_for_sender" /></li>
509    <li><label for="id_for_cc_myself">Cc myself -></label> <input type="checkbox" name="cc_myself" id="id_for_cc_myself" /></li>
510
511Note that the label suffix is added only if the last character of the
512label isn't a punctuation character (``.``, ``!``, ``?`` or ``:``)
513
514Notes on field ordering
515~~~~~~~~~~~~~~~~~~~~~~~
516
517In the ``as_p()``, ``as_ul()`` and ``as_table()`` shortcuts, the fields are
518displayed in the order in which you define them in your form class. For
519example, in the ``ContactForm`` example, the fields are defined in the order
520``subject``, ``message``, ``sender``, ``cc_myself``. To reorder the HTML
521output, just change the order in which those fields are listed in the class.
522
523How errors are displayed
524~~~~~~~~~~~~~~~~~~~~~~~~
525
526If you render a bound ``Form`` object, the act of rendering will automatically
527run the form's validation if it hasn't already happened, and the HTML output
528will include the validation errors as a ``<ul class="errorlist">`` near the
529field. The particular positioning of the error messages depends on the output
530method you're using::
531
532    >>> data = {'subject': '',
533    ...         'message': 'Hi there',
534    ...         'sender': 'invalid e-mail address',
535    ...         'cc_myself': True}
536    >>> f = ContactForm(data, auto_id=False)
537    >>> print f.as_table()
538    <tr><th>Subject:</th><td><ul class="errorlist"><li>This field is required.</li></ul><input type="text" name="subject" maxlength="100" /></td></tr>
539    <tr><th>Message:</th><td><input type="text" name="message" value="Hi there" /></td></tr>
540    <tr><th>Sender:</th><td><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul><input type="text" name="sender" value="invalid e-mail address" /></td></tr>
541    <tr><th>Cc myself:</th><td><input checked="checked" type="checkbox" name="cc_myself" /></td></tr>
542    >>> print f.as_ul()
543    <li><ul class="errorlist"><li>This field is required.</li></ul>Subject: <input type="text" name="subject" maxlength="100" /></li>
544    <li>Message: <input type="text" name="message" value="Hi there" /></li>
545    <li><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul>Sender: <input type="text" name="sender" value="invalid e-mail address" /></li>
546    <li>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></li>
547    >>> print f.as_p()
548    <p><ul class="errorlist"><li>This field is required.</li></ul></p>
549    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
550    <p>Message: <input type="text" name="message" value="Hi there" /></p>
551    <p><ul class="errorlist"><li>Enter a valid e-mail address.</li></ul></p>
552    <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
553    <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
554
555Customizing the error list format
556~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
557
558By default, forms use ``django.forms.util.ErrorList`` to format validation
559errors. If you'd like to use an alternate class for displaying errors, you can
560pass that in at construction time::
561
562    >>> from django.forms.util import ErrorList
563    >>> class DivErrorList(ErrorList):
564    ...     def __unicode__(self):
565    ...         return self.as_divs()
566    ...     def as_divs(self):
567    ...         if not self: return u''
568    ...         return u'<div class="errorlist">%s</div>' % ''.join([u'<div class="error">%s</div>' % e for e in self])
569    >>> f = ContactForm(data, auto_id=False, error_class=DivErrorList)
570    >>> f.as_p()
571    <div class="errorlist"><div class="error">This field is required.</div></div>
572    <p>Subject: <input type="text" name="subject" maxlength="100" /></p>
573    <p>Message: <input type="text" name="message" value="Hi there" /></p>
574    <div class="errorlist"><div class="error">Enter a valid e-mail address.</div></div>
575    <p>Sender: <input type="text" name="sender" value="invalid e-mail address" /></p>
576    <p>Cc myself: <input checked="checked" type="checkbox" name="cc_myself" /></p>
577
578More granular output
579~~~~~~~~~~~~~~~~~~~~
580
581The ``as_p()``, ``as_ul()`` and ``as_table()`` methods are simply shortcuts for
582lazy developers -- they're not the only way a form object can be displayed.
583
584.. class:: BoundField
585
586   Used to display HTML or access attributes for a single field of a
587   :class:`Form` instance.
588   
589   The :meth:`__unicode__` and :meth:`__str__` methods of this object displays
590   the HTML for this field.
591
592To retrieve a single ``BoundField``, use dictionary lookup syntax on your form
593using the field's name as the key::
594
595	>>> form = ContactForm()
596	>>> print form['subject']
597	<input id="id_subject" type="text" name="subject" maxlength="100" />
598
599To retrieve all ``BoundField`` objects, iterate the form::
600
601	>>> form = ContactForm()
602	>>> for boundfield in form: print boundfield
603	<input id="id_subject" type="text" name="subject" maxlength="100" />
604	<input type="text" name="message" id="id_message" />
605	<input type="text" name="sender" id="id_sender" />
606	<input type="checkbox" name="cc_myself" id="id_cc_myself" />
607
608The field-specific output honors the form object's ``auto_id`` setting::
609
610    >>> f = ContactForm(auto_id=False)
611    >>> print f['message']
612    <input type="text" name="message" />
613    >>> f = ContactForm(auto_id='id_%s')
614    >>> print f['message']
615    <input type="text" name="message" id="id_message" />
616
617For a field's list of errors, access the field's ``errors`` attribute.
618
619.. attribute:: BoundField.errors
620
621    A list-like object that is displayed as an HTML ``<ul class="errorlist">``
622    when printed::
623
624        >>> data = {'subject': 'hi', 'message': '', 'sender': '', 'cc_myself': ''}
625        >>> f = ContactForm(data, auto_id=False)
626        >>> print f['message']
627        <input type="text" name="message" />
628        >>> f['message'].errors
629        [u'This field is required.']
630        >>> print f['message'].errors
631        <ul class="errorlist"><li>This field is required.</li></ul>
632        >>> f['subject'].errors
633        []
634        >>> print f['subject'].errors
635
636        >>> str(f['subject'].errors)
637	    ''
638
639.. method:: BoundField.css_classes()
640
641   .. versionadded:: 1.2
642
643When you use Django's rendering shortcuts, CSS classes are used to
644indicate required form fields or fields that contain errors. If you're
645manually rendering a form, you can access these CSS classes using the
646``css_classes`` method::
647
648	>>> f = ContactForm(data)
649	>>> f['message'].css_classes()
650	'required'
651
652If you want to provide some additional classes in addition to the
653error and required classes that may be required, you can provide
654those classes as an argument::
655
656	>>> f = ContactForm(data)
657	>>> f['message'].css_classes('foo bar')
658	'foo bar required'
659
660.. method:: BoundField.value()
661
662   .. versionadded:: 1.3
663
664Use this method to render the raw value of this field as it would be rendered
665by a ``Widget``::
666
667    >>> initial = {'subject': 'welcome'}
668    >>> unbound_form = ContactForm(initial=initial)
669    >>> bound_form = ContactForm(data, initial=initial)
670    >>> print unbound_form['subject'].value()
671    welcome
672    >>> print bound_form['subject'].value()
673    hi
674
675.. _binding-uploaded-files:
676
677Binding uploaded files to a form
678--------------------------------
679
680Dealing with forms that have ``FileField`` and ``ImageField`` fields
681is a little more complicated than a normal form.
682
683Firstly, in order to upload files, you'll need to make sure that your
684``<form>`` element correctly defines the ``enctype`` as
685``"multipart/form-data"``::
686
687  <form enctype="multipart/form-data" method="post" action="/foo/">
688
689Secondly, when you use the form, you need to bind the file data. File
690data is handled separately to normal form data, so when your form
691contains a ``FileField`` and ``ImageField``, you will need to specify
692a second argument when you bind your form. So if we extend our
693ContactForm to include an ``ImageField`` called ``mugshot``, we
694need to bind the file data containing the mugshot image::
695
696    # Bound form with an image field
697    >>> from django.core.files.uploadedfile import SimpleUploadedFile
698    >>> data = {'subject': 'hello',
699    ...         'message': 'Hi there',
700    ...         'sender': 'foo@example.com',
701    ...         'cc_myself': True}
702    >>> file_data = {'mugshot': SimpleUploadedFile('face.jpg', <file data>)}
703    >>> f = ContactFormWithMugshot(data, file_data)
704
705In practice, you will usually specify ``request.FILES`` as the source
706of file data (just like you use ``request.POST`` as the source of
707form data)::
708
709    # Bound form with an image field, data from the request
710    >>> f = ContactFormWithMugshot(request.POST, request.FILES)
711
712Constructing an unbound form is the same as always -- just omit both
713form data *and* file data::
714
715    # Unbound form with a image field
716    >>> f = ContactFormWithMugshot()
717
718Testing for multipart forms
719~~~~~~~~~~~~~~~~~~~~~~~~~~~
720
721If you're writing reusable views or templates, you may not know ahead of time
722whether your form is a multipart form or not. The ``is_multipart()`` method
723tells you whether the form requires multipart encoding for submission::
724
725    >>> f = ContactFormWithMugshot()
726    >>> f.is_multipart()
727    True
728
729Here's an example of how you might use this in a template::
730
731    {% if form.is_multipart %}
732        <form enctype="multipart/form-data" method="post" action="/foo/">
733    {% else %}
734        <form method="post" action="/foo/">
735    {% endif %}
736    {{ form }}
737    </form>
738
739Subclassing forms
740-----------------
741
742If you have multiple ``Form`` classes that share fields, you can use
743subclassing to remove redundancy.
744
745When you subclass a custom ``Form`` class, the resulting subclass will
746include all fields of the parent class(es), followed by the fields you define
747in the subclass.
748
749In this example, ``ContactFormWithPriority`` contains all the fields from
750``ContactForm``, plus an additional field, ``priority``. The ``ContactForm``
751fields are ordered first::
752
753    >>> class ContactFormWithPriority(ContactForm):
754    ...     priority = forms.CharField()
755    >>> f = ContactFormWithPriority(auto_id=False)
756    >>> print f.as_ul()
757    <li>Subject: <input type="text" name="subject" maxlength="100" /></li>
758    <li>Message: <input type="text" name="message" /></li>
759    <li>Sender: <input type="text" name="sender" /></li>
760    <li>Cc myself: <input type="checkbox" name="cc_myself" /></li>
761    <li>Priority: <input type="text" name="priority" /></li>
762
763It's possible to subclass multiple forms, treating forms as "mix-ins." In this
764example, ``BeatleForm`` subclasses both ``PersonForm`` and ``InstrumentForm``
765(in that order), and its field list includes the fields from the parent
766classes::
767
768    >>> class PersonForm(Form):
769    ...     first_name = CharField()
770    ...     last_name = CharField()
771    >>> class InstrumentForm(Form):
772    ...     instrument = CharField()
773    >>> class BeatleForm(PersonForm, InstrumentForm):
774    ...     haircut_type = CharField()
775    >>> b = BeatleForm(auto_id=False)
776    >>> print b.as_ul()
777    <li>First name: <input type="text" name="first_name" /></li>
778    <li>Last name: <input type="text" name="last_name" /></li>
779    <li>Instrument: <input type="text" name="instrument" /></li>
780    <li>Haircut type: <input type="text" name="haircut_type" /></li>
781
782.. _form-prefix:
783
784Prefixes for forms
785------------------
786
787.. attribute:: Form.prefix
788
789You can put several Django forms inside one ``<form>`` tag. To give each
790``Form`` its own namespace, use the ``prefix`` keyword argument::
791
792    >>> mother = PersonForm(prefix="mother")
793    >>> father = PersonForm(prefix="father")
794    >>> print mother.as_ul()
795    <li><label for="id_mother-first_name">First name:</label> <input type="text" name="mother-first_name" id="id_mother-first_name" /></li>
796    <li><label for="id_mother-last_name">Last name:</label> <input type="text" name="mother-last_name" id="id_mother-last_name" /></li>
797    >>> print father.as_ul()
798    <li><label for="id_father-first_name">First name:</label> <input type="text" name="father-first_name" id="id_father-first_name" /></li>
799    <li><label for="id_father-last_name">Last name:</label> <input type="text" name="father-last_name" id="id_father-last_name" /></li>