Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

[1.1.X] Fixed #12097 -- Cleaned up the documentation for ModelChoiceF…

…ield and MultipleModelChoiceField. Thanks to JasonYosinski for the patch.

Backport of r12712 from trunk.

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.1.X@12715 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 1adc88f4b44b3e304029b49a0dce43cc785c346c 1 parent fdbf6c8
@freakboy3742 freakboy3742 authored
Showing with 35 additions and 24 deletions.
  1. +35 −24 docs/ref/forms/fields.txt
View
59 docs/ref/forms/fields.txt
@@ -755,15 +755,22 @@ for ``TimeField`` are used.
Fields which handle relationships
---------------------------------
-For representing relationships between models, two fields are
-provided which can derive their choices from a ``QuerySet``:
+Two fields are available for representing relationships between
+models: :class:`ModelChoiceField` and
+:class:`ModelMultipleChoiceField`. Both of these fields require a
+single ``queryset`` parameter that is used to create the choices for
+the field. Upon form validation, these fields will place either one
+model object (in the case of ``ModelChoiceField``) or multiple model
+objects (in the case of ``ModelMultipleChoiceField``) into the
+``cleaned_data`` dictionary of the form.
+
+``ModelChoiceField``
+~~~~~~~~~~~~~~~~~~~~
.. class:: ModelChoiceField(**kwargs)
-.. class:: ModelMultipleChoiceField(**kwargs)
-These fields place one or more model objects into the ``cleaned_data``
-dictionary of forms in which they're used. Both of these fields have an
-additional required argument:
+Allows the selection of a single model object, suitable for
+representing a foreign key. A single argument is required:
.. attribute:: ModelChoiceField.queryset
@@ -771,22 +778,7 @@ additional required argument:
field will be derived, and which will be used to validate the
user's selection.
-``ModelChoiceField``
-~~~~~~~~~~~~~~~~~~~~
-
-Allows the selection of a single model object, suitable for
-representing a foreign key.
-
-The ``__unicode__`` 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 ``ModelChoiceField``
-and override ``label_from_instance``. This method will receive a model
-object, and should return a string suitable for representing it. For
-example::
-
- class MyModelChoiceField(ModelChoiceField):
- def label_from_instance(self, obj):
- return "My Object #%i" % obj.id
+``ModelChoiceField`` also takes one optional argument:
.. attribute:: ModelChoiceField.empty_label
@@ -806,13 +798,32 @@ example::
initial value, no empty choice is created (regardless of the value
of ``empty_label``).
+The ``__unicode__`` 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 ``ModelChoiceField``
+and override ``label_from_instance``. This method will receive a model
+object, and should return a string suitable for representing it. For
+example::
+
+ class MyModelChoiceField(ModelChoiceField):
+ def label_from_instance(self, obj):
+ return "My Object #%i" % obj.id
+
``ModelMultipleChoiceField``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. class:: ModelMultipleChoiceField(**kwargs)
+
Allows the selection of one or more model objects, suitable for
-representing a many-to-many relation. As with ``ModelChoiceField``,
+representing a many-to-many relation. As with :class:`ModelChoiceField`,
you can use ``label_from_instance`` to customize the object
-representations.
+representations, and ``queryset`` is a required parameter:
+
+.. attribute:: ModelMultipleChoiceField.queryset
+
+ A ``QuerySet`` of model objects from which the choices for the
+ field will be derived, and which will be used to validate the
+ user's selection.
Creating custom fields
----------------------
Please sign in to comment.
Something went wrong with that request. Please try again.