Liferay & Velocity: Easy Theming for your portal

Nov 09, 2011
Diego Vergara

In the previous post I discussed some of the features that make Liferay an awesome portal. In this post I'm going to show you how easy is to create a custom theme for your personalized site. First you need to download the Liferay SDK and install it, remember that you need to have ant installed, JSE5 or higher.

Once you have installed you will see a structure like:

liferay sdk

In the root of the sdk, please create the file named build.username.properties where you will overwrite the properties needed to compile porlets and themes (you will also need to download the Liferay ext and if you need to customize your portal from the very ground download the Liferay source). The most important property you will overwrite is servlet container or application server location because once you deploy your theme, the sdk will use this info to get the auto-deploy dir and the required libraries.

To create a new theme use a console and go to the sdk directory, from there go into themes folder and type:
create.sh "Theme-Name" Theme-Name
If you're using Windows replace create.sh with create.bat

Once it is finished, to create the folder with your Theme-Name you must go inside docroot/_diffs - and there you can start to build you customized theme. So let's check the basic structure for a theme:

  • css: here you can create a custom.css file where you can overwrite the styles you need
  • images: place the images you want to override
  • templates: here's where the magic happens, the velocity templates are placed here, but remember place only those that you're overwriting

Before to continue, let's talk about a possible issue here: "How can I know the name of css files, images or even templates?" Well that's really easy, you can check the structure of your liferay installation in webapps/ROOT/html/themes/ and there choose the classic, _styled or _unstyled theme folder. I really prefer a different approach, which is to download a theme from Liferay.com (you can find a lot of plugins between portlets and themes). Once there, I usually search for a theme that looks something similar to the design I want to create.

liferay jedi theme

Ok, now that we're ready, let's start with the templates: Velocity is a template Engine and is a free Open Source project; Velocity permits you to use a simple yet powerful template language to reference objects defined in Java code. It is written in 100% pure Java and can be easily embedded into your own applications.

Ok you should start with portal_normal.vm where you can define the structure of your theme, and include some conditions based on certain criteria, for example:

#if ($show_sign_on)
#parse("$full_templates_path/guess.vm")
#else
#parse("$full_templates_path/authorizedUser.vm")
#end

Let's talk about those strange variables like $show_sign_on. Those variables are specific variables for Liferay portal as defined in the source code. So if you want to add more variables you should read the developers guide, but if you're comfortable with the predefined ones, here is a link that include the velocity variables for the portal. This link is for liferay 4.3, however there are no major modifications in variables and it's good for a quick review of the variables.

#if ($show_sign_on) returns true if you're not logged-in and the Sign-In icon is displayed

Sign-in icon

#parse("$full_templates_path/guess.vm") will include the content of guess.vm, so you should create a file called guess.vm inside the templates folder. Once that file is created you can include html content or more template definitions.

Once you've overwritten the styles, images and templates you must deploy the project so you can test it. Open a console and go to your Theme-Name folder, once there type: ant deploy

Once the deployment is finished you should wait a few seconds before it's ready to test on Liferay. So in the meanwhile, sign-on and go to the dock and select "Manage Pages": If you want to change the theme for only one page, select that page and click in the tab "Look and Feel", but if you want to change the theme for the entire location like "guest" or your "private location", select the parent page i.e., Guest and in the same portlet select "Look and Feel". You should see your theme, just select it and that's all.

manage pages portlet

If you want to predefine that theme for the entire portal or don't want to allow anyone to change that theme you should overwrite liferay.properties; for that please read the Administration Guide.

Basically you can create your new theme in short time (based on the criteria that you have your stylesheets, images and html prototype design ready). As an example here's a screenshot of the Oshyn Theme for Liferay. (I'd like to thank Carlos Araujo who help me with the stylesheets, images and html. You're a genius!)

oshyn-blue theme