Share Header Colour Customization

[ddraper]

Introduction

Alfresco Share has supported themes in general for some time, but it is more challenging to customize the colours used in the Share header bar. We've made some updates in the Aikau 1.0.18 release that now make this a much simpler process. You'll be able to take advantage of these in either Alfresco Community 5.0.d or Alfresco Enterprise 5.0.1 if you upgrade the default version of Aikau used, but will be available for use out-of-the-box in Alfresco Enterprise 5.0.2 and future Community releases. This blog post will explain how to create or update a Surf theme to customize the header colours, as well as providing some context on why it has taken so long to provide this capability and the ways in which it will further improve in the future.

A Bit of History...

The current widgets used for the Share header were created during the 4.2 release. At that time we were experimenting with ways in which we could improve theme handling but it wasn't until after the 4.2 release that we included dynamic LESS pre-processing into Surf page rendering.

Although there was an effort to generate some momentum in updating the Share themes it wasn't really a priority at the time and as a result the capabilities that were introduced weren't made use of in the 5.0 release.

It's only now that 5.0 is starting to get some focus in the field that we've started to see questions related to this particular type of customization. It has always been possible to change the header colours by modifying the CSS files directly or replacing them completely, but with the release of Aikau 1.0.18 we've gone back through the “alfresco/header” packaged widgets and updated the CSS files to make use of some new LESS variables.

LESS and Themes

Overriding the default LESS variables (which are defined in defaults.less in Aikau and included for every theme) is currently done by adding a particular element to the Surf Theme XML file. I appreciate that it's not ideal to be writing LESS in an XML file but there are historical reasons for this and in the future I hope to be able to change this so that the Theme XML file can reference one or more LESS files as required.

A Surf Theme is defined by an XML file that lives in the “themes” subfolder of the client’s Surf configuration folder, in Share this can be found in “share/WEB-INF/classes/alfresco/site-data/themes”. If you want to create a new theme for Share that supports the legacy YUI2 widgets you should also create a theme folder with a name that matches your Surf Theme name – if working with a standalone Aikau client (e.g. one created by the Aikau Maven Archetype) then this isn't necessary.

In the theme XML file include the following within the <theme> element:

<css-tokens>
  <less-variables>
  </less-variables>
</css-tokens>‍‍‍‍

Within the <less-variables> element you can place any valid LESS content (http://lesscss.org/features/). If we want to override the LESS variables for the header we can add the following content that results in an awesomely garish header:

@header-background-color: #0082c8;
@header-font-color: #ccc;
@header-hover-background-color: orange;
@header-hover-font-color: green;
@header-focus-background-color: yellow;
@header-focus-font-color: red;
@header-menubar-font-color: pink;
@header-dropdown-menu-font-color: purple;‍‍‍‍‍‍‍‍

Variable Breakdown

We've tried to make the LESS variables as semantically meaningful as possible, but in case it's not obvious I'll break down what each variable does.

• @header-background-color - This is the main background color for the header (e.g. in Share this is black)

• @header-font-color - This is the colour of fonts when menus are neither hovered or focused, in Share this is a light grey colour by default.

• @header-hover-background-color - This is used for the background colour of the header menu widgets when the mouse hovers over them. In Share this is a light grey colour.

• @header-hover-font-color - This is used as the colour of the header menu widgets when the mouse is hovered over them

• @header-focus-background-color - This is the background colour of the header menu widgets when they have focus, therefore it is also used as the background colour of drop-down menus (as they have focus when opened). In Share this is a darker grey colour by default.

• @header-focus-font-color - This is used as the font colour of focused header menu widgets. So it is used as the font colour of items in opened drop-down menus. In Share this is white by default

• @header-menubar-font-color - This is used as the font colour of menu bar items (e.g. not drop-down menu items). In Share this is the darker grey by default.

• @header-dropdown-menu-font-color - This is used as the font colour of drop-down menu items. In Share this is white by default.

  

If you look through the defaults.less file in Aikau you'll see that there are lots of other LESS variables that you can override. Although not all of the widget CSS files make use of these LESS variables we are going to endeavour to improve this over future releases. However, if there are any widgets in particular that you wish were easier to customize then please let us know – it's very difficult for us to support use cases that we don't know about, so please let us know by raising issues on GitHub or JIRA.

[blog_commenter]

[…] or CSS classes used within a widget for customizing its appearance (the correct approach is to create a theme file that overrides the necessary LESS variables). It also means that any automated tests cannot rely on CSS selectors continuing to work for all […]