From 7502d9c87282ac1c54c929a521cdafa6847dcaa4 Mon Sep 17 00:00:00 2001 From: Akihiro Motoki Date: Thu, 29 Jun 2017 19:10:38 +0900 Subject: [PATCH] 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 --- doc/source/configuration/branding.rst | 179 +++++++++ .../customizing.rst | 360 +----------------- doc/source/configuration/index.rst | 12 + doc/source/configuration/pluggable_panels.rst | 285 ++++++++++++++ .../{install => configuration}/settings.rst | 303 +-------------- doc/source/configuration/themes.rst | 179 +++++++++ doc/source/index.rst | 1 + doc/source/install/index.rst | 18 +- 8 files changed, 683 insertions(+), 654 deletions(-) create mode 100644 doc/source/configuration/branding.rst rename doc/source/{install => configuration}/customizing.rst (53%) create mode 100644 doc/source/configuration/index.rst create mode 100644 doc/source/configuration/pluggable_panels.rst rename doc/source/{install => configuration}/settings.rst (89%) create mode 100644 doc/source/configuration/themes.rst diff --git a/doc/source/configuration/branding.rst b/doc/source/configuration/branding.rst new file mode 100644 index 0000000000..c71b42ad80 --- /dev/null +++ b/doc/source/configuration/branding.rst @@ -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 diff --git a/doc/source/install/customizing.rst b/doc/source/configuration/customizing.rst similarity index 53% rename from doc/source/install/customizing.rst rename to doc/source/configuration/customizing.rst index 1c1fef07a4..c15b101e30 100644 --- a/doc/source/install/customizing.rst +++ b/doc/source/configuration/customizing.rst @@ -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 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/ diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst new file mode 100644 index 0000000000..2db0321e6d --- /dev/null +++ b/doc/source/configuration/index.rst @@ -0,0 +1,12 @@ +=================== +Configuration Guide +=================== + +.. toctree:: + :maxdepth: 1 + + settings + pluggable_panels + customizing + themes + branding diff --git a/doc/source/configuration/pluggable_panels.rst b/doc/source/configuration/pluggable_panels.rst new file mode 100644 index 0000000000..90c88b1d48 --- /dev/null +++ b/doc/source/configuration/pluggable_panels.rst @@ -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 = '' + 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' diff --git a/doc/source/install/settings.rst b/doc/source/configuration/settings.rst similarity index 89% rename from doc/source/install/settings.rst rename to doc/source/configuration/settings.rst index d6cf8b5f9c..50e455c6e8 100644 --- a/doc/source/install/settings.rst +++ b/doc/source/configuration/settings.rst @@ -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 = '' - 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' diff --git a/doc/source/configuration/themes.rst b/doc/source/configuration/themes.rst new file mode 100644 index 0000000000..2ea0606ca7 --- /dev/null +++ b/doc/source/configuration/themes.rst @@ -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. diff --git a/doc/source/index.rst b/doc/source/index.rst index 384145ee91..f6fb0a88bd 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -39,6 +39,7 @@ How to use Horizon in your own projects. :maxdepth: 2 install/index + configuration/index User Documentation admin/index diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst index 3e07d00470..2e4c4b9448 100644 --- a/doc/source/install/index.rst +++ b/doc/source/install/index.rst @@ -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