Turn Django admin into full-fledged dashboard with Unfold

By default, Django admin contains just a basic page when the admin area is visited. The native page consists of the list of currently registered models in Django admin and the log history of actions occurring at the top of models.

As these data are valid and there is nothing wrong with them, they don't have an important value for the users with administration access. The list of all registered applications is already visible in the sidebar and the history is not something that tends to be checked on a regular basis.

Overriding the base template

An option how to improve the Django admin page is to override it from the custom application. The template name for changing the visual is admin/index.html which needs to be created inside the templates directory. This approach is pretty straightforward and well-known.

The problem starts when you try to push custom data into this template or customize the visual. When pushing custom data into the dashboard template, by default you need to extend the default AdminSite, and override index method and after that, you can operate with for example database rows. Adjusting the visual is even more complex because the new design adjustments and components have to match with the rest of the admin. The solution for both problems is to start with the django-unfold admin theme which simplifies the tasks described above.

Quick guide into django-unfold installation

Here is a quick tutorial on how to install and start using the Unfold admin theme. First of all, we start with the theme installation by running poetry add django-unfold. After the installation, just add unfold to the INSTALLED_APPS list and you are ready to start. In this post we are not going deeper into all Unfold settings, they can be found in the official documentation.

# settings.py

INSTALLED_APPS = [
    "unfold",  # Unfold has to be first
    # Rest of required packages
]

Passing data into dashboard template

Adding custom data into the dashboard template is a general operation that is used all the time when the dashboard is customized. For this purpose, Unfold already contains a callback that allows to sending of custom data into the template.

# settings.py
UNFOLD = {
    "DASHBOARD_CALLBACK": "app.utils.dashboard_callback",
}

After configuring Unfold settings like above, Unfold is going to look for a function to pass additional data into index.html template when it is rendered. Below you can see an example function, for customizing passed data. An interesting argument in this function is context which is a dict type and it contains all variables, even variables coming from Django admin.

from app.models import MyModel

# utils.py
def dashboard_callback(request, context):
    context.update({
        "variable": MyModel.objects.some_results()
    })

    return context

Using Unfold components for the dashboard design

Unfold theme contains a little template helpers called components. These components already have the visual predefined and properly styled to match the rest of the admin area. The main difference between {% component %} and {% include %} tags is that components allow nesting in one template so it is not required to create multiple files to create a complex structure. With components, you can create a nested structure in one template and it is even possible to nest multiple components.

Once the data are available in index.html template, we can process them into a nice visual. First of all, we will create a basic structure for our index.html template. Below you can find a snippet that adds everything that is required for the base template. It already extends from a proper layout, has the page title configured, and proper tags loaded.

{% extends 'unfold/layouts/base_simple.html' %}

{% load i18n unfold %}

{% block breadcrumbs %}{% endblock %}

{% block title %}
    {% trans 'Dashboard' %} | {{ site_title|default:_('Django site admin') }}
{% endblock %}

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

{% block content %}{% endblock %}

Structuring the components into layout

Imagine that the dashboard already contains three numerical values which we want to display in nice KPI widgets. With Unfold it is easy to compose a KPI widget by using multiple components. In this case, 4 different components will be used.

The widget itself is going to be wrapped by a card.html component containing text.html and title.html The text component displays regular text without any specific design attributes. The title component displays a large text which will be displayed with a larger font size, different color, and font weight, ideal for important KPI information. All three widgets need to be wrapped in flex.html components, structuring all components side-by-side.

{% block content %}
    {% component "unfold/components/flex.html" with class="gap-8" %}
        {% component "unfold/components/card.html" with class="lg:w-1/3" %}
            {% component "unfold/components/text.html" %}
                {% trans "Some KPI title"}
            {% endcomponent %}

            {% component "unfold/components/title.html" %}
                {{ variable1.metric }}
            {% endcomponent %}
        {% endcomponent %}

        <!-- Copy/paste card components for each value to display or use for loop -->
    {% endcomponent %}
{% endblock %}

The list of all available components in the Unfold theme is listed in the official documentation. The example dashboard with more complex components is in the Formula repository.