Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Proofread some of docs/model-api.txt. Still not done with this one.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@2829 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 08fc16705fec15ab9b8b19333a07536aa8e4fe1d 1 parent 1f57fca
Adrian Holovaty authored

Showing 1 changed file with 311 additions and 197 deletions. Show diff stats Hide diff stats

  1. 508  docs/model-api.txt
508  docs/model-api.txt
@@ -37,7 +37,7 @@ This example model defines a ``Person``, which has a ``first_name`` and
37 37
 ``first_name`` and ``last_name`` are *fields* of the model. Each field is
38 38
 specified as a class attribute, and each attribute maps to a database column.
39 39
 
40  
-The above ``Person`` model would create an SQL table like this::
  40
+The above ``Person`` model would create a database table like this::
41 41
 
42 42
     CREATE TABLE myapp_person (
43 43
         "id" serial NOT NULL PRIMARY KEY,
@@ -45,7 +45,7 @@ The above ``Person`` model would create an SQL table like this::
45 45
         "last_name" varchar(30) NOT NULL
46 46
     );
47 47
 
48  
-Three technical notes:
  48
+Some technical notes:
49 49
 
50 50
     * The name of the table, ``myapp_person``, is automatically derived from
51 51
       some model metadata but can be overridden. See _`Table names` below.
@@ -630,16 +630,16 @@ any other ``Field`` type: by including it as a class attribute of your model.
630 630
 ``ForeignKey`` requires a positional argument: The class to which the model is
631 631
 related.
632 632
 
633  
-For example, if a ``Place`` model is in a ``City`` -- that is, a ``City``
634  
-contains multiple places but each ``Place`` is only in one ``City`` -- use the
635  
-following definitions::
  633
+For example, if a ``Car`` model has a ``Manufacturer`` -- that is, a
  634
+``Manufacturer`` makes multiple cars but each ``Car`` only has one
  635
+``Manufacturer`` -- use the following definitions::
636 636
 
637  
-    class City(models.Model):
  637
+    class Manufacturer(models.Model):
638 638
         # ...
639 639
 
640  
-    class Place(models.Model):
  640
+    class Car(models.Model):
  641
+        manufacturer = models.ForeignKey(Manufacturer)
641 642
         # ...
642  
-        city = models.ForeignKey(City)
643 643
 
644 644
 To create a recursive relationship -- an object that has a many-to-one
645 645
 relationship with itself -- use ``models.ForeignKey('self')``.
@@ -647,18 +647,30 @@ relationship with itself -- use ``models.ForeignKey('self')``.
647 647
 If you need to create a relationship on a model that has not yet been defined,
648 648
 you can use the name of the model, rather than the model object itself::
649 649
 
650  
-    class Place(models.Model):
  650
+    class Car(models.Model):
  651
+        manufacturer = models.ForeignKey('Manufacturer')
651 652
         # ...
652  
-        city = models.ForeignKey("City")
653 653
 
654  
-    class City(models.Model):
  654
+    class Manufacturer(models.Model):
655 655
         # ...
656 656
 
657  
-The name of a ``ForeignKey`` (``city`` in the example above) generally should
658  
-be the name of the model, in singular form. Behind the scenes, Django appends
659  
-"_id" to the field name to create its database column name. However, your code
  657
+Note, however, that support for strings around model names in ``ForeignKey`` is
  658
+quite new, and it can be buggy in some cases.
  659
+
  660
+Behind the scenes, Django appends ``"_id"`` to the field name to create its
  661
+database column name. In the above example, the database table for the ``Car``
  662
+model will have a ``manufacturer_id`` column. (You can change this explicitly
  663
+by specifying ``db_column``; see ``db_column`` below.)  However, your code
660 664
 should never have to deal with the database column name, unless you write
661  
-custom SQL.
  665
+custom SQL. You'll always deal with the field names of your model object.
  666
+
  667
+It's suggested, but not required, that the name of a ``ForeignKey`` field
  668
+(``manufacturer`` in the example above) be the name of the model, lowercase.
  669
+You can, of course, call the field whatever you want. For example::
  670
+
  671
+    class Car(models.Model):
  672
+        company_that_makes_it = models.ForeignKey(Manufacturer)
  673
+        # ...
662 674
 
663 675
 See the `Many-to-one relationship model example`_ for a full example.
