From 738cc3473545e929f8a86b2e3bc40d0d42f24d3c Mon Sep 17 00:00:00 2001 From: Rob Cresswell Date: Tue, 10 Nov 2015 15:04:05 +0000 Subject: [PATCH] Add dev docs for SCSS/and styling in Horizon This patch adds a topic guide explaining how developers should write and organise SCSS within Horizon. Change-Id: I4de2d1da73f6c7977a16fba9d09678923d7c443c Closes-Bug: 1514869 --- doc/source/index.rst | 1 + doc/source/topics/settings.rst | 3 + doc/source/topics/styling.rst | 124 +++++++++++++++++++++++++++++++++ 3 files changed, 128 insertions(+) mode change 100755 => 100644 doc/source/topics/settings.rst create mode 100644 doc/source/topics/styling.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index cc075c217..7bbede598 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -81,6 +81,7 @@ the following topic guides. topics/table_actions topics/angularjs topics/javascript_testing + topics/styling API Reference ------------- diff --git a/doc/source/topics/settings.rst b/doc/source/topics/settings.rst old mode 100755 new mode 100644 index 151569f4e..cd4b81b5f --- a/doc/source/topics/settings.rst +++ b/doc/source/topics/settings.rst @@ -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`` -------------------------------- diff --git a/doc/source/topics/styling.rst b/doc/source/topics/styling.rst new file mode 100644 index 000000000..335a856e9 --- /dev/null +++ b/doc/source/topics/styling.rst @@ -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 ` 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.