Customizing The Admin: Part 1
For many people, one of Django's best selling points is the Admin app. And as wonderful as it is, there often comes a point where you need/want more. With the changes that landed for Django 1.0 (newforms-admin), adding what you want to the admin area has become a very manageable task.
This post will be the first in a short series of posts on customizing the Admin to your liking. Over the next several days, I plan to cover:
- Customizing Admin Templates
- Adding Multiple Deletes
- Integrating Custom Javascript/CSS
- Altering Forms
- Adding Non-Model Related Functionality
Customizing Admin Templates
Since the admin is just a Django application, if you understand Django's templating, you already know virtually everything you need to know to customize the look and feel of your admin area.
The default templates are located in django.contrib.admin.templates.admin. These templates follow the "three-level" convention suggested in the Django documentation, which means that the base.html defines in very basic terms how the entire admin ("sitewide") looks and is laid out, the base_site.html defines how the specific admin site ("sectionwide") is setup and the individual templates control their specific chuck of output.
A common goal in customizing the look of the admin is to make it match (or at least use similar colors) as the site itself, as well as customizing text to be specific to that site. So that's what we'll do, converting the generic Django admin into something... toastier. Let's get started.
Setup
Within your templates directory (or one of your template directories), you'll want to create a new, top-level directory called admin. If you're OK with Django's default styling, this is the only thing you will have to do for the templates.
If you want even further control of the admin CSS/images/Javascript, you'll have to copy the contents of django.contrib.admin.media to a place where your customized media can be served. Depending on your setup, this may be a new directory in your existing media or setting up a whole virtual host specific to serving this media. In addition, you will have to set your ADMIN_MEDIA_PREFIX to point to this location (path in first case or full URL for the second).
Changing The Text
This is perhaps the easiest customization to make to the admin. To change the "Django administration" text, simply copy the django/contrib/admin/templates/admin/base_site.html template to your admin directory in your templates directory and start editing it. You'll find a {% trans %} tag (which allows this text to be localized) with the "Django administration" text in it.
Before:
{% extends "admin/base.html" %}
{% load i18n %}
{% block title %}{{ title }} | {% trans 'Django site admin' %}{% endblock %}
{% block branding %}
<h1 id="site-name">{% trans 'Django administration' %}</h1>
{% endblock %}
{% block nav-global %}{% endblock %}
Simply replace it with what you want and save. In my case, I've replaced the title text as well because I'm anal-retentive like that.
After:
{% extends "admin/base.html" %}
{% load i18n %}
{% block title %}{{ title }} | {% trans 'Toast Driven Admin' %}{% endblock %}
{% block branding %}
<h1 id="site-name">{% trans 'Toast Driven Admin' %}</h1>
{% endblock %}
{% block nav-global %}{% endblock %}
This new text will now appear in both the admin login screen as well as all the internal admin pages.
Changing The Styling
The Django admin usually follows generally regarded web design best practices, so most of the CSS is kept out of the templates themselves and in an included CSS file. To apply some colors that are more in line with the site (in this case Toast Driven), we'll start by copying over the admin media and editing layout.css to modify the header colors.
Before:
...
#header { background:#417690; color:#ffc; overflow:hidden; }
#header a:link, #header a:visited { color:white; }
#header a:hover { text-decoration:underline; }
#branding h1 { padding:0 10px; font-size:18px; margin:8px 0; font-weight:normal; color:#f4f379; }
#branding h2 { padding:0 10px; font-size:14px; margin:-8px 0 8px 0; font-weight:normal; color:#ffc; }
...
The lines we're concerned with are the #header and #branding h1 declarations. We'll change them like so:
After:
...
#header { background:#FAD9A4; color:#9A6002; overflow:hidden; }
#header a:link, #header a:visited { color:white; }
#header a:hover { text-decoration:underline; }
#branding h1 { padding:0 10px; font-size:18px; margin:8px 0; font-weight:bold; color:#9A6002; }
#branding h2 { padding:0 10px; font-size:14px; margin:-8px 0 8px 0; font-weight:normal; color:#9A6002; }
...
To get the tops of apps on the dashboard, you'll need to edit global.css like so:
Before:
...
.module h2, .module caption, .inline-group h2 { margin:0; padding:2px 5px 3px 5px; font-size:11px; text-align:left; font-weight:bold; background:#7CA0C7 url(../img/admin/default-bg.gif) top left repeat-x; color:white; }
...
After:
...
.module h2, .module caption, .inline-group h2 { margin:0; padding:2px 5px 3px 5px; font-size:11px; text-align:left; font-weight:bold; background-color:#9A6002; color:#9A6002; }
...
We have to remove the background image (as it is a gradient with the blue) in order to affect the color choice.
Altering The Dashboard View
Finally, you can reorganize the main page you're presented with when you login ("Home"). Simply copy the index.html template over to your admin template folder and override it to show apps in the order you want, leave apps out or change it in even more grandiose ways.
Note - Django (before 1.0) used to have a command called adminindex that would generate a snippet corresponding to your current admin. This appears to no longer be present in Django 1.0, so you'll likely have to fall back on making changes to the existing template.
Conclusion
This is a bit outside my standard fare, so what I've presented here is simply what has worked for me in the past. I'd be open to hear different/better ways to handle admin look/feel customizations.