From e9f8abb65911a6280abf36becb2c8c31058d0763 Mon Sep 17 00:00:00 2001 From: Adrian Turjak Date: Tue, 17 Apr 2018 19:42:35 +1200 Subject: [PATCH] Rework old customization templates and add new blocks 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 --- doc/source/configuration/customizing.rst | 109 +++++++++++++++--- .../local/local_settings.py.example | 1 + openstack_dashboard/templates/_footer.html | 11 +- .../templates/_login_footer.html | 9 +- .../templates/_login_form_footer.html | 13 ++- openstack_dashboard/templates/base.html | 10 +- .../templates/horizon/_custom_head_js.html | 10 ++ .../templates/horizon/_custom_meta.html | 10 ++ .../themes/example/static/_styles.scss | 0 .../themes/example/static/_variables.scss | 1 + .../example/static/js/my_analytics_js.js | 1 + .../themes/example/static/js/my_custom_js.js | 1 + .../example/templates/auth/_login_form.html | 9 ++ .../themes/example/templates/auth/login.html | 5 + .../themes/example/templates/base.html | 17 +++ ...tomization-templates-30384e91c5565328.yaml | 25 ++++ 16 files changed, 206 insertions(+), 26 deletions(-) create mode 100644 openstack_dashboard/themes/example/static/_styles.scss create mode 100644 openstack_dashboard/themes/example/static/_variables.scss create mode 100644 openstack_dashboard/themes/example/static/js/my_analytics_js.js create mode 100644 openstack_dashboard/themes/example/static/js/my_custom_js.js create mode 100644 openstack_dashboard/themes/example/templates/auth/_login_form.html create mode 100644 openstack_dashboard/themes/example/templates/auth/login.html create mode 100644 openstack_dashboard/themes/example/templates/base.html create mode 100644 releasenotes/notes/bp-less-customization-templates-30384e91c5565328.yaml diff --git a/doc/source/configuration/customizing.rst b/doc/source/configuration/customizing.rst index ff0bb413e0..324a8b371e 100644 --- a/doc/source/configuration/customizing.rst +++ b/doc/source/configuration/customizing.rst @@ -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 %} +

My custom footer

+ {% endblock %} + +Your theme's ``auth/login.html``:: + + {% extends "auth/login.html" %} + + {% block footer %} +

My custom login footer

+ {% 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 }} +

My custom login form footer

