Django Admin Site Overview

The content management portion of a website requires administrators to view, add, modify, and delete data. Implementing these repetitive features can be tedious and uncreative. Django solves this problem by automatically generating admin modules based on defined model classes. The admin site is enabled by default in Django projects.

Before using the admin interface, create an administrator account:

python manage.py createsuperuser

Follow the prompts to set a username, email, and password.

To activate admin functionality for a specific model, register it in the app's admin.py file. For example, to register the Region model:

from django.contrib import admin
from .models import Region

admin.site.register(Region)

Access the admin interface at:

http://127.0.0.1:8000/admin/

After logging in with admin credentials, the registered models appear in the dashboard where you can perform CRUD operations.

Controlling Admin Display with ModelAdmin

The ModelAdmin class controls how models appear in the admin interface, including list page presentation and edit form layout.

Define a custom admin class before registration:

class RegionAdmin(admin.ModelAdmin):
    pass

Two methods exist for connecting a model to its admin class:

Method 1: Registration with Parameters

admin.site.register(Region, RegionAdmin)

Method 2: Decorator

@admin.register(Region)
class RegionAdmin(admin.ModelAdmin):
    pass

List Page Configuration

Pagination

Control records per page using the list_per_page attribute. Default is 100 records:

class RegionAdmin(admin.ModelAdmin):
    list_per_page = 25

Action Bar Position

Control action button placement with these boolean atttributes:

class RegionAdmin(admin.ModelAdmin):
    actions_on_top = True   # Show at top, default True
    actions_on_bottom = False  # Show at bottom, default False

Customizing Columns

Display specific fields as columns using list_display:

class RegionAdmin(admin.ModelAdmin):
    list_display = ['id', 'name', 'created_date']

Clicking column headers sorts results by that field.

Adding Method Columns

Columns can display method results, not just model fields. In you're model:

class Region(models.Model):
    name = models.CharField(max_length=100)
    parent = models.ForeignKey('self', null=True, blank=True)
    
    def display_name(self):
        return self.name

Then register in admin:

class RegionAdmin(admin.ModelAdmin):
    list_display = ['id', 'display_name']

Method columns are not sortable by default. To enable sorting, set the admin_order_field attribute:

def display_name(self):
    return self.name
display_name.admin_order_field = 'name'

To customize column headers, set short_description:

display_name.short_description = 'Region Name'

Accessing Related Objects

Display related object properties by creating wrapper methods:

class Region(models.Model):
    name = models.CharField(max_length=100)
    parent = models.ForeignKey('self', null=True, blank=True)
    
    def parent_name(self):
        return self.parent.name if self.parent else '-'
    parent_name.short_description = 'Parent Region'

Add to admin display:

class RegionAdmin(admin.ModelAdmin):
    list_display = ['id', 'name', 'parent_name']

Filter Sidebar

Add a filtering sidebar with list_filter for fields with repetitive values:

class RegionAdmin(admin.ModelAdmin):
    list_filter = ['name']

Search Functionality

Enable search on specific fields using search_fields (supports partial matching):

class RegionAdmin(admin.ModelAdmin):
    search_fields = ['name']

Field Ordering on Edit Page

Control field order in the edit form with fields:

class RegionAdmin(admin.ModelAdmin):
    fields = ['parent', 'name']

For related fields displaying as dropdowns, add a __str__ method to show meaningful labels:

class Region(models.Model):
    def __str__(self):
        return self.name

Grouped Field Layout

Use fieldsets for grouped field presentation:

class RegionAdmin(admin.ModelAdmin):
    fieldsets = (
        ('Basic Information', {'fields': ['name']}),
        ('Hierarchy', {'fields': ['parent']})
    )

Note: fields and fieldsets are mutually exclusive.

Inline Relatedd Objects

For one-to-many relationships, edit related objects directly within the parent's edit page using inline classes.

Stacked Inline Layout:

class RegionInline(admin.StackedInline):
    model = Region
    extra = 3  # Show 3 empty slots

class RegionAdmin(admin.ModelAdmin):
    inlines = [RegionInline]

Tabular Inline Layout:

class RegionInline(admin.TabularInline):
    model = Region
    extra = 2

class RegionAdmin(admin.ModelAdmin):
    inlines = [RegionInline]

Customizing Admin Templates

Override admin templates to customize the site's appearance.

1. Create this directory structure in your project:

templates/admin/

2. Locate Django's admin templates in your virtual environment:

<virtualenv>/lib/python3.x/site-packages/django/contrib/admin/templates/admin/

3. Copy desired template files (such as base_site.html) to your project's templates/admin/ directory.

4. Modify the copied template:

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

{% block title %}{{ title }} | {{ site_header|default:_('Site Admin') }}{% endblock %}

{% block branding %}
<h1 id="site-name">
    <a href="{% url 'admin:index' %}">{{ site_header|default:_('Django Admin') }}</a>
</h1>
<hr>
<h1>Custom Admin Header</h1>
<hr>
{% endblock %}

{% block nav-global %}{% endblock %}

Apply the same approach to other admin templates as needed.