From b4f5e80cd1a6429a42f168142b5a3d90ce2afb26 Mon Sep 17 00:00:00 2001 From: Gary Wilson Jr Date: Fri, 25 Dec 2009 20:51:30 +0000 Subject: [PATCH] Added a few Sphinx directives to the form API and template API docs. git-svn-id: http://code.djangoproject.com/svn/django/trunk@11984 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/ref/forms/api.txt | 125 ++++++++++++++++++++----------------- docs/ref/templates/api.txt | 6 +- 2 files changed, 73 insertions(+), 58 deletions(-) diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt index 26934f07a3..c313eb5c6b 100644 --- a/docs/ref/forms/api.txt +++ b/docs/ref/forms/api.txt @@ -4,6 +4,8 @@ The Forms API ============= +.. module:: django.forms.forms + .. currentmodule:: django.forms .. admonition:: About this document @@ -25,6 +27,8 @@ A :class:`Form` instance is either **bound** to a set of data, or **unbound**. * 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 @@ Dynamic initial values .. 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 @@ instance level, and the latter gets precedence:: 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,49 +328,56 @@ a form object, and each rendering method returns a Unicode object. ``as_p()`` ~~~~~~~~~~ -``Form.as_p()`` renders the form as a series of ``

`` tags, with each ``

`` -containing one field:: +.. method:: Form.as_p - >>> f = ContactForm() - >>> f.as_p() - u'

\n

\n

\n

' - >>> print f.as_p() -

-

-

-

+ ``as_p()`` renders the form as a series of ``

`` tags, with each ``

`` + containing one field:: + + >>> f = ContactForm() + >>> f.as_p() + u'

\n

\n

\n

' + >>> print f.as_p() +

+

+

+

``as_ul()`` ~~~~~~~~~~~ -``Form.as_ul()`` renders the form as a series of ``
  • `` tags, with each -``
  • `` containing one field. It does *not* include the ````, -so that you can specify any HTML attributes on the ``