The Django Admin Site

For most modern web sites, an admin interface is an essential part of the infrastructure. This is a web-based interface, limited to trusted site administrators, that enables the adding, editing and deletion of site content. Some common examples include the interface you use to post to your blog, the backend site managers use to moderate user-generated comments and the tool your clients use to update the press releases on the web site you built for them.

There’s a problem with admin interfaces, though – it’s boring to build them. Web development is fun when you’re developing public-facing functionality, but building admin interfaces is always the same. You have to authenticate users, display and handle forms, validate input, and so on. It’s boring, and it’s repetitive.

So what’s Django’s approach to these boring, repetitive tasks?

It does it all for you.

With Django, building an admin interface is a solved problem. In this chapter we will be exploring Django’s automatic admin interface – checking out how it provides a convenient interface to our models, and some of the other useful things we can do with it.

Using the Django Admin Site

When you ran django-admin startproject mysite in Chapter 1, Django created and configured the default admin site for you. All that you need to do is create an admin user (superuser) and then you can log into the admin site.

To create an admin user, run the following command from within your project virtual environment:

(env_mysite) C:\...\mysite_project\mysite> python manage.py createsuperuser 

Enter your desired username and press enter.

Username: admin 

You will then be prompted for your desired email address:

Email address: admin@example.com 

The final step is to enter your password. You will be asked to enter your password twice, the second time as a confirmation of the first. Note that you will have to come up with a reasonable secure password, even for testing.

Django automatically checks the strength of your password and won’t let you use a simple or common password. This can be a little annoying when you’re testing, but at least you can be confident that Django won’t let you break it’s carefully crafted security with a dumb password.

Password: **********
Password (again): *********
Superuser created successfully.

Start the Development Server

In Django 1.11, the django admin site is activated by default. Let’s start the development server and explore it. Recall from previous chapters that you start the development server like so:

(env_mysite) C:\...\mysite_project\mysite> python manage.py runserver 

Now, open a web browser and go to /admin/ on your local domain – e.g., http://127.0.0.1:8000/admin/. You should see the admin’s login screen (Figure 5-1).

Django Admin Site - Django admin login screen
Figure 5-1: Django admin login screen

Since translation is turned on by default, the login screen may be displayed in your own language, depending on your browser’s settings and on whether Django has a translation for this language.

Enter the Admin Site

Now, try logging in with the superuser account you created in the previous step. You should see the Django admin index page (Figure 5-2). You should see two types of editable content: Groups and Users. They are provided by django.contrib.auth, the authentication framework shipped by Django. The admin site is designed to be used by nontechnical users, and as such it should be pretty self-explanatory. Nevertheless, I’ll give you a quick walk-through of the basic features.

Django Admin Site - Django admin home page
Figure 5-2: Django admin home page

Each type of data in the Django admin site has a change list and an edit form. Change lists show you all the available objects in the database, and edit forms let you add, change or delete particular records in your database. Click the "Change" link in the "Users" row to load the change list page for users (Figure 5-3).

Django Admin Site - The user change list page
Figure 5-3: The user change list page

This page displays all users in the database; you can think of it as a prettied-up web version of a SELECT * FROM auth_user; SQL query. If you’re following along with our ongoing example, you’ll only see one user here, but once you have more users, you’ll probably find the filtering, sorting and searching options useful.

Filtering options are at right, sorting is available by clicking a column header, and the search box at the top lets you search by username. Click the username of the user you created, and you’ll see the edit form for that user (Figure 5-4). This page lets you change the attributes of the user, like the first/last names and various permissions.

Note that the user’s password in not shown. As a security measure, Django doesn’t store raw passwords, so there is no way to retrieve a password, you have to change it.

Another thing to note here is that fields of different types get different widgets – for example, date/time fields have calendar controls, Boolean fields have checkboxes, character fields have simple text input fields.

Django Admin Site - The user edit form
Figure 5-4: The user edit form

You can delete a record by clicking the delete button at the bottom left of its edit form. That’ll take you to a confirmation page, which, in some cases, will display any dependent objects that will be deleted, too. (For example, if you delete a publisher, any book with that publisher will be deleted, too!)

You can add a record by clicking "Add" in the appropriate column of the admin home page. This will give you an empty version of the edit page, ready for you to fill out. You’ll also notice that the admin interface handles input validation for you. Try leaving a required field blank or putting an invalid date into a date field, and you’ll see those errors when you try to save, as shown in Figure 5-5.

Django Admin Site - An edit form displaying errors
Figure 5-5: An edit form displaying errors

When you edit an existing object, you’ll notice a History link in the upper-right corner of the window. Every change made through the admin interface is logged, and you can examine this log by clicking the History link (see Figure 5-6).

Django Admin Site - An object history page
Figure 5-6: An object history page

How the Admin Site Works

Behind the scenes, how does the admin site work?

It’s pretty straightforward. When Django loads at server startup, it runs the admin.autodiscover() function. In earlier versions of Django, you used to call this function from urls.py, but now Django runs it automatically. This function iterates over your INSTALLED_APPS setting and looks for a file called admin.py in each installed app. If an admin.py exists in a given app, it executes the code in that file.

The admin site will only display an edit/change interface for models that have been explicitly registered with admin.site.register() entered into the app’s admin.py file. This is why your books model is not displaying yet – we have not registered the model with the admin. We will get to that next.

The app django.contrib.auth includes its own admin.py, which is why Users and Groups showed up automatically in the admin. Other django.contrib apps, such as django.contrib.redirects, also add themselves to the admin, as do many third-party Django applications you might download from the web.

Beyond that, the Django admin site is just a Django application, with its own models, templates, views and URLpatterns. You add it to your application by hooking it into your URLconf, just as you hook in your own views. You can inspect its templates, views and URLpatterns by poking around in django/contrib/admin in your copy of the Django codebase – but don’t be tempted to change anything directly in there, as there are plenty of hooks for you to customize the way the admin site works.

<<< Django Models: Basic Data Access | Table of Contents | Adding Models to Django Admin >>>