Fixed #21860 -- Added to_field_name to ModelChoiceField docs.

Thanks Keryn Knight for the suggestion.
This commit is contained in:
Anubhav Joshi 2014-03-05 23:53:25 +05:30 committed by Tim Graham
parent abade6413b
commit ad43fdaa00
1 changed files with 35 additions and 1 deletions

View File

@ -1027,7 +1027,7 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
field will be derived, and which will be used to validate the field will be derived, and which will be used to validate the
user's selection. user's selection.
``ModelChoiceField`` also takes one optional argument: ``ModelChoiceField`` also takes two optional arguments:
.. attribute:: empty_label .. 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 initial value, no empty choice is created (regardless of the value
of ``empty_label``). 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 The ``__str__`` (``__unicode__`` on Python 2) method of the model will be
called to generate string representations of the objects for use in the called to generate string representations of the objects for use in the
field's choices; to provide customized representations, subclass field's choices; to provide customized representations, subclass