From 61ede43202aef10306dc70fa300f269bd3f4fe7f Mon Sep 17 00:00:00 2001
From: Adrian Holovaty <adrian@holovaty.com>
Date: Thu, 4 Jan 2007 06:52:50 +0000
Subject: [PATCH] Added first part of 'Using forms to validate data' section to
 docs/newforms.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@4285 bcc190cf-cafb-0310-a4f2-bffc1f526a37
---
 docs/newforms.txt | 48 ++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 47 insertions(+), 1 deletion(-)

diff --git a/docs/newforms.txt b/docs/newforms.txt
index 7744d83e5e..d72b22f092 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -74,7 +74,9 @@ The library deals with these concepts:
 
 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 system.
+``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
 ============
@@ -322,6 +324,50 @@ The field-specific output honors the form object's ``auto_id`` setting::
     >>> print f['message']
     <input type="text" name="message" id="id_message" />
 
+Using forms to validate data
+----------------------------
+
+In addition to HTML form display, a ``Form`` class is responsible for
+validating data. To validate data, pass it as a dictionary as the first
+parameter to your ``Form`` class' constructor::
+
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data)
+
+From then on, the ``Form`` instance is bound to that data. If you want to
+change the data somehow, or validate other data, create another ``Form``
+instance.
+
+Once you have a ``Form`` instance that's bound to data, call the ``is_valid()``
+method to run validation and return a boolean designating whether the data was
+valid::
+
+    >>> f.is_valid()
+    True
+
+Let's try with some invalid data::
+
+    >>> data = {'subject': '',
+    ...         'message': 'Hi there',
+    ...         'sender': 'invalid e-mail address',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(data)
+    >>> f.is_valid()
+    False
+
+Access the ``Form`` attribute ``errors`` to get a dictionary of error messages,
+keyed by the field name::
+
+    >>> f.errors
+    {'sender': [u'Enter a valid e-mail address.'], 'subject': [u'This field is required.']}
+
+You can access ``errors`` without having to call ``is_valid()`` first. The
+form's data will be validated the first time either you call ``is_valid()`` or
+access ``errors``.
+
 More coming soon
 ================