Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Fixed #12097 -- Cleaned up the documentation for ModelChoiceField and…

… MultipleModelChoiceField. Thanks to JasonYosinski for the patch.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@12712 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit d1e37f2b396d8b86c44d834bc404a22db7d7afb2 1 parent 6e030e7
Russell Keith-Magee authored March 08, 2010

Showing 1 changed file with 35 additions and 24 deletions. Show diff stats Hide diff stats

  1. 59  docs/ref/forms/fields.txt
59  docs/ref/forms/fields.txt
@@ -777,15 +777,22 @@ for ``TimeField`` are used.
777 777
 Fields which handle relationships
778 778
 ---------------------------------
779 779
 
780  
-For representing relationships between models, two fields are
781  
-provided which can derive their choices from a ``QuerySet``:
  780
+Two fields are available for representing relationships between
  781
+models: :class:`ModelChoiceField` and
  782
+:class:`ModelMultipleChoiceField`.  Both of these fields require a
  783
+single ``queryset`` parameter that is used to create the choices for
  784
+the field.  Upon form validation, these fields will place either one
  785
+model object (in the case of ``ModelChoiceField``) or multiple model
  786
+objects (in the case of ``ModelMultipleChoiceField``) into the
  787
+``cleaned_data`` dictionary of the form.
  788
+
  789
+``ModelChoiceField``
  790
+~~~~~~~~~~~~~~~~~~~~
782 791
 
783 792
 .. class:: ModelChoiceField(**kwargs)
784  
-.. class:: ModelMultipleChoiceField(**kwargs)
785 793
 
786  
-These fields place one or more model objects into the ``cleaned_data``
787  
-dictionary of forms in which they're used. Both of these fields have an
788  
-additional required argument:
  794
+Allows the selection of a single model object, suitable for
  795
+representing a foreign key.  A single argument is required:
789 796
 
790 797
 .. attribute:: ModelChoiceField.queryset
791 798
 
@@ -793,22 +800,7 @@ additional required argument:
793 800
     field will be derived, and which will be used to validate the
794 801
     user's selection.
795 802
 
796  
-``ModelChoiceField``
797  
-~~~~~~~~~~~~~~~~~~~~
798  
-
799  
-Allows the selection of a single model object, suitable for
800  
-representing a foreign key.
801  
-
802  
-The ``__unicode__`` method of the model will be called to generate
803  
-string representations of the objects for use in the field's choices;
804  
-to provide customized representations, subclass ``ModelChoiceField``
805  
-and override ``label_from_instance``. This method will receive a model
806  
-object, and should return a string suitable for representing it. For
807  
-example::
808  
-
809  
-    class MyModelChoiceField(ModelChoiceField):
810  
-        def label_from_instance(self, obj):
811  
-            return "My Object #%i" % obj.id
  803
+``ModelChoiceField`` also takes one optional argument:
812 804
 
813 805
 .. attribute:: ModelChoiceField.empty_label
814 806
 
@@ -828,13 +820,32 @@ example::
828 820
    initial value, no empty choice is created (regardless of the value
829 821
    of ``empty_label``).
830 822
 
  823
+The ``__unicode__`` method of the model will be called to generate
  824
+string representations of the objects for use in the field's choices;
  825
+to provide customized representations, subclass ``ModelChoiceField``
  826
+and override ``label_from_instance``. This method will receive a model
  827
+object, and should return a string suitable for representing it. For
  828
+example::
  829
+
  830
+    class MyModelChoiceField(ModelChoiceField):
  831
+        def label_from_instance(self, obj):
  832
+            return "My Object #%i" % obj.id
  833
+
831 834
 ``ModelMultipleChoiceField``
832 835
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
833 836
 
  837
+.. class:: ModelMultipleChoiceField(**kwargs)
  838
+
834 839
 Allows the selection of one or more model objects, suitable for
835  
-representing a many-to-many relation. As with ``ModelChoiceField``,
  840
+representing a many-to-many relation. As with :class:`ModelChoiceField`,
836 841
 you can use ``label_from_instance`` to customize the object
837  
-representations.
  842
+representations, and ``queryset`` is a required parameter:
  843
+
  844
+.. attribute:: ModelMultipleChoiceField.queryset
  845
+
  846
+    A ``QuerySet`` of model objects from which the choices for the
  847
+    field will be derived, and which will be used to validate the
  848
+    user's selection.
838 849
 
839 850
 Creating custom fields
840 851
 ----------------------

0 notes on commit d1e37f2

Please sign in to comment.
Something went wrong with that request. Please try again.