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 models in admin.py files. An admin.py file is automatically placed inside a Django app -- alongside the models.py and views.py files -- when you create an app.

Although you can technically use a single admin.py to register and configure all Django models -- just like you can have a single models.py to 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 models.py.

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 the 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 admin.site.register 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 @admin.register decorator. 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. super(StoreAdmin, 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 admin.site.register method.

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.