[1.6.x] Fixed #21792 -- Documented Form.has_changed()

Thanks bjb at credil.org for the suggestion and
Ivan Mesic for the draft patch.

Backport of edcc75e5ac from master

1 files changed, 25 insertions, 0 deletions

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 5ade678e95..8fa2de8db1 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -165,6 +165,31 @@ precedence::
     <tr><th>Url:</th><td><input type="url" name="url" /></td></tr>
     <tr><th>Comment:</th><td><input type="text" name="comment" /></td></tr>
 
+Checking if form data has changed
+---------------------------------
+
+.. method:: Form.has_changed()
+
+Use the ``has_changed()`` method on your ``Form`` when you need to check if the
+form data has been changed from the initial data.
+
+    >>> data = {'subject': 'hello',
+    ...         'message': 'Hi there',
+    ...         'sender': 'foo@example.com',
+    ...         'cc_myself': True}
+    >>> f = ContactForm(initial=data)
+    >>> f.has_changed()
+    False
+
+When the form is submitted, we reconstruct it and provide the original data
+so that the comparison can be done:
+
+    >>> f = ContactForm(request.POST, initial=data)
+    >>> f.has_changed()
+
+``has_changed()`` will be ``True`` if the data from ``request.POST`` differs
+from what was provided in :attr:`~Form.initial` or ``False`` otherwise.
+
 Accessing the fields from the form
 ----------------------------------