diff -r 5ff1fc726848 -r c6bca38c1cbf parts/django/docs/topics/forms/index.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/parts/django/docs/topics/forms/index.txt	Sat Jan 08 11:20:57 2011 +0530
@@ -0,0 +1,402 @@
+==================
+Working with forms
+==================
+
+.. admonition:: About this document
+
+    This document provides an introduction to Django's form handling features.
+    For a more detailed look at specific areas of the forms API, see
+    :doc:`/ref/forms/api`, :doc:`/ref/forms/fields`, and
+    :doc:`/ref/forms/validation`.
+
+.. highlightlang:: html+django
+
+``django.forms`` is Django's form-handling library.
+
+While it is possible to process form submissions just using Django's
+:class:`~django.http.HttpRequest` class, using the form library takes care of a
+number of common form-related tasks. Using it, you can:
+
+    1. Display an HTML form with automatically generated form widgets.
+    2. Check submitted data against a set of validation rules.
+    3. Redisplay a form in the case of validation errors.
+    4. Convert submitted form data to the relevant Python data types.
+
+Overview
+========
+
+The library deals with these concepts:
+
+.. glossary::
+
+    Widget
+        A class that corresponds to an HTML form widget, e.g.
+        ``<input type="text">`` or ``<textarea>``. This handles rendering of the
+        widget as HTML.
+
+    Field
+        A class that is responsible for doing validation, e.g.
+        an ``EmailField`` that makes sure its data is a valid e-mail address.
+
+    Form
+        A collection of fields that knows how to validate itself and
+        display itself as HTML.
+
+    Form Media
+        The CSS and JavaScript resources that are required to render a form.
+
+The library is decoupled from the other Django components, such as the database
+layer, views and templates. It relies only on Django settings, a couple of
+``django.utils`` helper functions and Django's internationalization hooks (but
+you're not required to be using internationalization features to use this
+library).
+
+Form objects
+============
+
+A Form object encapsulates a sequence of form fields and a collection of
+validation rules that must be fulfilled in order for the form to be accepted.
+Form classes are created as subclasses of ``django.forms.Form`` and
+make use of a declarative style that you'll be familiar with if you've used
+Django's database models.
+
+For example, consider a form used to implement "contact me" functionality on a
+personal Web site:
+
+.. code-block:: python
+
+    from django import forms
+
+    class ContactForm(forms.Form):
+        subject = forms.CharField(max_length=100)
+        message = forms.CharField()
+        sender = forms.EmailField()
+        cc_myself = forms.BooleanField(required=False)
+
+A form is composed of ``Field`` objects. In this case, our form has four
+fields: ``subject``, ``message``, ``sender`` and ``cc_myself``. ``CharField``,
+``EmailField`` and ``BooleanField`` are just three of the available field types;
+a full list can be found in :doc:`/ref/forms/fields`.
+
+If your form is going to be used to directly add or edit a Django model, you can
+use a :doc:`ModelForm </topics/forms/modelforms>` to avoid duplicating your model
+description.
+
+Using a form in a view
+----------------------
+
+The standard pattern for processing a form in a view looks like this:
+
+.. code-block:: python
+
+   def contact(request):
+       if request.method == 'POST': # If the form has been submitted...
+           form = ContactForm(request.POST) # A form bound to the POST data
+           if form.is_valid(): # All validation rules pass
+               # Process the data in form.cleaned_data
+               # ...
+               return HttpResponseRedirect('/thanks/') # Redirect after POST
+       else:
+           form = ContactForm() # An unbound form
+
+       return render_to_response('contact.html', {
+           'form': form,
+       })
+
+
+There are three code paths here:
+
+    1. If the form has not been submitted, an unbound instance of ContactForm is
+       created and passed to the template.
+    2. If the form has been submitted, a bound instance of the form is created
+       using ``request.POST``. If the submitted data is valid, it is processed
+       and the user is re-directed to a "thanks" page.
+    3. If the form has been submitted but is invalid, the bound form instance is
+       passed on to the template.
+
+.. versionchanged:: 1.0
+    The ``cleaned_data`` attribute was called ``clean_data`` in earlier releases.
+
+The distinction between **bound** and **unbound** forms is important. An unbound
+form does not have any data associated with it; when rendered to the user, it
+will be empty or will contain default values. A bound form does have 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 where
+they went wrong.
+
+See :ref:`ref-forms-api-bound-unbound` for further information on the
+differences between bound and unbound forms.
+
+Handling file uploads with a form
+---------------------------------
+
+To see how to handle file uploads with your form see
+:ref:`binding-uploaded-files` for more information.
+
+Processing the data from a form
+-------------------------------
+
+Once ``is_valid()`` returns ``True``, you can process the form submission safe
+in the knowledge that it conforms to the validation rules defined by your form.
+While you could access ``request.POST`` directly at this point, it is better to
+access ``form.cleaned_data``. This data has not only been validated but will
+also be converted in to the relevant Python types for you. In the above example,
+``cc_myself`` will be a boolean value. Likewise, fields such as ``IntegerField``
+and ``FloatField`` convert values to a Python int and float respectively.
+
+Extending the above example, here's how the form data could be processed:
+
+.. code-block:: python
+
+    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']
+
+        recipients = ['info@example.com']
+        if cc_myself:
+            recipients.append(sender)
+
+        from django.core.mail import send_mail
+        send_mail(subject, message, sender, recipients)
+        return HttpResponseRedirect('/thanks/') # Redirect after POST
+
+For more on sending e-mail from Django, see :doc:`/topics/email`.
+
+Displaying a form using a template
+----------------------------------
+
+Forms are designed to work with the Django template language. In the above
+example, we passed our ``ContactForm`` instance to the template using the
+context variable ``form``. Here's a simple example template::
+
+    <form action="/contact/" method="post">
+    {{ form.as_p }}
+    <input type="submit" value="Submit" />
+    </form>
+
+The form only outputs its own fields; it is up to you to provide the surrounding
+``<form>`` tags and the submit button.
+
+``form.as_p`` will output the form with each form field and accompanying label
+wrapped in a paragraph. Here's the output for our example template::
+
+   <form action="/contact/" method="post">
+   <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>
+   <input type="submit" value="Submit" />
+   </form>
+
+Note that each form field has an ID attribute set to ``id_<field-name>``, which
+is referenced by the accompanying label tag. This is important for ensuring
+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
+<ref-forms-api-configuring-label>`.
+
+You can also use ``form.as_table`` to output table rows (you'll need to provide
+your own ``<table>`` tags) and ``form.as_ul`` to output list items.
+
+Customizing the form template
+-----------------------------
+
+If the default generated HTML is not to your taste, you can completely customize
+the way a form is presented using the Django template language. Extending the
+above example::
+
+    <form action="/contact/" method="post">
+        {{ form.non_field_errors }}
+        <div class="fieldWrapper">
+            {{ form.subject.errors }}
+            <label for="id_subject">E-mail subject:</label>
+            {{ form.subject }}
+        </div>
+        <div class="fieldWrapper">
+            {{ form.message.errors }}
+            <label for="id_message">Your message:</label>
+            {{ form.message }}
+        </div>
+        <div class="fieldWrapper">
+            {{ form.sender.errors }}
+            <label for="id_sender">Your email address:</label>
+            {{ form.sender }}
+        </div>
+        <div class="fieldWrapper">
+            {{ form.cc_myself.errors }}
+            <label for="id_cc_myself">CC yourself?</label>
+            {{ form.cc_myself }}
+        </div>
+        <p><input type="submit" value="Send message" /></p>
+    </form>
+
+Each named form-field can be output to the template using
+``{{ form.name_of_field }}``, which will produce the HTML needed to display the
+form widget. Using ``{{ form.name_of_field.errors }}`` displays a list of form
+errors, rendered as an unordered list. This might look like::
+
+   <ul class="errorlist">
+       <li>Sender is required.</li>
+   </ul>
+
+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
+over them::
+
+    {% if form.subject.errors %}
+        <ol>
+        {% for error in form.subject.errors %}
+            <li><strong>{{ error|escape }}</strong></li>
+        {% endfor %}
+        </ol>
+    {% endif %}
+
+Looping over the form's fields
+------------------------------
+
+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 %}``
+loop::
+
+    <form action="/contact/" method="post">
+        {% for field in form %}
+            <div class="fieldWrapper">
+                {{ field.errors }}
+                {{ field.label_tag }}: {{ field }}
+            </div>
+        {% endfor %}
+        <p><input type="submit" value="Send message" /></p>
+    </form>
+
+Within this loop, ``{{ field }}`` is an instance of :class:`BoundField`.
+``BoundField`` also has the following attributes, which can be useful in your
+templates:
+
+    ``{{ field.label }}``
+        The label of the field, e.g. ``E-mail address``.
+
+    ``{{ field.label_tag }}``
+        The field's label wrapped in the appropriate HTML ``<label>`` tag,
+        e.g. ``<label for="id_email">E-mail address</label>``
+
+    ``{{ 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.
+
+    ``{{ field.help_text }}``
+        Any help text that has been associated with the field.
+
+    ``{{ 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.
+
+    ``field.is_hidden``
+        This attribute is ``True`` if the form field is a hidden field and
+        ``False`` otherwise. It's not particularly useful as a template
+        variable, but could be useful in conditional tests such as::
+
+            {% if field.is_hidden %}
+               {# Do something special #}
+            {% endif %}
+
+Looping over hidden and visible fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+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">``
+fields differently than non-hidden fields. For example, because hidden fields
+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.
+
+Django provides two methods on a form that allow you to loop over the hidden
+and visible fields independently: ``hidden_fields()`` and
+``visible_fields()``. Here's a modification of an earlier example that uses
+these two methods::
+
+    <form action="/contact/" method="post">
+        {% for field in form.visible_fields %}
+            <div class="fieldWrapper">
+
+                {# Include the hidden fields in the form #}
+                {% if forloop.first %}
+                    {% for hidden in form.hidden_fields %}
+                    {{ hidden }}
+                    {% endfor %}
+                {% endif %}
+
+                {{ field.errors }}
+                {{ field.label_tag }}: {{ field }}
+            </div>
+        {% endfor %}
+        <p><input type="submit" value="Send message" /></p>
+    </form>
+
+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
+displays for those form errors, as well.
+
+.. versionadded:: 1.1
+    The ``hidden_fields`` and ``visible_fields`` methods are new in Django
+    1.1.
+
+Reusable form templates
+-----------------------
+
+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
+using the :ttag:`include` tag to reuse it in other templates::
+
+    <form action="/contact/" method="post">
+        {% include "form_snippet.html" %}
+        <p><input type="submit" value="Send message" /></p>
+    </form>
+
+    # In form_snippet.html:
+
+    {% for field in form %}
+        <div class="fieldWrapper">
+            {{ field.errors }}
+            {{ field.label_tag }}: {{ field }}
+        </div>
+    {% endfor %}
+
+If the form object passed to a template has a different name within the
+context, you can alias it using the :ttag:`with` tag::
+
+    <form action="/comments/add/" method="post">
+        {% with comment_form as form %}
+            {% include "form_snippet.html" %}
+        {% endwith %}
+        <p><input type="submit" value="Submit comment" /></p>
+    </form>
+
+If you find yourself doing this often, you might consider creating a custom
+:ref:`inclusion tag<howto-custom-template-tags-inclusion-tags>`.
+
+Further topics
+==============
+
+This covers the basics, but forms can do a whole lot more:
+
+.. toctree::
+   :maxdepth: 2
+
+   modelforms
+   formsets
+   media
+
+.. seealso::
+
+    :doc:`The Forms Reference </ref/forms/index>`
+        Covers the full API reference, including form fields, form widgets, 
+        and form and field validation.