diff --git a/docs/howto/custom-model-fields.txt b/docs/howto/custom-model-fields.txt
index 7f0ea3799d..aac9883526 100644
--- a/docs/howto/custom-model-fields.txt
+++ b/docs/howto/custom-model-fields.txt
@@ -334,7 +334,6 @@ Once you have ``MytypeField``, you can use it in any model, just like any other
class Person(models.Model):
name = models.CharField(max_length=80)
- gender = models.CharField(max_length=1)
something_else = MytypeField()
If you aim to build a database-agnostic application, you should account for
diff --git a/docs/ref/forms/widgets.txt b/docs/ref/forms/widgets.txt
index ac110c2ee8..88d0d706cd 100644
--- a/docs/ref/forms/widgets.txt
+++ b/docs/ref/forms/widgets.txt
@@ -47,14 +47,12 @@ widget on the field. In the following example, the
from django.forms.extras.widgets import SelectDateWidget
BIRTH_YEAR_CHOICES = ('1980', '1981', '1982')
- GENDER_CHOICES = (('m', 'Male'), ('f', 'Female'))
FAVORITE_COLORS_CHOICES = (('blue', 'Blue'),
('green', 'Green'),
('black', 'Black'))
class SimpleForm(forms.Form):
birth_year = DateField(widget=SelectDateWidget(years=BIRTH_YEAR_CHOICES))
- gender = ChoiceField(widget=RadioSelect, choices=GENDER_CHOICES)
favorite_colors = forms.MultipleChoiceField(required=False,
widget=CheckboxSelectMultiple, choices=FAVORITE_COLORS_CHOICES)
diff --git a/docs/ref/models/fields.txt b/docs/ref/models/fields.txt
index 36bf60e9ac..5062e90ebe 100644
--- a/docs/ref/models/fields.txt
+++ b/docs/ref/models/fields.txt
@@ -103,20 +103,26 @@ element is the human-readable name for the option.
The choices list can be defined either as part of your model class::
class Foo(models.Model):
- GENDER_CHOICES = (
- ('M', 'Male'),
- ('F', 'Female'),
+ YEAR_IN_SCHOOL_CHOICES = (
+ ('FR', 'Freshman'),
+ ('SO', 'Sophomore'),
+ ('JR', 'Junior'),
+ ('SR', 'Senior'),
+ ('GR', 'Graduate'),
)
- gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
+ year_in_school = models.CharField(max_length=2, choices=YEAR_IN_SCHOOL_CHOICES)
or outside your model class altogether::
- GENDER_CHOICES = (
- ('M', 'Male'),
- ('F', 'Female'),
+ YEAR_IN_SCHOOL_CHOICES = (
+ ('FR', 'Freshman'),
+ ('SO', 'Sophomore'),
+ ('JR', 'Junior'),
+ ('SR', 'Senior'),
+ ('GR', 'Graduate'),
)
class Foo(models.Model):
- gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
+ year_in_school = models.CharField(max_length=2, choices=YEAR_IN_SCHOOL_CHOICES)
You can also collect your available choices into named groups that can
be used for organizational purposes::
diff --git a/docs/ref/models/instances.txt b/docs/ref/models/instances.txt
index 1f60f43c97..3b592d06dc 100644
--- a/docs/ref/models/instances.txt
+++ b/docs/ref/models/instances.txt
@@ -550,25 +550,29 @@ might have some of the following methods:
For every field that has :attr:`~django.db.models.Field.choices` set, the
object will have a ``get_FOO_display()`` method, where ``FOO`` is the name of
-the field. This method returns the "human-readable" value of the field. For
-example, in the following model::
+the field. This method returns the "human-readable" value of the field.
- GENDER_CHOICES = (
- ('M', 'Male'),
- ('F', 'Female'),
- )
- class Person(models.Model):
- name = models.CharField(max_length=20)
- gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
+For example::
-...each ``Person`` instance will have a ``get_gender_display()`` method. Example::
+ from django.db import models
- >>> p = Person(name='John', gender='M')
- >>> p.save()
- >>> p.gender
- 'M'
- >>> p.get_gender_display()
- 'Male'
+ class Person(models.Model):
+ SHIRT_SIZES = (
+ (u'S', u'Small'),
+ (u'M', u'Medium'),
+ (u'L', u'Large'),
+ )
+ name = models.CharField(max_length=60)
+ shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)
+
+ ::
+
+ >>> p = Person(name="Fred Flintstone", shirt_size="L")
+ >>> p.save()
+ >>> p.shirt_size
+ u'L'
+ >>> p.get_shirt_size_display()
+ u'Large'
.. method:: Model.get_next_by_FOO(\**kwargs)
.. method:: Model.get_previous_by_FOO(\**kwargs)
diff --git a/docs/ref/templates/builtins.txt b/docs/ref/templates/builtins.txt
index 0251dcbca4..e547cbc16a 100644
--- a/docs/ref/templates/builtins.txt
+++ b/docs/ref/templates/builtins.txt
@@ -771,48 +771,41 @@ regroup
Regroups a list of alike objects by a common attribute.
-This complex tag is best illustrated by use of an example: say that ``people``
-is a list of people represented by dictionaries with ``first_name``,
-``last_name``, and ``gender`` keys:
+This complex tag is best illustrated by way of an example: say that "places" is a list of cities represented by dictionaries containing ``"name"``, ``"population"``, and ``"country"`` keys:
.. code-block:: python
- people = [
- {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
- {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
- {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
- {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
- {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
+ cities = [
+ {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
+ {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
+ {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
+ {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
+ {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]
-...and you'd like to display a hierarchical list that is ordered by gender,
-like this:
+...and you'd like to display a hierarchical list that is ordered by country, like this:
-* Male:
+* India
+ * Mumbai: 19,000,000
+ * Calcutta: 15,000,000
+* USA
+ * New York: 20,000,000
+ * Chicago: 7,000,000
+* Japan
+ * Tokyo: 33,000,000
- * George Bush
- * Bill Clinton
-* Female:
-
- * Margaret Thatcher
- * Condoleezza Rice
-
-* Unknown:
-
- * Pat Smith
-
-You can use the ``{% regroup %}`` tag to group the list of people by gender.
+You can use the ``{% regroup %}`` tag to group the list of cities by country.
The following snippet of template code would accomplish this::
- {% regroup people by gender as gender_list %}
+ {% regroup cities by country as country_list %}
<ul>
- {% for gender in gender_list %}
- <li>{{ gender.grouper }}
+ {% for country in country_list %}
+ <li>{{ country.grouper }}
<ul>
- {% for item in gender.list %}
- <li>{{ item.first_name }} {{ item.last_name }}</li>
+ {% for item in country.list %}
+ <li>{{ item.name }}: {{ item.population }}</li>
{% endfor %}
</ul>
</li>
@@ -821,56 +814,45 @@ The following snippet of template code would accomplish this::
Let's walk through this example. ``{% regroup %}`` takes three arguments: the
list you want to regroup, the attribute to group by, and the name of the
-resulting list. Here, we're regrouping the ``people`` list by the ``gender``
-attribute and calling the result ``gender_list``.
+resulting list. Here, we're regrouping the ``cities`` list by the ``country``
+attribute and calling the result ``country_list``.
-``{% regroup %}`` produces a list (in this case, ``gender_list``) of
+``{% regroup %}`` produces a list (in this case, ``country_list``) of
**group objects**. Each group object has two attributes:
-* ``grouper`` -- the item that was grouped by (e.g., the string "Male" or
- "Female").
-* ``list`` -- a list of all items in this group (e.g., a list of all people
- with gender='Male').
+* ``grouper`` -- the item that was grouped by (e.g., the string "India" or
+ "Japan").
+* ``list`` -- a list of all items in this group (e.g., a list of all cities
+ with country='India').
Note that ``{% regroup %}`` does not order its input! Our example relies on
-the fact that the ``people`` list was ordered by ``gender`` in the first place.
-If the ``people`` list did *not* order its members by ``gender``, the
-regrouping would naively display more than one group for a single gender. For
-example, say the ``people`` list was set to this (note that the males are not
+the fact that the ``cities`` list was ordered by ``country`` in the first place.
+If the ``cities`` list did *not* order its members by ``country``, the
+regrouping would naively display more than one group for a single country. For
+example, say the ``cities`` list was set to this (note that the countries are not
grouped together):
.. code-block:: python
- people = [
- {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
- {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
- {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
- {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
- {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
+ cities = [
+ {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
+ {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
+ {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
+ {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
+ {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
]
-With this input for ``people``, the example ``{% regroup %}`` template code
+With this input for ``cities``, the example ``{% regroup %}`` template code
above would result in the following output:
-* Male:
-
- * Bill Clinton
-
-* Unknown:
-
- * Pat Smith
-
-* Female:
-
- * Margaret Thatcher
-
-* Male:
-
- * George Bush
-
-* Female:
-
- * Condoleezza Rice
+* India
+ * Mumbai: 19,000,000
+* USA
+ * New York: 20,000,000
+* India
+ * Calcutta: 15,000,000
+* Japan
+ * Tokyo: 33,000,000
The easiest solution to this gotcha is to make sure in your view code that the
data is ordered according to how you want to display it.
@@ -878,27 +860,26 @@ data is ordered according to how you want to display it.
Another solution is to sort the data in the template using the
:tfilter:`dictsort` filter, if your data is in a list of dictionaries::
- {% regroup people|dictsort:"gender" by gender as gender_list %}
-
+ {% regroup cities|dictsort:"country" by country as country_list %}
Grouping on other properties
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Any valid template lookup is a legal grouping attribute for the regroup
tag, including methods, attributes, dictionary keys and list items. For
-example, if the "gender" field is a foreign key to a class with
+example, if the "country" field is a foreign key to a class with
an attribute "description," you could use::
- {% regroup people by gender.description as gender_list %}
+ {% regroup cities by country.description as country_list %}
-Or, if ``gender`` is a field with ``choices``, it will have a
+Or, if ``country`` is a field with ``choices``, it will have a
:meth:`^django.db.models.Model.get_FOO_display` method available as an
attribute, allowing you to group on the display string rather than the
``choices`` key::
- {% regroup people by get_gender_display as gender_list %}
+ {% regroup cities by get_country_display as country_list %}
-``{{ gender.grouper }}`` will now display the value fields from the
+``{{ country.grouper }}`` will now display the value fields from the
``choices`` set rather than the keys.
.. templatetag:: spaceless
diff --git a/docs/topics/db/models.txt b/docs/topics/db/models.txt
index 12ae98a2b7..5b5a12dbd7 100644
--- a/docs/topics/db/models.txt
+++ b/docs/topics/db/models.txt
@@ -172,21 +172,22 @@ ones:
from django.db import models
class Person(models.Model):
- GENDER_CHOICES = (
- (u'M', u'Male'),
- (u'F', u'Female'),
+ SHIRT_SIZES = (
+ (u'S', u'Small'),
+ (u'M', u'Medium'),
+ (u'L', u'Large'),
)
name = models.CharField(max_length=60)
- gender = models.CharField(max_length=2, choices=GENDER_CHOICES)
+ shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)
::
- >>> p = Person(name="Fred Flintstone", gender="M")
+ >>> p = Person(name="Fred Flintstone", shirt_size="L")
>>> p.save()
- >>> p.gender
- u'M'
- >>> p.get_gender_display()
- u'Male'
+ >>> p.shirt_size
+ u'L'
+ >>> p.get_shirt_size_display()
+ u'Large'
:attr:`~Field.default`
The default value for the field. This can be a value or a callable