Browse files

Fixed #21654 -- Documented a use-case for Form.errors.as_data().

Thanks selwin for the suggestion.
  • Loading branch information...
loic authored and timgraham committed Feb 13, 2014
1 parent 007c5cd commit 2e4200b5c7cb4887b7034bb5dcbbd354e4698f27
Showing with 21 additions and 0 deletions.
  1. +14 −0 docs/ref/forms/api.txt
  2. +7 −0 docs/ref/forms/validation.txt
@@ -128,6 +128,20 @@ instances.
{'sender': [ValidationError(['Enter a valid email address.'])],
'subject': [ValidationError(['This field is required.'])]}
+Use this method anytime you need to identify an error by its ``code``. This
+enables things like rewriting the error's message or writing custom logic in a
+view when a given error is present. It can also be used to serialize the errors
+in a custom format (e.g. XML); for instance, :meth:`~Form.errors.as_json()`
+relies on ``as_data()``.
+The need for the ``as_data()`` method is due to backwards compatibility.
+Previously ``ValidationError`` instances were lost as soon as their
+**rendered** error messages were added to the ``Form.errors`` dictionary.
+Ideally ``Form.errors`` would have stored ``ValidationError`` instances
+and methods with an ``as_`` prefix could render them, but it had to be done
+the other way around in order not to break code that expects rendered error
+messages in ``Form.errors``.
.. method:: Form.errors.as_json()
.. versionadded:: 1.7
@@ -179,6 +179,13 @@ to override your error message you can still opt for the less verbose::
ValidationError(_('Invalid value: %s') % value)
+.. versionadded:: 1.7
+The :meth:`Form.errors.as_data() <django.forms.Form.errors.as_data()>` and
+:meth:`Form.errors.as_json() <django.forms.Form.errors.as_json()>` methods
+greatly benefit from fully featured ``ValidationError``\s (with a ``code`` name
+and a ``params`` dictionary).
Raising multiple errors

0 comments on commit 2e4200b

Please sign in to comment.