Creation of an Alfresco Share custom theme

The creation of an Alfresco’s custom theme for the end users (using Alfresco Share) is one of the first tasks to do to build an Enterprise Content Management. Like the most important activities for the Alfresco’s mainteinance, also that task is also well documented in the wiki to the link below:

http://wiki.alfresco.com/wiki/Alfresco_Share#Themes

With this post I collect the commands and activities in a todo list to let the creation of a custom theme, easier and faster. In fact, even if the wiki documentation is clear and complete, the time we spend the first time is too much for a very simple task.

Environment and versions

The described developments and tests have been done on Alfresco Community Edition v4.0.c but also on newer version until v4.2.c (the newest until today). The used operating system is Linux (CentOS v6.3, Ubuntu) but there are no particular reasons of problems about the solution also on Windows platforms.

Talking about methodology, everything is developed and tested in a specific development environment (using virtual machines, one for each developer) and only after deployed in pre-production and/or production environment.

As best practice teaches, is assumed that the user used for development is not root but a different user with enough authorizations on the Alfresco’s folders and files (in our case the standard ‘/opt/alfresco’). Starting from now we will call the installation folder as <alfresco>.

The strategy

As suggested from the wiki, the strategy of the creation of a custom theme is to copy the files and folders structure from an existing theme and modify it to customize the look&feel. Identifying the out-of-the-box theme more similar to the one you want to develop, will let the work easier and faster. In this example we assume to customize the theme starting from the greenTheme.

Creation of the custom theme

• cd <alfresco>/tomcat/webapps/share/themes/

Starting from now customTheme will be used to call the name of the theme in development.

• cp -R greenTheme customTheme
• cd <alfresco>/tomcat/webapps/share/WEB-INF/classes/alfresco/site-data/themes/
• cp default.xml customTheme.xml

Edit ‘customTheme.xml’ (gedit, nano, etc.) to put what is described below.

<?xml version='1.0' encoding='UTF-8'?>
<theme>
 <title>Custom Theme</title>
 <title-id>theme.customTheme</title-id>
</theme>

• cd <alfresco>/tomcat/webapps/share/themes/customTheme

Edit ‘presentation.css’ and ‘yui/assets/skin.css’ with gedit, nano or another textual editor able to execute a search&replace.

• Find&replace ‘.yui-skin-greenTheme’ with ‘.yui-skin-customTheme’ in both the css.
• Save and close.
• cd <alfresco>/tomcat/webapps/share/WEB-INF/classes/alfresco/messages

Edit ‘slingshot.properties’ (gedit, nano, etc.) to add what is described below. With this task the requested labels will be added to the administrator’s panel to describe the custom theme.

...
## Themes
theme.default=Default Blue Theme
theme.customTheme=Custom Theme
...

Edit ‘slingshot_it.properties’ (gedit, nano, etc.) to add what is described below. With this task the requested labels will be added to the administrator’s panel when the user’s browser is set with the italian language.

...
## Themes
theme.default=Tema blu di default
theme.customTheme=Tema Personalizzato
...

Talking about internalization of the Alfresco frontend regarding every supported language, it’s important to remember to modify every file called ‘slingshot_xx.properties’ (where ‘xx’ means the language encoding in I18N).

Now the creation of the customTheme starting from the greenTheme is completed with success. To activate the new theme in Alfresco we have to restart it using the commands described below.

• cd <alfresco>
• alfresco.sh stop
• alfresco.sh start

After Alfresco’s restart the user interface will not change and the same theme will be viewed from the users. To change it, access to Alfresco Share with a administrator user and set the custom theme explicitly as described in the picture below.

Fig.1 – Change the current theme on Alfresco Share

The current theme is the custom one with the same look&feel of the greenTheme. Now we have to make some changes to images and CSS to customize it completly. Remember that from now on, every customization to the new theme doesn’t need Alfresco to be restarted but it’s enough to refresh the page from the browser.

Here there are some of the most common customizations.

Customization of the logo in every page (image on the top, left)

This customization is the simpler because Alfresco Share allows it from the administration menu (the same of the Fig.1). It’s very important for the image to be:

• Format: png
• Dimension: 117px, 48px
• Background: not relevant, better if white or transparent.

Customization of the logo in the login form

To customize the login page have to work on the folder ‘<alfresco>/tomcat/webapps/share/themes/customTheme/images’. The image viewed in the login page is the one named ‘logo.png’. Replacing or modifying the image, everything will work! It’s very important for the image to be:

• Format: png
• Dimension: 200px, 58px
• Background: transparent

To see many other examples of the customization of the login page, read this post.

Colors customization

Starting from the greenTheme, the colors should be changed or adjusted. To do that, it’s mandatory to review the two CSS described below:

• <alfresco>/tomcat/webapps/share/themes/customTheme/presentation.css
• <alfresco>/tomcat/webapps/share/themes/customTheme/yui/assets/skin.css

The modification to do on the two CSS is to search and replace the colors codes with a preferred text editor (gedit, nano, etc.). Listed below are the colors codes of the greenTheme with the corresponding colors in the default theme. This example is a good starting point to customize your own theme in the way you prefer.

greenTheme	Default
#5FAC34	#6CA5CA
#92C15F	#D7E0E7
#00AE42	#6CA5CE
#D4F8C4	#DCEAF4
#008F22	#6CA5CE
#AED98D	#BBCAD5
#526A53	#515D6B
#C5C7C6	#C4C5C5
#F7FDF8	#F9FBFD
#DCEAF4	#F5FAFF
#E3EDE6	#E3EBEC
#E3FFE3	#000000
#F7FEF4	#F4FAFF

Colors apart you should change some images used as background of the panels:

• cd /opt/alfresco/tomcat/webapps/share/themes/customTheme
• cp ../default/images/dashlet-title-bg.png images/dashlet-title-bg.png
• cp ../default/images/title-button-bg.png images/title-button-bg.png

Deploy of the custom theme

Even if the customizations of Alfresco in an enterprise environment should follow a different life cycle (versioning control, ecc.), in this part of the post is described a very simple and “manual” way to save your theme and deploy it in a pre-production or production environment.

• cd <alfresco>
• tar zcvf customTheme.tgz tomcat/webapps/share/WEB-INF/classes/alfresco/messages/slingshot.properties tomcat/webapps/share/WEB-INF/classes/alfresco/messages/slingshot_it.properties tomcat/webapps/share/WEB-INF/classes/alfresco/site-data/themes/customTheme.xml tomcat/webapps/share/themes/customTheme

Now the ‘customTheme.tgz’ contains eveything is needed and could be deployed as described below:

• Copy ‘customTheme.tgz’ in <alfresco>.
• alfresco.sh stop
• tar zxvf customTheme.tgz
• alfresco.sh start

It will be enough to access to Alfresco Share with an administrator user and change the current theme to have everything well setted (see fig.1 for details about the interface).

Francesco Corti