Liferay is a Gartner Magic Quadrant Leader for the Sixth Year! Find out why
« Back to Themes

Themes v4.3-v5.2.x

Introduction #

Themes customize the overall look and feel of Liferay. They since version 4.3 are written using the plugins SDK and the templating language Velocity.

Deploying a Theme#

There are two methods to deploying a theme in Liferay. First you can download a prepackaged theme from the Software Catalogue Portlet or you can deploy a theme from a packaged WAR you have downloaded.

Deploying from the Software Catalogue#

To do so place the Software Catalogue Portlet on a page. You can find the Software Catalogue by going to the Dock and selecting the Add Application from the drop down menu. When the list of applications load, you'll find Software Catalogue in the Admin section.

Alternatively, if you are running Liferay 5.2.0 you can also access the Software Catalogue in the Control Panel. Both options will require you to have the proper permissions to be able to install a theme.

From the Software Catalogue Portlet you can search or browse for a new theme.

Deploying a Packaged Theme WAR#

To deploy a packed theme WAR you'll need access to the directory that Liferay listens to for auto deployment (by default this directory is the user folder). Simply copying the theme WAR file in this directory will deploy your theme.

Developing a Theme#

Installing the Plugins SDK#

As of Liferay 5.1, themes are built on top of default "styled" and "unstyled" themes.

To build a theme start by downloading and unzipping the Liferay Plugins SDK. Also see the Liferay Plugins Development Guide to set up your plugins environment.

Create a build.{username}.properties file in your SDK directory replacing {username} with your systems username. Then, add this line to the code within the file:

  app.server.dir={path to your app server}

You are now ready to create you blank theme! From the command line, navigate to the plugins/themes directory and type:

For windows:

create <project name> "<theme title>"

For Linux/Mac:

./ <project name> "<theme title>"

Where <project name> is what your theme will be called within the file structure, and <theme title> is the text that will actually be displayed within the liferay portal in the Available Themes list. The second parameter must have quotes around it to allow spaces in the name of the theme.

Writing Your Theme#

Now that your new theme has been created, you're ready to modify the default styling.

Inside the newly created theme you'll find several directories, one of which is called _diffs (located in docroot). In here you can overwrite any of the files that would be automatically created for your theme. Below are some of the files that can be overwritten.

      (many directories)
* (the name/theme id of the theme, which is specified in WEB-INF/liferay-look-and-feel.xml)

At the very least you'll need to modify the custom.css file to change the way your theme looks. We highly recommend that all changes be made to custom.css since the other css files are used to provide structure to your theme. To do this, in the _diffs folder create the "css" folder and save "custom.css" into this directory.

Likewise, for any javascript functionality creating the javascript.js file will also get included in your theme.

Browser/OS Consistency#

As a theme developer you'll notice the inconsistency of how your theme is rendered in multiple browsers (and even operating systems). If you find that you need to make a browser, or OS specific modification, these CSS class selectors are available to use:

Selecting different browsers would be like so:

  .ie h1{}
  .gecko h1{}
  .safari h1{}
  .ie6 h1{}
  .ie7 h1{}
  .konqueror h1{}

To feed rules to different operating systems you would do

  .win h1 {}
  .linux h1{}
  .mac h1{}

You can also feed rules to users who have javascript on like so:

  .js h1{}

You can also combine any of these rules by “chaining” the css selectors, like so:

  .firefox.mac h1 {} 
  .js.firefox h1{}

And you can do this with the different color schemes like this:

  .safari.js .blue h1{}

Velocity Templates#

Velocity templates control the different HTML of the portal using Apache Velocity Templates. We recommend that you view their docs to see how they are written.

  • portal_normal.vm - This file controls the basic skeleton HTML of the page Liferay will serve.
  • dock.vm - This provides the drop down dock on the page.
  • init_custom.vm - This file allows you to override and define new velocity variables.
  • navigation.vm - This file is called by portal_normal.vm and provides the HTML to make the navigation bar.
  • portal_pop_up.vm - This file handles the pop up notification for Liferay.
  • portlet.vm - This file wraps the content of very portlet.

With the combination of HTML and Velocity you can restructure how the HTML is served.


You probably have already noticed that there is another directory besides the _diffs folder in your theme. The WEB-INF could hold many important configuration files but we'll be looking at one important properties file.

You'll notice that the create script automatically created a file. Opening it with your favorite text editor will allow you to edit such information as the license, author, etc. You'll notice that some of the information has been auto populated.

The first thing you'll want to do is replace your name with for "Liferay, Inc." on the author field.

Change as many values as you'd like and save this file.


You should now have completed your first theme. To deploy your theme type,

ant deploy

from the command line in your theme folder. This will deploy your theme for you and all your users to enjoy.

Note: it is much easier to develop your theme if you first deploy the blank template and modify the files in the webapps folder of your Liferay installation and copy them back into the _diffs folder. If you choose to take this approach be sure to turn caching off for Liferay on your development machine. See Liferay Developer Mode for more information.

