Using the admin_theme

Note

This documentation page is aimed at developers who want to customize, change or extend the code of OpenWISP Utils in order to modify its behavior (e.g.: for personal or commercial purposes or to fix a bug, implement a new feature or contribute to the project in general).

If you aren't a developer and you are looking for information on how to use OpenWISP, please refer to:

The admin theme requires Django >= 2.2..

Make sure openwisp_utils.admin_theme is listed in INSTALLED_APPS (settings.py):

INSTALLED_APPS = [
    "django.contrib.auth",
    "django.contrib.contenttypes",
    "django.contrib.sessions",
    "django.contrib.messages",
    "django.contrib.staticfiles",
    "openwisp_utils.admin_theme",  # <----- add this
    # add when using autocomplete filter
    "admin_auto_filters",  # <----- add this
    "django.contrib.sites",
    # admin
    "django.contrib.admin",
]

Using DependencyLoader and DependencyFinder

Add the list of all packages extended to EXTENDED_APPS in settings.py.

For example, if you've extended django_x509:

EXTENDED_APPS = ["django_x509"]

DependencyFinder

This is a static finder which looks for static files in the static directory of the apps listed in settings.EXTENDED_APPS.

Add openwisp_utils.staticfiles.DependencyFinder to STATICFILES_FINDERS in settings.py.

STATICFILES_FINDERS = [
    "django.contrib.staticfiles.finders.FileSystemFinder",
    "django.contrib.staticfiles.finders.AppDirectoriesFinder",
    "openwisp_utils.staticfiles.DependencyFinder",  # <----- add this
]

DependencyLoader

This is a template loader which looks for templates in the templates directory of the apps listed in settings.EXTENDED_APPS.

Add openwisp_utils.loaders.DependencyLoader to template loaders in settings.py as shown below.

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "OPTIONS": {
            "loaders": [
                # ... other loaders ...
                "openwisp_utils.loaders.DependencyLoader",  # <----- add this
            ],
            "context_processors": [
                # ... omitted ...
            ],
        },
    },
]

Supplying Custom CSS and JS for the Admin Theme

Add openwisp_utils.admin_theme.context_processor.admin_theme_settings to template context_processors in settings.py as shown below. This will allow to set OPENWISP_ADMIN_THEME_LINKS and OPENWISP_ADMIN_THEME_JS settings to provide CSS and JS files to customize admin theme.

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [],
        "OPTIONS": {
            "loaders": [
                # ... omitted ...
            ],
            "context_processors": [
                # ... other context processors ...
                "openwisp_utils.admin_theme.context_processor.admin_theme_settings"  # <----- add this
            ],
        },
    },
]

Note

You will have to deploy these static files on your own.

In order to make django able to find and load these files you may want to use the STATICFILES_DIR setting in settings.py.

You can learn more in the Django documentation.

Extend Admin Theme Programmatically

openwisp_utils.admin_theme.theme.register_theme_js

Allows adding items to OPENWISP_ADMIN_THEME_JS.

Syntax:

register_theme_js(js)

Parameter

Description

js

(list) List of relative path of js files to be added to OPENWISP_ADMIN_THEME_JS

openwisp_utils.admin_theme.theme.unregister_theme_js

Allows removing items from OPENWISP_ADMIN_THEME_JS.

Syntax:

unregister_theme_js(js)

Parameter

Description

js

(list) List of relative path of js files to be removed from OPENWISP_ADMIN_THEME_JS

Sending emails

openwisp_utils.admin_theme.email.send_email

This function enables sending emails in both plain text and HTML formats. The HTML version uses a customizable template and logo.

You can set the logo using the OPENWISP_EMAIL_LOGO setting. To override the default template, see Customizing Email Templates.

In case the HTML version if not needed it may be disabled by setting OPENWISP_HTML_EMAIL to False.

Syntax:

send_email(subject, body_text, body_html, recipients, **kwargs)

Parameter

Description

subject

(str) The subject of the email template.

body_text

(str) The body of the text message to be emailed.

body_html

(str) The body of the html template to be emailed.

recipients

(list) The list of recipients to send the mail to.

extra_context

optional (dict) Extra context which is passed to the template. The dictionary keys call_to_action_text and call_to_action_url can be passed to show a call to action button. Similarly, footer can be passed to add a footer.

html_body_template

(optional, str) The path to the template used for generating the HTML version. By default, it uses openwisp_utils/email_template.html.

**kwargs

Any additional keyword arguments (e.g. attachments, headers, etc.) are passed directly to the django.core.mail.EmailMultiAlternatives.

Important

Data passed in body should be validated and user supplied data should not be sent directly to the function.

Customizing Email Templates

To customize the email templates used by the openwisp_utils.admin_theme.email.send_email function, you can override the openwisp_utils/email_template.html template in your Django project. Create a template with the same path (openwisp_utils/email_template.html) in your project's template directory to override the default template.

It is recommended to extend the default email template as shown below:

{% extends 'openwisp_utils/email_template.html' %}
{% block styles %}
{{ block.super }}
<style>
  .body {
    height: 100%;
    background: linear-gradient(to bottom, #8ccbbe 50%, #3797a4 50%);
    background-repeat: no-repeat;
    background-attachment: fixed;
    padding: 50px;
  }
</style>
{% endblock styles %}

Similarly, you can customize the HTML of the template by overriding the body block. See email_template.html for reference implementation.