Merge "Add dev docs for SCSS/and styling in Horizon"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
826c3ee39a
|
|
@ -82,6 +82,7 @@ the following topic guides.
|
|||
topics/table_actions
|
||||
topics/angularjs
|
||||
topics/javascript_testing
|
||||
topics/styling
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
|
|
|||
|
|
@ -404,6 +404,7 @@ This example sorts flavors by vcpus in descending order::
|
|||
'reverse': True,
|
||||
}
|
||||
|
||||
.. _custom_theme_path:
|
||||
|
||||
``CUSTOM_THEME_PATH``
|
||||
---------------------
|
||||
|
|
@ -1319,6 +1320,8 @@ IP address, that should be added. The setting may contain more than one entry.
|
|||
For more information see:
|
||||
https://docs.djangoproject.com/en/dev/ref/settings/#allowed-hosts
|
||||
|
||||
.. _debug_setting:
|
||||
|
||||
``DEBUG`` and ``TEMPLATE_DEBUG``
|
||||
--------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,124 @@
|
|||
=========================
|
||||
Styling in Horizon (SCSS)
|
||||
=========================
|
||||
|
||||
Horizon uses `SCSS`_ (not to be confused with Sass) to style its HTML. This
|
||||
guide is targeted at developers adding code to upstream Horizon. For
|
||||
information on creating your own branding/theming, see :doc:`customizing`.
|
||||
|
||||
.. _SCSS: http://sass-lang.com/guide
|
||||
|
||||
Code Layout
|
||||
===========
|
||||
|
||||
The base SCSS can be found at ``openstack_dashboard/static/dashboard/scss/``.
|
||||
This directory should **only** contain the minimal styling for functionality;
|
||||
code that isn't configurable by themes. ``horizon.scss`` is a top level file
|
||||
that imports from the ``components/`` directory, as well as other base styling
|
||||
files; potentially some basic page layout rules that Horizon relies on to
|
||||
function.
|
||||
|
||||
.. Note::
|
||||
Currently, a great deal of theming is also kept in the ``horizon.scss`` file
|
||||
in this directory, but that will be reduced as we proceed with the new code
|
||||
design.
|
||||
|
||||
Horizon's ``default`` theme stylesheets can be found at
|
||||
``openstack_dashboard/themes/default/``.
|
||||
|
||||
::
|
||||
|
||||
├── _styles.scss
|
||||
├── _variables.scss
|
||||
├── bootstrap/
|
||||
└── ...
|
||||
└── horizon/
|
||||
└── ...
|
||||
|
||||
The top level ``_styles.scss`` and ``_variables.scss`` contain imports from
|
||||
the ``bootstrap`` and ``horizon`` directories.
|
||||
|
||||
The "bootstrap" directory
|
||||
-------------------------
|
||||
|
||||
This directory contains overrides and customization of Bootstrap variables, and
|
||||
markup used by Bootstrap components. This should **only** override existing
|
||||
Bootstrap content. For examples of these components, see the
|
||||
`Theme Preview Page`_.
|
||||
|
||||
::
|
||||
|
||||
bootstrap/
|
||||
├── _styles.scss
|
||||
├── _variables.scss
|
||||
└── components/
|
||||
├── _component_0.scss
|
||||
├── _component_1.scss
|
||||
└── ...
|
||||
|
||||
- ``_styles.scss`` imports the SCSS defined for each component.
|
||||
- ``_variables.scss`` contains the definitions for every Bootstrap variable.
|
||||
These variables can be altered to affect the look and feel of Horizon's
|
||||
default theme.
|
||||
- The ``components`` directory contains overrides for Bootstrap components,
|
||||
such as tables or navbars.
|
||||
|
||||
The "horizon" directory
|
||||
-----------------------
|
||||
|
||||
This directory contains SCSS that is absolutely specific to Horizon; code here
|
||||
should **not** override existing Bootstrap content, such as variables and rules.
|
||||
|
||||
::
|
||||
|
||||
horizon/
|
||||
├── _styles.scss
|
||||
├── _variables.scss
|
||||
└── components/
|
||||
├── _component_0.scss
|
||||
├── _component_1.scss
|
||||
└── ...
|
||||
|
||||
- ``_styles.scss`` imports the SCSS defined for each component. It may also
|
||||
contain some minor styling overrides.
|
||||
- ``_variables.scss`` contains variable definitions that are specific to the
|
||||
horizon theme. This should **not** override any bootstrap variables, only
|
||||
define new ones. You can however, inherit bootstrap variables for reuse
|
||||
(and are encouraged to do so where possible).
|
||||
- The ``components`` directory contains styling for each individual component
|
||||
defined by Horizon, such as the sidebar or pie charts.
|
||||
|
||||
Adding new SCSS
|
||||
===============
|
||||
|
||||
To keep Horizon easily themable, there are several code design guidelines that
|
||||
should be adhered to:
|
||||
|
||||
- Reuse Bootstrap variables where possible. This allows themes to influence
|
||||
styling by simply overriding a few existing variables, instead of rewriting
|
||||
large chunks of the SCSS files.
|
||||
- If you are unable to use existing variables - such as for very specific
|
||||
functionality - keep the new rules as specific as possible to your component
|
||||
so they do not cause issues in unexpected places.
|
||||
- Check if existing components suit your use case. There may be existing
|
||||
components defined by Bootstrap or Horizon that can be reused, rather than
|
||||
writing new ones.
|
||||
|
||||
Theme Preview Page
|
||||
==================
|
||||
|
||||
When the :ref:`DEBUG <debug_setting>` setting is set to ``True``, the Developer
|
||||
dashboard will be present in Horizon's side nav. The Bootstrap Theme Preview
|
||||
panel contains examples of all stock Bootstrap markup with the currently
|
||||
applied theme, as well as source code for replicating them; click the ``</>``
|
||||
symbol when hovering over a component.
|
||||
|
||||
Alternate Theme
|
||||
===============
|
||||
|
||||
A second theme is provided by default at
|
||||
``openstack_dashboard/themes/material/``. When adding new SCSS to horizon, you
|
||||
should check that it does not interfere with the Material theme. Images of how
|
||||
the Material theme should look can be found at https://bootswatch.com/paper/.
|
||||
To set up this theme, see the :ref:`custom_theme_path` entry in our settings
|
||||
documentation.
|
||||
Loading…
Reference in New Issue