[1.6.x] Fixed #21319 -- Added documentation for the Form.fields attribute.

Thanks pydanny for the report. Also, added documentation about
base_fields attribute and its difference with fields attribute.

Backport of ea83102d0f from master

1 files changed, 34 insertions, 0 deletions

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 6195d7d4b8..9a10ebf533 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -165,6 +165,40 @@ 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>
 
+Accessing the fields from the form
+----------------------------------
+
+.. attribute:: Form.fields
+
+You can access the fields of :class:`Form` instance from its ``fields``
+attribute::
+
+    >>> for row in f.fields.values(): print(row)
+    ...
+    <django.forms.fields.CharField object at 0x7ffaac632510>
+    <django.forms.fields.URLField object at 0x7ffaac632f90>
+    <django.forms.fields.CharField object at 0x7ffaac3aa050>
+    >>> f.fields['name']
+    <django.forms.fields.CharField object at 0x7ffaac6324d0>
+
+You can alter the field of :class:`Form` instance to change the way it is
+presented in the form::
+
+    >>> f.as_table().split('\n')[0]
+    '<tr><th>Name:</th><td><input name="name" type="text" value="instance" /></td></tr>'
+    >>> f.fields['name'].label = "Username"
+    >>> f.as_table().split('\n')[0]
+    '<tr><th>Username:</th><td><input name="name" type="text" value="instance" /></td></tr>'
+
+Beware not to alter the ``base_fields`` attribute because this modification
+will influence all subsequent ``ContactForm`` instances within the same Python
+process::
+
+    >>> f.base_fields['name'].label = "Username"
+    >>> another_f = CommentForm(auto_id=False)
+    >>> another_f.as_table().split('\n')[0]
+    '<tr><th>Username:</th><td><input name="name" type="text" value="class" /></td></tr>'
+
 Accessing "clean" data
 ----------------------