Quality Control#

These are the steps to ensure that your theme will look good in some of the less visable areas of Liferay Portal.

Presentation and Legibility#

Thankfully, Liferay portal has been designed so that majority of the themed elements share properties, making the styling process very quick. That being said, there are certain portlets that are good to check on while you are theming to get a sampling of the whole.

  • Calendar Portlet - theming the tabs and dates of the summary, month, and week tabs
  • Page Comments Portlet - theming the heading and odd and even fields
  • Currency Converter - theming the table
  • Document Library - theming the iframe that is used for the classic uploader

Also if you choose light colored text or dark backgrounds in your theme you will want to check these portlets/elements:

  • Add Application module
  • Layout Template module
  • Quick Note Portlet
  • Sign In Portlet when signed out
  • Success and failure messages
  • Dock controls


Color Schemes#

See Theme variations using CSS for instructions on how to create a color scheme.

Theme Conventions#

CSS Conventions#

Here are CSS formatting conventions that will make sure your code is consistent, and easily readable:

  • Outside of selector bodies:
    • Group selectors under the common element that they style using comment tags
    • Keep global selectors towards the top, and more specific selectors towards the bottom
    • Keep only 1 endline between all selectors and comments
  • Inside selector bodies:
    • Insert 1 space between selector name and opening "{"
    • For using multiple selectors for the same body of declarations, separate selectors with "," and 1 endline
    • All declarations are indented by one tab
    • Keep all declarations in alphabetical order within the declaration body
    • For each declaration, be sure to put 1 space between the property and the value, after the ":"
    • Colors should only be specified by using their hexidecimal value.
    • Use all caps for hexidecimal values, and condense to 3 digits whenever possible
    • For the "background" property, make sure there is no space between "url" and opening "("
    • No quotes are required when using url() or for font names, unless using fonts that aren't browser-safe
    • Insert spaces after commas between font names
    • When using urls, always use a relative address instead of absolute
    • Condense all padding,margin, and border values whenever possible, leaving out measurement units on "0" values (i.e. px, pt, em, % etc)
    • Comments are only used to head and divide each section of the code appropriately. Comments without any content below it are not necessary.
    • Use shorthand properties where applicable.

Filename Conventions#

  • Use Conventional names when saving image files
  • Use underscores only in file names - no dashes

Related Articles#

Children Pages

0 Attachments
Average (1 Vote)
The average rating is 1.0 stars out of 5.
Threaded Replies Author Date
Should line #set ($change_language_url =... Igor Beslic December 15, 2008 5:12 PM
This should be good in 5.1.x: #set... Igor Beslic December 15, 2008 6:09 PM
Just a quick question. is it possible to create... Ziggy © January 8, 2009 1:16 PM
Hi, i am facing one problem while creating the... Bala raju G February 19, 2009 6:31 AM
This is a great. But how can we 'rebuild' and... Harry Ostreicker March 11, 2009 9:36 AM
Hy harry im not shure about your question and... Florian B. Jaton March 20, 2009 3:59 AM
Quick Tip: A great way to experiment with... Chris Stavros July 13, 2009 1:49 AM
Unfortunately the automatic files listed under... Bob Lyman August 31, 2009 2:11 PM
Bob, I also see this on 5.2.3, I am surprised... Ries Twisk September 27, 2009 8:24 AM
I got it to work by copying stuff from a other... Ries Twisk September 27, 2009 9:00 AM
Have a look at this threas to get it running ... Massimiliano Assante March 4, 2010 6:55 AM
This still doesn't address how to create a new... John Croft March 10, 2010 11:33 AM
I am quite new to liferay. I created a theme as... Bijay Mahato February 7, 2011 5:07 AM
its sorted out..uncommented the paths for... Bijay Mahato February 7, 2011 11:28 PM
Hey there, we are workinging on a project... Timo Bo June 2, 2011 7:15 AM

Should line #set ($change_language_url = $portletURLFactory.create($request, "82", $page.getPlid(), true))
look like
#set ($change_language_url = $portletURLFactory.create($request, "82", $page.getPlid(), "true"))?
In 5.1.x upper example is not valid because create method has signature portletURLFactory.create(HttpServletRequest request, String portletName, long plid, String lifecycle)
Posted on 12/15/08 5:12 PM.
This should be good in 5.1.x:
#set ($language_url = $portletURLFactory.create($request, "82", $page.getPlid(), "ACTION_PHASE"))
Posted on 12/15/08 6:09 PM.
Just a quick question. is it possible to create a theme using tiles/jsp? If so could someone please point me to a tutorial or guide for Tiles themes.

Posted on 1/8/09 1:16 PM in reply to Igor Beslic.

i am facing one problem while creating the url,
i have given the code as

