Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.4.X] Replaced documentation snippets using "gender" with less sens…

…itive examples.

Backport of [7edf231] from master.
  • Loading branch information...
commit 45d43317b7db845a7c565522b3e6e6b2dab46a64 1 parent 0a8a6b9
Jacob Kaplan-Moss authored June 06, 2012
1  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
334 334
 
335 335
     class Person(models.Model):
336 336
         name = models.CharField(max_length=80)
337  
-        gender = models.CharField(max_length=1)
338 337
         something_else = MytypeField()
339 338
 
340 339
 If you aim to build a database-agnostic application, you should account for
2  docs/ref/forms/widgets.txt
@@ -47,14 +47,12 @@ widget on the field. In the following example, the
47 47
     from django.forms.extras.widgets import SelectDateWidget
48 48
 
49 49
     BIRTH_YEAR_CHOICES = ('1980', '1981', '1982')
50  
-    GENDER_CHOICES = (('m', 'Male'), ('f', 'Female'))
51 50
     FAVORITE_COLORS_CHOICES = (('blue', 'Blue'),
52 51
                                 ('green', 'Green'),
53 52
                                 ('black', 'Black'))
54 53
 
55 54
     class SimpleForm(forms.Form):
56 55
         birth_year = DateField(widget=SelectDateWidget(years=BIRTH_YEAR_CHOICES))
57  
-        gender = ChoiceField(widget=RadioSelect, choices=GENDER_CHOICES)
58 56
         favorite_colors = forms.MultipleChoiceField(required=False,
59 57
             widget=CheckboxSelectMultiple, choices=FAVORITE_COLORS_CHOICES)
60 58
 
22  docs/ref/models/fields.txt
@@ -103,20 +103,26 @@ element is the human-readable name for the option.
103 103
 The choices list can be defined either as part of your model class::
104 104
 
105 105
     class Foo(models.Model):
