Django AdminLTE2

Django AdminLTE2 provides extensible templates for making use of the general purpose AdminLTE2 theme.

Contents

Quickstart

Install the pip package:

pip install django-adminlte2

Add the apps to INSTALLED_APPS:

INSTALLED_APPS = [
    # Any apps which will override adminlte's templates (i.e. your apps)
    ...

    # The general purpose templates
    'django_adminlte',

    # Optional: Skin for the admin interface
    'django_adminlte_theme',

    # Any apps which need to have their templates overridden by adminlte
    'django.contrib.admin',
    ...
]

Important

Take note of the ordering of INSTALLED_APPS. If you find templates are not being found & used as expected it is probably due to a problem here.

Django looks for a template in the order in which apps are listed in INSTALLED_APPS, hence the ordering above.

If you only wish to skin the admin interface, you can stop here. Your admin interface should now be displaying with the AdminLTE theme.

You can also make use of the AdminLTE theme for your app. This may be particularly useful for internal (non-public) apps which need a quick and effective layout.

Using the templates in your app

The base AdminLTE template provides much of what you need, but you’ll need to customise it in some ways to meet your needs. In particular, no navigation is provided (we’ll cover this shortly).

To add & modify the functionality of the base template you should create your own base template. This template should extend adminlte/base.html. Several blocks are available for you to extend.

{% extends 'adminlte/base.html' %}

{% block title %}My App{% endblock %}
{% block content %}
    Just some example content
{% endblock %}

Take a look at the base template to see the available blocks.

Adding navigation

The base template includes a number of other templates in order to create the whole.

For example, the sidebar navigation resides in adminlte/lib/_main_sidebar.html. To customise this template you should create a template of the same path & name in your app’s templates folder.

Important

Your app(s) must be listed before django_adminlte2 in INSTALLED_APPS. Otherwise Django will find the default default provided by django-adminlte2 before your customised one.

In your own app create the template adminlte/lib/_main_sidebar.html:

{% extends 'adminlte/lib/_main_sidebar.html' %}

{% block nav_links %}
    <li>
        <a href="/some/url">
            <i class="fa fa-dashboard"></i> <span>Home</span>
        </a>
    </li>
    <li>
        <a href="/some/url">
            <i class="fa fa-user"></i> <span>Users</span>
        </a>
    </li>
{% endblock nav_links %}

You should now find the navigation has updated.

Templates & Blocks Reference

Below you will find reference for each available template, and the blocks that can be overridden.

Note than when overriding some blocks it may make sense to make use of {{ block.super }} (inheritance docs).

Base templates

adminlte/base.html

The primary base template which provides a sidebar, top navigation with user information, and footer.

Block reference
title_outer

Wrapper around the the outside of the <title> tag. Default:

{% block title_outer %}
    <title>{% block title %}{{ site.name }}{% endblock %}</title>
{% endblock %}
title

Contents of the pages <title> tag. Default:

<title>{% block title %}{{ site.name }}{% endblock %}</title>

This will set a sensible default if the site variable references the current site object (from Django’s sites framework)

meta

All <meta> tags which appear in the pages <head>. Default:

{% block meta %}
    <meta charset="utf-8">
    <meta http-equiv="X-UA-COMPATIBLE" content="IE=edge">
    <meta content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=no" name="viewport">
{% endblock %}

Consider making use of {{ block.super }} when overriding this block.

stylesheets

All <style> tags which appear in the pages <head>. By default this includes all content from adminlte/lib/_styles.html.

Consider making use of {{ block.super }} when overriding this block.

extra_head
Additional HTML to be placed before the </head> tag. Empty by default.
body_class
Additional CSS classes which can be placed into the <body> tag’s class attribute.
content_wrapper

Wrapper around all of the content area (including the content header, messages, and actual page content).

You probably want to override the ``content`` block instead.

content_header

The header that appears over the page content, but within the content area of the design.

Default:

