doc: Move settings information to configuration/ dir
The new standard document structure suggests to have a dedicated dir named configuration/. It will be linked from docs.o.o directly, so it would be better to follow the guideline. This commit moves the pages on settings and customization to a new directory configuration/. It also splits the pages into meaningful pieces. Change-Id: I65a3b0b688c8abc176662f86a0dbbfa3b64c4101
This commit is contained in:
Akihiro Motoki
parent
70946f629d
commit
7502d9c872
179
doc/source/configuration/branding.rst
Normal file
179
doc/source/configuration/branding.rst
Normal file
@ -0,0 +1,179 @@
|
||||
================
|
||||
Branding Horizon
|
||||
================
|
||||
|
||||
As of the Liberty release, Horizon has begun to conform more strictly to
|
||||
Bootstrap standards in an effort to embrace more responsive web design as well
|
||||
as alleviate the future need to re-brand new functionality for every release.
|
||||
|
||||
Supported Components
|
||||
--------------------
|
||||
The following components, organized by release, are the only ones that make
|
||||
full use of the Bootstrap theme architecture.
|
||||
|
||||
* 8.0.0 (Liberty)
|
||||
|
||||
* `Top Navbar`_
|
||||
* `Side Nav`_
|
||||
* `Pie Charts`_
|
||||
|
||||
* 9.0.0 (Mitaka)
|
||||
|
||||
* Tables_
|
||||
* `Bar Charts`_
|
||||
* Login_
|
||||
* Tabs_
|
||||
* Alerts_
|
||||
* Checkboxes_
|
||||
|
||||
Step 1
|
||||
------
|
||||
|
||||
The first step needed to create a custom branded theme for Horizon is to create
|
||||
a custom Bootstrap theme. There are several tools to aid in this. Some of the
|
||||
more useful ones include:
|
||||
|
||||
- `Bootswatchr`_
|
||||
- `Paintstrap`_
|
||||
- `Bootstrap`_
|
||||
|
||||
.. note::
|
||||
|
||||
Bootstrap uses LESS by default, but we use SCSS. All of the above
|
||||
tools will provide the ``variables.less`` file, which will need to be
|
||||
converted to ``_variables.scss``
|
||||
|
||||
Top Navbar
|
||||
----------
|
||||
|
||||
The top navbar in Horizon now uses a native Bootstrap ``navbar``. There are a
|
||||
number of variables that can be used to customize this element. Please see the
|
||||
**Navbar** section of your variables file for specifics on what can be set: any
|
||||
variables that use ``navbar-default``.
|
||||
|
||||
It is important to also note that the navbar now uses native Bootstrap
|
||||
dropdowns, which are customizable with variables. Please see the **Dropdowns**
|
||||
section of your variables file.
|
||||
|
||||
The top navbar is now responsive on smaller screens. When the window size hits
|
||||
your ``$screen-sm`` value, the topbar will compress into a design that is
|
||||
better suited for small screens.
|
||||
|
||||
Side Nav
|
||||
--------
|
||||
|
||||
The side navigation component has been refactored to use the native Stacked
|
||||
Pills element from Bootstrap. See **Pills** section of your variables file
|
||||
for specific variables to customize.
|
||||
|
||||
Charts
|
||||
------
|
||||
|
||||
Pie Charts
|
||||
~~~~~~~~~~
|
||||
|
||||
Pie Charts are SVG elements. SVG elements allow CSS customizations for
|
||||
only a basic element's look and feel (i.e. colors, size).
|
||||
|
||||
Since there is no native element in Bootstrap specifically for pie charts,
|
||||
the look and feel of the charts are inheriting from other elements of the
|
||||
theme. Please see ``_pie_charts.scss`` for specifics.
|
||||
|
||||
.. _Bar Charts:
|
||||
|
||||
Bar Charts
|
||||
~~~~~~~~~~
|
||||
|
||||
Bar Charts can be either a Bootstrap Progress Bar or an SVG element. Either
|
||||
implementation will use the Bootstrap Progress Bar styles.
|
||||
|
||||
The SVG implementation will not make use of the customized Progress Bar
|
||||
height though, so it is recommended that Bootstrap Progress Bars are used
|
||||
whenever possible.
|
||||
|
||||
Please see ``_bar_charts.scss`` for specifics on what can be customized for
|
||||
SVGs. See the **Progress bars** section of your variables file for specific
|
||||
variables to customize.
|
||||
|
||||
Tables
|
||||
------
|
||||
|
||||
The standard Django tables now make use of the native Bootstrap table markup.
|
||||
See **Tables** section of your variables file for variables to customize.
|
||||
|
||||
The standard Bootstrap tables will be borderless by default. If you wish to
|
||||
add a border, like the ``default`` theme, see
|
||||
``openstack_dashboard/themes/default/horizon/components/_tables.scss``
|
||||
|
||||
.. _Login:
|
||||
|
||||
Login
|
||||
-----
|
||||
|
||||
Login Splash Page
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The login splash page now uses a standard Bootstrap panel in its implementation.
|
||||
See the **Panels** section in your variables file to variables to easily
|
||||
customize.
|
||||
|
||||
Modal Login
|
||||
~~~~~~~~~~~
|
||||
|
||||
The modal login experience, as used when switching regions, uses a standard
|
||||
Bootstrap dialog. See the **Modals** section of your variables file for
|
||||
specific variables to customize.
|
||||
|
||||
Tabs
|
||||
----
|
||||
|
||||
The standard tabs make use of the native Bootstrap tab markup.
|
||||
|
||||
See **Tabs** section of your variables file for variables to customize.
|
||||
|
||||
Alerts
|
||||
------
|
||||
|
||||
Alerts use the basic Bootstrap brand colors. See **Colors** section of your
|
||||
variables file for specifics.
|
||||
|
||||
Checkboxes
|
||||
----------
|
||||
|
||||
Horizon uses icon fonts to represent checkboxes. In order to customize
|
||||
this, you simply need to override the standard scss. For an example of
|
||||
this, see themes/material/static/horizon/components/_checkboxes.scss
|
||||
|
||||
Bootswatch and Material Design
|
||||
------------------------------
|
||||
|
||||
`Bootswatch`_ is a collection of free themes for Bootstrap and is now
|
||||
available for use in Horizon.
|
||||
|
||||
In order to showcase what can be done to enhance an existing Bootstrap theme,
|
||||
Horizon now includes a secondary theme, roughly based on `Google's Material
|
||||
Design`_ called ``material``. Bootswatch's **Paper** is a simple Bootstrap
|
||||
implementation of Material Design and is used by ``material``.
|
||||
|
||||
Bootswatch provides a number of other themes, that once Horizon is fully theme
|
||||
compliant, will allow easy toggling and customizations for darker or
|
||||
accessibility driven experiences.
|
||||
|
||||
Development Tips
|
||||
----------------
|
||||
|
||||
When developing a new theme for Horizon, it is required that the dynamically
|
||||
generated `static` directory be cleared after each change and the server
|
||||
restarted. This is not always ideal. If you wish to develop and not have
|
||||
to restart the server each time, it is recommended that you configure your
|
||||
development environment to not run in OFFLINE mode. Simply verify the
|
||||
following settings in your local_settings.py::
|
||||
|
||||
COMPRESS_OFFLINE = False
|
||||
COMPRESS_ENABLED = False
|
||||
|
||||
.. _Bootstrap: http://getbootstrap.com/customize/
|
||||
.. _Bootswatch: http://bootswatch.com
|
||||
.. _Bootswatchr: http://bootswatchr.com/create#!
|
||||
.. _Paintstrap: http://paintstrap.com
|
||||
.. _Google's Material Design: https://www.google.com/design/spec/material-design/introduction.html
|
||||
@ -4,360 +4,9 @@
|
||||
Customizing Horizon
|
||||
===================
|
||||
|
||||
Themes
|
||||
======
|
||||
.. seealso::
|
||||
|
||||
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";
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Branding Horizon
|
||||
================
|
||||
|
||||
As of the Liberty release, Horizon has begun to conform more strictly to
|
||||
Bootstrap standards in an effort to embrace more responsive web design as well
|
||||
as alleviate the future need to re-brand new functionality for every release.
|
||||
|
||||
Supported Components
|
||||
--------------------
|
||||
The following components, organized by release, are the only ones that make
|
||||
full use of the Bootstrap theme architecture.
|
||||
|
||||
8.0.0 (Liberty)
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
* `Top Navbar`_
|
||||
* `Side Nav`_
|
||||
* `Pie Charts`_
|
||||
|
||||
9.0.0 (Mitaka)
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
* Tables_
|
||||
* `Bar Charts`_
|
||||
* Login_
|
||||
* Tabs_
|
||||
* Alerts_
|
||||
* Checkboxes_
|
||||
|
||||
Step 1
|
||||
------
|
||||
|
||||
The first step needed to create a custom branded theme for Horizon is to create
|
||||
a custom Bootstrap theme. There are several tools to aid in this. Some of the
|
||||
more useful ones include:
|
||||
|
||||
- `Bootswatchr`_
|
||||
- `Paintstrap`_
|
||||
- `Bootstrap`_
|
||||
|
||||
.. note::
|
||||
|
||||
Bootstrap uses LESS by default, but we use SCSS. All of the above
|
||||
tools will provide the ``variables.less`` file, which will need to be
|
||||
converted to ``_variables.scss``
|
||||
|
||||
Top Navbar
|
||||
----------
|
||||
|
||||
The top navbar in Horizon now uses a native Bootstrap ``navbar``. There are a
|
||||
number of variables that can be used to customize this element. Please see the
|
||||
**Navbar** section of your variables file for specifics on what can be set: any
|
||||
variables that use ``navbar-default``.
|
||||
|
||||
It is important to also note that the navbar now uses native Bootstrap
|
||||
dropdowns, which are customizable with variables. Please see the **Dropdowns**
|
||||
section of your variables file.
|
||||
|
||||
The top navbar is now responsive on smaller screens. When the window size hits
|
||||
your ``$screen-sm`` value, the topbar will compress into a design that is
|
||||
better suited for small screens.
|
||||
|
||||
Side Nav
|
||||
--------
|
||||
|
||||
The side navigation component has been refactored to use the native Stacked
|
||||
Pills element from Bootstrap. See **Pills** section of your variables file
|
||||
for specific variables to customize.
|
||||
|
||||
Charts
|
||||
------
|
||||
|
||||
Pie Charts
|
||||
~~~~~~~~~~
|
||||
|
||||
Pie Charts are SVG elements. SVG elements allow CSS customizations for
|
||||
only a basic element's look and feel (i.e. colors, size).
|
||||
|
||||
Since there is no native element in Bootstrap specifically for pie charts,
|
||||
the look and feel of the charts are inheriting from other elements of the
|
||||
theme. Please see ``_pie_charts.scss`` for specifics.
|
||||
|
||||
.. _Bar Charts:
|
||||
|
||||
Bar Charts
|
||||
~~~~~~~~~~
|
||||
|
||||
Bar Charts can be either a Bootstrap Progress Bar or an SVG element. Either
|
||||
implementation will use the Bootstrap Progress Bar styles.
|
||||
|
||||
The SVG implementation will not make use of the customized Progress Bar
|
||||
height though, so it is recommended that Bootstrap Progress Bars are used
|
||||
whenever possible.
|
||||
|
||||
Please see ``_bar_charts.scss`` for specifics on what can be customized for
|
||||
SVGs. See the **Progress bars** section of your variables file for specific
|
||||
variables to customize.
|
||||
|
||||
Tables
|
||||
------
|
||||
|
||||
The standard Django tables now make use of the native Bootstrap table markup.
|
||||
See **Tables** section of your variables file for variables to customize.
|
||||
|
||||
The standard Bootstrap tables will be borderless by default. If you wish to
|
||||
add a border, like the ``default`` theme, see
|
||||
``openstack_dashboard/themes/default/horizon/components/_tables.scss``
|
||||
|
||||
.. _Login:
|
||||
|
||||
Login
|
||||
-----
|
||||
|
||||
Login Splash Page
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
The login splash page now uses a standard Bootstrap panel in its implementation.
|
||||
See the **Panels** section in your variables file to variables to easily
|
||||
customize.
|
||||
|
||||
Modal Login
|
||||
~~~~~~~~~~~
|
||||
|
||||
The modal login experience, as used when switching regions, uses a standard
|
||||
Bootstrap dialog. See the **Modals** section of your variables file for
|
||||
specific variables to customize.
|
||||
|
||||
Tabs
|
||||
----
|
||||
|
||||
The standard tabs make use of the native Bootstrap tab markup.
|
||||
|
||||
See **Tabs** section of your variables file for variables to customize.
|
||||
|
||||
Alerts
|
||||
------
|
||||
|
||||
Alerts use the basic Bootstrap brand colors. See **Colors** section of your
|
||||
variables file for specifics.
|
||||
|
||||
Checkboxes
|
||||
----------
|
||||
|
||||
Horizon uses icon fonts to represent checkboxes. In order to customize
|
||||
this, you simply need to override the standard scss. For an example of
|
||||
this, see themes/material/static/horizon/components/_checkboxes.scss
|
||||
|
||||
Bootswatch and Material Design
|
||||
------------------------------
|
||||
|
||||
`Bootswatch`_ is a collection of free themes for Bootstrap and is now
|
||||
available for use in Horizon.
|
||||
|
||||
In order to showcase what can be done to enhance an existing Bootstrap theme,
|
||||
Horizon now includes a secondary theme, roughly based on `Google's Material
|
||||
Design`_ called ``material``. Bootswatch's **Paper** is a simple Bootstrap
|
||||
implementation of Material Design and is used by ``material``.
|
||||
|
||||
Bootswatch provides a number of other themes, that once Horizon is fully theme
|
||||
compliant, will allow easy toggling and customizations for darker or
|
||||
accessibility driven experiences.
|
||||
|
||||
Development Tips
|
||||
----------------
|
||||
|
||||
When developing a new theme for Horizon, it is required that the dynamically
|
||||
generated `static` directory be cleared after each change and the server
|
||||
restarted. This is not always ideal. If you wish to develop and not have
|
||||
to restart the server each time, it is recommended that you configure your
|
||||
development environment to not run in OFFLINE mode. Simply verify the
|
||||
following settings in your local_settings.py::
|
||||
|
||||
COMPRESS_OFFLINE = False
|
||||
COMPRESS_ENABLED = False
|
||||
You may also be interested in :doc:`themes` and :doc:`branding`.
|
||||
|
||||
Changing the Site Title
|
||||
=======================
|
||||
@ -753,9 +402,4 @@ 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.
|
||||
|
||||
.. _Bootswatch: http://bootswatch.com
|
||||
.. _Bootswatchr: http://bootswatchr.com/create#!
|
||||
.. _Paintstrap: http://paintstrap.com
|
||||
.. _Bootstrap: http://getbootstrap.com/customize/
|
||||
.. _Google's Material Design: https://www.google.com/design/spec/material-design/introduction.html
|
||||
.. _Font Awesome: https://fortawesome.github.io/Font-Awesome/
|
||||
12
doc/source/configuration/index.rst
Normal file
12
doc/source/configuration/index.rst
Normal file
@ -0,0 +1,12 @@
|
||||
===================
|
||||
Configuration Guide
|
||||
===================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
settings
|
||||
pluggable_panels
|
||||
customizing
|
||||
themes
|
||||
branding
|
||||
285
doc/source/configuration/pluggable_panels.rst
Normal file
285
doc/source/configuration/pluggable_panels.rst
Normal file
@ -0,0 +1,285 @@
|
||||
.. _pluggable-settings-label:
|
||||
|
||||
===========================
|
||||
Pluggable Panels and Groups
|
||||
===========================
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
Horizon allows dashboards, panels and panel groups to be added without
|
||||
modifying the default settings. Pluggable settings are a mechanism to allow
|
||||
settings to be stored in separate files. Those files are read at startup and
|
||||
used to modify the default settings.
|
||||
|
||||
The default location for the dashboard configuration files is
|
||||
``openstack_dashboard/enabled``, with another directory,
|
||||
``openstack_dashboard/local/enabled`` for local overrides. Both sets of files
|
||||
will be loaded, but the settings in ``openstack_dashboard/local/enabled`` will
|
||||
overwrite the default ones. The settings are applied in alphabetical order of
|
||||
the filenames. If the same dashboard has configuration files in ``enabled`` and
|
||||
``local/enabled``, the local name will be used. Note, that since names of
|
||||
python modules can't start with a digit, the files are usually named with a
|
||||
leading underscore and a number, so that you can control their order easily.
|
||||
|
||||
General Pluggbale Settings
|
||||
==========================
|
||||
|
||||
Before we describe the specific use cases, the following keys can be used in
|
||||
any pluggable settings file:
|
||||
|
||||
``ADD_EXCEPTIONS``
|
||||
------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
A dictionary of exception classes to be added to ``HORIZON['exceptions']``.
|
||||
|
||||
``ADD_INSTALLED_APPS``
|
||||
----------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
A list of applications to be prepended to ``INSTALLED_APPS``.
|
||||
This is needed to expose static files from a plugin.
|
||||
|
||||
``ADD_ANGULAR_MODULES``
|
||||
-----------------------
|
||||
|
||||
.. versionadded:: 2014.2(Juno)
|
||||
|
||||
A list of AngularJS modules to be loaded when Angular bootstraps. These modules
|
||||
are added as dependencies on the root Horizon application ``horizon``.
|
||||
|
||||
``ADD_JS_FILES``
|
||||
----------------
|
||||
|
||||
.. versionadded:: 2014.2(Juno)
|
||||
|
||||
A list of javascript source files to be included in the compressed set of files that are
|
||||
loaded on every page. This is needed for AngularJS modules that are referenced in
|
||||
``ADD_ANGULAR_MODULES`` and therefore need to be included in every page.
|
||||
|
||||
``ADD_JS_SPEC_FILES``
|
||||
---------------------
|
||||
|
||||
.. versionadded:: 2015.1(Kilo)
|
||||
|
||||
A list of javascript spec files to include for integration with the Jasmine spec runner.
|
||||
Jasmine is a behavior-driven development framework for testing JavaScript code.
|
||||
|
||||
``ADD_SCSS_FILES``
|
||||
------------------
|
||||
|
||||
.. versionadded:: 8.0.0(Liberty)
|
||||
|
||||
A list of scss files to be included in the compressed set of files that are
|
||||
loaded on every page. We recommend one scss file per dashboard, use @import if
|
||||
you need to include additional scss files for panels.
|
||||
|
||||
.. _auto_discover_static_files:
|
||||
|
||||
``AUTO_DISCOVER_STATIC_FILES``
|
||||
------------------------------
|
||||
|
||||
.. versionadded:: 8.0.0(Liberty)
|
||||
|
||||
If set to ``True``, JavaScript files and static angular html template files will be
|
||||
automatically discovered from the `static` folder in each apps listed in ADD_INSTALLED_APPS.
|
||||
|
||||
JavaScript source files will be ordered based on naming convention: files with extension
|
||||
`.module.js` listed first, followed by other JavaScript source files.
|
||||
|
||||
JavaScript files for testing will also be ordered based on naming convention: files with extension
|
||||
`.mock.js` listed first, followed by files with extension `.spec.js`.
|
||||
|
||||
If ADD_JS_FILES and/or ADD_JS_SPEC_FILES are also specified, files manually listed there will be
|
||||
appended to the auto-discovered files.
|
||||
|
||||
``DISABLED``
|
||||
------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
If set to ``True``, this settings file will not be added to the settings.
|
||||
|
||||
``UPDATE_HORIZON_CONFIG``
|
||||
-------------------------
|
||||
|
||||
.. versionadded:: 2014.2(Juno)
|
||||
|
||||
A dictionary of values that will replace the values in ``HORIZON_CONFIG``.
|
||||
|
||||
|
||||
Pluggable Settings for Dashboards
|
||||
=================================
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The following keys are specific to registering a dashboard:
|
||||
|
||||
|
||||
``DASHBOARD``
|
||||
-------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the dashboard to be added to ``HORIZON['dashboards']``. Required.
|
||||
|
||||
``DEFAULT``
|
||||
-----------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
If set to ``True``, this dashboard will be set as the default dashboard.
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
To disable a dashboard locally, create a file
|
||||
``openstack_dashboard/local/enabled/_40_dashboard-name.py`` with the following
|
||||
content::
|
||||
|
||||
DASHBOARD = '<dashboard-name>'
|
||||
DISABLED = True
|
||||
|
||||
To add a Tuskar-UI (Infrastructure) dashboard, you have to install it, and then
|
||||
create a file ``openstack_dashboard/local/enabled/_50_tuskar.py`` with::
|
||||
|
||||
from tuskar_ui import exceptions
|
||||
|
||||
DASHBOARD = 'infrastructure'
|
||||
ADD_INSTALLED_APPS = [
|
||||
'tuskar_ui.infrastructure',
|
||||
]
|
||||
ADD_EXCEPTIONS = {
|
||||
'recoverable': exceptions.RECOVERABLE,
|
||||
'not_found': exceptions.NOT_FOUND,
|
||||
'unauthorized': exceptions.UNAUTHORIZED,
|
||||
}
|
||||
|
||||
|
||||
Pluggable Settings for Panels
|
||||
=============================
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The following keys are specific to registering or removing a panel:
|
||||
|
||||
``PANEL``
|
||||
---------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the panel to be added to ``HORIZON_CONFIG``. Required.
|
||||
|
||||
``PANEL_DASHBOARD``
|
||||
-------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the dashboard the ``PANEL`` associated with. Required.
|
||||
|
||||
|
||||
``PANEL_GROUP``
|
||||
---------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the panel group the ``PANEL`` is associated with. If you want the
|
||||
panel to show up without a panel group, use the panel group "default".
|
||||
|
||||
``DEFAULT_PANEL``
|
||||
-----------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
If set, it will update the default panel of the ``PANEL_DASHBOARD``.
|
||||
|
||||
``ADD_PANEL``
|
||||
-------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
Python panel class of the ``PANEL`` to be added.
|
||||
|
||||
``REMOVE_PANEL``
|
||||
----------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
If set to ``True``, the PANEL will be removed from PANEL_DASHBOARD/PANEL_GROUP.
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
To add a new panel to the Admin panel group in Admin dashboard, create a file
|
||||
``openstack_dashboard/local/enabled/_60_admin_add_panel.py`` with the following
|
||||
content::
|
||||
|
||||
PANEL = 'plugin_panel'
|
||||
PANEL_DASHBOARD = 'admin'
|
||||
PANEL_GROUP = 'admin'
|
||||
ADD_PANEL = 'test_panels.plugin_panel.panel.PluginPanel'
|
||||
|
||||
To remove Info panel from Admin panel group in Admin dashboard locally, create
|
||||
a file ``openstack_dashboard/local/enabled/_70_admin_remove_panel.py`` with
|
||||
the following content::
|
||||
|
||||
PANEL = 'info'
|
||||
PANEL_DASHBOARD = 'admin'
|
||||
PANEL_GROUP = 'admin'
|
||||
REMOVE_PANEL = True
|
||||
|
||||
To change the default panel of Admin dashboard to Instances panel, create a file
|
||||
``openstack_dashboard/local/enabled/_80_admin_default_panel.py`` with the
|
||||
following content::
|
||||
|
||||
PANEL = 'instances'
|
||||
PANEL_DASHBOARD = 'admin'
|
||||
PANEL_GROUP = 'admin'
|
||||
DEFAULT_PANEL = 'instances'
|
||||
|
||||
Pluggable Settings for Panel Groups
|
||||
===================================
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
|
||||
The following keys are specific to registering a panel group:
|
||||
|
||||
``PANEL_GROUP``
|
||||
---------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the panel group to be added to ``HORIZON_CONFIG``. Required.
|
||||
|
||||
``PANEL_GROUP_NAME``
|
||||
--------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The display name of the PANEL_GROUP. Required.
|
||||
|
||||
``PANEL_GROUP_DASHBOARD``
|
||||
-------------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the dashboard the ``PANEL_GROUP`` associated with. Required.
|
||||
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
To add a new panel group to the Admin dashboard, create a file
|
||||
``openstack_dashboard/local/enabled/_90_admin_add_panel_group.py`` with the
|
||||
following content::
|
||||
|
||||
PANEL_GROUP = 'plugin_panel_group'
|
||||
PANEL_GROUP_NAME = 'Plugin Panel Group'
|
||||
PANEL_GROUP_DASHBOARD = 'admin'
|
||||
@ -1,8 +1,8 @@
|
||||
.. _install-settings:
|
||||
|
||||
==========================
|
||||
Settings and Configuration
|
||||
==========================
|
||||
=======================
|
||||
Configuration Reference
|
||||
=======================
|
||||
|
||||
Introduction
|
||||
============
|
||||
@ -44,6 +44,10 @@ behavior of your Horizon installation. All of them are contained in the
|
||||
``dashboards``
|
||||
--------------
|
||||
|
||||
.. versionadded:: 2012.1(Essex)
|
||||
|
||||
Default: ``None``
|
||||
|
||||
.. warning::
|
||||
|
||||
In OpenStack Dashboard configuration, we suggest **NOT** to use this
|
||||
@ -56,10 +60,6 @@ behavior of your Horizon installation. All of them are contained in the
|
||||
Specifying the order in two places may cause confusion.
|
||||
Please use this parameter only when the pluggable config is not used.
|
||||
|
||||
.. versionadded:: 2012.1(Essex)
|
||||
|
||||
Default: ``None``
|
||||
|
||||
Horizon Dashboards are automatically discovered in the following way:
|
||||
|
||||
* By adding a configuration file to the ``openstack_dashboard/local/enabled``
|
||||
@ -90,6 +90,10 @@ is included in the ``INSTALLED_APPS`` list and on the Python path.
|
||||
``default_dashboard``
|
||||
---------------------
|
||||
|
||||
.. versionadded:: 2012.1(Essex)
|
||||
|
||||
Default: ``None``
|
||||
|
||||
.. warning::
|
||||
|
||||
In OpenStack Dashboard configuration, we suggest **NOT** to use this
|
||||
@ -103,10 +107,6 @@ is included in the ``INSTALLED_APPS`` list and on the Python path.
|
||||
Specifying the default dashboard in two places may cause confusion.
|
||||
Please use this parameter only when the pluggable config is not used.
|
||||
|
||||
.. versionadded:: 2012.1(Essex)
|
||||
|
||||
Default: ``None``
|
||||
|
||||
The slug of the dashboard which should act as the first-run/fallback dashboard
|
||||
whenever a user logs in or is otherwise redirected to an ambiguous location.
|
||||
|
||||
@ -287,7 +287,7 @@ Default: ``[]``
|
||||
A list of javascript spec files to include for integration with the Jasmine spec runner.
|
||||
Jasmine is a behavior-driven development framework for testing JavaScript code.
|
||||
|
||||
OpenStack Settings (Partial)
|
||||
OpenStack Dashboard Settings
|
||||
============================
|
||||
|
||||
The following settings inform the OpenStack Dashboard of information about the
|
||||
@ -1977,282 +1977,3 @@ help protect the session cookies from cross-site scripting.
|
||||
A list of Django applications to be prepended to the ``INSTALLED_APPS``
|
||||
setting. Allows extending the list of installed applications without having
|
||||
to override it completely.
|
||||
|
||||
|
||||
.. _pluggable-settings-label:
|
||||
|
||||
Pluggable Settings
|
||||
==================
|
||||
Horizon allows dashboards, panels and panel groups to be added without
|
||||
modifying the default settings. Pluggable settings are a mechanism to allow
|
||||
settings to be stored in separate files. Those files are read at startup and
|
||||
used to modify the default settings.
|
||||
|
||||
The default location for the dashboard configuration files is
|
||||
``openstack_dashboard/enabled``, with another directory,
|
||||
``openstack_dashboard/local/enabled`` for local overrides. Both sets of files
|
||||
will be loaded, but the settings in ``openstack_dashboard/local/enabled`` will
|
||||
overwrite the default ones. The settings are applied in alphabetical order of
|
||||
the filenames. If the same dashboard has configuration files in ``enabled`` and
|
||||
``local/enabled``, the local name will be used. Note, that since names of
|
||||
python modules can't start with a digit, the files are usually named with a
|
||||
leading underscore and a number, so that you can control their order easily.
|
||||
|
||||
Before we describe the specific use cases, the following keys can be used in
|
||||
any pluggable settings file:
|
||||
|
||||
``ADD_EXCEPTIONS``
|
||||
------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
A dictionary of exception classes to be added to ``HORIZON['exceptions']``.
|
||||
|
||||
``ADD_INSTALLED_APPS``
|
||||
----------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
A list of applications to be prepended to ``INSTALLED_APPS``.
|
||||
This is needed to expose static files from a plugin.
|
||||
|
||||
``ADD_ANGULAR_MODULES``
|
||||
-----------------------
|
||||
|
||||
.. versionadded:: 2014.2(Juno)
|
||||
|
||||
A list of AngularJS modules to be loaded when Angular bootstraps. These modules
|
||||
are added as dependencies on the root Horizon application ``horizon``.
|
||||
|
||||
``ADD_JS_FILES``
|
||||
----------------
|
||||
|
||||
.. versionadded:: 2014.2(Juno)
|
||||
|
||||
A list of javascript source files to be included in the compressed set of files that are
|
||||
loaded on every page. This is needed for AngularJS modules that are referenced in
|
||||
``ADD_ANGULAR_MODULES`` and therefore need to be included in every page.
|
||||
|
||||
``ADD_JS_SPEC_FILES``
|
||||
---------------------
|
||||
|
||||
.. versionadded:: 2015.1(Kilo)
|
||||
|
||||
A list of javascript spec files to include for integration with the Jasmine spec runner.
|
||||
Jasmine is a behavior-driven development framework for testing JavaScript code.
|
||||
|
||||
``ADD_SCSS_FILES``
|
||||
------------------
|
||||
|
||||
.. versionadded:: 8.0.0(Liberty)
|
||||
|
||||
A list of scss files to be included in the compressed set of files that are
|
||||
loaded on every page. We recommend one scss file per dashboard, use @import if
|
||||
you need to include additional scss files for panels.
|
||||
|
||||
.. _auto_discover_static_files:
|
||||
|
||||
``AUTO_DISCOVER_STATIC_FILES``
|
||||
------------------------------
|
||||
|
||||
.. versionadded:: 8.0.0(Liberty)
|
||||
|
||||
If set to ``True``, JavaScript files and static angular html template files will be
|
||||
automatically discovered from the `static` folder in each apps listed in ADD_INSTALLED_APPS.
|
||||
|
||||
JavaScript source files will be ordered based on naming convention: files with extension
|
||||
`.module.js` listed first, followed by other JavaScript source files.
|
||||
|
||||
JavaScript files for testing will also be ordered based on naming convention: files with extension
|
||||
`.mock.js` listed first, followed by files with extension `.spec.js`.
|
||||
|
||||
If ADD_JS_FILES and/or ADD_JS_SPEC_FILES are also specified, files manually listed there will be
|
||||
appended to the auto-discovered files.
|
||||
|
||||
``DISABLED``
|
||||
------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
If set to ``True``, this settings file will not be added to the settings.
|
||||
|
||||
``UPDATE_HORIZON_CONFIG``
|
||||
-------------------------
|
||||
|
||||
.. versionadded:: 2014.2(Juno)
|
||||
|
||||
A dictionary of values that will replace the values in ``HORIZON_CONFIG``.
|
||||
|
||||
|
||||
Pluggable Settings for Dashboards
|
||||
=================================
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The following keys are specific to registering a dashboard:
|
||||
|
||||
|
||||
``DASHBOARD``
|
||||
-------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the dashboard to be added to ``HORIZON['dashboards']``. Required.
|
||||
|
||||
``DEFAULT``
|
||||
-----------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
If set to ``True``, this dashboard will be set as the default dashboard.
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
To disable a dashboard locally, create a file
|
||||
``openstack_dashboard/local/enabled/_40_dashboard-name.py`` with the following
|
||||
content::
|
||||
|
||||
DASHBOARD = '<dashboard-name>'
|
||||
DISABLED = True
|
||||
|
||||
To add a Tuskar-UI (Infrastructure) dashboard, you have to install it, and then
|
||||
create a file ``openstack_dashboard/local/enabled/_50_tuskar.py`` with::
|
||||
|
||||
from tuskar_ui import exceptions
|
||||
|
||||
DASHBOARD = 'infrastructure'
|
||||
ADD_INSTALLED_APPS = [
|
||||
'tuskar_ui.infrastructure',
|
||||
]
|
||||
ADD_EXCEPTIONS = {
|
||||
'recoverable': exceptions.RECOVERABLE,
|
||||
'not_found': exceptions.NOT_FOUND,
|
||||
'unauthorized': exceptions.UNAUTHORIZED,
|
||||
}
|
||||
|
||||
|
||||
Pluggable Settings for Panels
|
||||
=============================
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The following keys are specific to registering or removing a panel:
|
||||
|
||||
``PANEL``
|
||||
---------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the panel to be added to ``HORIZON_CONFIG``. Required.
|
||||
|
||||
``PANEL_DASHBOARD``
|
||||
-------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the dashboard the ``PANEL`` associated with. Required.
|
||||
|
||||
|
||||
``PANEL_GROUP``
|
||||
---------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the panel group the ``PANEL`` is associated with. If you want the
|
||||
panel to show up without a panel group, use the panel group "default".
|
||||
|
||||
``DEFAULT_PANEL``
|
||||
-----------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
If set, it will update the default panel of the ``PANEL_DASHBOARD``.
|
||||
|
||||
``ADD_PANEL``
|
||||
-------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
Python panel class of the ``PANEL`` to be added.
|
||||
|
||||
``REMOVE_PANEL``
|
||||
----------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
If set to ``True``, the PANEL will be removed from PANEL_DASHBOARD/PANEL_GROUP.
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
To add a new panel to the Admin panel group in Admin dashboard, create a file
|
||||
``openstack_dashboard/local/enabled/_60_admin_add_panel.py`` with the following
|
||||
content::
|
||||
|
||||
PANEL = 'plugin_panel'
|
||||
PANEL_DASHBOARD = 'admin'
|
||||
PANEL_GROUP = 'admin'
|
||||
ADD_PANEL = 'test_panels.plugin_panel.panel.PluginPanel'
|
||||
|
||||
To remove Info panel from Admin panel group in Admin dashboard locally, create
|
||||
a file ``openstack_dashboard/local/enabled/_70_admin_remove_panel.py`` with
|
||||
the following content::
|
||||
|
||||
PANEL = 'info'
|
||||
PANEL_DASHBOARD = 'admin'
|
||||
PANEL_GROUP = 'admin'
|
||||
REMOVE_PANEL = True
|
||||
|
||||
To change the default panel of Admin dashboard to Instances panel, create a file
|
||||
``openstack_dashboard/local/enabled/_80_admin_default_panel.py`` with the
|
||||
following content::
|
||||
|
||||
PANEL = 'instances'
|
||||
PANEL_DASHBOARD = 'admin'
|
||||
PANEL_GROUP = 'admin'
|
||||
DEFAULT_PANEL = 'instances'
|
||||
|
||||
Pluggable Settings for Panel Groups
|
||||
===================================
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
|
||||
The following keys are specific to registering a panel group:
|
||||
|
||||
``PANEL_GROUP``
|
||||
---------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the panel group to be added to ``HORIZON_CONFIG``. Required.
|
||||
|
||||
``PANEL_GROUP_NAME``
|
||||
--------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The display name of the PANEL_GROUP. Required.
|
||||
|
||||
``PANEL_GROUP_DASHBOARD``
|
||||
-------------------------
|
||||
|
||||
.. versionadded:: 2014.1(Icehouse)
|
||||
|
||||
The slug of the dashboard the ``PANEL_GROUP`` associated with. Required.
|
||||
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
To add a new panel group to the Admin dashboard, create a file
|
||||
``openstack_dashboard/local/enabled/_90_admin_add_panel_group.py`` with the
|
||||
following content::
|
||||
|
||||
PANEL_GROUP = 'plugin_panel_group'
|
||||
PANEL_GROUP_NAME = 'Plugin Panel Group'
|
||||
PANEL_GROUP_DASHBOARD = 'admin'
|
||||
179
doc/source/configuration/themes.rst
Normal file
179
doc/source/configuration/themes.rst
Normal file
@ -0,0 +1,179 @@
|
||||
======
|
||||
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";
|
||||
|
||||
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.
|
||||
@ -39,6 +39,7 @@ How to use Horizon in your own projects.
|
||||
:maxdepth: 2
|
||||
|
||||
install/index
|
||||
configuration/index
|
||||
User Documentation <user/index>
|
||||
admin/index
|
||||
|
||||
|
||||
@ -1,6 +1,6 @@
|
||||
==========================
|
||||
Deployment & Configuration
|
||||
==========================
|
||||
==================
|
||||
Installation Guide
|
||||
==================
|
||||
|
||||
This section describes how to install and configure the dashboard
|
||||
on the controller node.
|
||||
@ -34,6 +34,14 @@ Installing from Source
|
||||
:maxdepth: 1
|
||||
|
||||
from-source.rst
|
||||
settings.rst
|
||||
customizing.rst
|
||||
|
||||
Horizon plugins
|
||||
===============
|
||||
|
||||
There are a number of horizon plugins for various useful features. You can get
|
||||
dashboard supports for them by installing corresponding horizon plugins.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
plugin-registry.rst
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user