mirror of
https://github.com/django/django.git
synced 2025-07-04 01:39:20 +00:00
newforms-admin: Moved the inner Admin docs over to the admin docs and updated to work with ModelAdmin.
git-svn-id: http://code.djangoproject.com/svn/django/branches/newforms-admin@7616 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Brian Rosner
parent
530670e27f
commit
c55c758531
387
docs/admin.txt
387
docs/admin.txt
@ -35,6 +35,393 @@ There are four steps in activating the Django admin site:
|
||||
``ModelAdmin`` objects
|
||||
======================
|
||||
|
||||
The ``ModelAdmin`` class is the representation of a model in the admin
|
||||
interface. These are stored in a file named ``admin.py`` in your application.
|
||||
Let's take a look at a very simple example the ``ModelAdmin``::
|
||||
|
||||
from django.contrib import admin
|
||||
from myproject.myapp.models import Author
|
||||
|
||||
class AuthorAdmin(admin.ModelAdmin):
|
||||
pass
|
||||
admin.site.register(Author, AuthorAdmin)
|
||||
|
||||
The ``ModelAdmin`` is very flexible. It has several options for dealing with
|
||||
customizing the interface. All options are defined on the ``ModelAdmin``
|
||||
subclass::
|
||||
|
||||
class AuthorAdmin(admin.ModelAdmin):
|
||||
date_hierarchy = 'pub_date'
|
||||
|
||||
``date_hierarchy``
|
||||
------------------
|
||||
|
||||
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.
|
||||
|
||||
Example::
|
||||
|
||||
date_hierarchy = 'pub_date'
|
||||
|
||||
``fieldsets``
|
||||
-------------
|
||||
|
||||
Set ``fieldsets`` to control the layout of admin "add" and "change" pages.
|
||||
|
||||
``fieldsets`` 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 FlatPageAdmin(admin.ModelAdmin):
|
||||
fieldsets = (
|
||||
(None, {
|
||||
'fields': ('url', 'title', 'content', 'sites')
|
||||
}),
|
||||
('Advanced options', {
|
||||
'classes': ('collapse',),
|
||||
'fields': ('enable_comments', 'registration_required', 'template_name')
|
||||
}),
|
||||
)
|
||||
|
||||
This results in an admin page that looks like:
|
||||
|
||||
.. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
|
||||
|
||||
If ``fieldsets`` 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.
|
||||
|
||||
The ``field_options`` dictionary can have the following keys:
|
||||
|
||||
``fields``
|
||||
~~~~~~~~~~
|
||||
|
||||
A tuple of field names to display in this fieldset. This key is required.
|
||||
|
||||
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',
|
||||
}
|
||||
|
||||
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.
|
||||
|
||||
``description``
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
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.
|
||||
|
||||
``list_display``
|
||||
----------------
|
||||
|
||||
Set ``list_display`` to control which fields are displayed on the change list
|
||||
page of the admin.
|
||||
|
||||
Example::
|
||||
|
||||
list_display = ('first_name', 'last_name')
|
||||
|
||||
If you don't set ``list_display``, the admin site will display a single column
|
||||
that displays the ``__unicode__()`` representation of each object.
|
||||
|
||||
A few special cases to note about ``list_display``:
|
||||
|
||||
* If the field is a ``ForeignKey``, Django will display the
|
||||
``__unicode__()`` of the related object.
|
||||
|
||||
* ``ManyToManyField`` fields aren't supported, because that would entail
|
||||
executing a separate SQL statement for each row in the table. If you
|
||||
want to do this nonetheless, give your model a custom method, and add
|
||||
that method's name to ``list_display``. (See below for more on custom
|
||||
methods in ``list_display``.)
|
||||
|
||||
* If the field is a ``BooleanField`` or ``NullBooleanField``, Django will
|
||||
display a pretty "on" or "off" icon instead of ``True`` or ``False``.
|
||||
|
||||
* 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(max_length=50)
|
||||
birthday = models.DateField()
|
||||
|
||||
def decade_born_in(self):
|
||||
return self.birthday.strftime('%Y')[:3] + "0's"
|
||||
decade_born_in.short_description = 'Birth decade'
|
||||
|
||||
class PersonAdmin(admin.ModelAdmin):
|
||||
list_display = ('name', 'decade_born_in')
|
||||
|
||||
* If the string given is a method of the model, Django will HTML-escape the
|
||||
output by default. If you'd rather not escape the output of the method,
|
||||
give the method an ``allow_tags`` attribute whose value is ``True``.
|
||||
|
||||
Here's a full example model::
|
||||
|
||||
class Person(models.Model):
|
||||
first_name = models.CharField(max_length=50)
|
||||
last_name = models.CharField(max_length=50)
|
||||
color_code = models.CharField(max_length=6)
|
||||
|
||||
def colored_name(self):
|
||||
return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)
|
||||
colored_name.allow_tags = True
|
||||
|
||||
class PersonAdmin(admin.ModelAdmin):
|
||||
list_display = ('first_name', 'last_name', 'colored_name')
|
||||
|
||||
* If the string given is a method of the model that returns True or False
|
||||
Django will display a pretty "on" or "off" icon if you give the method a
|
||||
``boolean`` attribute whose value is ``True``.
|
||||
|
||||
Here's a full example model::
|
||||
|
||||
class Person(models.Model):
|
||||
first_name = models.CharField(max_length=50)
|
||||
birthday = models.DateField()
|
||||
|
||||
def born_in_fifties(self):
|
||||
return self.birthday.strftime('%Y')[:3] == 5
|
||||
born_in_fifties.boolean = True
|
||||
|
||||
class PersonAdmin(admin.ModelAdmin):
|
||||
list_display = ('name', 'born_in_fifties')
|
||||
|
||||
|
||||
* The ``__str__()`` and ``__unicode__()`` methods are just as valid in
|
||||
``list_display`` as any other model method, so it's perfectly OK to do
|
||||
this::
|
||||
|
||||
list_display = ('__unicode__', 'some_other_field')
|
||||
|
||||
* Usually, elements of ``list_display`` that aren't actual database fields
|
||||
can't be used in sorting (because Django does all the sorting at the
|
||||
database level).
|
||||
|
||||
However, if an element of ``list_display`` represents a certain database
|
||||
field, you can indicate this fact by setting the ``admin_order_field``
|
||||
attribute of the item.
|
||||
|
||||
For example::
|
||||
|
||||
class Person(models.Model):
|
||||
first_name = models.CharField(max_length=50)
|
||||
color_code = models.CharField(max_length=6)
|
||||
|
||||
def colored_first_name(self):
|
||||
return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
|
||||
colored_first_name.allow_tags = True
|
||||
colored_first_name.admin_order_field = 'first_name'
|
||||
|
||||
class PersonAdmin(admin.ModelAdmin):
|
||||
list_display = ('first_name', 'colored_first_name')
|
||||
|
||||
The above will tell Django to order by the ``first_name`` field when
|
||||
trying to sort by ``colored_first_name`` in the admin.
|
||||
|
||||
``list_display_links``
|
||||
----------------------
|
||||
|
||||
Set ``list_display_links`` to control which fields in ``list_display`` should
|
||||
be linked to the "change" page for an object.
|
||||
|
||||
By default, the change list page will link the first column -- the first field
|
||||
specified in ``list_display`` -- to the change page for each item. But
|
||||
``list_display_links`` lets you change which columns are linked. Set
|
||||
``list_display_links`` to a list or tuple of field names (in the same format as
|
||||
``list_display``) to link.
|
||||
|
||||
``list_display_links`` can specify one or many field names. As long as the
|
||||
field names appear in ``list_display``, Django doesn't care how many (or how
|
||||
few) fields are linked. The only requirement is: If you want to use
|
||||
``list_display_links``, you must define ``list_display``.
|
||||
|
||||
In this example, the ``first_name`` and ``last_name`` fields will be linked on
|
||||
the change list page::
|
||||
|
||||
class PersonAdmin(admin.ModelAdmin):
|
||||
list_display = ('first_name', 'last_name', 'birthday')
|
||||
list_display_links = ('first_name', 'last_name')
|
||||
|
||||
Finally, note that in order to use ``list_display_links``, you must define
|
||||
``list_display``, too.
|
||||
|
||||
``list_filter``
|
||||
---------------
|
||||
|
||||
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``, ``CharField``, ``DateField``,
|
||||
``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
|
||||
|
||||
This example, taken from the ``django.contrib.auth.models.User`` model, shows
|
||||
how both ``list_display`` and ``list_filter`` work::
|
||||
|
||||
class UserAdmin(admin.ModelAdmin):
|
||||
list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
|
||||
list_filter = ('is_staff', 'is_superuser')
|
||||
|
||||
The above code results in an admin change list page that looks like this:
|
||||
|
||||
.. image:: http://media.djangoproject.com/img/doc/users_changelist.png
|
||||
|
||||
(This example also has ``search_fields`` defined. See below.)
|
||||
|
||||
``list_per_page``
|
||||
-----------------
|
||||
|
||||
Set ``list_per_page`` to control how many items appear on each paginated admin
|
||||
change list page. By default, this is set to ``100``.
|
||||
|
||||
``list_select_related``
|
||||
-----------------------
|
||||
|
||||
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`_.
|
||||
|
||||
.. _the select_related() docs: ../db-api/#select-related
|
||||
|
||||
``ordering``
|
||||
------------
|
||||
|
||||
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``
|
||||
-----------
|
||||
|
||||
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.
|
||||
|
||||
By default, ``save_as`` is set to ``False``.
|
||||
|
||||
``save_on_top``
|
||||
---------------
|
||||
|
||||
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``
|
||||
-----------------
|
||||
|
||||
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``. You can also perform a related lookup on a ``ForeignKey`` with
|
||||
the lookup API "follow" notation::
|
||||
|
||||
search_fields = ['foreign_key__related_fieldname']
|
||||
|
||||
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%')
|
||||
|
||||
For faster and/or more restrictive searches, prefix the field name
|
||||
with an operator:
|
||||
|
||||
``^``
|
||||
Matches the beginning of the field. 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%')
|
||||
|
||||
This query is more efficient than the normal ``'%john%'`` query, because
|
||||
the database only needs to check the beginning of a column's data, rather
|
||||
than seeking through the entire column's data. Plus, if the column has an
|
||||
index on it, some databases may be able to use the index for this query,
|
||||
even though it's a ``LIKE`` query.
|
||||
|
||||
``=``
|
||||
Matches exactly, case-insensitive. 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')
|
||||
|
||||
Note that the query input is split by spaces, so, following this example,
|
||||
it's currently not possible to search for all records in which
|
||||
``first_name`` is exactly ``'john winston'`` (containing a space).
|
||||
|
||||
``@``
|
||||
Performs a full-text match. This is like the default search method but uses
|
||||
an index. Currently this is only available for MySQL.
|
||||
|
||||
``AdminSite`` objects
|
||||
=====================
|
||||
|
||||
|
||||
@ -12,8 +12,6 @@ The basics:
|
||||
* Each attribute of the model represents a database field.
|
||||
* Model metadata (non-field information) goes in an inner class named
|
||||
``Meta``.
|
||||
* Metadata used for Django's admin site goes into an inner class named
|
||||
``Admin``.
|
||||
* With all of this, Django gives you an automatically-generated
|
||||
database-access API, which is explained in the `Database API reference`_.
|
||||
|
||||
@ -822,14 +820,6 @@ relationship should work. All are optional:
|
||||
======================= ============================================================
|
||||
Argument Description
|
||||
======================= ============================================================
|
||||
``edit_inline`` If not ``False``, this related object is edited
|
||||
"inline" on the related object's page. This means
|
||||
that the object will not have its own admin
|
||||
interface. Use either ``models.TABULAR`` or ``models.STACKED``,
|
||||
which, respectively, designate whether the inline-editable
|
||||
objects are displayed as a table or as a "stack" of
|
||||
fieldsets.
|
||||
|
||||
``limit_choices_to`` A dictionary of lookup arguments and values (see
|
||||
the `Database API reference`_) that limit the
|
||||
available admin choices for this object. Use this
|
||||
@ -848,39 +838,6 @@ relationship should work. All are optional:
|
||||
|
||||
Not compatible with ``edit_inline``.
|
||||
|
||||
``max_num_in_admin`` For inline-edited objects, this is the maximum
|
||||
number of related objects to display in the admin.
|
||||
Thus, if a pizza could only have up to 10
|
||||
toppings, ``max_num_in_admin=10`` would ensure
|
||||
that a user never enters more than 10 toppings.
|
||||
|
||||
Note that this doesn't ensure more than 10 related
|
||||
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,
|
||||
``num_in_admin`` inline objects are shown, and at
|
||||
the edit stage ``num_extra_on_change`` blank
|
||||
objects are shown in addition to all pre-existing
|
||||
related objects. However, no fewer than
|
||||
``min_num_in_admin`` related objects will ever be
|
||||
displayed.
|
||||
|
||||
``num_extra_on_change`` The number of extra blank related-object fields to
|
||||
show at the change stage.
|
||||
|
||||
``num_in_admin`` The default number of inline objects to display
|
||||
on the object page at the add stage.
|
||||
|
||||
``raw_id_admin`` Only display a field for the integer to be entered
|
||||
instead of a drop-down menu. This is useful when
|
||||
related to an object type that will have too many
|
||||
rows to make a select box practical.
|
||||
|
||||
Not used with ``edit_inline``.
|
||||
|
||||
``related_name`` The name to use for the relation from the related
|
||||
object back to this one. See the
|
||||
`related objects documentation`_ for a full
|
||||
@ -957,13 +914,6 @@ the relationship should work. All are optional:
|
||||
======================= ============================================================
|
||||
``related_name`` See the description under ``ForeignKey`` above.
|
||||
|
||||
``filter_interface`` Use a nifty unobtrusive Javascript "filter" interface
|
||||
instead of the usability-challenged ``<select multiple>``
|
||||
in the admin form for this object. The value should be
|
||||
``models.HORIZONTAL`` or ``models.VERTICAL`` (i.e.
|
||||
should the interface be stacked horizontally or
|
||||
vertically).
|
||||
|
||||
``limit_choices_to`` See the description under ``ForeignKey`` above.
|
||||
|
||||
``symmetrical`` Only used in the definition of ManyToManyFields on self.
|
||||
@ -1255,412 +1205,6 @@ attribute is the primary key field for the model. You can read and set this
|
||||
value, just as you would for any other attribute, and it will update the
|
||||
correct field in the model.
|
||||
|
||||
Admin options
|
||||
=============
|
||||
|
||||
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(max_length=30)
|
||||
last_name = models.CharField(max_length=30)
|
||||
|
||||
class Admin:
|
||||
# Admin options go here
|
||||
pass
|
||||
|
||||
The ``Admin`` class tells Django how to display the model in the admin site.
|
||||
|
||||
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``
|
||||
------------------
|
||||
|
||||
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.
|
||||
|
||||
Example::
|
||||
|
||||
date_hierarchy = 'pub_date'
|
||||
|
||||
``fields``
|
||||
----------
|
||||
|
||||
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')
|
||||
}),
|
||||
)
|
||||
|
||||
This results in an admin page that looks like:
|
||||
|
||||
.. image:: http://media.djangoproject.com/img/doc/flatfiles_admin.png
|
||||
|
||||
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.
|
||||
|
||||
The ``field_options`` dictionary can have the following keys:
|
||||
|
||||
``fields``
|
||||
~~~~~~~~~~
|
||||
|
||||
A tuple of field names to display in this fieldset. This key is required.
|
||||
|
||||
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',
|
||||
}
|
||||
|
||||
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.
|
||||
|
||||
``description``
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
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 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.
|
||||
|
||||
If you use relative URLs -- URLs that don't start with ``http://`` or ``/`` --
|
||||
then the admin site will automatically prefix these links with
|
||||
``settings.ADMIN_MEDIA_PREFIX``.
|
||||
|
||||
``list_display``
|
||||
----------------
|
||||
|
||||
Set ``list_display`` to control which fields are displayed on the change list
|
||||
page of the admin.
|
||||
|
||||
Example::
|
||||
|
||||
list_display = ('first_name', 'last_name')
|
||||
|
||||
If you don't set ``list_display``, the admin site will display a single column
|
||||
that displays the ``__str__()`` representation of each object.
|
||||
|
||||
A few special cases to note about ``list_display``:
|
||||
|
||||
* If the field is a ``ForeignKey``, Django will display the
|
||||
``__unicode__()`` of the related object.
|
||||
|
||||
* ``ManyToManyField`` fields aren't supported, because that would entail
|
||||
executing a separate SQL statement for each row in the table. If you
|
||||
want to do this nonetheless, give your model a custom method, and add
|
||||
that method's name to ``list_display``. (See below for more on custom
|
||||
methods in ``list_display``.)
|
||||
|
||||
* If the field is a ``BooleanField`` or ``NullBooleanField``, Django will
|
||||
display a pretty "on" or "off" icon instead of ``True`` or ``False``.
|
||||
|
||||
* 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(max_length=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'
|
||||
|
||||
* If the string given is a method of the model, Django will HTML-escape the
|
||||
output by default. If you'd rather not escape the output of the method,
|
||||
give the method an ``allow_tags`` attribute whose value is ``True``.
|
||||
|
||||
Here's a full example model::
|
||||
|
||||
class Person(models.Model):
|
||||
first_name = models.CharField(max_length=50)
|
||||
last_name = models.CharField(max_length=50)
|
||||
color_code = models.CharField(max_length=6)
|
||||
|
||||
class Admin:
|
||||
list_display = ('first_name', 'last_name', 'colored_name')
|
||||
|
||||
def colored_name(self):
|
||||
return '<span style="color: #%s;">%s %s</span>' % (self.color_code, self.first_name, self.last_name)
|
||||
colored_name.allow_tags = True
|
||||
|
||||
* If the string given is a method of the model that returns True or False
|
||||
Django will display a pretty "on" or "off" icon if you give the method a
|
||||
``boolean`` attribute whose value is ``True``.
|
||||
|
||||
Here's a full example model::
|
||||
|
||||
class Person(models.Model):
|
||||
first_name = models.CharField(max_length=50)
|
||||
birthday = models.DateField()
|
||||
|
||||
class Admin:
|
||||
list_display = ('name', 'born_in_fifties')
|
||||
|
||||
def born_in_fifties(self):
|
||||
return self.birthday.strftime('%Y')[:3] == 5
|
||||
born_in_fifties.boolean = True
|
||||
|
||||
|
||||
* The ``__str__()`` and ``__unicode__()`` methods are just as valid in
|
||||
``list_display`` as any other model method, so it's perfectly OK to do
|
||||
this::
|
||||
|
||||
list_display = ('__unicode__', 'some_other_field')
|
||||
|
||||
* Usually, elements of ``list_display`` that aren't actual database fields
|
||||
can't be used in sorting (because Django does all the sorting at the
|
||||
database level).
|
||||
|
||||
However, if an element of ``list_display`` represents a certain database
|
||||
field, you can indicate this fact by setting the ``admin_order_field``
|
||||
attribute of the item.
|
||||
|
||||
For example::
|
||||
|
||||
class Person(models.Model):
|
||||
first_name = models.CharField(max_length=50)
|
||||
color_code = models.CharField(max_length=6)
|
||||
|
||||
class Admin:
|
||||
list_display = ('first_name', 'colored_first_name')
|
||||
|
||||
def colored_first_name(self):
|
||||
return '<span style="color: #%s;">%s</span>' % (self.color_code, self.first_name)
|
||||
colored_first_name.allow_tags = True
|
||||
colored_first_name.admin_order_field = 'first_name'
|
||||
|
||||
The above will tell Django to order by the ``first_name`` field when
|
||||
trying to sort by ``colored_first_name`` in the admin.
|
||||
|
||||
``list_display_links``
|
||||
----------------------
|
||||
|
||||
Set ``list_display_links`` to control which fields in ``list_display`` should
|
||||
be linked to the "change" page for an object.
|
||||
|
||||
By default, the change list page will link the first column -- the first field
|
||||
specified in ``list_display`` -- to the change page for each item. But
|
||||
``list_display_links`` lets you change which columns are linked. Set
|
||||
``list_display_links`` to a list or tuple of field names (in the same format as
|
||||
``list_display``) to link.
|
||||
|
||||
``list_display_links`` can specify one or many field names. As long as the
|
||||
field names appear in ``list_display``, Django doesn't care how many (or how
|
||||
few) fields are linked. The only requirement is: If you want to use
|
||||
``list_display_links``, you must define ``list_display``.
|
||||
|
||||
In this example, the ``first_name`` and ``last_name`` fields will be linked on
|
||||
the change list page::
|
||||
|
||||
class Admin:
|
||||
list_display = ('first_name', 'last_name', 'birthday')
|
||||
list_display_links = ('first_name', 'last_name')
|
||||
|
||||
Finally, note that in order to use ``list_display_links``, you must define
|
||||
``list_display``, too.
|
||||
|
||||
``list_filter``
|
||||
---------------
|
||||
|
||||
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``, ``CharField``, ``DateField``,
|
||||
``DateTimeField``, ``IntegerField`` or ``ForeignKey``.
|
||||
|
||||
This example, taken from the ``django.contrib.auth.models.User`` model, shows
|
||||
how both ``list_display`` and ``list_filter`` work::
|
||||
|
||||
class Admin:
|
||||
list_display = ('username', 'email', 'first_name', 'last_name', 'is_staff')
|
||||
list_filter = ('is_staff', 'is_superuser')
|
||||
|
||||
The above code results in an admin change list page that looks like this:
|
||||
|
||||
.. image:: http://media.djangoproject.com/img/doc/users_changelist.png
|
||||
|
||||
(This example also has ``search_fields`` defined. See below.)
|
||||
|
||||
``list_per_page``
|
||||
-----------------
|
||||
|
||||
Set ``list_per_page`` to control how many items appear on each paginated admin
|
||||
change list page. By default, this is set to ``100``.
|
||||
|
||||
``list_select_related``
|
||||
-----------------------
|
||||
|
||||
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`_.
|
||||
|
||||
.. _the select_related() docs: ../db-api/#select-related
|
||||
|
||||
``ordering``
|
||||
------------
|
||||
|
||||
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``
|
||||
-----------
|
||||
|
||||
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.
|
||||
|
||||
By default, ``save_as`` is set to ``False``.
|
||||
|
||||
``save_on_top``
|
||||
---------------
|
||||
|
||||
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``
|
||||
-----------------
|
||||
|
||||
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``. You can also perform a related lookup on a ``ForeignKey`` with
|
||||
the lookup API "follow" notation::
|
||||
|
||||
search_fields = ['foreign_key__related_fieldname']
|
||||
|
||||
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%')
|
||||
|
||||
For faster and/or more restrictive searches, prefix the field name
|
||||
with an operator:
|
||||
|
||||
``^``
|
||||
Matches the beginning of the field. 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%')
|
||||
|
||||
This query is more efficient than the normal ``'%john%'`` query, because
|
||||
the database only needs to check the beginning of a column's data, rather
|
||||
than seeking through the entire column's data. Plus, if the column has an
|
||||
index on it, some databases may be able to use the index for this query,
|
||||
even though it's a ``LIKE`` query.
|
||||
|
||||
``=``
|
||||
Matches exactly, case-insensitive. 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')
|
||||
|
||||
Note that the query input is split by spaces, so, following this example,
|
||||
it's currently not possible to search for all records in which
|
||||
``first_name`` is exactly ``'john winston'`` (containing a space).
|
||||
|
||||
``@``
|
||||
Performs a full-text match. This is like the default search method but uses
|
||||
an index. Currently this is only available for MySQL.
|
||||
|
||||
Managers
|
||||
========
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user