horizon/doc/source/configuration/themes.rst

======
Themes
======

As of the Kilo release, styling for the OpenStack Dashboard can be altered
through the use of a theme. A theme is a directory containing a
``_variables.scss`` file to override the color codes used throughout the SCSS
and a ``_styles.scss`` file with additional styles to load after dashboard
styles have loaded.

As of the Mitaka release, Horizon can be configured to run with multiple
themes available at run time.  It uses a browser cookie to allow users to
toggle between the configured themes.  By default, Horizon is configured
with the two standard themes available: 'default' and 'material'.

To configure or alter the available themes, set ``AVAILABLE_THEMES`` in
``local_settings.py`` to a list of tuples, such that
``('name', 'label', 'path')``

``name``
  The key by which the theme value is stored within the cookie

``label``
  The label shown in the theme toggle under the User Menu

``path``
  The directory location for the theme. The path must be relative to the
  ``openstack_dashboard`` directory or an absolute path to an accessible
  location on the file system

To use a custom theme, set ``AVAILABLE_THEMES`` in ``local_settings.py`` to
a list of themes.  If you wish to run in a mode similar to legacy Horizon,
set ``AVAILABLE_THEMES`` with a single tuple, and the theme toggle will not
be available at all through the application to allow user configuration themes.

For example, a configuration with multiple themes::

  AVAILABLE_THEMES = [
      ('default', 'Default', 'themes/default'),
      ('material', 'Material', 'themes/material'),
  ]

A configuration with a single theme::

  AVAILABLE_THEMES = [
      ('default', 'Default', 'themes/default'),
  ]

Both the Dashboard custom variables and Bootstrap variables can be overridden.
For a full list of the Dashboard SCSS variables that can be changed,
see the variables file at
``openstack_dashboard/static/dashboard/scss/_variables.scss``.

In order to build a custom theme, both ``_variables.scss`` and ``_styles.scss``
are required and ``_variables.scss`` must provide all the default Bootstrap
variables.

Inherit from an Existing Theme
------------------------------

Custom themes must implement all of the Bootstrap variables required by
Horizon in ``_variables.scss`` and ``_styles.scss``. To make this easier, you
can inherit the variables needed in the default theme and only override those
that you need to customize. To inherit from the default theme, put this in your
theme's ``_variables.scss``::

   @import "/themes/default/variables";

Once you have made your changes you must re-generate the static files with
 ``tox -e manage -- collectstatic``.

By default, all of the themes configured by ``AVAILABLE_THEMES`` setting are
collected by horizon during the `collectstatic` process. By default, the themes
are collected into the dynamic `static/themes` directory, but this location can
be customized via the ``local_settings.py`` variable: ``THEME_COLLECTION_DIR``

Once collected, any theme configured via ``AVAILABLE_THEMES`` is available to
inherit from by importing its variables and styles from its collection
directory.  The following is an example of inheriting from the material theme::

  @import "/themes/material/variables";
  @import "/themes/material/styles";

All themes will need to be configured in ``AVAILABLE_THEMES`` to allow
inheritance.  If you wish to inherit from a theme, but not show that theme
as a selectable option in the theme picker widget, then simply configure the
``SELECTABLE_THEMES`` to exclude the parent theme.  ``SELECTABLE_THEMES`` must
be of the same format as ``AVAILABLE_THEMES``.  It defaults to
``AVAILABLE_THEMES`` if it is not set explicitly.

Bootswatch
~~~~~~~~~~

Horizon packages the Bootswatch SCSS files for use with its ``material`` theme.
Because of this, it is simple to use an existing Bootswatch theme as a base.
This is due to the fact that Bootswatch is loaded as a 3rd party static asset,
and therefore is automatically collected into the `static` directory in
`/horizon/lib/`.  The following is an example of how to inherit from
Bootswatch's ``darkly`` theme::

  @import "/horizon/lib/bootswatch/darkly/variables";
  @import "/horizon/lib/bootswatch/darkly/bootswatch";


Organizing Your Theme Directory
-------------------------------

A custom theme directory can be organized differently, depending on the
level of customization that is desired, as it can include static files
as well as Django templates.  It can include special subdirectories that will
be used differently: ``static``, ``templates`` and ``img``.

The ``static`` Folder
~~~~~~~~~~~~~~~~~~~~~

If the theme folder contains a sub-folder called ``static``, then that sub
folder will be used as the **static root of the theme**.  I.e., Horizon will
look in that sub-folder for the _variables.scss and _styles.scss files.
The contents of this folder will also be served up at ``/static/custom``.

The ``templates`` Folder
~~~~~~~~~~~~~~~~~~~~~~~~

If the theme folder contains a sub-folder ``templates``, then the path
to that sub-folder will be prepended to the ``TEMPLATE_DIRS`` tuple to
allow for theme specific template customizations.

Using the ``templates`` Folder
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Any Django template that is used in Horizon can be overridden through a theme.
This allows highly customized user experiences to exist within the scope of
different themes.  Any template that is overridden must adhere to the same
directory structure that the extending template expects.

For example, if you wish to customize the sidebar, Horizon expects the template
to live at ``horizon/_sidebar.html``.  You would need to duplicate that
directory structure under your templates directory, such that your override
would live at ``{ theme_path }/templates/horizon/_sidebar.html``.

The ``img`` Folder
~~~~~~~~~~~~~~~~~~

If the static root of the theme folder contains an ``img`` directory,
then all images that make use of the {% themable_asset %} templatetag
can be overridden.

These assets include logo.svg, splash-logo.svg and favicon.ico, however
overriding the SVG/GIF assets used by Heat within the `dashboard/img` folder
is not currently supported.

Customizing the Logo
--------------------

Simple
~~~~~~

If you wish to customize the logo that is used on the splash screen or in the
top navigation bar, then you need to create an ``img`` directory under your
theme's static root directory and place your custom ``logo.svg`` or
``logo-splash.svg`` within it.

If you wish to override the ``logo.svg`` using the previous method, and if the
image used is larger than the height of the top navigation, then the image will
be constrained to fit within the height of nav.  You can customize the height
of the top navigation bar by customizing the SCSS variable: ``$navbar-height``.
If the image's height is smaller than the navbar height, then the image
will retain its original resolution and size, and simply be centered
vertically in the available space.

Prior to the Kilo release the images files inside of Horizon needed to be
replaced by your images files or the Horizon stylesheets needed to be altered
to point to the location of your image.

Advanced
~~~~~~~~

If you need to do more to customize the logo than simply replacing the existing
PNG, then you can also override the _brand.html through a custom theme.  To use
this technique, simply add a ``templates/header/_brand.html`` to the root of
your custom theme, and add markup directly to the file.  For an example of how
to do this, see
``openstack_dashboard/themes/material/templates/header/_brand.html``.

The splash / login panel can also be customized by adding
``templates/auth/_splash.html``.  See
``openstack_dashboard/themes/material/templates/auth/_splash.html`` for an
example.