[multi-db] Merge trunk to [3812]. Some tests still failing.

git-svn-id: http://code.djangoproject.com/svn/django/branches/multiple-db-support@4139 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 30 insertions, 3 deletions

diff --git a/docs/forms.txt b/docs/forms.txt
index d6ef6f791b..0ffb0bdcb7 100644
--- a/docs/forms.txt
+++ b/docs/forms.txt
@@ -136,7 +136,7 @@ template::
     {% endblock %}
 
 Before we get back to the problems with these naive set of views, let's go over
-some salient points of the above template::
+some salient points of the above template:
 
     * Field "widgets" are handled for you: ``{{ form.field }}`` automatically
       creates the "right" type of widget for the form, as you can see with the
@@ -148,8 +148,8 @@ some salient points of the above template::
       If you must use tables, use tables. If you're a semantic purist, you can
       probably find better HTML than in the above template.
 
-    * To avoid name conflicts, the ``id``s of form elements take the form
-      "id_*fieldname*".
+    * To avoid name conflicts, the ``id`` values of form elements take the
+      form "id_*fieldname*".
 
 By creating a creation form we've solved problem number 3 above, but we still
 don't have any validation. Let's revise the validation issue by writing a new
@@ -481,6 +481,33 @@ the data being validated.
 Also, because consistency in user interfaces is important, we strongly urge you
 to put punctuation at the end of your validation messages.
 
+When Are Validators Called?
+---------------------------
+
+After a form has been submitted, Django first checks to see that all the
+required fields are present and non-empty. For each field that passes that
+test *and if the form submission contained data* for that field, all the
+validators for that field are called in turn. The emphasised portion in the
+last sentence is important: if a form field is not submitted (because it
+contains no data -- which is normal HTML behaviour), the validators are not
+run against the field.
+
+This feature is particularly important for models using
+``models.BooleanField`` or custom manipulators using things like
+``forms.CheckBoxField``. If the checkbox is not selected, it will not
+contribute to the form submission.
+
+If you would like your validator to *always* run, regardless of whether the
+field it is attached to contains any data, set the ``always_test`` attribute
+on the validator function. For example::
+
+    def my_custom_validator(field_data, all_data):
+        # ...
+
+    my_custom_validator.always_test = True
+
+This validator will always be executed for any field it is attached to.
+
 Ready-made Validators
 ---------------------