How to override and extend basic Django admin templates?

Question

How do I override an admin template (e.g. admin/index.html) while at the same time extending it (see https://docs.djangoproject.com/en/dev/ref/contrib/admin/#overriding-vs-r

Answer 1

I couldn't find a single answer or a section in the official Django docs that had all the information I needed to override/extend the default admin templates, so I'm writing this answer as a complete guide, hoping that it would be helpful for others in the future.

Assuming the standard Django project structure:

mysite-container/         # project container directory
    manage.py
    mysite/               # project package
        __init__.py
        admin.py
        apps.py
        settings.py
        urls.py
        wsgi.py
    app1/
    app2/
    ...
    static/
    templates/

Here's what you need to do:

1. In mysite/admin.py, create a sub-class of AdminSite:

   from django.contrib.admin import AdminSite
   
   
   class CustomAdminSite(AdminSite):
       # set values for `site_header`, `site_title`, `index_title` etc.
       site_header = 'Custom Admin Site'
       ...
   
       # extend / override admin views, such as `index()`
       def index(self, request, extra_context=None):
           extra_context = extra_context or {}
   
           # do whatever you want to do and save the values in `extra_context`
           extra_context['world'] = 'Earth'
   
           return super(CustomAdminSite, self).index(request, extra_context)
   
   
   custom_admin_site = CustomAdminSite()
   

   Make sure to import custom_admin_site in the admin.py of your apps and register your models on it to display them on your customized admin site (if you want to).

2. In mysite/apps.py, create a sub-class of AdminConfig and set default_site to admin.CustomAdminSite from the previous step:

   from django.contrib.admin.apps import AdminConfig
   
   
   class CustomAdminConfig(AdminConfig):
       default_site = 'admin.CustomAdminSite'
   

3. In mysite/settings.py, replace django.admin.site in INSTALLED_APPS with apps.CustomAdminConfig (your custom admin app config from the previous step).

4. In mysite/urls.py, replace admin.site.urls from the admin URL to custom_admin_site.urls

   from .admin import custom_admin_site
   
   
   urlpatterns = [
       ...
       path('admin/', custom_admin_site.urls),
       # for Django 1.x versions: url(r'^admin/', include(custom_admin_site.urls)),
       ...
   ]
   

5. Create the template you want to modify in your templates directory, maintaining the default Django admin templates directory structure as specified in the docs. For example, if you were modifying admin/index.html, create the file templates/admin/index.html.

   All of the existing templates can be modified this way, and their names and structures can be found in Django's source code.

6. Now you can either override the template by writing it from scratch or extend it and then override/extend specific blocks.

   For example, if you wanted to keep everything as-is but wanted to override the content block (which on the index page lists the apps and their models that you registered), add the following to templates/admin/index.html:

   {% extends 'admin/index.html' %}
   
   {% block content %}
     
   
       Hello, {{ world }}!
     
   {% endblock %}
   

   To preserve the original contents of a block, add {{ block.super }} wherever you want the original contents to be displayed:

   {% extends 'admin/index.html' %}
   
   {% block content %}
     
   
       Hello, {{ world }}!
     
     {{ block.super }}
   {% endblock %}
   

   You can also add custom styles and scripts by modifying the extrastyle and extrahead blocks.