From 1bf43df33dda231daab66451a7efcbc6c68304ae Mon Sep 17 00:00:00 2001
From: Adrian Holovaty <adrian@holovaty.com>
Date: Sun, 20 May 2007 20:39:32 +0000
Subject: [PATCH] Edited docs/newforms.txt changes from [5294] and [5295]

git-svn-id: http://code.djangoproject.com/svn/django/trunk@5298 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/newforms.txt | 125 +++++++++++++++++++---------------------------
 1 file changed, 52 insertions(+), 73 deletions(-)

diff --git a/docs/newforms.txt b/docs/newforms.txt
index a94cc665c5..aaabebe5ce 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -313,33 +313,6 @@ record, here's what happens with unbound forms::
     ...
     AttributeError: 'ContactForm' object has no attribute 'cleaned_data'
 
-
-Example View
-~~~~~~~~~~~~
-
-Putting this all together, here is a simple view method that uses our contact
-form::
-
-    from django.shortcuts import render_to_response
-    from django.http import HttpResponseRedirect
-    from django import newforms as forms
-
-    class ContactForm(forms.Form):
-        subject = forms.CharField(max_length=100)
-        message = forms.CharField()
-        sender = forms.EmailField()
-        cc_myself = forms.BooleanField()
-
-    def contact(request):
-        if request.POST:
-            f = ContactForm(request.POST)
-            if f.is_valid:
-                # ... do something with f.cleaned_data
-                return HttpResponseRedirect('/url/on_success/')
-        else:
-            f = ContactForm()
-        return render_to_response('contact.html', {'form': f})
-
 Outputting forms as HTML
 ------------------------
 
@@ -416,12 +389,6 @@ containing one field::
     <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>
 
-In a template, you can invoke this if the form has been handed into the
-context. For example::
-
-    {{ f.as_p }}
-
-
 ``as_ul()``
 ~~~~~~~~~~~
 
@@ -438,11 +405,6 @@ so that you can specify any HTML attributes on the ``<ul>`` for flexibility::
     <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>
 
-In a template, you can invoke this if the form has been handed into the
-context. For example::
-
-    {{ f.as_ul }}
-
 ``as_table()``
 ~~~~~~~~~~~~~~
 
@@ -459,18 +421,6 @@ calls its ``as_table()`` method behind the scenes::
     <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>
 
-In a template, you can invoke this if the form has been handed into the
-context. For example::
-
-    {{ f.as_table }}
-
-which is the same as
-
-::
-
-    {{ f }}
-
-
 Configuring HTML ``<label>`` tags
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -652,68 +602,97 @@ when printed::
     >>> str(f['subject'].errors)
     ''
 
-In the templates
-----------------
+Using forms in views and templates
+----------------------------------
 
-Using the above example, let's put this into a view and show how you can use
-these parts from the template designer's point of view. Assuming you start
-with a view like this::
+Let's put this all together and use the ``ContactForm`` example in a Django
+view and template. This example view displays the contact form by default and
+validates/processes it if accessed via a POST request::
 
     def contact(request):
         if request.method == 'POST':
             form = ContactForm(request.POST)
             if form.is_valid():
-                # do form processing here...
+                # Do form processing here...
                 return HttpResponseRedirect('/url/on_success/')
         else:
             form = ContactForm()
         return render_to_response('contact.html', {'form': form})
 
-...you can have a simple template that uses the shortcuts ``form.as_ul``,
-``form.as_p``, or ``form.as_table`` (which is the default rendering method for
-a form variable). An example ``contact.html`` template::
+Simple template output
+~~~~~~~~~~~~~~~~~~~~~~
 
-    <form method="POST">
-    {{ form }}
+The template, ``contact.html``, is responsible for displaying the form as HTML.
+To do this, we can use the techniques outlined in the "Outputting forms as HTML"
+section above.
+
+The simplest way to display a form's HTML is to use the variable on its own,
+like this::
+
+    <form method="post">
+    <table>{{ form }}</table>
+    <input type="submit" />
     </form>
 
-Equivalently, you could write::
+The above template code will display the form as an HTML table, using the
+``form.as_table()`` method explained previously. This works because Django's
+template system displays an object's ``__str__()`` value, and the ``Form``
+class' ``__str__()`` method calls its ``as_table()`` method.
 
-    <form method="POST">
-    {{ form.as_table }}
+The following is equivalent but a bit more explicit::
+
+    <form method="post">
+    <table>{{ form.as_table }}</table>
+    <input type="submit" />
     </form>
 
-If you wanted to work with the individual inputs of the form, you can either
-call out the fields directly or iterate over them::
+``form.as_ul`` and ``form.as_p`` are also available, as you may expect.
 
-    <form method="POST">
+Note that in the above two examples, we included the ``<form>``, ``<table>``
+``<input type="submit" />``, ``</table>`` and ``</form>`` tags. The form
+convenience methods (``as_table()``, ``as_ul()`` and ``as_p()``) do not include
+that HTML.
+
+Complex template output
+~~~~~~~~~~~~~~~~~~~~~~~
+
+As we've stressed several times, the ``as_table()``, ``as_ul()`` and ``as_p()``
+methods are just shortcuts for the common case. You can also work with the
+individual fields for complete template control over the form's design.
+
+The easiest way is to iterate over the form's fields, with
+``{% for field in form %}``. For example::
+
+    <form method="post">
     <dl>
     {% for field in form %}
         <dt>{{ field.label }}</dt>
         <dd>{{ field }}</dd>
-        <dd>{{ field.help_text }}</dd>
+        {% if field.help_text %}<dd>{{ field.help_text }}</dd>{% endif %}
         {% if field.errors %}<dd class="myerrors">{{ field.errors }}</dd>{% endif %}
     {% endfor %}
     </dl>
+    <input type="submit" />
     </form>
 
-Alternatively::
+Alternatively, you can arrange the form's fields explicitly, by name. Do that
+by accessing ``{{ form.fieldname }}``, where ``fieldname`` is the field's name.
+For example::
 
-    <form method="POST">
+    <form method="post">
     <ul class="myformclass">
         <li>{{ form.sender.label }} {{ form.sender.label }}</li>
-        <li class="helptext" >{{ form.sender.help_text }}</li>
+        <li class="helptext">{{ form.sender.help_text }}</li>
         {% if form.sender.errors %}<ul class="errorlist">{{ form.sender.errors }}</dd>{% endif %}
 
         <li>{{ form.subject.label }} {{ form.subject.label }}</li>
-        <li class="helptext" >{{ form.subject.help_text }}</li>
+        <li class="helptext">{{ form.subject.help_text }}</li>
         {% if form.subject.errors %}<ul class="errorlist">{{ form.subject.errors }}</dd>{% endif %}
 
         ...
     </ul>
     </form>
 
-
 Subclassing forms
 -----------------