Fixed #25294 -- Allowed custom BoundFields on forms.

docs/ref/forms/api.txt

@@ -932,6 +932,48 @@ and using the template above, would render something like:
 
     <label for="myFIELD">...</label><input id="myFIELD" type="text" name="my_field" />
 
+Customizing ``BoundField``
+--------------------------
+
+.. versionadded:: 1.9
+
+If you need to access some additional information about a form field in a
+template and using a subclass of :class:`~django.forms.Field` isn't
+sufficient, consider also customizing :class:`~django.forms.BoundField`.
+
+A custom form field can override ``get_bound_field()``:
+
+.. method:: Field.get_bound_field(form, field_name)
+
+    Takes an instance of :class:`~django.forms.Form` and the name of the field.
+    The return value will be used when accessing the field in a template. Most
+    likely it will be an instance of a subclass of
+    :class:`~django.forms.BoundField`.
+
+If you have a ``GPSCoordinatesField``, for example, and want to be able to
+access additional information about the coordinates in a template, this could
+be implemented as follows::
+
+    class GPSCoordinatesBoundField(BoundField):
+        @property
+        def country(self):
+            """
+            Return the country the coordinates lie in or None if it can't be
+            determined.
+            """
+            value = self.value()
+            if value:
+                return get_country_from_coordinates(value)
+            else:
+                return None
+
+    class GPSCoordinatesField(Field):
+        def get_bound_field(self, form, field_name):
+            return GPSCoordinatesBoundField(form, self, field_name)
+
+Now you can access the country in a template with
+``{{ form.coordinates.country }}``.
+
 .. _binding-uploaded-files:
 
 Binding uploaded files to a form

docs/ref/forms/fields.txt

@@ -1239,3 +1239,6 @@ custom ``Field`` classes. To do this, just create a subclass of
 ``clean()`` method and that its ``__init__()`` method accept the core arguments
 mentioned above (``required``, ``label``, ``initial``, ``widget``,
 ``help_text``).
+
+You can also customize how a field will be accessed by overriding
+:meth:`~django.forms.Field.get_bound_field()`.

docs/releases/1.9.txt

@@ -364,6 +364,9 @@ Forms
 * Form fields now support the :attr:`~django.forms.Field.disabled` argument,
   allowing the field widget to be displayed disabled by browsers.
 
+* It's now possible to customize bound fields by overriding a field's
+  :meth:`~django.forms.Field.get_bound_field()` method.
+
 Generic Views
 ^^^^^^^^^^^^^