Set up the Django admin site
The Django admin site provides a web based interface to access the database connected to a Django project. Even for experienced technical administrators, doing database CRUD (Create-Read-Update-Delete) operations directly on a database can be difficult and time consuming, given the need to issue raw SQL commands and navigate database structures. For non-technical users, doing database CRUD operations directly on a database can be daunting, if not impossible. The Django admin site fixes this problem.
The Django admin site can expose all Django project related data structures linked to a database, so it's easy for experts and novices alike to perform database CRUD operations. As a Django project grows, the Django admin site can be a vital tool to administer the growing body of information in the database connected to a Django project.
The Django admin site is built as a Django app, this means the only thing you need to do to set up the Django admin site is configure and install the app as any other Django app. If you're unfamiliar with the term Django app, read the previous section 'Set up content: Understand urls, templates and apps'.
The Django admin site requires that you previously configure a database and also install the Django base tables. So if you still haven't done this, see the prior section 'Set up a database for a Django project'.
Configure and install the Django admin site app
By default, the Django admin is
enabled on all Django projects. If you open a Django project's
urls.py file, in the
you'll see the line
This last path definition tells Django to enable the
admin site app on the
/admin/ url directory (e.g.
Next, if you open the project's
settings.py file and go to the
INSTALLED_APPS variable. Near the top of this variable
you'll also see the line
indicates the Django admin site app is enabled.
Start the development web server
python manage.py runserver on Django's
BASE_DIR. Open a browser on the Django admin site
http://127.0.0.1:8000/admin/. You'll see a login screen
like the one in Figure 1-5.
Figure 1-5. Django admin site login
Next, let's create a Django
superuser or administrator to access the Django admin via the
interface in Figure 1-5. To create a Django superuser you can use
createsuperuser command from
manage.py as illustrated in listing 1-27.
Listing 1-27. Create Django superuser for admin interface
[user@coffeehouse ~]$ python manage.py createsuperuser Username (leave blank to use 'admin'): Email address: email@example.com Password: Password (again): The password is too similar to the email address. This password is too short. It must contain at least 8 characters. This password is too common. Bypass password validation and create user anyway? [y/N]: Password: Password (again): Superuser created successfully.
Caution If you receive the error
OperationalError - no such table: auth_user, this means the database for a Django project is still not setup properly. You'll need to run
python manage.py migratein a project's BASE_DIR so Django creates the necessary tables to keep track of users. See the previous section 'Set up a database for a Django project' for more details.
Tip By default, Django enforces user passwords comply with a minimum level of security. For example, in listing 1-27 you can see that after attempting to use the password coffee, Django rejects the assignment with a series of error messages and forces a new attempt. You can modify these password validation rules in the
AUTH_PASSWORD_VALIDATORSvariable in a project's
setttings.pyfile or as illustrated in listing 1-27 bypass this password validation.
This last process creates a
superuser whose information is stored in the database connected to
the Django project, specifically in the
table. Now you might be asking yourself, how do you update this
user's name, password or email ? While you could go straight to the
database table and perform updates, this is a tortuous route, a
better approach is to rely on the Django admin which gives you a
very friendly view into the database tables present in your Django
Next, introduce the superuser username and password you just created into the interface from figure 1-5. Once you provide the superuser username and password on the admin site, you'll access the home page for the admin site illustrated in figure 1-6.
Figure 1-6.- Django admin site home page
On the home page of the Django admin site illustrated in figure 1-6, click on the 'Users' link. You'll see a list of users with access to the Django project. At the moment, you'll only see the superuser you created in the past step. You can change this user's credentials (e.g. password, email, username) or add new users directly from this Django admin site screen.
This flexibility to modify or add records stored in a database that's tied to a Django project is what makes the Django admin site so powerful. For example, if you develop a coffeehouse project and add apps like stores, drinks or customers, Django admin authorized users can do CRUD operations on these objects (e.g. create stores, update drinks, delete customers). This is tremendously powerful from a content management point of view, particularly for non-technical users. And most importantly it requires little to no additional development work to enable the Django admin site on a project's apps.
The Django admin site tasks presented here are just the 'tip of the iceberg' in functionality, a future chapter covers the Django admin site functionality in greater detail.
Configure and install the Django admin site docs app
The Django admin site also has
its own documentation app. The Django admin site documentation app
not only provides information about the operation of the admin site
itself, but also includes other general documentation about Django
filters for Django templates. More importantly, the Django admin
site documentation app introspects the source code for all
installed project apps to present documentation on controller
methods and model objects (i.e. documentation embedded in the
source code of app
To install the Django admin site
documentation app you first need to install the docutils Python
package with the
pip package manager executing the following
python3 -m pip install docutils. Once you install the
docutils package, you can proceed to install the Django admin site
documentation app as any other Django app.
First you must add the url to access the Django
admin site documentation app. Open the project's
urls.py file and add the highlighted lines illustrated in listing 1-28:
Listing 1-28. Add Django admin docs to admin interface
from django.contrib import admin from django.urls import path, include from django.views.generic import TemplateView from coffeehouse.about import views as about_views urlpatterns = [ path('',TemplateView.as_view(template_name='homepage.html')), path('about/', about_views.contact), path('admin/doc/', include('django.contrib.admindocs.urls')), path('admin/', admin.site.urls), ]
The first line adds the
include method to the
import statement from the
django.urls package, which is necessary to load the built-in urls from the admin site documentation app.
Next, inside the
urlpatterns list is the
'admin/doc/' path which tells Django to enable the admin site
documentation app on the /admin/doc/ url (e.g.http://127.0.0.1:8000/admin/doc/).
admin/docpath must be declared before the
admin/path for things to work. The url definition order matters and is a topic that's discussed in the next chapter.
Next, open the project's
settings.py file and go to the
INSTALLED_APPS variable. Add the line
django.contrib.admindocs to the
INSTALLED_APPS list to enable the Django admin site documentation app.
With the development web server running. Open a browser on the address http://127.0.0.1:8000/admin/doc/ and you should see a page like the one in figure 1-7.
Figure 1-7.- Django admin site doc home page
If you logged off the Django admin site, you'll need to login again to access the documentation since it also requires user authentication. Once you login, you'll be able to see the documentation home page for the Django admin site -- illustrated in figure 1-7 -- as well as the documentation on a project's controller methods and model objects.
Caution If you receive the error
TemplateDoesNotExist at /admin/doc/or see the message
The admin documentation system requires Python’s docutils library.this means you missed a prerequisite outlined earlier. Either the
django.contrib.admindocspackage wasn't added to the
settings.pyor the docutils package wasn't installed with
python3 -m pip install docutils.