ModelAdmin.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__()
(__unicode__()
on Python 2) representation of each object.
You have four possible values that can be used in list_display
:
-
A field of the model. For example:
class PersonAdmin(admin.ModelAdmin): list_display = ('first_name', 'last_name')
-
A callable that accepts one parameter for the model instance. For example:
def upper_case_name(obj): return ("%s %s" % (obj.first_name, obj.last_name)).upper() upper_case_name.short_description = 'Name' class PersonAdmin(admin.ModelAdmin): list_display = (upper_case_name,)
-
A string representing an attribute on the
ModelAdmin
. This behaves same as the callable. For example:class PersonAdmin(admin.ModelAdmin): list_display = ('upper_case_name',) def upper_case_name(self, obj): return ("%s %s" % (obj.first_name, obj.last_name)).upper() upper_case_name.short_description = 'Name'
-
A string representing an attribute on the model. This behaves almost the same as the callable, but
self
in this context is the model instance. Here’s a full model example:from django.db import models from django.contrib import admin 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')
A few special cases to note about list_display
:
- If the field is a
ForeignKey
, Django will display the__str__()
(__unicode__()
on Python 2) 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 tolist_display
. (See below for more on custom methods inlist_display
.) - If the field is a
BooleanField
orNullBooleanField
, Django will display a pretty “on” or “off” icon instead ofTrue
orFalse
. -
If the string given is a method of the model,
ModelAdmin
or a callable, Django will HTML-escape the output by default. To escape user input and allow your own unescaped tags, useformat_html()
.Here’s a full example model:
from django.db import models from django.contrib import admin from django.utils.html import format_html 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 format_html( '<span style="color: #{};">{} {}</span>', self.color_code, self.first_name, self.last_name, ) class PersonAdmin(admin.ModelAdmin): list_display = ('first_name', 'last_name', 'colored_name')
Deprecated since version 1.9: In older versions, you could add an
allow_tags
attribute to the method to prevent auto-escaping. This attribute is deprecated as it’s safer to useformat_html()
,format_html_join()
, ormark_safe()
instead. -
If the value of a field is
None
, an empty string, or an iterable without elements, Django will display-
(a dash). You can override this withAdminSite.empty_value_display
:from django.contrib import admin admin.site.empty_value_display = '(None)'
You can also use
ModelAdmin.empty_value_display
:class PersonAdmin(admin.ModelAdmin): empty_value_display = 'unknown'
Or on a field level:
class PersonAdmin(admin.ModelAdmin): list_display = ('name', 'birth_date_view') def birth_date_view(self, obj): return obj.birth_date birth_date_view.empty_value_display = 'unknown'
New in Django 1.9:The ability to customize
empty_value_display
was added. -
If the string given is a method of the model,
ModelAdmin
or a callable that returns True or False Django will display a pretty “on” or “off” icon if you give the method aboolean
attribute whose value isTrue
.Here’s a full example model:
from django.db import models from django.contrib import admin 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] == '195' born_in_fifties.boolean = True class PersonAdmin(admin.ModelAdmin): list_display = ('name', 'born_in_fifties')
-
The
__str__()
(__unicode__()
on Python 2) method is just as valid inlist_display
as any other model method, so it’s perfectly OK to do this:list_display = ('__str__', '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 theadmin_order_field
attribute of the item.For example:
from django.db import models from django.contrib import admin from django.utils.html import format_html class Person(models.Model): first_name = models.CharField(max_length=50) color_code = models.CharField(max_length=6) def colored_first_name(self): return format_html( '<span style="color: #{};">{}</span>', self.color_code, self.first_name, ) 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 bycolored_first_name
in the admin.To indicate descending order with
admin_order_field
you can use a hyphen prefix on the field name. Using the above example, this would look like:colored_first_name.admin_order_field = '-first_name'
admin_order_field
supports query lookups to sort by values on related models. This example includes an “author first name” column in the list display and allows sorting it by first name:class Blog(models.Model): title = models.CharField(max_length=255) author = models.ForeignKey(Person, on_delete=models.CASCADE) class BlogAdmin(admin.ModelAdmin): list_display = ('title', 'author', 'author_first_name') def author_first_name(self, obj): return obj.author.first_name author_first_name.admin_order_field = 'author__first_name'
-
Elements of
list_display
can also be properties. Please note however, that due to the way properties work in Python, settingshort_description
on a property is only possible when using theproperty()
function and not with the@property
decorator.For example:
class Person(models.Model): first_name = models.CharField(max_length=50) last_name = models.CharField(max_length=50) def my_property(self): return self.first_name + ' ' + self.last_name my_property.short_description = "Full name of the person" full_name = property(my_property) class PersonAdmin(admin.ModelAdmin): list_display = ('full_name',)
- The field names in
list_display
will also appear as CSS classes in the HTML output, in the form ofcolumn-<field_name>
on each<th>
element. This can be used to set column widths in a CSS file for example. -
Django will try to interpret every element of
list_display
in this order:- A field of the model.
- A callable.
- A string representing a
ModelAdmin
attribute. - A string representing a model attribute.
For example if you have
first_name
as a model field and as aModelAdmin
attribute, the model field will be used.
Please login to continue.