This section describe how to create new themes for WireCloud.
This documentation is based in WireCloud 0.8.2. Previous versions of WireCloud works in a similiar way, but some details may differ.
Basic themes¶
If you do not require a full customised theme, you can create a new theme by changing some of the values (colours, default sizes, etc.) used by another theme.
NOTE: Currently you can only customise in this way the default theme, although support for parameterizing other themes is work in progress. For now you can copy the theme folder and make the changes as described in this section.
For doing that you have to create a new folder with the following structure:
mytheme +-- __init__.py +-- static +-- css +-- _variables.scss
The __init__.py
file is required by the plugin architecture used by WireCloud
and should be an empty file (although you know what you do :-). See the next
section for more details). The _variables.scss
file is the one that is going
to allow us to change the values used by the theme.
For example, you can use this _variables.scss
example file for changing the
primary color used by the primary buttons, the highlighted menu items, ... and
to use plain buttons:
$brand-primary: rgb(107, 21, 161); /* This color can also be defined using its hex code or its hsl definition: $brand-primary: #6B15A1; $brand-primary: hsl(277, 77%, 36%); */ $button-gradients: false; @import 'defaults';
The _variables.scss
file must be written using the SCSS (Sassy CSS) syntax
and is used for defining the base constants to be used by the theme. This file
must always import the _defaults.scss
file (using the @import 'defaults'
line) to load the default values for the other constants.
Using your themes¶
There are two options for using your themes:
-
If you don't want to distribute or share it with other WireCloud instances you can simply drop the theme folder inside your WireCloud instance folder. Then you can configure your WireCloud instance for using your them by editing the
settings.py
file and modifying theTHEME_ACTIVE
setting.For example, if you created the
mytheme
folder, you can move it into the folder of your WireCloud instance and useTHEME_ACTIVE = 'mytheme'
in thesettings.py
file. -
You can package and distribute your theme using the standard tools used in python for that purpose, e.g. using setuptools for building your packages and pypi for distributing your theme.
Once installed the theme package into the system, virtual env, ... used by the WireCloud instance, you will be able to use it through the
THEME_ACTIVE
setting as usual.Take into account that in this case you should provide a good module name for yout theme to avoid any clash with other python modules.
Full theme structure and background details¶
Themes in WireCloud are Django applications as well as python modules (that is
the reason for the __init__.py
file). The theme folder is splited in several
folders, each of them containing the different resources used by the theme
(templates, images, SCSS files, etc). The folder structure of a WireCloud theme
should be similar to the following one:
mytheme +-- __init__.py +-- static | | ... | +-- css | +-- fonts | +-- images +-- templates | ... +-- 400.html +-- 401.html +-- 403.html +-- 404.html +-- 500.html +-- wirecloud | ... +-- workspace +-- views
-
static
: Contains the static files provided by the theme. This is served using the Django's staticfiles app. Usually, this folder is composed of the following subfolders:css
: Contains the SCSS files used by the theme. As stated previously, WireCloud uses the SCSS (Sassy CSS) syntax for the stylesheets. WireCoud also include Compass v0.12.1 so you can make use of it if needed.fonts
: Fonts used by the SCSS filesimages
: Images used by the SCSS files or directly from the Django templates
-
templates
: This folder contains the Django templates used by the theme. Take into account that using this folder, themes can also override templates provided by the third party Django apps used by WireCloud (e.g. the Django's admin app). There are also other generic templates that can be overrided using this folder (e.g.404.html
,500.html
, ...)-
wirecloud
: This folder contains the templates used directly by WireCloud. In general those templates are snippets for each of the components/pieces used inside WireCloud. For example, thewirecloud/workspace/iwidget.html
template is used for creating the HTML of the widgets as shown in the workspace area.The exception are the templates provided in the
views
folder that pretends to provide the templates for the master HTML documents used by WireCloud.
-
Note: Take into account that the SCSS syntax is compatible with the standard CSS syntax. You do not have to use the SCSS features if you do not want to do it (except for the
_variables.scss
file).
When developing a WireCloud theme you have to take into account two things:
-
You can add any file you want into the
static
folder, but WireCloud will use a predefined list of SCSS files. If you add a SCSS file not used by WireCloud it just will be ignored by default. If you want to add a SCSS file to the ones used by WireCloud you will have to modify the Django template for the master HTML pages.Something similar applies to the Django templates: the list of the used templates is defined by WireCloud, by the third party applications used by it and by the enabled WireCloud plugins.
-
You do not have to write a complete version of every SCSS and template files used by WireCloud. If the corresponding file does not exits, the default version of the file will be used (taken from
wirecloud.defaulttheme
).
The list of the used SCSS files and django templates is provided in the next sections.
Available templates¶
workspace/iwidget.html
: HTML structure for the boxes where the widget iframes are inserted on the workspaces.ui/window_menu.html
: HTML structure for the dialogs/modals displayed in WireCloud.views/embedded.html
: HTML structure for the embedded version of WireCloud.
Available SCSS files¶
_variables.scss
: File defining the values of the constants used in the other SCSS files.workspace/dragboard_cursor.scss
: contains the style for the cursor displayed when moving widgets inside a workspace.workspace/iwidget.scss
: contains the style for displaying widgets inside the dashboard.window_menu.scss
: contains the style for the dialogs used in WireCloud.mac_field.scss
: contains the style for the mashable application component input fields.
Default theme: wirecloud.defaulttheme
¶
Used images¶
favicon.ico
: Image inimage/x-icon
format to use as favicon. Only used when the theme is configured as the main theme.logos/header.png
: Image inimage/png
used in the header.
Available SCSS constants¶
Base colours:
$brand-default
: Colour used by default when WireCloud does not need to associate a concrete status to an element$brand-primary
: Colour used as base for primary actions$brand-success
: Colour used for denoting success$brand-info
: Colour used for informative elements$brand-warning
: Colour used for warning elements and alerting the user it might need attention$brand-danger
: Colour used for alerting the user that something danger or potentially negative may happen
Misc constants:
button-gradients
:true
for styling buttons using gradients,false
for plain buttons.