newforms-admin: Merged to [5300]

git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@5301 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 96 insertions, 0 deletions

diff --git a/docs/newforms.txt b/docs/newforms.txt
index ed43670960..5516f60683 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -602,6 +602,102 @@ when printed::
     >>> str(f['subject'].errors)
     ''
 
+Using forms in views and templates
+----------------------------------
+
+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...
+                return HttpResponseRedirect('/url/on_success/')
+        else:
+            form = ContactForm()
+        return render_to_response('contact.html', {'form': form})
+
+Simple template output
+~~~~~~~~~~~~~~~~~~~~~~
+
+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>
+
+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.
+
+The following is equivalent but a bit more explicit::
+
+    <form method="post">
+    <table>{{ form.as_table }}</table>
+    <input type="submit" />
+    </form>
+
+``form.as_ul`` and ``form.as_p`` are also available, as you may expect.
+
+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>
+        {% 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>
+
+This iteration technique is useful if you want to apply the same HTML
+formatting to each field, or if you don't know the names of the form fields
+ahead of time. Note that the fields will be listed in the order in which
+they're defined in the ``Form`` class.
+
+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">
+    <ul class="myformclass">
+        <li>{{ form.sender.label }} {{ form.sender.label }}</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>
+        {% if form.subject.errors %}<ul class="errorlist">{{ form.subject.errors }}</dd>{% endif %}
+
+        ...
+    </ul>
+    </form>
+
 Subclassing forms
 -----------------