admin.ModelAdmin.list_display

ModelAdmin.list_display

Set list_display to control which fields are displayed on the change list page of the admin.

Example:

1	`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:

1
2
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 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, ModelAdmin or a callable, Django will HTML-escape the output by default. To escape user input and allow your own unescaped tags, use format_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 use format_html(), format_html_join(), or mark_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 with AdminSite.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 a boolean attribute whose value is True.

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 in list_display as any other model method, so it’s perfectly OK to do this:

1
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 the admin_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 by colored_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:

1	`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, setting short_description on a property is only possible when using the property() 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 of column-<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 a ModelAdmin attribute, the model field will be used.

Links:

https://docs.djangoproject.com/en/1.10/ref/contrib/admin/index/#django.contrib.admin.ModelAdmin.list_display

doc_Django

2025-01-10 15:47:30

Comments