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 %}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.