Getting Started with AdminSite

You will learn how to set up and customize the Django admin interface using the AdminSite class. By the end of this tutorial, you will be able to register models, customize the admin's appearance, and create multiple independent admin sites within a single project.

Prerequisites

Before starting, ensure you have a Django application with at least one model defined. For this tutorial, we will assume a model named MyModel exists in an app named myapp.

# myapp/models.py
from django.db import models

class MyModel(models.Model):
    name = models.CharField(max_length=100)
    created_at = models.DateTimeField(auto_now_add=True)

Step 1: Basic Model Registration

The quickest way to make a model editable in the admin is to register it with the default site instance provided by django.contrib.admin.

In your app's admin.py file, use the register() method:

# myapp/admin.py
from django.contrib import admin
from .models import MyModel

admin.site.register(MyModel)

The admin.site object is an instance of DefaultAdminSite, which acts as a lazy wrapper around the standard AdminSite. When you call register(MyModel), the AdminSite adds the model to its internal _registry and associates it with a default ModelAdmin instance.

Step 2: Customizing Registration with Options

You can customize how your model appears in the admin by passing a ModelAdmin subclass or by providing keyword arguments directly to register().

To quickly add search and list display options without creating a separate class:

# myapp/admin.py
from django.contrib import admin
from .models import MyModel

admin.site.register(
    MyModel, 
    list_display=['name', 'created_at'], 
    search_fields=['name']
)

When you provide keyword arguments like list_display to AdminSite.register(), the site dynamically constructs a subclass of ModelAdmin with those options applied. This is handled internally by the register method in django/contrib/admin/sites.py:

# Internal logic in AdminSite.register
if options:
    admin_class = type(
        "%sAdmin" % model.__name__, (admin_class,), options
    )
self._registry[model] = admin_class(model, self)

Step 3: Branding the Admin Interface

You can change the branding of the admin site by modifying attributes on the admin.site instance. This affects the text displayed in the browser title and the header of every admin page.

# myapp/admin.py
from django.contrib import admin

admin.site.site_header = "My Project Administration"
admin.site.site_title = "Project Admin Portal"
admin.site.index_title = "Welcome to the Management Area"

These attributes correspond to the following AdminSite properties:

• site_header: Text put in each page's <div id="site-name">.
• site_title: Text put at the end of each page's <title>.
• index_title: Text put at the top of the admin index page.

Step 4: Creating a Custom AdminSite

If you need multiple independent admin interfaces or want to encapsulate your customizations in a class, you can subclass AdminSite.

# myapp/admin.py
from django.contrib.admin import AdminSite
from .models import MyModel

class MyAdminSite(AdminSite):
    site_header = 'Custom Admin'
    site_title = 'Admin Portal'
    index_title = 'App Administration'

# Instantiate the custom site
my_admin_site = MyAdminSite(name='myadmin')

# Register models to this specific site
my_admin_site.register(MyModel)

To use this custom site, you must hook its urls into your project's urls.py:

# project/urls.py
from django.urls import path
from myapp.admin import my_admin_site

urlpatterns = [
    path('myadmin/', my_admin_site.urls),
]

The urls property on AdminSite returns a tuple containing the URL patterns generated by get_urls(), the app name ('admin'), and the instance name (e.g., 'myadmin').

Step 5: Configuring a Custom Default Site

If you want your custom AdminSite to be the default site used by the @admin.register decorator and the standard admin.site import, you can configure it in your AppConfig.

First, create a subclass of SimpleAdminConfig:

# myapp/apps.py
from django.contrib.admin.apps import SimpleAdminConfig

class MyCustomAdminConfig(SimpleAdminConfig):
    default_site = 'myapp.admin.MyAdminSite'

Then, replace 'django.contrib.admin' with 'myapp.apps.MyCustomAdminConfig' in your INSTALLED_APPS setting. The DefaultAdminSite class will then use your custom class when it initializes:

# django/contrib/admin/sites.py
class DefaultAdminSite(LazyObject):
    def _setup(self):
        # This looks up the 'default_site' string from your AppConfig
        AdminSiteClass = import_string(apps.get_app_config("admin").default_site)
        self._wrapped = AdminSiteClass()

Summary

You have now configured the Django admin by:

1. Registering models with admin.site.register().
2. Using dynamic options to customize the list view and search.
3. Overriding branding attributes like site_header.
4. Creating a standalone AdminSite instance for specialized routing.
5. Setting a project-wide default admin site via AppConfig.