Fixed #4620: you can now easily add custom labels to ModelChoiceFields via subclassing. Thanks, PhiR.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@7326 bcc190cf-cafb-0310-a4f2-bffc1f526a37

1 files changed, 13 insertions, 5 deletions

diff --git a/docs/newforms.txt b/docs/newforms.txt
index 26dde439ef..533ff75185 100644
--- a/docs/newforms.txt
+++ b/docs/newforms.txt
@@ -1549,15 +1549,23 @@ additional required argument:
 ``ModelChoiceField``
 ~~~~~~~~~~~~~~~~~~~~
 
-Allows the selection of a single model object, suitable for
-representing a foreign key.
+Allows the selection of a single model object, suitable for representing a
+foreign key. The method receives an object as an argument and must return a
+string to represent it.
+
+The labels for the choice field call the ``__unicode__`` method of the model to
+generate string representations. To provide custom labels, subclass ``ModelChoiceField`` and override ``label_for_model``::
+
+    class MyModelChoiceField(ModelChoiceField):
+        def label_from_instance(self, obj):
+            return "My Object #%i" % obj.id
 
 ``ModelMultipleChoiceField``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Allows the selection of one or more model objects, suitable for
-representing a many-to-many relation.
-
+Allows the selection of one or more model objects, suitable for representing a
+many-to-many relation. As with ``ModelChoiceField``, you can use
+``label_from_instance`` to customize the object labels.
 
 Creating custom fields
 ----------------------