horizon/doc/source/contributor/topics/styling.rst

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 install-customizing.

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 Panel.

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 Panel

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.

To enable the Developer dashboard with the Theme Preview panel:

1. Set DEBUG <debug_setting> setting to True.
2. Copy _9001_developer.py and _9010_preview.py from openstack_dashboard/contrib/developer/enabled/ to openstack_dashboard/local/enabled/.
3. Restart the web server.

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/3/paper/. This theme is now configured to run as the alternate theme within Horizon.