Customizing the Django Admin site

Django’s official doc here

Let’s start by saying that Django’s admin site is spectacular. It can literally save you months of work, but having said that, one thing that one needs to understand is that Django’s admin site is only ok as an internal tool. It is not, and never has been intended to be, an end user tool. Or in the words of Django’s doc:

The admin’s recommended use is limited to an organization’s internal management tool. It’s not intended for building your entire front end around.

The reason for that is that the admin site works by doing introspection on your Model classes so it will expose all your data and DB schema and while it provides ways to customize it at your heart’s content, if you need to customize it you will probably be better replacing it.

What I am going to explain next are ways to tailor it a little to make it more powerful but not with the intention of changing the way it works.

The AdminSite object

If you’ve been using the admin app you probably already created an admin.py file in your Django app and add it a bunch of calls like this one (if not you’ll need to check the admin tutorial):

# admin.py
from django.contrib import admin
admin.site.register(Book)
admin.site.register(Author)

The admin.py file is automatically looked for and imported by the Admin Django application when it launches so this is the place where you hook your models into the admin app.

Those admin.site.register() calls do exactly that.

But that admin.site object is the main object that represents your Admin and it provides customization options (documentation).

These are the ones that I always change:

admin.site.site_header, this is the “Django Administration” <h1> text that you find when you enter the site.

admin.site.site_title, same thing, but as <title>

admin.site.index_title, this is the heading that appears with a default text of “Site administration”(set it to blank if you don’t want to use it)

If you want to change that view you can set your own template modifying admin.site.index_template and admin.site.app_template.

If you want to just change the CSS what you can do is to specify here your own template and that template to extend the default one. Of course in your new template you would be adding your own CSS file.

(Same thing with the other template options)

Customizing the list views

The one thing that I care most to customize is the list view (or Change view rather how the documentation calls it). This is the view that it is used when you select a Model and you get a list with all that Model instances in your DB.

And to do that what you need to do next is to create a ModelAdmin instance. Like this:

# admin.py
from django.contrib import admin
import models
@admin.register(models.Author)
class AuthorAdmin(admin.ModelAdmin):
  date_hierarchy = 'created'
  search_fields = ['first_name', 'last_name', 'email']
  list_display = ('first_name','last_name','email')
  list_filter = ('status',)

Let’s dissect that example.

the @admin.register() decorator does the same thing as

admin.site.register(models.Author, AuthorAdmin)

It just shorter, what we are doing is registering the Author model in the admin app but also telling the app that it needs to use AuthorAdmin as ModelAdmin.

The ModelAdmin is how you customize its appearance.

The date_hierarchy (here) when set will make the app show a “timeline browser”. So you can use it to filter by date (ie, all model instances from July of 2015). The value need to be a Date or Datetime field from your model.

The search_fields (here), is a list of “QuerySet” fields, that can be used to filter search your result set. Here you can use as value any join expression, for instance “coauthor__name”

The list_display (here) is a tuple of field names. If set instead of being the view a single list, that list can be turned into a table! And in that case list_display the fields to be columns of such table.

Now. I said that it is a tuple of field names, but it can contain Model fields as well ModelAdmin fields. So you can extend what is shown here by adding a method in your ModelAdmin that returns complex query (this is useful because you can’t use QuerySet joins operations here, like “coauthor__first_name” kind of thing. Check the doc for more info)

The list_filter (here) is another tuple. If present then at the right of the table a filter box will be added with options to filter the given fields. This is particularly useful for Choice fields. (for free-text fields doesn’t make sense)

Rounding up. You can customize the Django admin and turn it into a very powerful DB console. It will still be something of an internal tool, but it will be a very powerful internal tool.

The options mentioned above are my favorite, are plenty more, and you can also customize the look and feel at your hearts content by replacing the defaults templates and by adding custom CSS (I don’t usually do it because it’s an internal tool after all)

You can find all that in the official doc. Here.

PS: this talk seems interesting: here