Skip to content

Loading…

Fixed #21860 -- Added to_field_name to ModelChoiceField docs. #2399

Closed
wants to merge 1 commit into from

3 participants

@kezabelle kezabelle commented on an outdated diff
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 argument:

argument would now need to be pluralised into arguments

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@kezabelle kezabelle commented on an outdated diff
docs/ref/forms/fields.txt
@@ -1043,6 +1043,39 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
+ .. attribute:: to_field_name
+
+ This optional argument is used to specify the name of the field of the model
+ objects which will be used as value of the ``<option>`` in the ``<select>``

used as value ... should probably have used as the value

Additionally, this is talking specifically about select and option, both of which are part of a widget's contract, not the field itself.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@kezabelle kezabelle commented on an outdated diff
docs/ref/forms/fields.txt
@@ -1043,6 +1043,39 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
+ .. attribute:: to_field_name
+
+ This optional argument is used to specify the name of the field of the model
+ objects which will be used as value of the ``<option>`` in the ``<select>``
+ widget of ``ModelChoiceField``. By default, it is set to ``None`` and uses
+ the Primary Key as value of the selected field.
+ We can see its usage in the following example::
+
+ # A test model
+ class person(models.Model):

Person, not person, is the generally accepted casing.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@coder9042

@kezabelle
Corrected the docs. Thanks for reviewing.

@coder9042

@timgraham
Please suggest any changes, if required.

@timgraham timgraham commented on an outdated diff
docs/ref/forms/fields.txt
@@ -1043,6 +1043,39 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
+ .. attribute:: to_field_name
+
+ This optional argument is used to specify the name of the field of the model
+ objects which will be used as the value of the choices in the ``<select>``
+ widget of ``ModelChoiceField``. By default, it is set to ``None`` and uses
+ the Primary Key as value of the selected field.
@timgraham Django member

"primary key" isn't a proper noun and shouldn't be capitalized.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@timgraham timgraham commented on an outdated diff
docs/ref/forms/fields.txt
((21 lines not shown))
+ <option value="Person_object1.pk">Person_object1</option>
+ <option value="Person_object2.pk">Person_object2</option>
+ ...
+ </select>
+
+ # to_field_name provided
+ field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")
+
+ # Generated Result
+ <select id="id_field2" name="field2">
+ <option value="Person_object1.name">Person_object1</option>
+ <option value="Person_object2.name">Person_object2</option>
+ ...
+ </select>
+
+
@timgraham Django member

only 1 space between sections please

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@timgraham timgraham commented on an outdated diff
docs/ref/forms/fields.txt
@@ -1043,6 +1043,39 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
+ .. attribute:: to_field_name
+
+ This optional argument is used to specify the name of the field of the model
+ objects which will be used as the value of the choices in the ``<select>``
@timgraham Django member

Might be helpful to describe this more generally. For example, what if I choose not to use the default "select" widget?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
@timgraham
Django member

merged in ad43fda.

@timgraham timgraham closed this
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Showing with 33 additions and 1 deletion.
  1. +33 −1 docs/ref/forms/fields.txt
View
34 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
@@ -1043,6 +1043,38 @@ objects (in the case of ``ModelMultipleChoiceField``) into the
# No empty label
field2 = forms.ModelChoiceField(queryset=..., empty_label=None)
+ .. attribute:: to_field_name
+
+ This optional argument is used to specify the name of the field of the model
+ objects which will be used as the value of the choices in ``ModelChoiceField``
+ in the form. By default, it is set to ``None`` and uses the primary key
+ as value of the selected field.
+ We can see its usage in the following example::
+
+ # A test model
+ class Person(models.Model):
+ name = models.CharField(max_length=30)
+
+ # No custom to_field_name
+ field1 = forms.ModelChoiceField(queryset=...)
+
+ # Generated Result
+ <select id="id_field1" name="field1">
+ <option value="Person_object1.pk">Person_object1</option>
+ <option value="Person_object2.pk">Person_object2</option>
+ ...
+ </select>
+
+ # to_field_name provided
+ field2 = forms.ModelChoiceField(queryset=..., to_field_name="name")
+
+ # Generated Result
+ <select id="id_field2" name="field2">
+ <option value="Person_object1.name">Person_object1</option>
+ <option value="Person_object2.name">Person_object2</option>
+ ...
+ </select>
+
Note that if a ``ModelChoiceField`` is required and has a default
initial value, no empty choice is created (regardless of the value
of ``empty_label``).
Something went wrong with that request. Please try again.