openstack/horizon
Code Issues Proposed changes

Rework old customization templates and add new blocks

Browse Source 
From Rocky we can now support Django's recursive template
inheritance. Let's move away from all these stand alone
templates for deployers to override and instead direct them
to recursively extend the existing templates and the blocks they
need.

This adds more blocks, docs on how to use them, and an example
theme which can be turned on and used to show how this works.

blueprint: less-customization-templates
Change-Id: I69f1e16ff1b88cec78580df0911fe3c01b7507dd
This commit is contained in:
Adrian Turjak 2018-04-17 19:42:35 +12:00
parent 07070c437d
commit e9f8abb659
16 changed files with 206 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

109
doc/source/configuration/customizing.rst
View File

@ -29,10 +29,42 @@ the desired url target e.g., ``http://sample-company.com`` in
Customizing the Footer
======================
It is possible to customize the global and login footers using a theme's
template override. Simply add ``_footer.html`` for a global footer
override or ``_login_footer.html`` for the login page's footer to your
theme's template directory.
It is possible to customize the global and login footers by using Django's
recursive inheritance to extend the ``base.html``, ``auth/login.html``, and
``auth/_login_form.html`` templates. You do this by naming your template the
same name as the template you wish to extend and only overriding the blocks you
wish to change.
Your theme's ``base.html``::
{% extends "base.html" %}
{% block footer %}
<p>My custom footer</p>
{% endblock %}
Your theme's ``auth/login.html``::
{% extends "auth/login.html" %}
{% block footer %}
<p>My custom login footer</p>
{% endblock %}
Your theme's ``auth/_login_form.html``::
{% extends "auth/_login_form.html" %}
{% block login_footer %}
{% comment %}
You MUST have block.super because that includes the login button.
{% endcomment %}
{{ block.super }}
<p>My custom login form footer</p>
{% endblock %}
See the ``example`` theme for a working theme that uses these blocks.
Modifying Existing Dashboards and Panels
========================================
@ -384,26 +416,69 @@ my_custom_dashboard/templates/my_custom_dashboard/base.html`` override
The result is a single compressed js file consisting both Horizon and
dashboard's custom scripts.
Additionally, some marketing and analytics scripts require you to place them
within the page's <head> tag. To do this, place them within the
``horizon/_custom_head_js.html`` file. Similar to the ``_scripts.html`` file
mentioned above, you may link to an existing file::
Custom Head js
--------------
<script src='{{ STATIC_URL }}/my_custom_dashboard/js/my_marketing_js.js' type='text/javascript' charset='utf-8'></script>
Additionally, some scripts require you to place them within the page's <head>
tag. To do this, recursively extend the ``base.html`` template in your theme
to override the ``custom_head_js`` block.
or you can paste your script directly in the file, being sure to use
appropriate tags::
Your theme's ``base.html``::
<script type="text/javascript">
//some javascript
</script>
{% extends "base.html" %}
{% block custom_head_js %}
<script src='{{ STATIC_URL }}/my_custom_dashboard/js/my_custom_js.js' type='text/javascript' charset='utf-8'></script>
{% endblock %}
See the ``example`` theme for a working theme that uses these blocks.
.. warning::
Don't use the ``custom_head_js`` block for analytics tracking. See below.
Custom Analytics
----------------
For analytics or tracking scripts you should avoid the ``custom_head_js``
block. We have a specific block instead called ``custom_analytics``. Much like
the ``custom_head_js`` block this inserts additional content into the head of
the ``base.html`` template and it will be on all pages.
The reason for an analytics specific block is that for security purposes we
want to be able to turn off tracking on certain pages that we deem sensitive.
This is done for the safety of the users and the cloud admins. By using this
block instead, pages using ``base.html`` can override it themselves when they
want to avoid tracking. They can't simply override the custom js because it may
be non-tracking code.
Your theme's ``base.html``::
{% extends "base.html" %}
{% block custom_analytics %}
<script src='{{ STATIC_URL }}/my_custom_dashboard/js/my_tracking_js.js' type='text/javascript' charset='utf-8'></script>
{% endblock %}
See the ``example`` theme for a working theme that uses these blocks.
Customizing Meta Attributes
===========================
To add custom metadata attributes to your project's base template, include
them in the ``horizon/_custom_meta.html`` file. The contents of this file will
be inserted into the page's <head> just after the default Horizon meta tags.
To add custom metadata attributes to your project's base template use the
``custom_metadata`` block. To do this, recursively extend the ``base.html``
template in your theme to override the ``custom_metadata`` block. The contents
of this block will be inserted into the page's <head> just after the default
Horizon meta tags.
Your theme's ``base.html``::
{% extends "base.html" %}
{% block custom_metadata %}
<meta name="description" content="My custom metadata.">
{% endblock %}
See the ``example`` theme for a working theme that uses these blocks.
.. _Font Awesome: https://fortawesome.github.io/Font-Awesome/

