Changing the default Alfresco Share Theme

Alfresco Share is an open-source enterprise-class collaborative content management application based on the Alfresco content repository. 


Share was built using Alfresco's web development framework called Surf.  Surf is a flexible platform that allows quick and easy development and customization of web applications, like Share.  The framework evolved as Alfresco engineers needed a tool for quickly building content-rich applications.  Surf is Alfresco's second generation architecture for building web applications.   First generation Alfresco applications were based on a web client built using Java JSF, a technology significantly more difficult to develop with than Surf.  


From the beginning, Alfresco technology has been built up around the Java Spring framework.  Surf continues to use Spring.  In fact the developers of Spriong at SpringSource were so impressed with Surf that they agreed to cooperate jointly with Alfresco on a project under the Apache banner called the Spring Surf Extension.


"Alfresco and SpringSource share a common vision for providing more modular and productive web application development frameworks.  We welcome this contribution and are pleased to have Alfresco as an active member of the Spring community," said Rod Johnson, General Manager of the SpringSource Division of VMware and the creator of Spring.


Spring is all about the 'wiring' of interchangeable components.  Alfresco Surf/Share has adopted Spring application configurability and also introduced additional XML configuration files.  Most Surf customizations and changes start by making a change to an XML property file.


As a simple example of how this wiring plays out, I'll show here how the 'theme' or color scheme can be changed in Alfresco Share.  By default, which theme to use is defined in the file: share/WEB-INF/classes/alfresco/web-framework-config-application.xml.


Not too surprisingly, the default theme is called default.  If you look into that xml configuration file you will find code similar to the following: 



There are three out-of-the-box themes that ship with Share and the definitions for those themes can be found in the directories under the themes directory:

By changing the theme for the application, you can change the color schema for the application.  For example, shown on the top below is the standard default theme for Share, and below that you can see the greenTheme for Share.




                 The default Alfresco Share Blue Theme



                          The Alfresco Green Theme


A quick way to test out how well a new theme will look is to simply include the theme parameter at the end of the URL, as in:  http://localhost:8080/share/page/user/admin/dashboard?theme=default.  (Although this trick doesn't seem to be swapping out the new theme images; it only changes the theme css files.)


To change the theme globally so that it will be applied to every page, it is necessary to make changes to the file:  share/WEB-INF/classes/alfresco/web-framework-config-custom.xml.  If the file doesn't exist, you should create it in that directory.  Otherwise the existing file should be modified to include the following content:





As shown above, each theme is grouped into its own directory and contains a folder of images along with two CSS files, one for the login page (login.css), and another for all other pages in the application (presentation.css).  To create a new theme, just create a new directory under themes -- the easiest way to get started is to copy over the default theme and then start editing and replacing.


Often the first step in customizing the Share site is to change the logo.  With themes, swapping in a new logo is easy.  By looking into the images directory, we find that there are images called logo.png (the logo displayed on the login page) and app-logo.gif (the logo displayed in the upper left of all other application pages).  Making new files with identical file names and placed within your new theme area will override the default logos.


Next you should have a look at how to change the css files for your new theme.  The presentation.css file holds most of those definitions.  But looking at the presentation.css file can be a bit daunting.  It is about 800 lines of css, including a lot of hex color codes.  A good way to get a handle for what's going on in this file is to compare the presentation.css files between two out-of-the-box Alfresco themes.  For example, do a diff between the presentation.css file of the greenTheme with the default one.


For example, using a source diff tool (like the free SourceGear DiffMerge) you'll quickly see that there are  a lot of differences between the theme files, but things begin to make some sense.   You'll need to rename skin references in the file to use your new theme name -- something which occurs in more than 100 places in the file.  For example yui-skin-default will need to be renamed yui-skin-NewTheme.  Global replace will quickly help with that.  


Because the browser can be forced to reload the image and css files, the theme files can be modified and reloaded without having to stop and start the web server.


From there on it is possible to experiment with some of the colors.  It is also a good idea to investigate using a point and click tool like Firefox/Firebug to visually examine the css.  You'll find that about the last hundred lines of presentation.css is marked as "Theme background colors".  This is a good place to start making changes.  After changing colors there and also changing the dashlet-title-bg.png file, which is the image file used to produce a gradient color effect on the dashlet titlebars, you'll be pretty far along in transforming the skin of the application.


Creating a new theme is obviously tedious, but Alfresco has done a great job in separating out css from the markup, which at least makes the job possible.


Here are some screenshots of the Alfresco optional Green Theme:
http://www.slideshare.net/AlfrescoUE/visual-design-alfresco-green-theme-presentation.