Changeset 9177

Timestamp:

10/06/08 06:21:11 (3 months ago)

Author:

mtredinnick

Message:

Added a lot more explanation about form field validation, including expanded
examples. Fixed #5843, #6652, #7428.

Files:

• django/trunk/docs/ref/forms/validation.txt (modified) (7 diffs)

django/trunk/docs/ref/forms/validation.txt

@@ -26 +26 @@
-      for cleaning the data in a way that is generic for that type of field.
-      For example, a FloatField will turn the data into a Python ``float`` or
-
+
+
-
-    * The ``clean_<fieldname>()`` method in a form subclass -- where
@@ -45 +46 @@
-      cleaning/normalizing the data.
-
+      Just like the general field ``clean()`` method, above, this method
+      should return the cleaned data, regardless of whether it changed
+      anything or not.
+
-    * The Form subclass's ``clean()`` method. This method can perform
-      any validation that requires access to multiple fields from the form at
@@ -57 +62 @@
-      be associated with any field in particular. They go into a special
-      "field" (called ``__all__``), which you can access via the
-
+
+
+
-
-These methods are run in the order given above, one field at a time.  That is,
@@ -65 +72 @@
-field, the ``Form.clean()`` method, or its override, is executed.
-
-
-
+
+
+
+
-field-specific cleaning method is not called. However, the cleaning methods
-for all remaining fields are still executed.
@@ -79 +88 @@
-already know which fields have passed their individual validation requirements.
-
-
-
-
-
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
-containing comma-separated e-mail addresses, with at least one address. We'll
-keep it simple and assume e-mail validation is contained in a function called
-
+ looks like this
-
-    from django import forms
@@ -91 +154 @@
-    class MultiEmailField(forms.Field):
-        def clean(self, value):
+            """
+            Check that the field contains one or more comma-separated emails
+            and normalizes the data to a list of the email strings.
+            """
-            if not value:
-                raise forms.ValidationError('Enter at least one e-mail address.')
@@ -97 +164 @@
-                if not is_valid_email(email):
-                    raise forms.ValidationError('%s is not a valid e-mail address.' % email)
+
+            # Always return the cleaned data.
-            return emails
-
-
-
-
+
+
+
+
+
+
-
-    class ContactForm(forms.Form):
-        subject = forms.CharField(max_length=100)
-        message = forms.CharField()
-
+
+
-        cc_myself = forms.BooleanField(required=False)
+
+Simply use ``MultiEmailField`` like any other form field. When the
+``is_valid()`` method is called on the form, the ``MultiEmailField.clean()``
+method will be run as part of the cleaning process.
+
+Cleaning a specific field attribute
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Continuing on from the previous example, suppose that in our ``ContactForm``,
+we want to make sure that the ``recipients`` field always contains the address
+``"fred@example.com"``. This is validation that is specific to our form, so we
+don't want to put it into the general ``MultiEmailField`` class. Instead, we
+write a cleaning method that operates on the ``recipients`` field, like so::
+
+    class ContactForm(forms.Form):
+        # Everything as before.
+        ...
+
+        def clean_recipients(self):
+            data = self.cleaned_data['recipients']
+            if "fred@example.com" not in data:
+                raise forms.ValidationError("You have forgotten about Fred!")
+
+            # Always return the cleaned data, whether you have changed it or
+            # not.
+            return data
+
+Cleaning and validating fields that depend on each other
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Suppose we add another requirement to our contact form: if the ``cc_myself``
+field is ``True``, the ``subject`` must contain the word ``"help"``. We are
+performing validation on more than one field at a time, so the form's
+``clean()`` method is a good spot to do this. Notice that we are talking about
+the ``clean()`` method on the form here, whereas earlier we were writing a
+``clean()`` method on a field. It's important to keep the field and form
+difference clear when working out where to validate things. Fields are single
+data points, forms are a collection of fields.
+
+By the time the form's ``clean()`` method is called, all the individual field
+clean methods will have been run (the previous two sections), so
+``self.cleaned_data`` will be populated with any data that has survived so
+far. So you also need to remember to allow for the fact that the fields you
+are wanting to validate might not have survived the initial individual field
+checks.
+
+There are two way to report any errors from this step. Probably the most
+common method is to display the error at the top of the form. To create such
+an error, you can raise a ``ValidationError`` from the ``clean()`` method. For
+example::
+
+    class ContactForm(forms.Form):
+        # Everything as before.
+        ...
+
+        def clean(self):
+            cleaned_data = self.cleaned_data
+            cc_myself = cleaned_data.get("cc_myself")
+            subject = cleaned_data.get("subject")
+
+            if cc_myself and subject:
+                # Only do something if both fields are valid so far.
+                if "help" not in subject:
+                    raise forms.ValidationError("Did not send for 'help' in "
+                            "the subject despite CC'ing yourself.")
+
+            # Always return the full collection of cleaned data.
+            return cleaned_data
+
+In this code, if the validation error is raised, the form will display an
+error message at the top of the form (normally) describing the problem.
+
+The second approach might involve assigning the error message to one of the
+fields. In this case, let's assign an error message to both the "subject" and
+"cc_myself" rows in the form display. Be careful when doing this in practice,
+since it can lead to confusing form output. We're showing what is possible
+here and leaving it up to you and your designers to work out what works
+effectively in your particular situation. Our new code (replacing the previous
+sample) looks like this::
+
+    from django.forms.utils import ErrorList
+
+    class ContactForm(forms.Form):
+        # Everything as before.
+        ...
+
+        def clean(self):
+            cleaned_data = self.cleaned_data
+            cc_myself = cleaned_data.get("cc_myself")
+            subject = cleaned_data.get("subject")
+
+            if cc_myself and subject and "help" not in subject:
+                # We know these are not in self._errors now (see discussion
+                # below).
+                msg = u"Must put 'help' in subject when cc'ing yourself."
+                self._errors["cc_myself"] = ErrorList([msg])
+                self._errors["subject"] = ErrorList([msg])
+
+                # These fields are no longer valid. Remove them from the
+                # cleaned data.
+                del cleaned_data["cc_myself"]
+                del cleaned_data["subject"]
+
+            # Always return the full collection of cleaned data.
+            return cleaned_data
+
+As you can see, this approach requires a bit more effort, not withstanding the
+extra design effort to create a sensible form display. The details are worth
+noting, however. Firstly, earlier we mentioned that you might need to check if
+the field name keys already exist in the ``_errors`` dictionary. In this case,
+since we know the fields exist in ``self.cleaned_data``, they must have been
+valid when cleaned as individual fields, so there will be no corresonding
+entries in ``_errors``.
+
+Secondly, once we have decided that the combined data in the two fields we are
+considering aren't valid, we must remember to remove them from the
+``cleaned_data``.
+
+In fact, Django will currently completely wipe out the ``cleaned_data``
+dictionary if there are any errors in the form. However, this behaviour may
+change in the future, so it's not a bad idea to clean up after yourself in the
+first place.
+