This page explains how to override Django admin and import a custom template to it. Along with the tutorial, we provide a working sample coded on top of Black Dashboard design (free version) designed by Creative-Tim.
Django provides default pages for login, registration, 404 and 500 pages (etc) the full list can be found in the site-packages/django folder:
1
.../site-packages/django/contrib/admin/templates/
2
│
3
├── admin/
4
│ │
5
│ ├── auth/
6
│ │ └── user/
7
│ │ ├── add_form.html
8
│ │ └── change_password.html
9
│ │
10
│ ├── 404.html
11
│ ├── 500.html
12
│ ├── actions.html
13
│ ├── app_index.html
14
│ ├── base.html
15
│ ├── base_site.html
16
│ ├── index.html
17
│ ├── invalid_setup.html
18
│ ├── login.html
19
│ ├── pagination.html
20
│ ├── popup_response.html
21
│ └── submit_line.html
22
│
23
└── registration/
24
├── logged_out.html
25
├── password_change_done.html
26
├── password_change_form.html
27
├── password_reset_complete.html
28
├── password_reset_confirm.html
29
├── password_reset_done.html
30
├── password_reset_email.html
31
└── password_reset_form.html
Copied!
To customize a template, we need to provide the page in a custom templates directory and inform Django to use it. When a template page is used, Django will try to resolve the file by scanning the templates provided by the user and after this step, it defaults to ones provided by the Django core.
Customize 404 page
The admin templates come in two directories:
admin is for the model object pages.
registration is for password changes and logging in and out.
To customize the 404 page, you need to override the right file. The relative path leading to the file has to be the same as the one being overridden. The file you’re interested in is 404.html.
Step #1 - Create template directory
1
# Django Root Project <-- you are here
2
mkdir -p templates/
Copied!
Step #2 - Update Django Settings
To use the new templates the project settings file should be updated as bellow to use it.
As mentioned before, Django will try to resolve a template file by scanning the directories defined by the user in the settings file. If nothing is found, the default version will be used from site-packages/django/contrib/admin/templates/ directory.
Step #3 - Customize 404 page
The custom version of our 404 page can be easily done by copying the default version from admin/templates/ directory and save it in the directory created in Step #2
1
# Django Root Project <-- you are here
2
vi templates/404.html
Copied!
1
<!-- templates/404.html -->
2
3
{% extends "admin/base_site.html" %}
4
{% load i18n %}
5
6
{% block title %}{% trans 'Page not found' %}{% endblock %}
7
8
{% block content %}
9
10
<h2>{% trans 'Page not found' %} - Custom File</h2>
11
12
<p>{% trans "We're sorry, but the requested page could not be found." %}</p>
13
14
{% endblock %}
Copied!
Once we save the file, Django will use it when a 404 error case occur when users interacts with our application.
A complete example
This section explains the process of integrating Black Dashboard design (free version) to style the default admin section for Django.
Download UI Kit & Assets
Download your favorite template which usually contains css, js, images and fonts files. The sample we are using here (Black Dashboard) can be downloaded from the product page.
Django Admin Black
Please note that you may have to change the template slightly to do this. Because the relevant template must be usable for Django Admin features.
Create Your Django Project
Create a Django project and a new application inside using a descriptive name admin_black, for instance.
1
$ python manage.py startapp admin_black
Copied!
Create new directories templates, static and templatetages inside. The application folders structure should look as below:
1
admin_black/
2
migrations/
3
__init__.py
4
static/
5
# we gonna add something here
6
templates/
7
# we gonna add something here
8
templatetags/
9
__init__.py
10
# we gonna add something here
11
__init__.py
12
admin.py
13
apps.py
14
models.py
15
tests.py
16
utils.py # To add public and commonly used functions.
17
views.py
Copied!
Add your application (admin_black) to the INSTALLED_APPS setting of your Django project settings.py file (note it should be before 'django.contrib.admin'):
1
INSTALLED_APPS =[
2
# ...
3
'admin_black.apps.AdminBlackConfig',
4
'django.contrib.admin',
5
]
Copied!
Now your application is ready to add a template. To do this, you need to add your template assets files like css, js, images and fonts in your application static folder.
The folders' structure of this section is completely arbitrary.
1
admin_black/
2
...
3
static/
4
admin/ # In this section you can override the admin assets file like css, js and etc.
5
css/
6
admin_black/ # This section is for your template assets. You can choose your own name.
7
assets/
8
css/
9
demo/
10
fonts/
11
img/
12
js/
13
scss/
14
LICENSE.md
15
libs/ # this section is for libs like jQuery, jQuery-confirm or etc
16
...
Copied!
This is my structure and you can make your own structure.
Define new Django templates
In the previous, we added all the required information to our project. Now we want to override the Django admin template and add our template. To do this, you need to know that all Django admin template files are located at:
1
.../site-packages/django/contrib/admin/templates
Copied!
In this section you will see two folders that include admin and registration. As it is clear from the name, the admin folder is related to the admin templates and the registration folder is related to registration, such as password_reset_form.html, logged_out.html and etc templates.
In Django admin, to override the templates, just create the same files with the same address in your application. For example, to change the base.html, just create such a file in your application:
1
admin_black/
2
...
3
templates/
4
admin/
5
base.html # change this
6
registration/
7
...
Copied!
Note that you must pay attention to the blocks.
base.html is a file that you can start with. All other files import this file to use assets. So, you can add your own template files in it.
Note that in sections head and footer I created a new block so that I can make changes to these sections on other pages.
You can also use templatetags to provide more customization like a custom sidebar and navigation. To do this create a new file inside the templatetags as below:
1
admin_black/
2
...
3
templatetags/
4
__init__.py
5
admin_black.py
6
...
Copied!
1
<!-- sidebar.html -->
2
3
{% load admin_black %}
4
5
<divclass="sidebar">
6
<divclass="sidebar-wrapper">
7
...
8
{% admin_black_get_menu as app_list %}
9
{% if app_list %}
10
...
11
{% endif %}
12
...
13
</div>
14
</div>
Copied!
This way you can override the Django admin template and import your own template.
Links & Resource
Page editor and Django Admin Black author - Iman Karimi