Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #21860 -- Added to_field_name to ModelChoiceField docs.

Thanks Keryn Knight for the suggestion.
  • Loading branch information...
commit ad43fdaa0008ce8d3d05e840f67af631d1329489 1 parent abade64
@coder9042 coder9042 authored timgraham committed
Showing with 35 additions and 1 deletion.
  1. +35 −1 docs/ref/forms/fields.txt
View
36 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
Please sign in to comment.
Something went wrong with that request. Please try again.