+ {% 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 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 +-------------- - +Additionally, some scripts require you to place them within the page's +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``:: - + {% extends "base.html" %} + {% block custom_head_js %} + + {% 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 %} + + {% 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 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 just after the default +Horizon meta tags. + +Your theme's ``base.html``:: + + {% extends "base.html" %} + + {% block custom_metadata %} + + {% endblock %} + +See the ``example`` theme for a working theme that uses these blocks. .. _Font Awesome: https://fortawesome.github.io/Font-Awesome/ diff --git a/openstack_dashboard/local/local_settings.py.example b/openstack_dashboard/local/local_settings.py.example index 6f366096c6..353fed3dd9 100644 --- a/openstack_dashboard/local/local_settings.py.example +++ b/openstack_dashboard/local/local_settings.py.example @@ -538,6 +538,7 @@ TIME_ZONE = "UTC" #AVAILABLE_THEMES = [ # ('default', 'Default', 'themes/default'), # ('material', 'Material', 'themes/material'), +# ('example', 'Example', 'themes/example'), #] LOGGING = { diff --git a/openstack_dashboard/templates/_footer.html b/openstack_dashboard/templates/_footer.html index 881e6d7489..32c0e28008 100644 --- a/openstack_dashboard/templates/_footer.html +++ b/openstack_dashboard/templates/_footer.html @@ -1,3 +1,10 @@ {% comment %} - A simple placeholder template for custom global footer content -{% endcomment %} \ No newline at end of file + 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 %} diff --git a/openstack_dashboard/templates/_login_footer.html b/openstack_dashboard/templates/_login_footer.html index 68dec4cbdd..5fecbf64cb 100644 --- a/openstack_dashboard/templates/_login_footer.html +++ b/openstack_dashboard/templates/_login_footer.html @@ -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 %} diff --git a/openstack_dashboard/templates/_login_form_footer.html b/openstack_dashboard/templates/_login_form_footer.html index eb9ff48b2f..040bcef240 100644 --- a/openstack_dashboard/templates/_login_form_footer.html +++ b/openstack_dashboard/templates/_login_form_footer.html @@ -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 %} diff --git a/openstack_dashboard/templates/base.html b/openstack_dashboard/templates/base.html index f92e5320e6..ddc70ffc91 100644 --- a/openstack_dashboard/templates/base.html +++ b/openstack_dashboard/templates/base.html @@ -5,10 +5,14 @@ + {% block custom_analytics %} + {% endblock %} - {% include "horizon/_custom_meta.html" %} + {% block custom_metadata %} + {% include "horizon/_custom_meta.html" %} + {% endblock %} {% block title %}{% endblock %} - {% site_branding %} {% 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 %} diff --git a/openstack_dashboard/templates/horizon/_custom_head_js.html b/openstack_dashboard/templates/horizon/_custom_head_js.html index e69de29bb2..ee4705382c 100644 --- a/openstack_dashboard/templates/horizon/_custom_head_js.html +++ b/openstack_dashboard/templates/horizon/_custom_head_js.html @@ -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 %} diff --git a/openstack_dashboard/templates/horizon/_custom_meta.html b/openstack_dashboard/templates/horizon/_custom_meta.html index e69de29bb2..5345fa485f 100644 --- a/openstack_dashboard/templates/horizon/_custom_meta.html +++ b/openstack_dashboard/templates/horizon/_custom_meta.html @@ -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 %} diff --git a/openstack_dashboard/themes/example/static/_styles.scss b/openstack_dashboard/themes/example/static/_styles.scss new file mode 100644 index 0000000000..e69de29bb2 diff --git a/openstack_dashboard/themes/example/static/_variables.scss b/openstack_dashboard/themes/example/static/_variables.scss new file mode 100644 index 0000000000..119ff2900c --- /dev/null +++ b/openstack_dashboard/themes/example/static/_variables.scss @@ -0,0 +1 @@ +@import "../default/variables"; diff --git a/openstack_dashboard/themes/example/static/js/my_analytics_js.js b/openstack_dashboard/themes/example/static/js/my_analytics_js.js new file mode 100644 index 0000000000..3373e6fcd5 --- /dev/null +++ b/openstack_dashboard/themes/example/static/js/my_analytics_js.js @@ -0,0 +1 @@ +console.log("EXAMPLE: your analytics js was loaded"); diff --git a/openstack_dashboard/themes/example/static/js/my_custom_js.js b/openstack_dashboard/themes/example/static/js/my_custom_js.js new file mode 100644 index 0000000000..70ac6a4bac --- /dev/null +++ b/openstack_dashboard/themes/example/static/js/my_custom_js.js @@ -0,0 +1 @@ +console.log("EXAMPLE: your custom js was loaded"); diff --git a/openstack_dashboard/themes/example/templates/auth/_login_form.html b/openstack_dashboard/themes/example/templates/auth/_login_form.html new file mode 100644 index 0000000000..56dce43356 --- /dev/null +++ b/openstack_dashboard/themes/example/templates/auth/_login_form.html @@ -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 }} +

My custom login form footer

+{% endblock %} diff --git a/openstack_dashboard/themes/example/templates/auth/login.html b/openstack_dashboard/themes/example/templates/auth/login.html new file mode 100644 index 0000000000..67670f2d8a --- /dev/null +++ b/openstack_dashboard/themes/example/templates/auth/login.html @@ -0,0 +1,5 @@ +{% extends "auth/login.html" %} + +{% block footer %} +

My custom login footer

+{% endblock %} diff --git a/openstack_dashboard/themes/example/templates/base.html b/openstack_dashboard/themes/example/templates/base.html new file mode 100644 index 0000000000..ee7ab74c8e --- /dev/null +++ b/openstack_dashboard/themes/example/templates/base.html @@ -0,0 +1,17 @@ +{% extends "base.html" %} + +{% block custom_analytics %} + +{% endblock %} + +{% block custom_metadata %} + +{% endblock %} + +{% block custom_head_js %} + +{% endblock %} + +{% block footer %} +

My custom footer

+{% endblock %} diff --git a/releasenotes/notes/bp-less-customization-templates-30384e91c5565328.yaml b/releasenotes/notes/bp-less-customization-templates-30384e91c5565328.yaml new file mode 100644 index 0000000000..845eb79c93 --- /dev/null +++ b/releasenotes/notes/bp-less-customization-templates-30384e91c5565328.yaml @@ -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.