From ad43fdaa0008ce8d3d05e840f67af631d1329489 Mon Sep 17 00:00:00 2001
From: Anubhav Joshi <anubhav9042@gmail.com>
Date: Wed, 5 Mar 2014 23:53:25 +0530
Subject: [PATCH] Fixed #21860 -- Added to_field_name to ModelChoiceField docs.

Thanks Keryn Knight for the suggestion.
---
 docs/ref/forms/fields.txt | 36 +++++++++++++++++++++++++++++++++++-
 1 file changed, 35 insertions(+), 1 deletion(-)

diff --git a/docs/ref/forms/fields.txt b/docs/ref/forms/fields.txt
index c2194cc5122..975b77ef292 100644
--- a/docs/ref/forms/fields.txt
+++ b/docs/ref/forms/fields.txt
@@ -1027,7 +1027,7 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
         field will be derived, and which will be used to validate the
         user's selection.
 
-    ``ModelChoiceField`` also takes one optional argument:
+    ``ModelChoiceField`` also takes two optional arguments:
 
     .. attribute:: empty_label
 
@@ -1047,6 +1047,40 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
         initial value, no empty choice is created (regardless of the value
         of ``empty_label``).
 
+    .. attribute:: to_field_name
+
+        This optional argument is used to specify the field to use as the value
+        of the choices in the field's widget. By default it is set to ``None``,
+        in which case the primary key of each object will be used. For example::
+
+            # No custom to_field_name
+            field1 = forms.ModelChoiceField(queryset=...)
+
+        would yield:
+
+        .. code-block:: html
+
+            <select id="id_field1" name="field1">
+            <option value="obj1.pk">Object1</option>
+            <option value="obj2.pk">Object2</option>
+            ...
+            </select>
+
+        and::
+
+            # to_field_name provided
+            field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")
+
+        would yield:
+
+        .. code-block:: html
+
+            <select id="id_field2" name="field2">
+            <option value="obj1.name">Object1</option>
+            <option value="obj2.name">Object2</option>
+            ...
+            </select>
+
     The ``__str__`` (``__unicode__`` on Python 2) method of the model will be
     called to generate string representations of the objects for use in the
     field's choices; to provide customized representations, subclass