Skip to content


Subversion checkout URL

You can clone with
Download ZIP
Browse files

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

git-svn-id: bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
1 parent 5162e47 commit 081f2f8c8d0a8902f04dfcca3a83cd7eb7779bff @adrianholovaty adrianholovaty committed
Showing with 89 additions and 0 deletions.
  1. +89 −0 docs/tutorial02.txt
89 docs/tutorial02.txt
@@ -345,6 +345,95 @@ in a more compact, table-based format:
.. image::
: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::
+ :alt: Polls change list page
+ :target:
+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::
+ :alt: Polls change list page, updated
+ :target:
+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 ==
+ 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::
+ :alt: Polls change list page, updated
+ :target:
+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
+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.

0 comments on commit 081f2f8

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