From 3bd9852401cfbc8a1dfec4082303a5514ee69bf4 Mon Sep 17 00:00:00 2001
From: Tim Graham <timograham@gmail.com>
Date: Thu, 6 Jun 2013 14:15:26 -0400
Subject: [PATCH] [1.5.x] Fixed #20567 - Documented BoundField.id_for_label.

Thanks littlepig for the suggestion.

Backport of 175a102ddc from master.
---
 docs/ref/forms/api.txt     | 23 +++++++++++++++++++++++
 docs/ref/forms/widgets.txt |  5 +++++
 2 files changed, 28 insertions(+)

diff --git a/docs/ref/forms/api.txt b/docs/ref/forms/api.txt
index 8d9e43bd3b..e6b0d3e6ee 100644
--- a/docs/ref/forms/api.txt
+++ b/docs/ref/forms/api.txt
@@ -683,6 +683,29 @@ by a ``Widget``::
     >>> print(bound_form['subject'].value())
     hi
 
+.. attribute:: BoundField.id_for_label
+
+Use this property to render the ID of this field. For example, if you are
+manually constructing a ``<label>`` in your template (despite the fact that
+:meth:`~BoundField.label_tag` will do this for you):
+
+.. code-block:: html+django
+
+    <label for="{{ form.my_field.id_for_label }}">...</label>{{ my_field }}
+
+By default, this will be the field's name prefixed by ``id_``
+("``id_my_field``" for the example above). You may modify the ID by setting
+:attr:`~django.forms.Widget.attrs` on the field's widget. For example,
+declaring a field like this::
+
+    my_field = forms.CharField(widget=forms.TextInput(attrs={'id': 'myFIELD'}))
+
+and using the template above, would render something like:
+
+.. code-block:: html
+
+    <label for="myFIELD">...</label><input id="myFIELD" type="text" name="my_field" />
+
 .. _binding-uploaded-files:
 
 Binding uploaded files to a form
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index 98383b89dd..ac16b3c02a 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -163,6 +163,9 @@ Django will then include the extra attributes in the rendered output:
     <tr><th>Url:</th><td><input type="text" name="url"/></td></tr>
     <tr><th>Comment:</th><td><input type="text" name="comment" size="40"/></td></tr>
 
+You can also set the HTML ``id`` using :attr:`~Widget.attrs`. See
+:attr:`BoundField.id_for_label` for an example.
+
 .. _styling-widget-classes:
 
 Styling widget classes
@@ -249,6 +252,8 @@ foundation for custom widgets.
         :class:`~datetime.datetime` value into a list with date and time split
         into two separate values::
 
+            from django.forms import MultiWidget
+
             class SplitDateTimeWidget(MultiWidget):
 
                 # ...