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_link
Allows adding items to OPENWISP_ADMIN_THEME_LINKS.
This function is meant to be used by third party apps or OpenWISP modules which aim to extend the core look and feel of the OpenWISP theme (e.g.: add new menu icons).
Syntax:
register_theme_link(links)
Parameter |
Description |
|
( |
openwisp_utils.admin_theme.theme.unregister_theme_link
Allows removing items from OPENWISP_ADMIN_THEME_LINKS.
This function is meant to be used by third party apps or OpenWISP modules which aim additional functionalities to UI of OpenWISP (e.g.: adding a support chat bot).
Syntax:
unregister_theme_link(links)
Parameter |
Description |
|
( |
openwisp_utils.admin_theme.theme.register_theme_js
Allows adding items to OPENWISP_ADMIN_THEME_JS.
Syntax:
register_theme_js(js)
Parameter |
Description |
|
( |
openwisp_utils.admin_theme.theme.unregister_theme_js
Allows removing items from OPENWISP_ADMIN_THEME_JS.
Syntax:
unregister_theme_js(js)
Parameter |
Description |
|
( |
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 |
|
( |
|
( |
|
( |
|
( |
|
optional ( |
|
(optional, str) The path to the template used for generating the HTML version. By
default, it uses |
|
Any additional keyword arguments (e.g. |
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.