106  
-        GENDER_CHOICES = (
107  
-            ('M', 'Male'),
108  
-            ('F', 'Female'),
  106
+        YEAR_IN_SCHOOL_CHOICES = (
  107
+            ('FR', 'Freshman'),
  108
+            ('SO', 'Sophomore'),
  109
+            ('JR', 'Junior'),
  110
+            ('SR', 'Senior'),
  111
+            ('GR', 'Graduate'),
109 112
         )
110  
-        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
  113
+        year_in_school = models.CharField(max_length=2, choices=YEAR_IN_SCHOOL_CHOICES)
111 114
 
112 115
 or outside your model class altogether::
113 116
 
114  
-    GENDER_CHOICES = (
115  
-        ('M', 'Male'),
116  
-        ('F', 'Female'),
  117
+    YEAR_IN_SCHOOL_CHOICES = (
  118
+        ('FR', 'Freshman'),
  119
+        ('SO', 'Sophomore'),
  120
+        ('JR', 'Junior'),
  121
+        ('SR', 'Senior'),
  122
+        ('GR', 'Graduate'),
117 123
     )
118 124
     class Foo(models.Model):
119  
-        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
  125
+        year_in_school = models.CharField(max_length=2, choices=YEAR_IN_SCHOOL_CHOICES)
120 126
 
121 127
 You can also collect your available choices into named groups that can
122 128
 be used for organizational purposes::
38  docs/ref/models/instances.txt
@@ -550,25 +550,29 @@ might have some of the following methods:
550 550
 
551 551
 For every field that has :attr:`~django.db.models.Field.choices` set, the
552 552
 object will have a ``get_FOO_display()`` method, where ``FOO`` is the name of
553  
-the field. This method returns the "human-readable" value of the field. For
554  
-example, in the following model::
  553
+the field. This method returns the "human-readable" value of the field.
555 554
 
556  
-    GENDER_CHOICES = (
557  
-        ('M', 'Male'),
558  
-        ('F', 'Female'),
559  
-    )
560  
-    class Person(models.Model):
561  
-        name = models.CharField(max_length=20)
562  
-        gender = models.CharField(max_length=1, choices=GENDER_CHOICES)
563  
-
564  
-...each ``Person`` instance will have a ``get_gender_display()`` method. Example::
  555
+For example::
565 556
 
566  
-    >>> p = Person(name='John', gender='M')
567  
-    >>> p.save()
568  
-    >>> p.gender
569  
-    'M'
570  
-    >>> p.get_gender_display()
571  
-    'Male'
  557
+        from django.db import models
  558
+
  559
+        class Person(models.Model):
  560
+            SHIRT_SIZES = (
  561
+                (u'S', u'Small'),
  562
+                (u'M', u'Medium'),
  563
+                (u'L', u'Large'),
  564
+            )
  565
+            name = models.CharField(max_length=60)
  566
+            shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)
  567
+
  568
+    ::
  569
+
  570
+        >>> p = Person(name="Fred Flintstone", shirt_size="L")
  571
+        >>> p.save()
  572
+        >>> p.shirt_size
  573
+        u'L'
  574
+        >>> p.get_shirt_size_display()
  575
+        u'Large'
572 576
 
573 577
 .. method:: Model.get_next_by_FOO(\**kwargs)
574 578
 .. method:: Model.get_previous_by_FOO(\**kwargs)
127  docs/ref/templates/builtins.txt
@@ -771,48 +771,41 @@ regroup
771 771
 
772 772
 Regroups a list of alike objects by a common attribute.
773 773
 
774  
-This complex tag is best illustrated by use of an example: say that ``people``
775  
-is a list of people represented by dictionaries with ``first_name``,
776  
-``last_name``, and ``gender`` keys:
  774
+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:
777 775
 
778 776
 .. code-block:: python
779 777
 
780  
-    people = [
781  
-        {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
782  
-        {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
783  
-        {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
784  
-        {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
785  
-        {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
  778
+    cities = [
  779
+        {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
  780
+        {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
  781
+        {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
  782
+        {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
  783
+        {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
786 784
     ]
787 785
 
788  
-...and you'd like to display a hierarchical list that is ordered by gender,
789  
-like this:
  786
+...and you'd like to display a hierarchical list that is ordered by country, like this:
790 787
 
791  
-* Male:
  788
+* India
  789
+    * Mumbai: 19,000,000
  790
+    * Calcutta: 15,000,000
  791
+* USA
  792
+    * New York: 20,000,000
  793
+    * Chicago: 7,000,000
  794
+* Japan
  795
+    * Tokyo: 33,000,000
792 796
 
793  
-  * George Bush
794  
-  * Bill Clinton
795 797
 
796  
-* Female:
797  
-
798  
-  * Margaret Thatcher
799  
-  * Condoleezza Rice
800  
-
801  
-* Unknown:
802  
-
803  
-  * Pat Smith
804  
-
805  
-You can use the ``{% regroup %}`` tag to group the list of people by gender.
  798
+You can use the ``{% regroup %}`` tag to group the list of cities by country.
806 799
 The following snippet of template code would accomplish this::
807 800
 
808  
-    {% regroup people by gender as gender_list %}
  801
+    {% regroup cities by country as country_list %}
809 802
 
810 803
     <ul>
811  
-    {% for gender in gender_list %}
812  
-        <li>{{ gender.grouper }}
  804
+    {% for country in country_list %}
  805
+        <li>{{ country.grouper }}
813 806
         <ul>
814  
-            {% for item in gender.list %}
815  
-            <li>{{ item.first_name }} {{ item.last_name }}</li>
  807
+            {% for item in country.list %}
  808
+              <li>{{ item.name }}: {{ item.population }}</li>
816 809
             {% endfor %}
817 810
         </ul>
818 811
         </li>
@@ -821,56 +814,45 @@ The following snippet of template code would accomplish this::
821 814
 
822 815
 Let's walk through this example. ``{% regroup %}`` takes three arguments: the
823 816
 list you want to regroup, the attribute to group by, and the name of the
824  
-resulting list. Here, we're regrouping the ``people`` list by the ``gender``
825  
-attribute and calling the result ``gender_list``.
  817
+resulting list. Here, we're regrouping the ``cities`` list by the ``country``
  818
+attribute and calling the result ``country_list``.
826 819
 
827  
-``{% regroup %}`` produces a list (in this case, ``gender_list``) of
  820
+``{% regroup %}`` produces a list (in this case, ``country_list``) of
828 821
 **group objects**. Each group object has two attributes:
829 822
 
830  
-* ``grouper`` -- the item that was grouped by (e.g., the string "Male" or
831  
-  "Female").
832  
-* ``list`` -- a list of all items in this group (e.g., a list of all people
833  
-  with gender='Male').
  823
+* ``grouper`` -- the item that was grouped by (e.g., the string "India" or
  824
+  "Japan").
  825
+* ``list`` -- a list of all items in this group (e.g., a list of all cities
  826
+  with country='India').
834 827
 
835 828
 Note that ``{% regroup %}`` does not order its input! Our example relies on
836  
-the fact that the ``people`` list was ordered by ``gender`` in the first place.
837  
-If the ``people`` list did *not* order its members by ``gender``, the
838  
-regrouping would naively display more than one group for a single gender. For
839  
-example, say the ``people`` list was set to this (note that the males are not
  829
+the fact that the ``cities`` list was ordered by ``country`` in the first place.
  830
+If the ``cities`` list did *not* order its members by ``country``, the
  831
+regrouping would naively display more than one group for a single country. For
  832
+example, say the ``cities`` list was set to this (note that the countries are not
840 833
 grouped together):
841 834
 
842 835
 .. code-block:: python
843 836
 
844  
-    people = [
845  
-        {'first_name': 'Bill', 'last_name': 'Clinton', 'gender': 'Male'},
846  
-        {'first_name': 'Pat', 'last_name': 'Smith', 'gender': 'Unknown'},
847  
-        {'first_name': 'Margaret', 'last_name': 'Thatcher', 'gender': 'Female'},
848  
-        {'first_name': 'George', 'last_name': 'Bush', 'gender': 'Male'},
849  
-        {'first_name': 'Condoleezza', 'last_name': 'Rice', 'gender': 'Female'},
  837
+    cities = [
  838
+        {'name': 'Mumbai', 'population': '19,000,000', 'country': 'India'},
  839
+        {'name': 'New York', 'population': '20,000,000', 'country': 'USA'},
  840
+        {'name': 'Calcutta', 'population': '15,000,000', 'country': 'India'},
  841
+        {'name': 'Chicago', 'population': '7,000,000', 'country': 'USA'},
  842
+        {'name': 'Tokyo', 'population': '33,000,000', 'country': 'Japan'},
850 843
     ]
851 844
 
852  
-With this input for ``people``, the example ``{% regroup %}`` template code
  845
+With this input for ``cities``, the example ``{% regroup %}`` template code
853 846
 above would result in the following output:
854 847
 
855  
-* Male:
856  
-
857  
-  * Bill Clinton
858  
-
859  
-* Unknown:
860  
-
861  
-  * Pat Smith
862  
-
863  
-* Female:
864  
-
865  
-  * Margaret Thatcher
866  
-
867  
-* Male:
868  
-
869  
-  * George Bush
870  
-
871  
-* Female:
872  
-
873  
-  * Condoleezza Rice
  848
+* India
  849
+    * Mumbai: 19,000,000
  850
+* USA
  851
+    * New York: 20,000,000
  852
+* India
  853
+    * Calcutta: 15,000,000
  854
+* Japan
  855
+    * Tokyo: 33,000,000
874 856
 
875 857
 The easiest solution to this gotcha is to make sure in your view code that the
876 858
 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.
878 860
 Another solution is to sort the data in the template using the
879 861
 :tfilter:`dictsort` filter, if your data is in a list of dictionaries::
880 862
 
881  
-    {% regroup people|dictsort:"gender" by gender as gender_list %}
882  
-
  863
+    {% regroup cities|dictsort:"country" by country as country_list %}
883 864
 
884 865
 Grouping on other properties
885 866
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
886 867
 
887 868
 Any valid template lookup is a legal grouping attribute for the regroup
888 869
 tag, including methods, attributes, dictionary keys and list items. For
889  
-example, if the "gender" field is a foreign key to a class with
  870
+example, if the "country" field is a foreign key to a class with
890 871
 an attribute "description," you could use::
891 872
 
892  
-    {% regroup people by gender.description as gender_list %}
  873
+    {% regroup cities by country.description as country_list %}
893 874
 
894  
-Or, if ``gender`` is a field with ``choices``, it will have a
  875
+Or, if ``country`` is a field with ``choices``, it will have a
895 876
 :meth:`^django.db.models.Model.get_FOO_display` method available as an
896 877
 attribute, allowing  you to group on the display string rather than the
897 878
 ``choices`` key::
898 879
 
899  
-    {% regroup people by get_gender_display as gender_list %}
  880
+    {% regroup cities by get_country_display as country_list %}
900 881
 
901  
-``{{ gender.grouper }}`` will now display the value fields from the
  882
+``{{ country.grouper }}`` will now display the value fields from the
902 883
 ``choices`` set rather than the keys.
903 884
 
904 885
 .. templatetag:: spaceless
19  docs/topics/db/models.txt
@@ -172,21 +172,22 @@ ones:
172 172
         from django.db import models
173 173
 
174 174
         class Person(models.Model):
175  
-            GENDER_CHOICES = (
176  
-                (u'M', u'Male'),
177  
-                (u'F', u'Female'),
  175
+            SHIRT_SIZES = (
  176
+                (u'S', u'Small'),
  177
+                (u'M', u'Medium'),
  178
+                (u'L', u'Large'),
178 179
             )
179 180
             name = models.CharField(max_length=60)
180  
-            gender = models.CharField(max_length=2, choices=GENDER_CHOICES)
  181
+            shirt_size = models.CharField(max_length=2, choices=SHIRT_SIZES)
181 182
 
182 183
     ::
183 184
 
184  
-        >>> p = Person(name="Fred Flintstone", gender="M")
  185
+        >>> p = Person(name="Fred Flintstone", shirt_size="L")
185 186
         >>> p.save()
186  
-        >>> p.gender
187  
-        u'M'
188  
-        >>> p.get_gender_display()
189  
-        u'Male'
  187
+        >>> p.shirt_size
  188
+        u'L'
  189
+        >>> p.get_shirt_size_display()
  190
+        u'Large'
190 191
 
191 192
 :attr:`~Field.default`
192 193
     The default value for the field. This can be a value or a callable

0 notes on commit 45d4331

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