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:
parent
70946f629d
commit
7502d9c872
|
@ -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
|
Customizing Horizon
|
||||||
===================
|
===================
|
||||||
|
|
||||||
Themes
|
.. seealso::
|
||||||
======
|
|
||||||
|
|
||||||
As of the Kilo release, styling for the OpenStack Dashboard can be altered
|
You may also be interested in :doc:`themes` and :doc:`branding`.
|
||||||
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
|
|
||||||
|
|
||||||
Changing the Site Title
|
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
|
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.
|
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/
|
.. _Font Awesome: https://fortawesome.github.io/Font-Awesome/
|
|
@ -0,0 +1,12 @@
|
||||||
|
===================
|
||||||
|
Configuration Guide
|
||||||
|
===================
|
||||||
|
|
||||||
|
.. toctree::
|
||||||
|
:maxdepth: 1
|
||||||
|
|
||||||
|
settings
|
||||||
|
pluggable_panels
|
||||||
|
customizing
|
||||||
|
themes
|
||||||
|
branding
|
|
@ -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:
|
.. _install-settings:
|
||||||
|
|
||||||
==========================
|
=======================
|
||||||
Settings and Configuration
|
Configuration Reference
|
||||||
==========================
|
=======================
|
||||||
|
|
||||||
Introduction
|
Introduction
|
||||||
============
|
============
|
||||||
|
@ -44,6 +44,10 @@ behavior of your Horizon installation. All of them are contained in the
|
||||||
``dashboards``
|
``dashboards``
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
|
.. versionadded:: 2012.1(Essex)
|
||||||
|
|
||||||
|
Default: ``None``
|
||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
In OpenStack Dashboard configuration, we suggest **NOT** to use this
|
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.
|
Specifying the order in two places may cause confusion.
|
||||||
Please use this parameter only when the pluggable config is not used.
|
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:
|
Horizon Dashboards are automatically discovered in the following way:
|
||||||
|
|
||||||
* By adding a configuration file to the ``openstack_dashboard/local/enabled``
|
* 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``
|
``default_dashboard``
|
||||||
---------------------
|
---------------------
|
||||||
|
|
||||||
|
.. versionadded:: 2012.1(Essex)
|
||||||
|
|
||||||
|
Default: ``None``
|
||||||
|
|
||||||
.. warning::
|
.. warning::
|
||||||
|
|
||||||
In OpenStack Dashboard configuration, we suggest **NOT** to use this
|
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.
|
Specifying the default dashboard in two places may cause confusion.
|
||||||
Please use this parameter only when the pluggable config is not used.
|
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
|
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.
|
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.
|
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.
|
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
|
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``
|
A list of Django applications to be prepended to the ``INSTALLED_APPS``
|
||||||
setting. Allows extending the list of installed applications without having
|
setting. Allows extending the list of installed applications without having
|
||||||
to override it completely.
|
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'
|
|
|
@ -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
|
:maxdepth: 2
|
||||||
|
|
||||||
install/index
|
install/index
|
||||||
|
configuration/index
|
||||||
User Documentation <user/index>
|
User Documentation <user/index>
|
||||||
admin/index
|
admin/index
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
==========================
|
==================
|
||||||
Deployment & Configuration
|
Installation Guide
|
||||||
==========================
|
==================
|
||||||
|
|
||||||
This section describes how to install and configure the dashboard
|
This section describes how to install and configure the dashboard
|
||||||
on the controller node.
|
on the controller node.
|
||||||
|
@ -34,6 +34,14 @@ Installing from Source
|
||||||
:maxdepth: 1
|
:maxdepth: 1
|
||||||
|
|
||||||
from-source.rst
|
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
|
plugin-registry.rst
|
||||||
|
|
Loading…
Reference in New Issue