#set ($feedback_url = $portletURLFactory.create($request, "admin_user", $page.getPlid(), "ACTION_PHASE"))
here "admin_user" is my portlet id

this perticular method is creating the url as


based on the url generated it is observed that it is generating the url based on the current page, observe the url generated (/frontoffice/home, frontoffice/messages)
here home and messages are two diff pages

i want the url to be independent of current page and it sholud be based on one page only

can any one please provide me in this regard, so that it can be helpful for me

Posted on 2/19/09 6:31 AM in reply to ziggy R Omar.
This is a great. But how can we 'rebuild' and deploy an existing theme once we've downloaded and modified it? -harry
Posted on 3/11/09 9:36 AM.
Hy harry

im not shure about your question and my answer:

If you modify the files in the webapp folder of your running liferay to see your changes in realtime just copy them after finished changing ito your "_diff" folder of your theme in the sdk(where you build it first time)

When you Deploy your theme out of the sdk ("ant deploy"), the theme specific files will be replaced by standard-files (of the base-theme) but if there are som files in the _diff Folder, it will build the new files based on yours (out of the _diff folder)

i hope it helps and give you any new english is quite bad and its dificult to explain...SORRY ;-)
Posted on 3/20/09 3:59 AM in reply to Harry Ostreicker.
Quick Tip:

A great way to experiment with theme styles is to drop a hidden Web Content Display portlet on the page and use a <style></style> tag to experiment. This can be very useful to override styles that trump inline changes made under the "Look & Feel" section for a Community or Page. Its also great for experimenting with minor tweaks to an existing theme. Once you figure out what sorts of edits you want to make permanent you can stuff them in the correct CSS location and build your custom theme.

1. Add a Web Content Display portlet to the page you want to experiment with
2. Create a new content block by clicking on the Add Web Content icon
-be sure to click the "source" button in the WYSIWYG editor to inject your CSS properly
3. Place your CSS between the tags:
4. Save the block.
5. In the portlet controls, click on the "Look and Feel" link and uncheck "Show Borders", Save, and reload the page

Now you can make changes to that block and override pretty much any style call. Works great!

Stavie the Portal Guy
Looking for a Lifray hosting provider? Check us out!: - 877-411-2220
Posted on 7/13/09 1:49 AM.
Unfortunately the automatic files listed under "Writing your theme" are not created using 5.2.3

I've tried copying the files from the Classic theme in the source, but alas I can't seem to get anything to work. None of the styles are applied with my theme and so I revert back to the Classic theme.

Also the file has none of the required .xml files for WEB-INF.
Posted on 8/31/09 2:11 PM.

I also see this on 5.2.3, I am surprised that nobody responded to you on that.

So what's next? Sit back and relax, or is there a way to get this running??

Posted on 9/27/09 8:24 AM in reply to Bob Lyman.
I got it to work by copying stuff from a other template....

Posted on 9/27/09 9:00 AM in reply to Ries Twisk.
Have a look at this threas to get it running­e/3318043
Posted on 3/4/10 6:55 AM in reply to Ries Twisk.
This still doesn't address how to create a new theme for the control panel. There has to be some setting that allows a custom theme to appear in the list of control panel themes in Control Panel > Portal > Settings > Display Settings > Look And Feel > Default Control Panel Theme. Setting in ROOT/WEB-INF/classes/ doesn't seem to do anything.
Posted on 3/10/10 11:33 AM.
I am quite new to liferay. I created a theme as described above and it successfully created my theme under the themes inside the SDK folder.

But when I tried to deploy it using ant deploy initially gave the error of "lib/ext" folder not existing under the tomcat directory. Then I created those folders manually then triggered the ant deploy again and now its giving following error. Any suggestion pls..

java.lang.NoClassDefFoundError: com/liferay/portal/kernel/image/ImageBag
Caused by: java.lang.ClassNotFoundException: com.liferay.portal.kernel.image.ImageBag
at Method)
at java.lang.ClassLoader.loadClass(
at sun.misc.Launcher$AppClassLoader.loadClass(
at java.lang.ClassLoader.loadClass(
Could not find the main class: Program will exit.
Exception in thread "main"
Posted on 2/7/11 5:07 AM.
its sorted out..uncommented the paths for tomcat 5.5 in build.<<username>>.properties under SDK folder and it got all the jar files in the classpath. Previously i have uncommented the paths for tomcat 6 and thats why it was not getting the required jar files.
Posted on 2/7/11 11:28 PM in reply to Bijay Mahato.
Hey there,

we are workinging on a project evaluating liferay. And we as well want to evaluate the theme/style part of liferay.
I already tried to manipulate some .css files to change e.g. the navigation color of the 'classic theme' we use but it did not work.
So my questions is - how can I easily change the apperance of my portal and wich files have to be manipulated to e.g. change the color of the navigation bar or even more simple the background of the website.

Thanks for your help.
Posted on 6/2/11 7:15 AM in reply to Bijay Mahato.