, Johann Schmitz

This article is part of the Customizing the Django admin application series:

  1. Django Admin customizing
  2. Django Admin customizing - part 2
  3. Django Admin customizing - part 3

One of the things i totally love on Django is it wonderful Admin application. It provides a good starting point for a backend to your application and can easily customized to improve the overall administrative workflow.

For this series i will use a simple model: A list of countries. If taken the data from geonames.org, licensed under Creative Commons Attribution 3.0 License.

The database model is pretty straight forward:

class Country(models.Model):
    iso_code = models.CharField(max_length=2, unique=True)
    iso3_code = models.CharField(max_length=3, unique=True)
    iso_numeric_code = models.PositiveSmallIntegerField(unique=True)
    name = models.CharField(max_length=200)
    capital = models.CharField(max_length=200, null=True, blank=True)
    area = models.PositiveIntegerField(help_text='in sq km', null=True, blank=True)
    population = models.BigIntegerField()
    continent = models.CharField(max_length=5)
    tld = models.CharField(max_length=10)
    currency = models.CharField(max_length=5)
    currency_name = models.CharField(max_length=100)

    def __unicode__(self):
        return self.name

    class Meta:
        ordering = ('name', )

Once we have imported the data and wired everything up, the Django admin application gives us a nice, sorted list of countries:

Django admin application

In most cases, this list is enough. However, sometimes it's good to have a more detailed user interface. Django's admin application uses (optional) Model admin objects to customize the rendering and actions in the admin interface.

Model Admin object can be registered in many different ways - i will show you the most simple. Start by adding a class to your project which inherits from django.contrib.admin.ModelAdmin and register it with your model in admin.py:

from django.contrib import admin

class CountryModelAdmin(admin.ModelAdmin):
    pass

admin.site.register(Country, CountryModelAdmin)

Using list_display

We can define several fields on the CountryModelAdmin class to change the behaviour of the admin application. By default, the django admin application renders only __str__ (Python 3) / __unicode__ (Python 2) in the list view. Let's say we want to show some more columns in our list. We can define the list_display field to do so:

class CountryModelAdmin(admin.ModelAdmin):
    list_display = ('name', 'capital', 'population', 'area', )

The list_display field takes a name of fields of the model class and automatically renders the values in the list view:

ModelAdmin with custom list_display

The list_display field isn't limited to model fields - we can use anything accessible to django like properties or instance methods, too.

Quick filter via list_filter

Another handy feature is the list_filter field of the ModelAdmin class:

class CountryModelAdmin(admin.ModelAdmin):
    list_display = ('name', 'capital', 'population', 'area', )
    list_filter = ('currency_name', )

When defined, django builds a quick filter on the right side of our list with the unique values of the specified field(s):

ModelAdmin with custom list_filter

As you can see, django gives us a great administration tool which can be customized with almost no code. Next time, we'll dive into building custom filters and customizing the create/update view.