664 676
 
@@ -684,7 +696,7 @@ relationship should work. All are optional:
684 696
                              with ``models.LazyDate`` to limit choices of objects
685 697
                              by date. For example::
686 698
 
687  
-                                limit_choices_to = {'pub_date__lte' : models.LazyDate()}
  699
+                                limit_choices_to = {'pub_date__lte': models.LazyDate()}
688 700
 
689 701
                              only allows the choice of related objects with a
690 702
                              ``pub_date`` before the current date/time to be
@@ -699,8 +711,9 @@ relationship should work. All are optional:
699 711
                              that a user never enters more than 10 toppings.
700 712
 
701 713
                              Note that this doesn't ensure more than 10 related
702  
-                             toppings ever get created. It just controls the
703  
-                             interface.
  714
+                             toppings ever get created. It simply controls the
  715
+                             admin interface; it doesn't enforce things at the
  716
+                             Python API level or database level.
704 717
 
705 718
     ``min_num_in_admin``     The minimum number of related objects displayed in
706 719
                              the admin. Normally, at the creation stage,
@@ -725,35 +738,9 @@ relationship should work. All are optional:
725 738
                              Not used with ``edit_inline``.
726 739
 
727 740
     ``related_name``         The name to use for the relation from the related
728  
-                             object back to this one.  For example, when if
729  
-                             ``Topping`` has this field::
730  
-
731  
-                                    models.ForeignKey(Pizza)
732  
-
733  
-                             the ``related_name`` will be "topping_set" (taken from
734  
-                             the class name), which will in turn give ``Pizza``
735  
-                             a ``topping_set`` Object Set Descriptor.
736  
-
737  
-                             If you instead were to use::
738  
-
739  
-                                    models.ForeignKey(Pizza, related_name="munchies")
740  
-
741  
-                             then the Object Set Descriptor on ``Topping`` would
742  
-                             be called ``munchies``.
743  
-
744  
-                             This is only really useful when you have a single
745  
-                             object that relates to the same object more than
746  
-                             once.  For example, if a ``Story`` object has both
747  
-                             ``primary_category`` and ``secondary_category``
748  
-                             fields, to make sure that the ``Category`` objects
749  
-                             have the correct methods, you'd use fields like::
750  
-
751  
-                                    models.ForeignKey(Category, related_name="primary_stories")
752  
-                                    models.ForeignKey(Category, related_name="secondary_stories")
753  
-
754  
-                             ...which would give ``Category`` objects two Object Set
755  
-                             descriptors - one called ``primary_stories`` and one
756  
-                             called ``secondary_stories``.
  741
+                             object back to this one. See the
  742
+                             `related objects documentation`_ for a full
  743
+                             explanation and example.
757 744
 
758 745
     ``to_field``             The field on the related object that the relation
759 746
                              is to. By default, Django uses the primary key of
@@ -761,6 +748,7 @@ relationship should work. All are optional:
761 748
     =======================  ============================================================
762 749
 
763 750
 .. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/
  751
+.. _related objects documentation: http://www.djangoproject.com/documentation/db_api/#related-objects
764 752
 
765 753
 Many-to-many relationships
766 754
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -784,11 +772,12 @@ here's how you'd represent that::
784 772
         toppings = models.ManyToManyField(Topping)
785 773
 
786 774
 As with ``ForeignKey``, a relationship to self can be defined by using the
787  
-string ``"self"`` instead of the model name; references to as-yet undefined
788  
-models can be made by using a string containing the model name.
  775
+string ``'self'`` instead of the model name, and you can refer to as-yet
  776
+undefined models by using a string containing the model name.
789 777
 
790  
-The name of a ``ManyToManyField`` (``toppings`` in the example above) should
791  
-generally be a plural describing the set of related model objects.
  778
+It's suggested, but not required, that the name of a ``ManyToManyField``
  779
+(``toppings`` in the example above) be a plural describing the set of related
  780
+model objects.
792 781
 
793 782
 Behind the scenes, Django creates an intermediary join table to represent the
794 783
 many-to-many relationship.
@@ -797,11 +786,11 @@ It doesn't matter which model gets the ``ManyToManyField``, but you only need
797 786
 it in one of the models -- not in both.
798 787
 
