Admin Site

One of Django's most powerful features is its automatic admin interface. It reads metadata from your models to provide a quick, model-centric interface where trusted users can manage content on your site.

Creating an Admin User

To access the admin site, you need an initial user with administrative privileges (a "superuser"). You can create one using the createsuperuser management command.

python manage.py createsuperuser

You will be prompted to enter a username, email address, and password. Once created, you can start the development server and navigate to /admin/ in your browser to log in.

Add Models to Admin Site

By default, the admin site is only accessible to users with the is_staff flag set to True. Superusers (is_superuser=True) automatically have all permissions, while staff users need specific permissions assigned to them via the admin interface to add, change, or delete models.

To make your models accessible in the admin interface, you must register them in your app's admin.py file.

from django.contrib import admin
from .models import Author

# Basic registration
admin.site.register(Author)

You can also use the @admin.register() decorator which is equivalent to admin.site.register(), but it allows you to easily customize how the model is displayed in the admin interface by subclassing ModelAdmin.

ModelAdmin Customization

The ModelAdmin class provides numerous options to customize how your models are displayed and edited. Here are some of the most common configuration attributes:

• list_display: A tuple or list of field names to display as columns on the model's change list page.
• list_filter: Fields to use to filter the change list by. It creates a sidebar filter on the right.
• search_fields: Enables a search box on the change list page. It should be a tuple of field names that will be searched (e.g., ("title", "author__name")).
• fieldsets: Controls the layout of the "add" and "change" pages. It allows you to group fields into sections with optional titles and classes.
• readonly_fields: Fields that cannot be edited but should still be displayed on the form.
• list_editable: A list of field names that can be edited directly on the change list page without opening the item.

from django.contrib import admin
from .models import Book

@admin.register(Book)
class BookAdmin(admin.ModelAdmin):
    list_display = ("title", "author", "price", "is_in_stock")
    list_filter = ("author", "is_in_stock")
    search_fields = ("title", "isbn")
    list_editable = ("price", "is_in_stock")
    readonly_fields = ("created_at",)
    
    fieldsets = [
        (None, {"fields": ["title", "author", "isbn"]}),
        ("Pricing & Inventory", {"fields": ["price", "is_in_stock"]}),
        ("Metadata", {"fields": ["created_at"], "classes": ["collapse"]}),
    ]

Admin Actions

Admin actions allow you to perform bulk operations on multiple objects at once from the change list page. Django provides a default "delete selected objects" action.

You can write custom actions to automate routine tasks.

from django.contrib import admin
from .models import Article

@admin.action(description="Mark selected articles as published")
def make_published(modeladmin, request, queryset):
    queryset.update(status="p")

@admin.register(Article)
class ArticleAdmin(admin.ModelAdmin):
    list_display = ("title", "status")
    actions = [make_published]

Actions receive three arguments: the current ModelAdmin, the HttpRequest, and a QuerySet containing the selected objects.

Django Admin Docs

The django.contrib.admindocs app pulls documentation from the docstrings of models, views, template tags, and template filters for any application in INSTALLED_APPS and makes it available directly from the admin interface.

To enable it:

1. Ensure django.contrib.admindocs is in your INSTALLED_APPS.
2. Add path('admin/doc/', include('django.contrib.admindocs.urls')) to your urls.py before the admin/ URL pattern.
3. Install the docutils Python package (pip install docutils).

The documentation will then be accessible via a link in the top right of the admin index page or directly at /admin/doc/.

NOTE

The admin docs generator expects docstrings to be formatted as reStructuredText (reST).

History (django_admin_log)

Django automatically tracks all additions, modifications, and deletions made through the admin interface. This is stored in the django_admin_log database table (represented by the LogEntry model in django.contrib.admin.models).

This provides an audit trail for the admin site, showing what action was performed, when it was performed, and which user performed it. You can view an object's history by clicking the "History" button on the top right of an object's change page.

UI Customization

While the default admin is highly functional, you often need to customize its appearance or structure.

Customizing Templates

You can override any admin template by creating a file with the same name in a directory that matches the admin's template structure (e.g., templates/admin/base_site.html):

{% extends "admin/base.html" %}

{% block title %}{{ title }} | My Custom Admin{% endblock %}

{% block branding %}
<h1 id="site-name"><a href="{% url 'admin:index' %}">My Awesome App Admin</a></h1>
{% endblock %}

Make sure your project's templates directory is configured in TEMPLATES in settings.py and that 'DIRS' includes your custom directory.

Customizing the AdminSite Class

For deeper customization (like changing the admin URL, index template, or context), you can subclass AdminSite and use it instead of the default admin.site.

from django.contrib.admin import AdminSite

class MyAdminSite(AdminSite):
    site_header = "My Custom Admin Header"
    site_title = "My Admin Portal"
    index_title = "Welcome to the portal"

admin_site = MyAdminSite(name="myadmin")