p31829507
/
django
mirror of https://github.com/django/django.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Replaced documentation snippets using "gender" with less sensitive examples.

This commit is contained in:
Jacob Kaplan-Moss 2012-06-06 11:54:26 +02:00
parent 70a0351fef
commit 7edf231d46
6 changed files with 98 additions and 109 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/howto/custom-model-fields.txt
View File

@ -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

2
docs/ref/forms/widgets.txt
View File

@ -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)

22
docs/ref/models/fields.txt
View File

@ -102,20 +102,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::

36
docs/ref/models/instances.txt
View File

@ -572,25 +572,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)

127
docs/ref/templates/builtins.txt
View File

@ -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

19
docs/topics/db/models.txt
View File

@ -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