799 788
 Generally, ``ManyToManyField`` instances should go in the object that's going
800  
-to be edited in the admin. In the above example, ``toppings`` is in ``Pizza``
801  
-(rather than ``Topping`` having a ``pizzas`` ``ManyToManyField`` ) because it's
802  
-more natural to think about a ``Pizza`` having toppings than a topping being on
803  
-multiple pizzas. The way it's set up above, the ``Pizza`` admin form would let
804  
-users select the toppings.
  789
+to be edited in the admin interface, if you're using Django's admin. In the
  790
+above example, ``toppings`` is in ``Pizza`` (rather than ``Topping`` having a
  791
+``pizzas`` ``ManyToManyField`` ) because it's more natural to think about a
  792
+``Pizza`` having toppings than a topping being on multiple pizzas. The way it's
  793
+set up above, the ``Pizza`` admin form would let users select the toppings.
805 794
 
806 795
 See the `Many-to-many relationship model example`_ for a full example.
807 796
 
@@ -813,8 +802,7 @@ the relationship should work. All are optional:
813 802
     =======================  ============================================================
814 803
     Argument                 Description
815 804
     =======================  ============================================================
816  
-    ``related_name``         See the description of ``related_name`` in
817  
-                             ``ForeignKey`` above.
  805
+    ``related_name``         See the description under ``ForeignKey`` above.
818 806
 
819 807
     ``filter_interface``     Use a nifty unobtrusive Javascript "filter" interface
820 808
                              instead of the usability-challenged ``<select multiple>``
@@ -825,14 +813,6 @@ the relationship should work. All are optional:
825 813
 
826 814
     ``limit_choices_to``     See the description under ``ForeignKey`` above.
827 815
 
828  
-    ``singular``             The singular name of the field.  Use to name the ``get_*``
829  
-                             methods: in the example above, Django gives the ``Pizza``
830  
-                             objects a ``get_topping_list()`` method, where ``topping``
831  
-                             is the default ``singular`` value derived from the lowercase
832  
-                             version of the class being linked to.  Use the singular
833  
-                             parameter to change this, which is if you want one model to
834  
-                             have multiple ``ManyToMany`` relationships to another model.
835  
-
836 816
     ``symmetrical``          Only used in the definition of ManyToManyFields on self.
837 817
                              Consider the following model:
838 818
 
@@ -840,21 +820,26 @@ the relationship should work. All are optional:
840 820
                                  friends = models.ManyToManyField("self")
841 821
 
842 822
                              When Django processes this model, it identifies that it has
843  
-                             a ManyToManyField on itself, and as a result, it doesn't add
844  
-                             a ``person_set`` attribute to the Person class. Instead, the
845  
-                             ManyToManyField is assumed to be symmetrical - that is, if
846  
-                             I am your friend, then you are my friend.
847  
-
848  
-                             If you do not want symmetry in ManyToMany relationships with
849  
-                             self, set ``symmetrical`` to False. This will force Django to
850  
-                             add the descriptor for the reverse relationship, allow
851  
-                             ManyToMany relationships to be non-symmetrical.
  823
+                             a ``ManyToManyField`` on itself, and as a result, it
  824
+                             doesn't add a ``person_set`` attribute to the ``Person``
  825
+                             class. Instead, the ``ManyToManyField`` is assumed to be
  826
+                             symmetrical -- that is, if I am your friend, then you are
  827
+                             my friend.
  828
+
  829
+                             If you do not want symmetry in ``ManyToMany`` relationships
  830
+                             with ``self``, set ``symmetrical`` to ``False``. This will
  831
+                             force Django to add the descriptor for the reverse
  832
+                             relationship, allowing ``ManyToMany`` relationships to be
  833
+                             non-symmetrical.
852 834
 
853 835
     =======================  ============================================================
854 836
 
855 837
 One-to-one relationships
856 838
 ~~~~~~~~~~~~~~~~~~~~~~~~
857 839
 
  840
+The semantics of one-to-one relationships will be changing soon, so we don't
  841
+recommend you use them. If that doesn't scare you away, keep reading.
  842
+
858 843
 To define a one-to-one relationship, use ``OneToOneField``. You use it just
859 844
 like any other ``Field`` type: by including it as a class attribute of your
860 845
 model.
@@ -903,11 +888,12 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
903 888
 ``db_table``