{% block content_header %}
    <section class="content-header">
        <h1>
            {% block page_name %}{% endblock %}
            {% block no_description %}
            <small>{% block page_description %}{% endblock %}</small>
            {% endblock %}
        </h1>
        {% block breadcrumbs %}
            {# Breadcrumb implementation left to developers #}
        {% endblock %}
    </section>
{% endblock %}
page_name
The name of the page as will be displayed in the content header.
page_description
The description of the page tht will appear alongside the page name in the header.
no_description

If no description is to be displayed, you can implement this as an empty block to remove the wrapper HTML. For example:

{% block no_description %}{% endblock %}
page_actions

Generally used to display actions/buttons relevant to the current page. For example:

{% block page_actions %}
    <a href="{% url 'alerts:create' %}" class="btn btn-success btn-sm">Create new</a>
{% endblock %}
content_outer

Wraps the outside of the content area and any messages.

You probably want to override the ``content`` block instead.

messages

Wrapper around the entirety of the message area. Default:

{% block messages %}
    {% include 'adminlte/lib/_messages.html' %}
{% endblock %}

See the Django messages framework.

content_block_wrap
Wraps the content block. May be useful in some cases.
content
Block for the main content which will be displayed in the page. Empty by default.
javascript

All <script> tags which appear before the </body> tag. By default this includes all content from adminlte/lib/_scripts.html.

Consider making use of {{ block.super }} when overriding this block.

extra_foot
Additional HTML to be placed before the </body> tag. Empty by default.
body
Wraps the entire contents of the body tag, excluding the javascript and extra_foot blocks. Define if you wish to replace the entire body of the page
adminlte/login.html

Base template for a login interface. This excludes the navigational elements which are usually present. Example:

{% extends "adminlte/login.html" %}

{% block form %}
    <form method="post">
        {% csrf_token %}
        {{ form  }}
    </form>
{% endblock %}
Block reference

The login form defines some blocks in addition to those available on adminlte/base.html.

logo_text

The name of the site as shown above the login form. Default:

{% block logo_text %}<b>Admin</b>LTE{% endblock %}
logo_href
URL the logo should link to. Default: /
login_form
The form to be displayed. Defaults to a static HTML form.

Include templates

Much of the HTML rendering is done in included template files. These files reside in adminlte/lib/.

The easiest way to do this is to create a file of the same path and name in your app’s templates folder. This new template can then extend the original template and tweak blocks as necessary (or, if you wish, forgo the extending the reimplement the entire template).

Here is an example of the overriding and extension. We will be overriding the sidebar template (adminlte/lib/_main_sidebar.html), so we’ll create a template called my_app_name/templates/adminlte/lib/_main_sidebar.html:

{% extends 'adminlte/lib/_main_sidebar.html' %}

{% block nav_links %}
    <li>
        <a href="/some/url">
            <i class="fa fa-dashboard"></i> <span>Home</span>
        </a>
    </li>
    <li>
        <a href="/some/url">
            <i class="fa fa-user"></i> <span>Users</span>
        </a>
    </li>
{% endblock nav_links %}
adminlte/lib/_main_sidebar.html

Renders the sidebar navigation. You’ll likely need to implement this template at a minimum.

Block Reference
user_panel
Wraps the user details panel
form
An empty tag where you may wish to include a form. The AdminLTE examples place a search box here.
adminlte/lib/_main_header.html

Renders the header. Contains the site name and details regarding the currently logged in user.

Block Reference
logo

Wraps the logo HTML. Default:

{% block logo %}
<a href="{% block logo_href %}/{% endblock %}" class="logo">
    <!-- mini logo for sidebar mini 50x50 pixels -->
    <span class="logo-mini"><b>On</b>ly</span>
    <!-- logo for regular state and mobile devices -->
    <span class="logo-lg"><b>Only</b>Admin</span>
</a>
{% endblock %}
logo_href
URL the logo should link to. Default: /
logo_text

The name of the site as shown in the header. Default:

{% block logo_text %}<b>Admin</b>LTE{% endblock %}
logo_text_small

The logo name of the site as show in the header (used on narrow/mobile screens). Default:

{% block logo_text_small %}<b>A</b>LTE{% endblock %}
header_dropdowns
The dropdown menus in the header.
user_header

The contents of the user dropdown in the header. Default:

{% block user_header %}
<li class="user-header">
    <img src="{% avatar_url size=180 %}" class="img-circle" alt="User Image">
    <p>
        {% firstof request.user.get_short_name request.user.get_username %}
        <small>Member since {{ request.user.date_joined }}</small>
    </p>
</li>
{% endblock %}
change_password_url
The URL to the change password interface (defaults to Django admin’s change password page)
logout_url
The URL used for logging out the current user. Defaults to the value given in the LOGOUT_URL setting, or /logout if not set.

Templates & Blocks Reference

Some utility template tags are provided which you may find useful.

{% add_active %}

Returns the string " active " if the current url matches the one provided. You may find this useful in your lib/_main_sidebar.html template.

Example:

<li class="{% add_active 'myapp:detail' object.pk %}">
    <a href="{% url 'myapp:detail' object.pk %}">Details</a>
</li>

This will normally match any URL which starts with the provided value. Therefore the ‘active’ class will be applied for child pages too.

You can also specify the exact_only parameter which will override this behaviour. This is often useful for the home page:

<li class="{% add_active 'myapp:home' exact_match=True %}">
    <a href="{% url 'myapp:home' %}">Home</a>
</li>

{% avatar_url %}

Used in the based templates to find an avatar for the current user (uses Gravatar).

{% logout_url %}

Used in the based templates to determine the default logout url by looking for the LOGOUT_URL setting.

Credits

This project a based heavily on work by the following:

Indices and tables