Author: gwilson
Date: 2009-12-25 14:51:30 -0600 (Fri, 25 Dec 2009)
New Revision: 11984
Modified:
django/trunk/docs/ref/forms/api.txt
django/trunk/docs/ref/templates/api.txt
Log:
Added a few Sphinx directives to the form API and template API docs.
Modified: django/trunk/docs/ref/forms/api.txt
===================================================================
--- django/trunk/docs/ref/forms/api.txt 2009-12-25 14:37:57 UTC (rev 11983)
+++ django/trunk/docs/ref/forms/api.txt 2009-12-25 20:51:30 UTC (rev 11984)
@@ -4,6 +4,8 @@
The Forms API
=============
+.. module:: django.forms.forms
+
.. currentmodule:: django.forms
.. admonition:: About this document
@@ -25,6 +27,8 @@
* If it's **unbound**, it cannot do validation (because there's no data to
validate!), but it can still render the blank form as HTML.
+.. class:: Form
+
To create an unbound :class:`Form` instance, simply instantiate the class::
>>> f = ContactForm()
@@ -134,24 +138,25 @@
.. attribute:: Form.initial
-Use ``initial`` to declare the initial value of form fields at runtime. For
-example, you might want to fill in a ``username`` field with the username of
the
-current session.
+Use :attr:`~Form.initial` to declare the initial value of form fields at
+runtime. For example, you might want to fill in a ``username`` field with the
+username of the current session.
-To accomplish this, use the ``initial`` argument to a ``Form``. This argument,
-if given, should be a dictionary mapping field names to initial values. Only
-include the fields for which you're specifying an initial value; it's not
-necessary to include every field in your form. For example::
+To accomplish this, use the :attr:`~Form.initial` argument to a :class:`Form`.
+This argument, if given, should be a dictionary mapping field names to initial
+values. Only include the fields for which you're specifying an initial value;
+it's not necessary to include every field in your form. For example::
>>> f = ContactForm(initial={'subject': 'Hi there!'})
These values are only displayed for unbound forms, and they're not used as
fallback values if a particular value isn't provided.
-Note that if a ``Field`` defines ``initial`` *and* you include ``initial`` when
-instantiating the ``Form``, then the latter ``initial`` will have precedence.
In
-this example, ``initial`` is provided both at the field level and at the form
-instance level, and the latter gets precedence::
+Note that if a :class:`~django.forms.fields.Field` defines
+:attr:`~Form.initial` *and* you include ``initial`` when instantiating the
+``Form``, then the latter ``initial`` will have precedence. In this example,
+``initial`` is provided both at the field level and at the form instance level,
+and the latter gets precedence::
>>> class CommentForm(forms.Form):
... name = forms.CharField(initial='class')
@@ -166,20 +171,21 @@
Accessing "clean" data
----------------------
-Each ``Field`` in a ``Form`` class is responsible not only for validating data,
-but also for "cleaning" it -- normalizing it to a consistent format. This is a
-nice feature, because it allows data for a particular field to be input in
+.. attribute:: Form.cleaned_data
+
+Each field in a :class:`Form` class is responsible not only for validating
+data, but also for "cleaning" it -- normalizing it to a consistent format. This
+is a nice feature, because it allows data for a particular field to be input in
a variety of ways, always resulting in consistent output.
-For example, ``DateField`` normalizes input into a Python ``datetime.date``
-object. Regardless of whether you pass it a string in the format
-``'1994-07-15'``, a ``datetime.date`` object or a number of other formats,
-``DateField`` will always normalize it to a ``datetime.date`` object as long as
-it's valid.
+For example, :class:`~django.forms.DateField` normalizes input into a
+Python ``datetime.date`` object. Regardless of whether you pass it a string in
+the format ``'1994-07-15'``, a ``datetime.date`` object, or a number of other
+formats, ``DateField`` will always normalize it to a ``datetime.date`` object
+as long as it's valid.
-Once you've created a ``Form`` instance with a set of data and validated it,
-you can access the clean data via the ``cleaned_data`` attribute of the
``Form``
-object::
+Once you've created a :class:`~Form` instance with a set of data and validated
+it, you can access the clean data via its ``cleaned_data`` attribute::
>>> data = {'subject': 'hello',
... 'message': 'Hi there',
@@ -322,50 +328,57 @@
``as_p()``
~~~~~~~~~~
-``Form.as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>``
-containing one field::
+.. method:: Form.as_p
- >>> f = ContactForm()
- >>> f.as_p()
- 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>'
- >>> print f.as_p()
- <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="text" 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>
+ ``as_p()`` renders the form as a series of ``<p>`` tags, with each ``<p>``
+ containing one field::
+ >>> f = ContactForm()
+ >>> f.as_p()
+ 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>'
+ >>> print f.as_p()
+ <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="text"
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>
+
``as_ul()``
~~~~~~~~~~~
-``Form.as_ul()`` renders the form as a series of ``<li>`` tags, with each
-``<li>`` containing one field. It does *not* include the ``<ul>`` or ``</ul>``,
-so that you can specify any HTML attributes on the ``<ul>`` for flexibility::
+.. method:: Form.as_ul
- >>> f = ContactForm()
- >>> f.as_ul()
- 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>'
- >>> print f.as_ul()
- <li><label for="id_subject">Subject:</label> <input id="id_subject"
type="text" name="subject" maxlength="100" /></li>
- <li><label for="id_message">Message:</label> <input type="text"
name="message" id="id_message" /></li>
- <li><label for="id_sender">Sender:</label> <input type="text"
name="sender" id="id_sender" /></li>
- <li><label for="id_cc_myself">Cc myself:</label> <input type="checkbox"
name="cc_myself" id="id_cc_myself" /></li>
+ ``as_ul()`` renders the form as a series of ``<li>`` tags, with each
+ ``<li>`` containing one field. It does *not* include the ``<ul>`` or
+ ``</ul>``, so that you can specify any HTML attributes on the ``<ul>`` for
+ flexibility::
+ >>> f = ContactForm()
+ >>> f.as_ul()
+ 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>'
+ >>> print f.as_ul()
+ <li><label for="id_subject">Subject:</label> <input id="id_subject"
type="text" name="subject" maxlength="100" /></li>
+ <li><label for="id_message">Message:</label> <input type="text"
name="message" id="id_message" /></li>
+ <li><label for="id_sender">Sender:</label> <input type="text"
name="sender" id="id_sender" /></li>
+ <li><label for="id_cc_myself">Cc myself:</label> <input
type="checkbox" name="cc_myself" id="id_cc_myself" /></li>
+
``as_table()``
~~~~~~~~~~~~~~
-Finally, ``Form.as_table()`` outputs the form as an HTML ``<table>``. This is
-exactly the same as ``print``. In fact, when you ``print`` a form object, it
-calls its ``as_table()`` method behind the scenes::
+.. method:: Form.as_table
- >>> f = ContactForm()
- >>> f.as_table()
- 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>'
- >>> print f.as_table()
- <tr><th><label for="id_subject">Subject:</label></th><td><input
id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
- <tr><th><label for="id_message">Message:</label></th><td><input
type="text" name="message" id="id_message" /></td></tr>
- <tr><th><label for="id_sender">Sender:</label></th><td><input type="text"
name="sender" id="id_sender" /></td></tr>
- <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input
type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>
+ Finally, ``as_table()`` outputs the form as an HTML ``<table>``. This is
+ exactly the same as ``print``. In fact, when you ``print`` a form object,
+ it calls its ``as_table()`` method behind the scenes::
+ >>> f = ContactForm()
+ >>> f.as_table()
+ 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>'
+ >>> print f.as_table()
+ <tr><th><label for="id_subject">Subject:</label></th><td><input
id="id_subject" type="text" name="subject" maxlength="100" /></td></tr>
+ <tr><th><label for="id_message">Message:</label></th><td><input
type="text" name="message" id="id_message" /></td></tr>
+ <tr><th><label for="id_sender">Sender:</label></th><td><input
type="text" name="sender" id="id_sender" /></td></tr>
+ <tr><th><label for="id_cc_myself">Cc myself:</label></th><td><input
type="checkbox" name="cc_myself" id="id_cc_myself" /></td></tr>
+
Styling required or erroneous form rows
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -383,9 +396,9 @@
class ContactForm(Form):
error_css_class = 'error'
required_css_class = 'required'
-
+
# ... and the rest of your fields here
-
+
Once you've done that, rows will be given ``"error"`` and/or ``"required"``
classes, as needed. The HTML will look something like::
Modified: django/trunk/docs/ref/templates/api.txt
===================================================================
--- django/trunk/docs/ref/templates/api.txt 2009-12-25 14:37:57 UTC (rev
11983)
+++ django/trunk/docs/ref/templates/api.txt 2009-12-25 20:51:30 UTC (rev
11984)
@@ -502,12 +502,14 @@
Django has two ways to load templates from files:
-``django.template.loader.get_template(template_name)``
+.. function:: django.template.loader.get_template(template_name)
+
``get_template`` returns the compiled template (a ``Template`` object) for
the template with the given name. If the template doesn't exist, it raises
``django.template.TemplateDoesNotExist``.
-``django.template.loader.select_template(template_name_list)``
+.. function:: django.template.loader.select_template(template_name_list)
+
``select_template`` is just like ``get_template``, except it takes a list
of template names. Of the list, it returns the first template that exists.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-upda...@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