904 889
 ------------
905 890
 
906  
-The name of the database table to use for the module::
  891
+The name of the database table to use for the model::
907 892
 
908  
-    db_table = "pizza_orders"
  893
+    db_table = 'music_album'
909 894
 
910 895
 If this isn't given, Django will use ``app_label + '_' + model_class_name``.
  896
+See "Table names" below for more.
911 897
 
912 898
 If your database table name is an SQL reserved word, or contains characters
913 899
 that aren't allowed in Python variable names -- notably, the hyphen --
@@ -916,27 +902,32 @@ that's OK. Django quotes column and table names behind the scenes.
916 902
 ``get_latest_by``
917 903
 -----------------
918 904
 
919  
-The name of a ``DateField`` or ``DateTimeField``. If given, the module will
920  
-have a ``get_latest()`` function that fetches the "latest" object according
921  
-to that field::
  905
+The name of a ``DateField`` or ``DateTimeField`` in the model. This specifies
  906
+the default field to use in your model ``Manager``'s ``latest()`` method.
  907
+
  908
+Example::
922 909
 
923 910
     get_latest_by = "order_date"
924 911
 
925  
-See `Getting the "latest" object`_ for a full example.
  912
+See the `docs for latest()`_ for more.
926 913
 
927  
-.. _Getting the "latest" object: http://www.djangoproject.com/documentation/models/get_latest/
  914
+.. _docs for latest(): http://www.djangoproject.com/documentation/db_api/#latest-field-name-none
928 915
 
929 916
 ``order_with_respect_to``
930 917
 -------------------------
931 918
 
932 919
 Marks this object as "orderable" with respect to the given field. This is
933 920
 almost always used with related objects to allow them to be ordered with
934  
-respect to a parent object. For example, if a ``PizzaToppping`` relates to
935  
-a ``Pizza`` object, you might use::
  921
+respect to a parent object. For example, if an ``Answer`` relates to a
  922
+``Question`` object, and a question has more than one answer, and the order
  923
+of answers matters, you'd do this::
936 924
 
937  
-    order_with_respect_to = 'pizza'
  925
+    class Answer(models.Model):
  926
+        question = models.ForeignKey(Question)
  927
+        # ...
938 928
 
939  
-...to allow the toppings to be ordered with respect to the associated pizza.
  929
+        class Meta:
  930
+            order_with_respect_to = 'question'
940 931
 
941 932
 ``ordering``
942 933
 ------------
@@ -1012,177 +1003,297 @@ The plural name for the object::
1012 1003
 
1013 1004
 If this isn't given, Django will use ``verbose_name + "s"``.
1014 1005
 
  1006
+Table names
  1007
+===========
1015 1008
 
  1009
+To save you time, Django automatically derives the name of the database table
  1010
+from the name of your model class and the app that contains it. A model's
  1011
+database table name is constructed by joining the model's "app label" -- the
  1012
+name you used in ``manage.py startapp`` -- to the model's class name, with an
  1013
+underscore between them.
1016 1014
 
1017  
-========================================
1018  
-THE REST OF THIS HAS NOT YET BEEN EDITED
1019  
-========================================
1020  
-
1021  
-
  1015
+For example, if you have an app ``bookstore`` (as created by
  1016
+``manage.py startapp bookstore``), a model defined as ``class Book`` will have
  1017
+a database table named ``bookstore_book``.
1022 1018
 
1023  
-Table names
1024  
-===========
  1019
+To override the database table name, use the ``db_table`` parameter in
  1020
+``class Meta``.
1025 1021
 
1026 1022
 Automatic primary key fields
1027 1023
 ============================
1028 1024
 
  1025
+By default, Django gives each model the following field::
  1026
+
  1027
+    id = models.AutoField(primary_key=True)
  1028
+
  1029
+This is an auto-incrementing primary key.
  1030
+
  1031
+If you'd like to specify a custom primary key, just specify ``primary_key=True``
  1032
+on one of your fields. If Django sees you've explicitly set ``primary_key``, it
  1033
+won't add the automatic ``id`` column.
  1034
+
  1035
+Each model requires exactly one field to have ``primary_key=True``.
1029 1036
 
1030 1037
 Admin options
1031 1038
 =============
1032 1039
 
