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.
You will then be prompted for your desired email address:
Email address: firstname.lastname@example.org
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).
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.
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).
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.
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.
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).
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.
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.