1
openstack_dashboard/local/local_settings.py.example
View File

@ -538,6 +538,7 @@ TIME_ZONE = "UTC"
#AVAILABLE_THEMES = [
# ('default', 'Default', 'themes/default'),
# ('material', 'Material', 'themes/material'),
# ('example', 'Example', 'themes/example'),
#]
LOGGING = {

9
openstack_dashboard/templates/_footer.html
View File

@ -1,3 +1,10 @@
{% comment %}
A simple placeholder template for custom global footer content
This template has been deprecated since the Rocky release and is slated for
removal in the T release. To achieve the same functionality as this template
used to provide, look at the docs on how to recursively extend the
'base.html' template.
You will want to override the block 'footer' in 'base.html'.
See 'base.html' in the example theme.
{% endcomment %}

9
openstack_dashboard/templates/_login_footer.html
View File

@ -1,3 +1,10 @@
{% comment %}
A simple placeholder template for custom login footer content
This template has been deprecated since the Rocky release and is slated for
removal in the T release. To achieve the same functionality as this template
used to provide, look at the docs on how to recursively extend the
'auth/login.html' template.
You will want to override the block 'footer' in 'auth/login.html'.
See 'auth/login.html' in the example theme.
{% endcomment %}

13
openstack_dashboard/templates/_login_form_footer.html
View File

@ -1,6 +1,11 @@
{% comment %}
A simple placeholder template for custom login form footer content.
Unlike the login footer, this template places content into the form
right below the login button. Such as a link to a password reset
form or other additional links.
This template has been deprecated since the Rocky release and is slated for
removal in the T release. To achieve the same functionality as this template
used to provide, look at the docs on how to recursively extend the
'auth/_login_form.html' template.
You will want to override the block 'login_footer' in
'auth/_login_form.html'.
See 'auth/_login_form.html' in the example theme.
{% endcomment %}

10
openstack_dashboard/templates/base.html
View File

@ -5,10 +5,14 @@
<!DOCTYPE html>
<html>
<head>
{% block custom_analytics %}
{% endblock %}
<meta content='IE=edge' http-equiv='X-UA-Compatible' />
<meta content='text/html; charset=utf-8' http-equiv='Content-Type' />
<meta name="viewport" content="width=device-width, initial-scale=1">
{% include "horizon/_custom_meta.html" %}
{% block custom_metadata %}
{% include "horizon/_custom_meta.html" %}
{% endblock %}
<title>{% block title %}{% endblock %} - {% site_branding %}</title>
{% comment %} Load CSS sheets before Javascript {% endcomment %}
{% block css %}
@ -17,7 +21,9 @@
{% iframe_embed_settings %}
{% include "horizon/_conf.html" %}
{% include "horizon/client_side/_script_loader.html" %}
{% include "horizon/_custom_head_js.html" %}
{% block custom_head_js %}
{% include "horizon/_custom_head_js.html" %}
{% endblock %}
{% block ng_route_base %} {% endblock %}
</head>
<body id="{% block body_id %}{% endblock %}" ng-app='horizon.app' ng-strict-di>

10
openstack_dashboard/templates/horizon/_custom_head_js.html
View File

@ -0,0 +1,10 @@
{% comment %}
This template has been deprecated since the Rocky release and is slated for
removal in the T release. To achieve the same functionality as this template
used to provide, look at the docs on how to recursively extend the
'base.html' template.
You will want to override the block 'custom_head_js' in 'base.html'.
See 'base.html' in the example theme.
{% endcomment %}

10
openstack_dashboard/templates/horizon/_custom_meta.html
View File

@ -0,0 +1,10 @@
{% comment %}
This template has been deprecated since the Rocky release and is slated for
removal in the T release. To achieve the same functionality as this template
used to provide, look at the docs on how to recursively extend the
'base.html' template.
You will want to override the block 'custom_metadata' in 'base.html'.
See 'base.html' in the example theme.
{% endcomment %}

0
openstack_dashboard/themes/example/static/_styles.scss Normal file
View File

1
openstack_dashboard/themes/example/static/_variables.scss Normal file
View File

@ -0,0 +1 @@
@import "../default/variables";

1
openstack_dashboard/themes/example/static/js/my_analytics_js.js Normal file
View File

@ -0,0 +1 @@
console.log("EXAMPLE: your analytics js was loaded");

1
openstack_dashboard/themes/example/static/js/my_custom_js.js Normal file
View File

@ -0,0 +1 @@
console.log("EXAMPLE: your custom js was loaded");

9
openstack_dashboard/themes/example/templates/auth/_login_form.html Normal file
View File

@ -0,0 +1,9 @@
{% extends "auth/_login_form.html" %}
{% block login_footer %}
{% comment %}
You MUST have block.super because that includes the login button.
{% endcomment %}
{{ block.super }}
<p>My custom login form footer</p>
{% endblock %}

5
openstack_dashboard/themes/example/templates/auth/login.html Normal file
View File

@ -0,0 +1,5 @@
{% extends "auth/login.html" %}
{% block footer %}
<p>My custom login footer</p>
{% endblock %}

17
openstack_dashboard/themes/example/templates/base.html Normal file
View File

@ -0,0 +1,17 @@
{% extends "base.html" %}
{% block custom_analytics %}
<script src='{{ STATIC_URL }}/themes/example/js/my_analytics_js.js' type='text/javascript' charset='utf-8'></script>
{% endblock %}
{% block custom_metadata %}
<meta name="description" content="My custom metadata.">
{% endblock %}
{% block custom_head_js %}
<script src='{{ STATIC_URL }}/themes/example/js/my_custom_js.js' type='text/javascript' charset='utf-8'></script>
{% endblock %}
{% block footer %}
<p>My custom footer</p>
{% endblock %}

25
releasenotes/notes/bp-less-customization-templates-30384e91c5565328.yaml Normal file
View File

@ -0,0 +1,25 @@
---
features:
- |
With the fixes in Rocky that allow using Django's recursive template
inheritance we have added new blocks in our ``base.html`` template to allow
a better means of customizing through your themes. For details see the
``customizing`` docs.
deprecations:
- |
The customization override templates have been deprecated in favor of using
recursive inheritance in your themes. The following templates have been
deprecated and are slated for removal in the U release:
* ``_footer.html'``
* ``_login_footer.html``
* ``_login_form_footer.html``
* ``horizon/_custom_head_js.html``
* ``horizon/_custom_meta.html``
upgrade:
- |
To allow certain views to optionally disable analytics tracking when
handling sensitive data, don't use the ``custom_head_js`` block, or the now
deprecated template ``horizon/_custom_head_js.html`` for analytics
tracking. Please read the ``customizing`` docs and instead use the
dedicated ``custom_analytics`` block so Horizon or its plugins can when
needed disable tracking on a given view.