1033  
-If you want your model to be visible to the automatic Administration
1034  
-system, your model must have an inner ``"class Admin"``, like so::
  1040
+If you want your model to be visible to Django's admin site, give your model an
  1041
+inner ``"class Admin"``, like so::
  1042
+
  1043
+    class Person(models.Model):
  1044
+        first_name = models.CharField(maxlength=30)
  1045
+        last_name = models.CharField(maxlength=30)
1035 1046
 
1036  
-    class Foo(models.Model):
1037  
-        bar = models.CharField(maxlength=30)
1038  
-        # ...
1039 1047
         class Admin:
1040  
-            # ...
  1048
+            # Admin options go here
  1049
+            pass
1041 1050
 
1042  
-The Admin class gives instructions to Django on how to display the Model
1043  
-to the Administration system.
  1051
+The ``Admin`` class tells Django how to display the model in the admin site.
1044 1052
 
1045  
-Here's a list of all possible ``Admin`` options. No options are required. Adding
1046  
-``class Admin`` to a model is completely optional.
  1053
+Here's a list of all possible ``Admin`` options. None of these options are
  1054
+required. To use an admin interface without specifying any options, use
  1055
+``pass``, like so::
  1056
+
  1057
+    class Admin:
  1058
+        pass
  1059
+
  1060
+Adding ``class Admin`` to a model is completely optional.
1047 1061
 
1048 1062
 ``date_hierarchy``
1049  
-    To allow filtering of objects in the admin by date, set ``date_hierarchy``
1050  
-    to the name of the field to filter by::
  1063
+------------------
  1064
+
  1065
+Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in
  1066
+your model, and the change list page will include a date-based drilldown
  1067
+navigation by that field.
1051 1068
 
1052  
-        date_hierarchy = 'order_date'
  1069
+Example::
  1070
+
  1071
+    date_hierarchy = 'pub_date'
1053 1072
 
1054 1073
 ``fields``
1055  
-    A list of fieldsets to display on the admin page.  Each fieldset is a 2-tuple:
1056  
-    ``(name, field_options)``.  The ``name`` is a string to name the field set,
1057  
-    and ``field_options`` is a dictionary of information about the fields to be
1058  
-    displayed in that fieldset. This dictionary has the following keys:
  1074
+----------
  1075
+
  1076
+Set ``fields`` to control the layout of admin "add" and "change" pages.
  1077
+
  1078
+``fields`` is a list of two-tuples, in which each two-tuple represents a
  1079
+``<fieldset>`` on the admin form page. (A ``<fieldset>`` is a "section" of the
  1080
+form.)
  1081
+
  1082
+The two-tuples are in the format ``(name, field_options)``, where ``name`` is a
  1083
+string representing the title of the fieldset and ``field_options`` is a
  1084
+dictionary of information about the fieldset, including a list of fields to be
  1085
+displayed in it.
  1086
+
  1087
+A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::
  1088
+
  1089
+    class Admin:
  1090
+        fields = (
  1091
+            (None, {
  1092
+                'fields': ('url', 'title', 'content', 'sites')
  1093
+            }),
  1094
+            ('Advanced options', {
  1095
+                'classes': 'collapse',
  1096
+                'fields' : ('enable_comments', 'registration_required', 'template_name')
  1097
+            }),
  1098
+        )
1059 1099
 
1060  
-        ``fields``
1061  
-            A tuple of field names to display in this fieldset. To display
1062  
-            multiple fields on the same line, wrap those fields in their
1063  
-            own tuple.
  1100
+This results in an admin page that looks like:
1064 1101
 
1065  
-            This key is required in the dictionary.
  1102
+    .. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
1066 1103
 
1067  
-        ``classes``
1068  
-            Extra CSS classes to apply to the fieldset. This is a simple
1069  
-            string. You can apply multiple classes by separating them with
1070  
-            spaces.
  1104
+If ``fields`` isn't given, Django will default to displaying each field that
  1105
+isn't an ``AutoField`` and has ``editable=True``, in a single fieldset, in
  1106
+the same order as the fields are defined in the model.
1071 1107
 
1072  
-            Two useful classes defined by the default stylesheet are
1073  
-            ``collapse`` and ``wide``.  Fieldsets with the ``collapse`` style
1074  
-            will be initially collapsed in the admin and replaced with a small
1075  
-            "click to expand" link.  Fieldsets with the ``wide`` style will be
1076  
-            given extra horizontal space.
  1108
