Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

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
@adrianholovaty adrianholovaty authored
Showing with 311 additions and 197 deletions.
  1. +311 −197 docs/model-api.txt
View
508 docs/model-api.txt
@@ -37,7 +37,7 @@ This example model defines a ``Person``, which has a ``first_name`` and
``first_name`` and ``last_name`` are *fields* of the model. Each field is
specified as a class attribute, and each attribute maps to a database column.
-The above ``Person`` model would create an SQL table like this::
+The above ``Person`` model would create a database table like this::
CREATE TABLE myapp_person (
"id" serial NOT NULL PRIMARY KEY,
@@ -45,7 +45,7 @@ The above ``Person`` model would create an SQL table like this::
"last_name" varchar(30) NOT NULL
);
-Three technical notes:
+Some technical notes:
* The name of the table, ``myapp_person``, is automatically derived from
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.
``ForeignKey`` requires a positional argument: The class to which the model is
related.
-For example, if a ``Place`` model is in a ``City`` -- that is, a ``City``
-contains multiple places but each ``Place`` is only in one ``City`` -- use the
-following definitions::
+For example, if a ``Car`` model has a ``Manufacturer`` -- that is, a
+``Manufacturer`` makes multiple cars but each ``Car`` only has one
+``Manufacturer`` -- use the following definitions::
- class City(models.Model):
+ class Manufacturer(models.Model):
# ...
- class Place(models.Model):
+ class Car(models.Model):
+ manufacturer = models.ForeignKey(Manufacturer)
# ...
- city = models.ForeignKey(City)
To create a recursive relationship -- an object that has a many-to-one
relationship with itself -- use ``models.ForeignKey('self')``.
@@ -647,18 +647,30 @@ relationship with itself -- use ``models.ForeignKey('self')``.
If you need to create a relationship on a model that has not yet been defined,
you can use the name of the model, rather than the model object itself::
- class Place(models.Model):
+ class Car(models.Model):
+ manufacturer = models.ForeignKey('Manufacturer')
# ...
- city = models.ForeignKey("City")
- class City(models.Model):
+ class Manufacturer(models.Model):
# ...
-The name of a ``ForeignKey`` (``city`` in the example above) generally should
-be the name of the model, in singular form. Behind the scenes, Django appends
-"_id" to the field name to create its database column name. However, your code
+Note, however, that support for strings around model names in ``ForeignKey`` is
+quite new, and it can be buggy in some cases.
+
+Behind the scenes, Django appends ``"_id"`` to the field name to create its
+database column name. In the above example, the database table for the ``Car``
+model will have a ``manufacturer_id`` column. (You can change this explicitly
+by specifying ``db_column``; see ``db_column`` below.) However, your code
should never have to deal with the database column name, unless you write
-custom SQL.
+custom SQL. You'll always deal with the field names of your model object.
+
+It's suggested, but not required, that the name of a ``ForeignKey`` field
+(``manufacturer`` in the example above) be the name of the model, lowercase.
+You can, of course, call the field whatever you want. For example::
+
+ class Car(models.Model):
+ company_that_makes_it = models.ForeignKey(Manufacturer)
+ # ...
See the `Many-to-one relationship model example`_ for a full example.
@@ -684,7 +696,7 @@ relationship should work. All are optional:
with ``models.LazyDate`` to limit choices of objects
by date. For example::
- limit_choices_to = {'pub_date__lte' : models.LazyDate()}
+ limit_choices_to = {'pub_date__lte': models.LazyDate()}
only allows the choice of related objects with a
``pub_date`` before the current date/time to be
@@ -699,8 +711,9 @@ relationship should work. All are optional:
that a user never enters more than 10 toppings.
Note that this doesn't ensure more than 10 related
- toppings ever get created. It just controls the
- interface.
+ toppings ever get created. It simply controls the
+ admin interface; it doesn't enforce things at the
+ Python API level or database level.
``min_num_in_admin`` The minimum number of related objects displayed in
the admin. Normally, at the creation stage,
@@ -725,35 +738,9 @@ relationship should work. All are optional:
Not used with ``edit_inline``.
``related_name`` The name to use for the relation from the related
- object back to this one. For example, when if
- ``Topping`` has this field::
-
- models.ForeignKey(Pizza)
-
- the ``related_name`` will be "topping_set" (taken from
- the class name), which will in turn give ``Pizza``
- a ``topping_set`` Object Set Descriptor.
-
- If you instead were to use::
-
- models.ForeignKey(Pizza, related_name="munchies")
-
- then the Object Set Descriptor on ``Topping`` would
- be called ``munchies``.
-
- This is only really useful when you have a single
- object that relates to the same object more than
- once. For example, if a ``Story`` object has both
- ``primary_category`` and ``secondary_category``
- fields, to make sure that the ``Category`` objects
- have the correct methods, you'd use fields like::
-
- models.ForeignKey(Category, related_name="primary_stories")
- models.ForeignKey(Category, related_name="secondary_stories")
-
- ...which would give ``Category`` objects two Object Set
- descriptors - one called ``primary_stories`` and one
- called ``secondary_stories``.
+ object back to this one. See the
+ `related objects documentation`_ for a full
+ explanation and example.
``to_field`` The field on the related object that the relation
is to. By default, Django uses the primary key of
@@ -761,6 +748,7 @@ relationship should work. All are optional:
======================= ============================================================
.. _`Database API reference`: http://www.djangoproject.com/documentation/db_api/
+.. _related objects documentation: http://www.djangoproject.com/documentation/db_api/#related-objects
Many-to-many relationships
~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -784,11 +772,12 @@ here's how you'd represent that::
toppings = models.ManyToManyField(Topping)
As with ``ForeignKey``, a relationship to self can be defined by using the
-string ``"self"`` instead of the model name; references to as-yet undefined
-models can be made by using a string containing the model name.
+string ``'self'`` instead of the model name, and you can refer to as-yet
+undefined models by using a string containing the model name.
-The name of a ``ManyToManyField`` (``toppings`` in the example above) should
-generally be a plural describing the set of related model objects.
+It's suggested, but not required, that the name of a ``ManyToManyField``
+(``toppings`` in the example above) be a plural describing the set of related
+model objects.
Behind the scenes, Django creates an intermediary join table to represent the
many-to-many relationship.
@@ -797,11 +786,11 @@ It doesn't matter which model gets the ``ManyToManyField``, but you only need
it in one of the models -- not in both.
Generally, ``ManyToManyField`` instances should go in the object that's going
-to be edited in the admin. In the above example, ``toppings`` is in ``Pizza``
-(rather than ``Topping`` having a ``pizzas`` ``ManyToManyField`` ) because it's
-more natural to think about a ``Pizza`` having toppings than a topping being on
-multiple pizzas. The way it's set up above, the ``Pizza`` admin form would let
-users select the toppings.
+to be edited in the admin interface, if you're using Django's admin. In the
+above example, ``toppings`` is in ``Pizza`` (rather than ``Topping`` having a
+``pizzas`` ``ManyToManyField`` ) because it's more natural to think about a
+``Pizza`` having toppings than a topping being on multiple pizzas. The way it's
+set up above, the ``Pizza`` admin form would let users select the toppings.
See the `Many-to-many relationship model example`_ for a full example.
@@ -813,8 +802,7 @@ the relationship should work. All are optional:
======================= ============================================================
Argument Description
======================= ============================================================
- ``related_name`` See the description of ``related_name`` in
- ``ForeignKey`` above.
+ ``related_name`` See the description under ``ForeignKey`` above.
``filter_interface`` Use a nifty unobtrusive Javascript "filter" interface
instead of the usability-challenged ``<select multiple>``
@@ -825,14 +813,6 @@ the relationship should work. All are optional:
``limit_choices_to`` See the description under ``ForeignKey`` above.
- ``singular`` The singular name of the field. Use to name the ``get_*``
- methods: in the example above, Django gives the ``Pizza``
- objects a ``get_topping_list()`` method, where ``topping``
- is the default ``singular`` value derived from the lowercase
- version of the class being linked to. Use the singular
- parameter to change this, which is if you want one model to
- have multiple ``ManyToMany`` relationships to another model.
-
``symmetrical`` Only used in the definition of ManyToManyFields on self.
Consider the following model:
@@ -840,21 +820,26 @@ the relationship should work. All are optional:
friends = models.ManyToManyField("self")
When Django processes this model, it identifies that it has
- a ManyToManyField on itself, and as a result, it doesn't add
- a ``person_set`` attribute to the Person class. Instead, the
- ManyToManyField is assumed to be symmetrical - that is, if
- I am your friend, then you are my friend.
-
- If you do not want symmetry in ManyToMany relationships with
- self, set ``symmetrical`` to False. This will force Django to
- add the descriptor for the reverse relationship, allow
- ManyToMany relationships to be non-symmetrical.
+ a ``ManyToManyField`` on itself, and as a result, it
+ doesn't add a ``person_set`` attribute to the ``Person``
+ class. Instead, the ``ManyToManyField`` is assumed to be
+ symmetrical -- that is, if I am your friend, then you are
+ my friend.
+
+ If you do not want symmetry in ``ManyToMany`` relationships
+ with ``self``, set ``symmetrical`` to ``False``. This will
+ force Django to add the descriptor for the reverse
+ relationship, allowing ``ManyToMany`` relationships to be
+ non-symmetrical.
======================= ============================================================
One-to-one relationships
~~~~~~~~~~~~~~~~~~~~~~~~
+The semantics of one-to-one relationships will be changing soon, so we don't
+recommend you use them. If that doesn't scare you away, keep reading.
+
To define a one-to-one relationship, use ``OneToOneField``. You use it just
like any other ``Field`` type: by including it as a class attribute of your
model.
@@ -903,11 +888,12 @@ Here's a list of all possible ``Meta`` options. No options are required. Adding
``db_table``
------------
-The name of the database table to use for the module::
+The name of the database table to use for the model::
- db_table = "pizza_orders"
+ db_table = 'music_album'
If this isn't given, Django will use ``app_label + '_' + model_class_name``.
+See "Table names" below for more.
If your database table name is an SQL reserved word, or contains characters
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.
``get_latest_by``
-----------------
-The name of a ``DateField`` or ``DateTimeField``. If given, the module will
-have a ``get_latest()`` function that fetches the "latest" object according
-to that field::
+The name of a ``DateField`` or ``DateTimeField`` in the model. This specifies
+the default field to use in your model ``Manager``'s ``latest()`` method.
+
+Example::
get_latest_by = "order_date"
-See `Getting the "latest" object`_ for a full example.
+See the `docs for latest()`_ for more.
-.. _Getting the "latest" object: http://www.djangoproject.com/documentation/models/get_latest/
+.. _docs for latest(): http://www.djangoproject.com/documentation/db_api/#latest-field-name-none
``order_with_respect_to``
-------------------------
Marks this object as "orderable" with respect to the given field. This is
almost always used with related objects to allow them to be ordered with
-respect to a parent object. For example, if a ``PizzaToppping`` relates to
-a ``Pizza`` object, you might use::
+respect to a parent object. For example, if an ``Answer`` relates to a
+``Question`` object, and a question has more than one answer, and the order
+of answers matters, you'd do this::
- order_with_respect_to = 'pizza'
+ class Answer(models.Model):
+ question = models.ForeignKey(Question)
+ # ...
-...to allow the toppings to be ordered with respect to the associated pizza.
+ class Meta:
+ order_with_respect_to = 'question'
``ordering``
------------
@@ -1012,177 +1003,297 @@ The plural name for the object::
If this isn't given, Django will use ``verbose_name + "s"``.
+Table names
+===========
+To save you time, Django automatically derives the name of the database table
+from the name of your model class and the app that contains it. A model's
+database table name is constructed by joining the model's "app label" -- the
+name you used in ``manage.py startapp`` -- to the model's class name, with an
+underscore between them.
-========================================
-THE REST OF THIS HAS NOT YET BEEN EDITED
-========================================
-
-
+For example, if you have an app ``bookstore`` (as created by
+``manage.py startapp bookstore``), a model defined as ``class Book`` will have
+a database table named ``bookstore_book``.
-Table names
-===========
+To override the database table name, use the ``db_table`` parameter in
+``class Meta``.
Automatic primary key fields
============================
+By default, Django gives each model the following field::
+
+ id = models.AutoField(primary_key=True)
+
+This is an auto-incrementing primary key.
+
+If you'd like to specify a custom primary key, just specify ``primary_key=True``
+on one of your fields. If Django sees you've explicitly set ``primary_key``, it
+won't add the automatic ``id`` column.
+
+Each model requires exactly one field to have ``primary_key=True``.
Admin options
=============
-If you want your model to be visible to the automatic Administration
-system, your model must have an inner ``"class Admin"``, like so::
+If you want your model to be visible to Django's admin site, give your model an
+inner ``"class Admin"``, like so::
+
+ class Person(models.Model):
+ first_name = models.CharField(maxlength=30)
+ last_name = models.CharField(maxlength=30)
- class Foo(models.Model):
- bar = models.CharField(maxlength=30)
- # ...
class Admin:
- # ...
+ # Admin options go here
+ pass
-The Admin class gives instructions to Django on how to display the Model
-to the Administration system.
+The ``Admin`` class tells Django how to display the model in the admin site.
-Here's a list of all possible ``Admin`` options. No options are required. Adding
-``class Admin`` to a model is completely optional.
+Here's a list of all possible ``Admin`` options. None of these options are
+required. To use an admin interface without specifying any options, use
+``pass``, like so::
+
+ class Admin:
+ pass
+
+Adding ``class Admin`` to a model is completely optional.
``date_hierarchy``
- To allow filtering of objects in the admin by date, set ``date_hierarchy``
- to the name of the field to filter by::
+------------------
+
+Set ``date_hierarchy`` to the name of a ``DateField`` or ``DateTimeField`` in
+your model, and the change list page will include a date-based drilldown
+navigation by that field.
- date_hierarchy = 'order_date'
+Example::
+
+ date_hierarchy = 'pub_date'
``fields``
- A list of fieldsets to display on the admin page. Each fieldset is a 2-tuple:
- ``(name, field_options)``. The ``name`` is a string to name the field set,
- and ``field_options`` is a dictionary of information about the fields to be
- displayed in that fieldset. This dictionary has the following keys:
+----------
+
+Set ``fields`` to control the layout of admin "add" and "change" pages.
+
+``fields`` is a list of two-tuples, in which each two-tuple represents a
+``<fieldset>`` on the admin form page. (A ``<fieldset>`` is a "section" of the
+form.)
+
+The two-tuples are in the format ``(name, field_options)``, where ``name`` is a
+string representing the title of the fieldset and ``field_options`` is a
+dictionary of information about the fieldset, including a list of fields to be
+displayed in it.
+
+A full example, taken from the ``django.contrib.flatpages.FlatPage`` model::
+
+ class Admin:
+ fields = (
+ (None, {
+ 'fields': ('url', 'title', 'content', 'sites')
+ }),
+ ('Advanced options', {
+ 'classes': 'collapse',
+ 'fields' : ('enable_comments', 'registration_required', 'template_name')
+ }),
+ )
- ``fields``
- A tuple of field names to display in this fieldset. To display
- multiple fields on the same line, wrap those fields in their
- own tuple.
+This results in an admin page that looks like:
- This key is required in the dictionary.
+ .. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
- ``classes``
- Extra CSS classes to apply to the fieldset. This is a simple
- string. You can apply multiple classes by separating them with
- spaces.
+If ``fields`` isn't given, Django will default to displaying each field that
+isn't an ``AutoField`` and has ``editable=True``, in a single fieldset, in
+the same order as the fields are defined in the model.
- Two useful classes defined by the default stylesheet are
- ``collapse`` and ``wide``. Fieldsets with the ``collapse`` style
- will be initially collapsed in the admin and replaced with a small
- "click to expand" link. Fieldsets with the ``wide`` style will be
- given extra horizontal space.
+The ``field_options`` dictionary can have the following keys::
- ``description``
- Optional extra text to be displayed at the top of each fieldset,
- underneath the heading of the fieldset. It is used verbatim,
- so you can use any HTML and you must escape any special HTML
- characters (such as ampersand) yourself.
+``fields``
+~~~~~~~~~~
- For example (taken from the ``django.contrib.flatpages`` model)::
+A tuple of field names to display in this fieldset. This key is required.
- class Admin:
- ...
- fields = (
- (None, {
- 'fields': ('url', 'title', 'content', 'sites')
- }),
- ('Advanced options', {
- 'classes': 'collapse',
- 'fields' : ('enable_comments', 'registration_required', 'template_name')
- }),
- )
+Example::
+
+ {
+ 'fields': ('first_name', 'last_name', 'address', 'city', 'state'),
+ }
+
+To display multiple fields on the same line, wrap those fields in their own
+tuple. In this example, the ``first_name`` and ``last_name`` fields will
+display on the same line::
+
+ {
+ 'fields': (('first_name', 'last_name'), 'address', 'city', 'state'),
+ }
+
+``classes``
+~~~~~~~~~~~
+
+A string containing extra CSS classes to apply to the fieldset.
+
+Example::
+
+ {
+ 'classes': 'wide',
+ }
+
+Apply multiple classes by separating them with spaces. Example::
+
+ {
+ 'classes': 'wide extrapretty',
+ }
- results in an admin that looks like:
+Two useful classes defined by the default admin-site stylesheet are
+``collapse`` and ``wide``. Fieldsets with the ``collapse`` style will be
+initially collapsed in the admin and replaced with a small "click to expand"
+link. Fieldsets with the ``wide`` style will be given extra horizontal space.
- .. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
+``description``
+~~~~~~~~~~~~~~~
- If ``fields`` isn't given Django will default to displaying each field that
- isn't an ``AutoField`` and has ``editable=True``, in a single fieldset, in
- the same order as the fields are defined in the model.
+A string of optional extra text to be displayed at the top of each fieldset,
+under the heading of the fieldset. It's used verbatim, so you can use any HTML
+and you must escape any special HTML characters (such as ampersands) yourself.
``js``
- A list of strings representing URLs of JavaScript files to link into the
- admin screen. This can be used to tweak a given type of admin page in JS or
- to provide "quick links" to fill in default values for certain fields.
+------
+
+A list of strings representing URLs of JavaScript files to link into the admin
+screen via ``<script src="">`` tags. This can be used to tweak a given type of
+admin page in JavaScript or to provide "quick links" to fill in default values
+for certain fields.
``list_display``
- List of fields to display on the list page in the admin.
+----------------
+
+Set ``list_display`` to control which fields are displayed on the change list
+page of the admin.
+
+Example::
- There are a few special cases that do other things besides displaying the
- contents of the given fields:
+ list_display = ('first_name', 'last_name')
- * If the field given is a ``ForeignKey``, the ``repr()`` of the related
- object will be displayed.
+If you don't set ``list_display``, the admin site will display a single column
+that displays the ``__str__()`` representation of each object.
- * ``ManyToManyField`` fields aren't supported, because that would
- entail executing a separate SQL statement for each row in the table.
+A few special cases to note about ``list_display``:
- * If the field is a ``BooleanField``, a "on" or "off" icon will
- be displayed instead of ``True`` or ``False``.
+ * If the field is a ``ForeignKey``, Django will display the ``__str__()``
+ of the related object.
- * If the field name is a method of the model, it'll be called, and the
- output will be displayed. This method should have a
- ``short_description`` function attribute, for use as the header for
- the field.
+ * ``ManyToManyField`` fields aren't supported, because that would entail
+ executing a separate SQL statement for each row in the table.
- * Use the string ``"__str__"`` to output the representation of the
- object, according to your model's ``__str__()`` function. If you
- don't define ``list_display``, Django will use the ``__str__`` by
- default.
+ * If the field is a ``BooleanField``, Django will display a pretty "on" or
+ "off" icon instead of ``True`` or ``False``.
- See the example below.
+ * If the string given is a method of the model, Django will call it and
+ display the output. This method should have a ``short_description``
+ function attribute, for use as the header for the field.
+
+ Here's a full example model::
+
+ class Person(models.Model):
+ name = models.CharField(maxlength=50)
+ birthday = models.DateField()
+
+ class Admin:
+ list_display = ('name', 'decade_born_in')
+
+ def decade_born_in(self):
+ return self.birthday.strftime('%Y')[:3] + "0's"
+ decade_born_in.short_description = 'Birth decade'
``list_filter``
- List of fields to filter by. Each field should either be a ``BooleanField``
- or else a field with a ``ManyToOne`` relation.
+---------------
- Here's an example of how ``list_display`` and ``list_filter`` work (taken
- from the ``auth.user`` model)::
+Set ``list_filter`` to activate filters in the right sidebar of the change list
+page of the admin. This should be a list of field names, and each specified
+field should be either a ``BooleanField``, ``DateField``, ``DateTimeField``
+or ``ForeignKey``.
- class Admin:
- #...
- list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
- list_filter = ('is_staff', 'is_superuser')
+This example, taken from the ``django.contrib.auth.models.User`` model, shows
+how both ``list_display`` and ``list_filter`` work::
- The above code results in an admin that looks like this:
+ class Admin:
+ list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
+ list_filter = ('is_staff', 'is_superuser')
- .. image:: http://media.djangoproject.com/img/doc/users_changelist.png
+The above code results in an admin change list page that looks like this:
- (This example also has ``search_fields`` defined; see below).
+ .. image:: http://media.djangoproject.com/img/doc/users_changelist.png
+
+(This example also has ``search_fields`` defined. See below.)
``list_select_related``
- Either ``True`` or ``False``. Default is ``False``. If ``True``, the admin
- change list page will use the ``select_related`` database-API parameter in
- its query that retrieves the list of items.
+-----------------------
+
+Set ``list_select_related`` to tell Django to use ``select_related()`` in
+retrieving the list of objects on the admin change list page. This can save you
+a bunch of database queries.
+
+The value should be either ``True`` or ``False``. Default is ``False``.
+
+Note that Django will use ``select_related()``, regardless of this setting,
+if one of the ``list_display`` fields is a ``ForeignKey``.
+
+For more on ``select_related()``, see `the select_related() docs`_.
- Note that Django will use ``select_related``, regardless of this setting,
- if one of the ``list_display`` fields is a ``ForeignKey``.
+.. _the select_related() docs: http://www.djangoproject.com/documentation/db_api/#select-related
``ordering``
- A list or tuple (see the `Meta options`_, above) that gives a
- different ordering for the admin change list. If this isn't given, the
- model's default ordering will be used.
+------------
+
+Set ``ordering`` to specify how objects on the admin change list page should be
+ordered. This should be a list or tuple in the same format as a model's
+``ordering`` parameter.
+
+If this isn't provided, the Django admin will use the model's default ordering.
``save_as``
- Enables a "save as" feature on object pages. Normally, objects have three
- save options: "Save", "Save and continue editing" and "Save and add
- another". If ``save_as`` is ``True``, "Save and add another" will be
- replaced by a "Save as" button.
+-----------
+
+Set ``save_as`` to enable a "save as" feature on admin change forms.
+
+Normally, objects have three save options: "Save", "Save and continue editing"
+and "Save and add another". If ``save_as`` is ``True``, "Save and add another"
+will be replaced by a "Save as" button.
- "Save as" means the object will be saved as a new object (with a new ID),
- rather than the old object.
+"Save as" means the object will be saved as a new object (with a new ID),
+rather than the old object.
+
+By default, ``save_as`` is set to ``False``.
``save_on_top``
- If this option is ``True``, object pages will have the save buttons across
- the top as well as at the bottom of the page.
+---------------
+
+Set ``save_on_top`` to add save buttons across the top of your admin change
+forms.
+
+Normally, the save buttons appear only at the bottom of the forms. If you set
+``save_on_top``, the buttons will appear both on the top and the bottom.
+
+By default, ``save_on_top`` is set to ``False``.
``search_fields``
- A list of field names to provide a text search for. These fields should,
- obviously, be some kind of text field, such as ``CharField`` or
- ``TextField``.
+-----------------
+
+Set ``search_fields`` to enable a search box on the admin change list page.
+This should be set to a list of field names that will be searched whenever
+somebody submits a search query in that text box.
+
+These fields should be some kind of text field, such as ``CharField`` or
+``TextField``.
+
+When somebody does a search in the admin search box, Django splits the search
+query into words and returns all objects that contain each of the words, case
+insensitive, where each word must be in at least one of ``search_fields``. For
+example, if ``search_fields`` is set to ``['first_name', 'last_name']`` and a
+user searches for ``john lennon``, Django will do the equivalent of this SQL
+``WHERE`` clause::
+
+ WHERE (first_name ILIKE '%john%' OR last_name ILIKE '%john%')
+ AND (first_name ILIKE '%lennon%' OR last_name ILIKE '%lennon%')
Managers
========
@@ -1339,6 +1450,9 @@ method::
Manipulator methods
-------------------
+(The functionality in this section is going away soon. This documentation is
+provided only for legacy purposes at this point.)
+
Similarly, you can add methods to the object's manipulators by defining methods
that being with "_manipulator_". This is most useful for providing custom
validators for certain fields, because manipulators automatically call any

0 comments on commit 08fc167

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