Horizon Logo Documentation is out of date

Due to recent changes to faciliate logo and favicon overrides,
the documentation was out of date.

Also, it was noted that the theme path needed to get updated as
well because it was recently moved up a directory.

It was noted, while writing the documentation, that styles had
been placed in the 'default' theme that should be global.

Change-Id: I025514b8ff31863858a7941c2380dd8c6397772a
Closes-bug: #1485272
This commit is contained in:
Diana Whitten 2015-08-15 16:48:35 -07:00
parent e69a1c2868
commit a7ac8791d5
6 changed files with 78 additions and 36 deletions

View File

@ -12,36 +12,76 @@ and a ``_styles.scss`` file with additional styles to load after dashboard
styles have loaded.
To use a custom theme, set ``CUSTOM_THEME_PATH`` in ``local_settings.py`` to
the directory location for the theme (e.g., ``"static/themes/blue"``). The
the directory location for the theme (e.g., ``"themes/blue"``). The
path can either be relative to the ``openstack_dashboard`` directory or an
absolute path to an accessible location on the file system. The default
``CUSTOM_THEME_PATH`` is ``static/themes/default``.
``CUSTOM_THEME_PATH`` is ``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``.
Changing the Logo
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
-----------------
There are currently two places where the OpenStack logo is pulled in
through the stylesheets. The first is shown at the login screen and the other
on top of the menu bar. To override the logo place your logo in your themes
directory and set the image to use in ``_styles.scss``. For example::
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``.
#splash .login {
background-image: url(/static/themes/THEME/logo-splash.png);
}
The Templates Folder
--------------------
.topbar {
h1.brand a {
background-image: url(/static/themes/THEME/logo.png);
}
}
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.
``THEME`` should be replaced by the name of your theme directory.
The dimensions should be ``width: 216px, height: 35px`` for a drop in
replacement.
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 ``{CUSTOM_THEME_PATH}/templates/horizon/_sidebar.html``.
The Img Folder
--------------
If the static root of the theme folder contains an ``img`` directory,
then all images contained within ``dashboard/img`` can be overridden by
providing a file with the same name.
For a complete list of the images that can be overridden this way, see:
``openstack_dashboard/static/dashboard/img``
Customizing the Logo
--------------------
If you wish to customize the logo that is used on the splash screen or in the
top navigation bar, then you simply need to create an ``img`` directory under
your theme's static root directory and place your custom ``logo.png`` or
``logo-splash.png`` within it.
If you wish to override the ``logo.png`` using the previous method, and if the
image used is larger than the height of the top navbar, then the image will be
constrained to fit within the height of nav. You can customize the height of
the top navigation 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

View File

@ -393,6 +393,7 @@ This example sorts flavors by vcpus in descending order::
'reverse': True,
}
``CUSTOM_THEME_PATH``
---------------------
@ -400,21 +401,21 @@ This example sorts flavors by vcpus in descending order::
Default: ``"themes/default"``
This setting allows Horizon to use a custom theme. The theme folder
should contain one _variables.scss file and one _styles.scss file.
_variables.scss contains or must import all the bootstrap and horizon
specific variables which are used to style the GUI. Whereas _styles.scss
contains extra styling. For example themes, see:
/horizon/openstack_dashboard/themes/
This setting tells Horizon to use a directory as a custom theme.
If the static theme folder also contains a sub-folder 'templates', then
the path to that sub-folder will be prepended to TEMPLATE_DIRS tuple
to allow for theme specific template customizations.
By default, this directory will serve as the static root of the theme
and the entire contents of the directory will be served up at
``/static/custom``. If you wish to include content other than static
files in a theme directory, but do not wish that content to be served up,
then you can create a sub directory named ``static``. If the theme folder
contains a sub-directory with the name ``static``, then
``static/custom/static``` will be used as the root for the content
served at ``/static/custom``.
If the theme folder (or its static folder) contain an 'img' directory,
then all images contained within dashboard/img can be overridden by providing
a file with the same name. This makes it very easy to customize logo.png,
logo-splash.png and favicon.ico.
The static root of the theme folder must always contain a _variables.scss
file and a _styles.scss file. These must contain or import all the
bootstrap and horizon specific variables and styles which are used to style
the GUI. For example themes, see: /horizon/openstack_dashboard/themes/
``DEFAULT_THEME_PATH``

View File

@ -370,7 +370,7 @@ TIME_ZONE = "UTC"
# Change this patch to the appropriate static directory containing
# two files: _variables.scss and _styles.scss
#CUSTOM_THEME_PATH = 'static/themes/default'
#CUSTOM_THEME_PATH = 'themes/default'
LOGGING = {
'version': 1,

View File

@ -0,0 +1,4 @@
.navbar-brand img {
max-height: $navbar-height;
vertical-align: middle;
}

View File

@ -16,6 +16,7 @@
@import "splash";
@import "components/resource_browser";
@import "components/sidebar";
@import "components/navbar";
@import "components/inline_edit";
@import "components/charts";
@import "components/workflow";

View File

@ -15,10 +15,6 @@ $navbar-dropdown-arrow-offset: $padding-small-horizontal;
height: 100%;
vertical-align: middle;
}
img {
vertical-align: middle;
max-height: $navbar-height;
}
}
.navbar {