+The ``field_options`` dictionary can have the following keys::
1077 1109
 
1078  
-        ``description``
1079  
-            Optional extra text to be displayed at the top of each fieldset,
1080  
-            underneath the heading of the fieldset.  It is used verbatim,
1081  
-            so you can use any HTML and you must escape any special HTML
1082  
-            characters (such as ampersand) yourself.
  1110
+``fields``
  1111
+~~~~~~~~~~
1083 1112
 
1084  
-    For example (taken from the ``django.contrib.flatpages`` model)::
  1113
+A tuple of field names to display in this fieldset. This key is required.
1085 1114
 
1086  
-        class Admin:
1087  
-            ...
1088  
-            fields = (
1089  
-                (None, {
1090  
-                    'fields': ('url', 'title', 'content', 'sites')
1091  
-                }),
1092  
-                ('Advanced options', {
1093  
-                    'classes': 'collapse',
1094  
-                    'fields' : ('enable_comments', 'registration_required', 'template_name')
1095  
-                }),
1096  
-            )
  1115
+Example::
  1116
+
  1117
+    {
  1118
+    'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
  1119
+    }
  1120
+
  1121
+To display multiple fields on the same line, wrap those fields in their own
  1122
+tuple. In this example, the ``first_name`` and ``last_name`` fields will
  1123
+display on the same line::
  1124
+
  1125
+    {
  1126
+    'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
  1127
+    }
  1128
+
  1129
+``classes``
  1130
+~~~~~~~~~~~
  1131
+
  1132
+A string containing extra CSS classes to apply to the fieldset.
  1133
+
  1134
+Example::
  1135
+
  1136
+    {
  1137
+    'classes': 'wide',
  1138
+    }
  1139
+
  1140
+Apply multiple classes by separating them with spaces. Example::
  1141
+
  1142
+    {
  1143
+    'classes': 'wide extrapretty',
  1144
+    }
1097 1145
 
1098  
-    results in an admin that looks like:
  1146
+Two useful classes defined by the default admin-site stylesheet are
  1147
+``collapse`` and ``wide``. Fieldsets with the ``collapse`` style will be
  1148
+initially collapsed in the admin and replaced with a small "click to expand"
  1149
+link. Fieldsets with the ``wide`` style will be given extra horizontal space.
1099 1150
 
1100  
-        .. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
  1151
+``description``
  1152
+~~~~~~~~~~~~~~~
1101 1153
 
1102  
-    If ``fields`` isn't given Django will default to displaying each field that
1103  
-    isn't an ``AutoField`` and has ``editable=True``, in a single fieldset, in
1104  
-    the same order as the fields are defined in the model.
  1154
+A string of optional extra text to be displayed at the top of each fieldset,
  1155
+under the heading of the fieldset. It's used verbatim, so you can use any HTML
  1156
+and you must escape any special HTML characters (such as ampersands) yourself.
1105 1157
 
1106 1158
 ``js``
1107  
-    A list of strings representing URLs of JavaScript files to link into the
1108  
-    admin screen. This can be used to tweak a given type of admin page in JS or
1109  
-    to provide "quick links" to fill in default values for certain fields.
  1159
+------
  1160
+
  1161
+A list of strings representing URLs of JavaScript files to link into the admin
  1162
+screen via ``<script src="">`` tags. This can be used to tweak a given type of
  1163
+admin page in JavaScript or to provide "quick links" to fill in default values
  1164
+for certain fields.
1110 1165
 
1111 1166
 ``list_display``
1112  
-    List of fields to display on the list page in the admin.
  1167
+----------------
  1168
+
  1169
+Set ``list_display`` to control which fields are displayed on the change list
  1170
+page of the admin.
  1171
+
  1172
+Example::
1113 1173
 
1114  
-    There are a few special cases that do other things besides displaying the
1115  
-    contents of the given fields:
  1174
+    list_display = ('first_name', 'last_name')
1116 1175
 
1117  
-        * If the field given is a ``ForeignKey``, the ``repr()`` of the related
1118  
-          object will be displayed.
  1176
+If you don't set ``list_display``, the admin site will display a single column
  1177
