Added 'Customize the admin change list' section to docs/tutorial02.txt

git-svn-id: http://code.djangoproject.com/svn/django/trunk@139 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Adrian Holovaty 2005-07-17 05:52:07 +00:00
parent 5162e4745f
commit 081f2f8c8d
1 changed files with 89 additions and 0 deletions

View File

@ -345,6 +345,95 @@ in a more compact, table-based format:
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin12.png
:alt: Add poll page now has more compact choices
Customize the admin change list
===============================
Now that the Poll admin page is looking good, let's make some tweaks to the
"change list" page -- the one that displays all the polls in the system.
Here's what it looks like at this point:
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin04t.png
:alt: Polls change list page
:target: http://media.djangoproject.com/img/doc/tutorial/admin04.png
By default, Django displays the ``repr()`` of each object. But it'd be more
helpful if we could display individual fields. To do that, use the
``list_display`` option, which is a tuple of field names to display, as columns,
on the change list page for the object::
class Poll(meta.Model):
# ...
admin = meta.Admin(
fields = (
(None, {'fields': ('question', 'pub_date')}),
),
list_display = ('question', 'pub_date'),
)
Just for good measure, let's also include the ``was_published_today`` custom
method from Tutorial 1::
list_display = ('question', 'pub_date', 'was_published_today'),
Now the poll change list page looks like this:
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin13t.png
:alt: Polls change list page, updated
:target: http://media.djangoproject.com/img/doc/tutorial/admin13.png
You can click on the column headers to sort by those values -- except in the
case of the ``was_published_today`` header, because sorting by the output of
an arbitrary method is not supported. Also note that the column header for
``was_published_today`` is, by default, the name of the method. But you can
change that by giving that method a ``short_description`` attribute::
def was_published_today(self):
return self.pub_date.date() == datetime.date.today()
was_published_today.short_description = 'Was published today'
Let's add another improvement to the Poll change list page: Filters. Add the
following line to ``Poll.admin``:
list_filter = ('pub_date', )
That adds a "Filter" sidebar that lets people filter the change list by the
``pub_date`` field:
.. image:: http://media.djangoproject.com/img/doc/tutorial/admin14t.png
:alt: Polls change list page, updated
:target: http://media.djangoproject.com/img/doc/tutorial/admin14.png
The type of filter displayed depends on the type of field you're filtering on.
Because ``pub_date`` is a DateTimeField, Django knows to give the default
filter options for DateTimeFields: "Any date," "Today," "Past 7 days,"
"This month," "This year." Explore using ``list_filter`` on other types of
fields.
This is shaping up well. Finally, let's add some search capability:
search_fields = ('question', )
That adds a search box at the top of the change list. When somebody enters
search terms, Django will search the ``question`` field. You can use as many
fields as you'd like -- although because it uses a LIKE query behind the
scenes, keep it reasonable to mind your database performance.
Finally, because Poll objects have dates, it'd be convenient to be able to
drill down by date. Add this line::
date_hierarchy = 'pub_date',
That adds hierarchical navigation, by date, to the top of the change list page.
At top level, it displays all available years. Then it drills down to months
and, ultimately, days.
Now's also a good time to note that change lists give you free pagination. The
default is to display 50 items per page. Change-list pagination, search boxes,
filters, date-hierarchies and column-header-ordering all work together like you
think they should.
More
====