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:

./create.sh <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.

/THEME_ID/ *
    /css/
      base.css
      custom.css
      main.css
      navigation.css
      forms.css
      portlet.css
      deprecated.css
      tabs.css
      layout.css
    /images/
      (many directories)
    /javascript/
      javascript.js
    /templates/
      dock.vm
      navigation.vm
      portal_normal.vm
      portal_popup.vm
      portlet.vm
 /WEB-INF
 /META-INF
* (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.

Properties#

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 liferay-plugin-package.properties 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.

Finished!#

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

Advanced#

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#

• Plugins SDK
• Theme variations using CSS
• Themes (WAP)
• How To Change Liferay Default Theme
• Create Liferay Themes for 6.0.x
• Upgrade 5.2.x Themes to 6.0.x