+that displays the ``__str__()`` representation of each object.
1119 1178
 
1120  
-        * ``ManyToManyField`` fields aren't supported, because that would
1121  
-          entail executing a separate SQL statement for each row in the table.
  1179
+A few special cases to note about ``list_display``:
1122 1180
 
1123  
-        * If the field is a ``BooleanField``, a "on" or "off" icon will
1124  
-          be displayed instead of ``True`` or ``False``.
  1181
+    * If the field is a ``ForeignKey``, Django will display the ``__str__()``
  1182
+      of the related object.
1125 1183
 
1126  
-        * If the field name is a method of the model, it'll be called, and the
1127  
-          output will be displayed. This method should have a
1128  
-          ``short_description`` function attribute, for use as the header for
1129  
-          the field.
  1184
+    * ``ManyToManyField`` fields aren't supported, because that would entail
  1185
+        executing a separate SQL statement for each row in the table.
1130 1186
 
1131  
-        * Use the string ``"__str__"`` to output the representation of the
1132  
-          object, according to your model's ``__str__()`` function. If you
1133  
-          don't define ``list_display``, Django will use the ``__str__`` by
1134  
-          default.
  1187
+    * If the field is a ``BooleanField``, Django will display a pretty "on" or
  1188
+      "off" icon instead of ``True`` or ``False``.
1135 1189
 
1136  
-    See the example below.
  1190
+    * If the string given is a method of the model, Django will call it and
  1191
+      display the output. This method should have a ``short_description``
  1192
+      function attribute, for use as the header for the field.
  1193
+
  1194
+      Here's a full example model::
  1195
+
  1196
+          class Person(models.Model):
  1197
+              name = models.CharField(maxlength=50)
  1198
+              birthday = models.DateField()
  1199
+
  1200
+              class Admin:
  1201
+                  list_display = ('name', 'decade_born_in')
  1202
+
  1203
+              def decade_born_in(self):
  1204
+                  return self.birthday.strftime('%Y')[:3] + "0's"
  1205
+              decade_born_in.short_description = 'Birth decade'
1137 1206
 
1138 1207
 ``list_filter``
1139  
-    List of fields to filter by. Each field should either be a ``BooleanField``
1140  
-    or else a field with a ``ManyToOne`` relation.
  1208
+---------------
1141 1209
 
1142  
-    Here's an example of how ``list_display`` and ``list_filter`` work (taken
1143  
-    from the ``auth.user`` model)::
  1210
+Set ``list_filter`` to activate filters in the right sidebar of the change list
  1211
+page of the admin. This should be a list of field names, and each specified
  1212
+field should be either a ``BooleanField``, ``DateField``, ``DateTimeField``
  1213
+or ``ForeignKey``.
1144 1214
 
1145  
-        class Admin:
1146  
-            #...
1147  
-            list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
1148  
-            list_filter = ('is_staff', 'is_superuser')
  1215
+This example, taken from the ``django.contrib.auth.models.User`` model, shows
  1216
+how both ``list_display`` and ``list_filter`` work::
1149 1217
 
1150  
-    The above code results in an admin that looks like this:
  1218
+    class Admin:
  1219
+        list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
  1220
+        list_filter = ('is_staff', 'is_superuser')
1151 1221
 
1152  
-        .. image:: http://media.djangoproject.com/img/doc/users_changelist.png
  1222
+The above code results in an admin change list page that looks like this:
1153 1223
 
1154  
-    (This example also has ``search_fields`` defined; see below).
  1224
+    .. image:: http://media.djangoproject.com/img/doc/users_changelist.png
  1225
+
  1226
+(This example also has ``search_fields`` defined. See below.)
1155 1227
 
1156 1228
 ``list_select_related``
1157  
-    Either ``True`` or ``False``. Default is ``False``. If ``True``, the admin
1158  
-    change list page will use the ``select_related`` database-API parameter in
1159  
-    its query that retrieves the list of items.
  1229
+-----------------------
  1230
+
  1231
+Set ``list_select_related`` to tell Django to use ``select_related()`` in
  1232
+retrieving the list of objects on the admin change list page. This can save you
  1233
+a bunch of database queries.
  1234
+
  1235
+The value should be either ``True`` or ``False``. Default is ``False``.
  1236
+
  1237
