The Django admin is a user friendly application to administer the contents of a relational database linked to a Django project. Although the Django admin is almost effortless in terms of setting it up -- as described in chapter 1 -- there are multiple configuration options you'll learn in this chapter to create more powerful Django admin displays and functionalities.
In this chapter you'll first learn how to register Django models in the Django admin. Next, you'll learn how to display records in the Django admin and use techniques like ordering, in-line editing, pagination, search and actions buttons, among other things. In addition, you'll learn how how to customize Django admin forms and relationships to easily create, update and delete model records with the Django admin.
Next, you'll learn how to customize Django admin pages through configuration fields and custom templates, as well as how to add custom data and override Django admin class methods and fields to create the most flexible Django admin pages possible. Finally, you'll learn how configure and enforce Django admin permissions, as well as how to create multiple Django admin site instances.
Set up Django models in the Django admin
Although the Django admin provides an excellent management tool for a Django project's database, simply creating and installing Django models isn't enough to access their data in the Django admin.
In order to access Django model
records in the Django admin you must register and configure Django
admin.py files. An
file is automatically placed inside a Django app -- alongside the
views.py files -- when you
create an app.
Although you can technically use
admin.py to register and configure all Django
models -- just like you can have a single
define all Django models -- it's a recommended practice that each
Django app use its own
admin.py file to manage its
corresponding model defined in
There are three ways to register a Django model for the Django admin in admin.py files, all of which are illustrated in listing 11-1.
Listing 11-1 Register Django models in admin.py file
from django.contrib import admin from coffeehouse.stores.models import Store # Option 1 - Basic admin.site.register(Store) # Option 2 - Allows customizing Django admin behavior class StoreAdmin(admin.ModelAdmin): pass admin.site.register(Store, StoreAdmin) # Option 3 -- Decorator @admin.register(Store) class StoreAdmin(admin.ModelAdmin): pass
The first option in listing 11-1
provides basic Django model registration and consists of declaring
a Django model class as the input of the
admin.site.register method. If you don't require
customizing the default Django admin behavior for a model, this
option is sufficient.
The second option in listing 11-1
makes use of a Django admin class which inherits its behavior from
admin.ModelAdmin class. In this case, you can see
the class is empty, but it's possible to customize the Django admin
behavior, as I'll describe throughout this chapter. Once the Django
admin class is declared, it must be registered and associated with
a Django model using the same
method in option one, where the first argument is the Django model
and the second argument is the Django admin class.
The third option in listing 11-1
makes use of a Django admin
The syntax difference between option three and option two is the
registration and association takes place decorating the Django
admin class with
@admin.register where the decorator
takes the Django model as its argument.
It's worth mentioning that
although option two and three are functionally equal, using the
@admin.register decorator -- option three -- has the
limitation that you can't reference the Django admin class in its
__init__() method (e.g.
self).__init__(*args, **kwargs)) which is an issue in Python
2 and for certain designs, if you're in this situation then you
must use option two to register a model with the
Now that you know how to register Django models in the Django admin, I'll describe the various options available to customize the Django admin behavior through a Django admin class. To make it easier to look for custom options, I'll classify the options into two main sections: 'Read record options' and 'Create,update,delete record options' to cover the entire scope of CRUD operation options available in the Django admin, in addition to including sub-sections to group functionality under each main section.