Surf Support for LESS CSS Pre-Processing

[ddraper]

by Dave Draper

Introduction

At Summit 2013 I briefly mentioned that Surf provided support for simple CSS token substitution via the Surf Theme XML files. We've since integrated LESS for Java directly into Surf to allow dynamic LESS pre-processing to be performed. This capability is currently available in the Alfresco Community nightly builds and in the Alfresco Community SVN trunk. This isn't going to be a blog post on LESS... if you don't know what it is, or how to use it (and to be perfectly honest - I'm no expert myself!) then you can find plenty of information elsewhere on the internet... this post is simply going to explain how you can now make use of the LESS support that is available in Surf.

Surf Themes

Hopefully you're aware that Share provides a number of different themes out-of-the-box and that many Community members have created their own. If you look in the 'webapps/share/themes' folder of your installation you will find a number of sub-folders ('default', 'greenTheme', 'greyTheme', 'lightTheme', etc) all of which hold the CSS and associated image files for rendering that theme. In the 'webapps/share/WEB-INF/classes/alfresco/site-data/themes' you will find a number of XML files whose names correspond to those theme folders (e.g. 'default.xml', 'greenTheme.xml', etc. etc.). When a Share page is loaded it will load the 'presentation.css' file for the current theme which will customize the appearance of the page (mostly this just effects the colour scheme).

Basic CSS Tokenization

In the XML files now support the element '<css-tokens>' in which you can define any number of custom elements the value of which will be substituted into any CSS file containing a token matching that element. For example, if you current theme XML file contains:

<css-tokens>

  <theme-font-family-1>Open Sans Condensed,Arial,sans-serif</theme-font-family-1>

</css-tokens>

...and you have a CSS source file containing...

.alfresco-example-CssSelector {

  font-family: $theme-font-family-1;

}

...then the CSS file loaded by the browser would actually contain:

.alfresco-example-CssSelector {

  font-family: Open Sans Condensed,Arial,sans-serif;

}

LESS Pre-Processing

There is one special token that is reserved for LESS pre-processing - '<less-variables>'. The value of this element is injected into a CSS file and dynamically 'compiled' by LESS for Java when that CSS file is required (Surf caches the compiled CSS file so that this only occurs once for each file).



This means that if the theme XML file contains:

<css-tokens>

  <less-variables>

    @toolTipBorderColour: #e5e5e5;

  </less-variables>

</css-tokens>

...and the CSS source file contains:

.alfresco-example-CssSelector {

border: 1px solid @toolTipBorderColour;

}

...then the CSS file loaded by the browser would actually contain:

.alfresco-example-CssSelector {

  border: 1px solid #e5e5e5;

}

This is obviously a very simplistic example - you can actually do much, much more with LESS than simple substitution.

Summary

As well as the obvious benefits of being able to take advantage of CSS pre-processing we have implemented this so that our new AMD widget based approach for developing Share can be written in a modular way but still support externally defined themes.



At the time of writing we have not yet adapted all the new widgets that have been written to take advantage of the LESS pre-processing but are starting to make the transition so you will start to see code appearing in SVN soon.



We have yet to completely identify and define the LESS variables that will be defined by the themes but we will be sure to make the information available as and when we have them so that the community can update their own themes to ensure that the new widgets are rendered as they would wish.