From 649463dd348abd6d0cab890e2372e88fc452128e Mon Sep 17 00:00:00 2001 From: Russell Keith-Magee Date: Sat, 19 Jul 2008 07:53:02 +0000 Subject: Fixed #4412 -- Added support for optgroups, both in the model when defining choices, and in the form field and widgets when the optgroups are displayed. Thanks to Matt McClanahan , Tai Lee and SmileyChris for their contributions at various stages in the life of this ticket. git-svn-id: http://code.djangoproject.com/svn/django/trunk@7977 bcc190cf-cafb-0310-a4f2-bffc1f526a37 --- docs/model-api.txt | 23 +++++++++++++++++++++++ docs/newforms.txt | 10 ++++++++-- 2 files changed, 31 insertions(+), 2 deletions(-) (limited to 'docs') diff --git a/docs/model-api.txt b/docs/model-api.txt index 4accad122a..4975953b97 100644 --- a/docs/model-api.txt +++ b/docs/model-api.txt @@ -554,6 +554,29 @@ or outside your model class altogether:: class Foo(models.Model): gender = models.CharField(max_length=1, choices=GENDER_CHOICES) +You can also collect your available choices into named groups that can +be used for organizational purposes:: + + MEDIA_CHOICES = ( + ('Audio', ( + ('vinyl', 'Vinyl'), + ('cd', 'CD'), + ) + ), + ('Video', ( + ('vhs', 'VHS Tape'), + ('dvd', 'DVD'), + ) + ), + ('unknown', 'Unknown'), + ) + +The first element in each tuple is the name to apply to the group. The +second element is an iterable of 2-tuples, with each 2-tuple containing +a value and a human-readable name for an option. Grouped options may be +combined with ungrouped options within a single list (such as the +`unknown` option in this example). + For each model field that has ``choices`` set, Django will add a method to retrieve the human-readable name for the field's current value. See `get_FOO_display`_ in the database API documentation. diff --git a/docs/newforms.txt b/docs/newforms.txt index 530c9ce828..c3f4a2c21c 100644 --- a/docs/newforms.txt +++ b/docs/newforms.txt @@ -1236,7 +1236,11 @@ given length. * Error message keys: ``required``, ``invalid_choice`` Takes one extra argument, ``choices``, which is an iterable (e.g., a list or -tuple) of 2-tuples to use as choices for this field. +tuple) of 2-tuples to use as choices for this field. This argument accepts +the same formats as the ``choices`` argument to a model field. See the +`model API documentation on choices`_ for more details. + +.. _model API documentation on choices: ../model-api#choices ``DateField`` ~~~~~~~~~~~~~ @@ -1444,7 +1448,9 @@ These control the range of values permitted in the field. * Error message keys: ``required``, ``invalid_choice``, ``invalid_list`` Takes one extra argument, ``choices``, which is an iterable (e.g., a list or -tuple) of 2-tuples to use as choices for this field. +tuple) of 2-tuples to use as choices for this field. This argument accepts +the same formats as the ``choices`` argument to a model field. See the +`model API documentation on choices`_ for more details. ``NullBooleanField`` ~~~~~~~~~~~~~~~~~~~~ -- cgit v1.3