+Note that Django will use ``select_related()``, regardless of this setting,
  1238
+if one of the ``list_display`` fields is a ``ForeignKey``.
  1239
+
  1240
+For more on ``select_related()``, see `the select_related() docs`_.
1160 1241
 
1161  
-    Note that Django will use ``select_related``, regardless of this setting,
1162  
-    if one of the ``list_display`` fields is a ``ForeignKey``.
  1242
+.. _the select_related() docs: http://www.djangoproject.com/documentation/db_api/#select-related
1163 1243
 
1164 1244
 ``ordering``
1165  
-    A list or tuple (see the `Meta options`_, above) that gives a
1166  
-    different ordering for the admin change list. If this isn't given, the
1167  
-    model's default ordering will be used.
  1245
+------------
  1246
+
  1247
+Set ``ordering`` to specify how objects on the admin change list page should be
  1248
+ordered. This should be a list or tuple in the same format as a model's
  1249
+``ordering`` parameter.
  1250
+
  1251
+If this isn't provided, the Django admin will use the model's default ordering.
1168 1252
 
1169 1253
 ``save_as``
1170  
-    Enables a "save as" feature on object pages.  Normally, objects have three
1171  
-    save options: "Save", "Save and continue editing" and "Save and add
1172  
-    another". If ``save_as`` is ``True``, "Save and add another" will be
1173  
-    replaced by a "Save as" button.
  1254
+-----------
  1255
+
  1256
+Set ``save_as`` to enable a "save as" feature on admin change forms.
  1257
+
  1258
+Normally, objects have three save options: "Save", "Save and continue editing"
  1259
+and "Save and add another". If ``save_as`` is ``True``, "Save and add another"
  1260
+will be replaced by a "Save as" button.
1174 1261
 
1175  
-    "Save as" means the object will be saved as a new object (with a new ID),
1176  
-    rather than the old object.
  1262
+"Save as" means the object will be saved as a new object (with a new ID),
  1263
+rather than the old object.
  1264
+
  1265
+By default, ``save_as`` is set to ``False``.
1177 1266
 
1178 1267
 ``save_on_top``
1179  
-    If this option is ``True``, object pages will have the save buttons across
1180  
-    the top as well as at the bottom of the page.
  1268
+---------------
  1269
+
  1270
+Set ``save_on_top`` to add save buttons across the top of your admin change
  1271
+forms.
  1272
+
  1273
+Normally, the save buttons appear only at the bottom of the forms. If you set
  1274
+``save_on_top``, the buttons will appear both on the top and the bottom.
  1275
+
  1276
+By default, ``save_on_top`` is set to ``False``.
1181 1277
 
1182 1278
 ``search_fields``
1183  
-    A list of field names to provide a text search for. These fields should,
1184  
-    obviously, be some kind of text field, such as ``CharField`` or
1185  
-    ``TextField``.
  1279
+-----------------
  1280
+
  1281
+Set ``search_fields`` to enable a search box on the admin change list page.
  1282
+This should be set to a list of field names that will be searched whenever
  1283
+somebody submits a search query in that text box.
  1284
+
  1285
+These fields should be some kind of text field, such as ``CharField`` or
  1286
+``TextField``.
  1287
+
  1288
+When somebody does a search in the admin search box, Django splits the search
  1289
+query into words and returns all objects that contain each of the words, case
  1290
+insensitive, where each word must be in at least one of ``search_fields``. For
  1291
+example, if ``search_fields`` is set to ``['first_name', 'last_name']`` and a
  1292
+user searches for ``john lennon``, Django will do the equivalent of this SQL
  1293
+``WHERE`` clause::
  1294
+
  1295
+    WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')
  1296
+    AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')
1186 1297
 
1187 1298
 Managers
1188 1299
 ========
@@ -1339,6 +1450,9 @@ method::
1339 1450
 Manipulator methods
1340 1451
 -------------------
1341 1452
 
  1453
+(The functionality in this section is going away soon. This documentation is
  1454
+provided only for legacy purposes at this point.)
  1455
+
1342 1456
 Similarly, you can add methods to the object's manipulators by defining methods
1343 1457
 that being with "_manipulator_". This is most useful for providing custom
1344 1458
 validators for certain fields, because manipulators automatically call any

0 notes on commit 08fc167

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