« Back to Themes

Themes v6.0

Alternative Languages: 日本語

Introduction #

Themes customize the overall look and feel of Liferay. They are written using the plugins SDK and, since version 6.0, can be written using one of the templating languages, Freemarker or 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 or you can hot deploy a theme from a WAR.

Using the Software Catalogue#

You can also access the Software Catalogue in the Control Panel under "Plugins Installation". From there you can search or browse for a new theme.

Hot Deploying a 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 #

Prerequisites #

  • Plugins SDK for your Liferay version.
    • The plugins SDK is needed because it generates a framework. You don't need to use any fancy editors or install anything crazy though -- an SDK is simply a bunch of files and scripts that make your life easier. You can download the SDK from the Liferay main page, unzip it, set up the file called build.username.properties, and you're good to go. You simply need it to do the first step -- everything after that is what you already know: CSS in your editor of choice. Don't get scared because it's called an SDK!
  • Good understanding of CSS (you cannot edit the HTML -- only CSS can be modified to style Liferay)

Recommended Tools #

Writing your Theme #

  1. Navigate using command prompt or terminal to the $PLUGINS_SDK/themes folder. Run:
     create newtheme "My New Theme" 
    or, on Linux/Mac:
     ./create.sh newtheme "My New Theme"
  1. Navigate to the newly created $PLUGINS_SDK/themes/newtheme/_diffs and add some customizations to the default theme. The way to do this is to create a directory called 'css' in _diffs, then add/edit the file css/custom.css. Liferay doesn't allow you to directly modify the "base" CSS -- you can however hide elements at will using CSS (display:none;) and move them around to your liking. This follows the principle for separation of content and style.
  2. Issue 'ant all' in the $PLUGINS_SDK/themes/newtheme folder to build and deploy.
  3. Log in into Liferay and check out your new creation.

Your modifications to the theme should go into the css/custom.css file in the _diffs folder. All the changes you make in other css files will be overwritten when you deploy the theme again.

Side tip for non-noobs (power users): If you want your theme to be developed from an existing theme other than the classic plain theme, you can modify the file build.xml (inside the folder of the theme) and change the parent.theme attribute to the id of the theme you want it to be copied from (for example, classic) and then deploy again. Generally you just want to use the basic plain Liferay setup however, because it's pretty empty and you style everything yourself.

The theme's folder is set up like this:

/THEME_NAME/
    /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

Additional Notes #

  • Liferay's theming process is pretty unique: a pre-made theme, the "_unstyled" theme (default) is applied first when you create a new theme (when you do create newtheme "My New Theme"). In fact, try creating a theme but not adding any _diffs files -- you'll see that the site is still styled! That's because it's the "_unstyled" theme, which does give your site minimal structure. It looks very plain though. That's because it's ready for you to make your modifications.
  • On top of the classic theme's code, you add your own styles, images, dock customizations and et cetera by creating the above directory structure in your theme _diffs folder. If you don't want to overwrite a file (you like the classic/default way it looks), you don't have to. If you want to rewrite everything, you can do that too. Liferay is super flexible. Say you want to change something in the dock. Open up dock.vm from the classic theme, and make your modifications. Save it to your _diffs (take care that you put it in the right directory, e.g custom.css goes in yourtheme/_diffs/css/custom.css) and you should have a functional theme.

Dockbar #

A lot of questions are asked about the Dockbar. Starting in Liferay 6.0.x, the dock was moved to being a portlet instead of something directly in themes. What that means is that dock.vm no longer exists: instead, to edit dockbar requires that you create a hook or ext plugin that overrides the dockbar's JSP or whatever else you're seeking to change. It sounds involved, but it really isn't hard -- once you've created the new hook, you simply overwrite whatever you want on the JSP or other files.

Styling the dockbar is easy still too, since the CSS is all in dockbar.css.

Creating the links on the dockbar while removing the dockbar itself is a common request also. For more information on linking dockbar items, see Link to Dockbar

See Also #

0 Attachments
98630 Views
Average (3 Votes)
The average rating is 3.0 stars out of 5.
Comments
Threaded Replies Author Date
There is no dock.vm in liferay 6 themes. It has... Sandeep Nair July 30, 2010 5:16 AM
Hi Sandeep, Yes the dockbar is now a portlet.... Samuel Liu August 2, 2010 11:07 AM
Thanks Samuel. Sandeep Nair August 3, 2010 1:34 AM
I am trying to generate a custom theme, but am... Daniel Wilmes June 10, 2011 7:54 AM
One gotcha I found is that your theme folder... Laurie MacDougall Sookraj June 24, 2011 1:32 PM
This article mentions parent.theme, where in... Alexei Vidmich August 5, 2011 8:52 PM
if your theme needs to display i18n'ed strings,... JS Bournival March 30, 2012 1:23 PM

There is no dock.vm in liferay 6 themes. It has been replaced by dockbar.js(too difficult to understand) and view.jsp in dockbar portlet. What is the ideal way to modify dock now, previously it was very straight forward, just make the change in dock.vm. But now there is lots of thing to do, may be i have to do extension plugin build now to customize dock.
Posted on 7/30/10 5:16 AM.
Hi Sandeep,

Yes the dockbar is now a portlet. So to make changes to the dockbar, you need to use either ext environment or a hook (you have the right idea). However, style for the dockbar is still in the theme and can be edited in dockbar.css.

If you have more questions, don't hesitate to ask. Thanks for your patience emoticon

Warm regards,
Sam
Posted on 8/2/10 11:07 AM in reply to Sandeep Nair.
Thanks Samuel.
Posted on 8/3/10 1:34 AM in reply to Samuel Liu.
I am trying to generate a custom theme, but am having problems.

The changes in the _diff do not seem to show when I deploy the war file.

I am using netbeans 7 and run the ant script that is created in the IDE to generate the war file.

If anyone could help that would be great.

I have put my custom css, images, etc in the _diff file but get a directory structure like this in the war file:
├───css
├───images
│ ├───add_content
│ ├───application
│ ├───arrows
│ ├───aui
│ ├───blogs
│ ├───bookmarks
│ ├───calendar
│ ├───common
│ ├───control_panel
│ ├───custom
│ ├───diff
│ ├───dock
│ ├───dockbar
│ ├───document_library
│ ├───emoticons
│ ├───enterprise_admin
│ ├───file_system
│ │ ├───large
│ │ └───small
│ ├───forms
│ ├───image_gallery
│ ├───journal
│ ├───language
│ ├───mail
│ ├───messages
│ ├───message_boards
│ ├───navigation
│ ├───portlet
│ ├───progress_bar
│ ├───ratings
│ ├───shadow
│ ├───shopping
│ ├───social_bookmarks
│ ├───tays_image
│ ├───trees
│ └───wiki
├───js
├───META-INF
├───templates
├───WEB-INF
└───_diff
├───css
├───images
│ ├───img
│ ├───social
│ └───_image
├───js
└───templates
Posted on 6/10/11 7:54 AM in reply to Sandeep Nair.
One gotcha I found is that your theme folder under themes must be named <name>-theme or else it will be deployed as a web application instead of as a theme. Also the name of the theme in liferay-plugin-package.properties should end with -theme.

On successful deployment you should see "[ThemeHotDeployListener:89] 1 theme for <name>-theme is available for use" (instead of "[PortletHotDeployListener:369] 1 portlet for <theme_name> is available for use")
Posted on 6/24/11 1:32 PM in reply to Daniel Wilmes.
This article mentions parent.theme, where in reality the name of that Ant property is theme.parent.
Posted on 8/5/11 8:52 PM in reply to Laurie MacDougall Sookraj.
if your theme needs to display i18n'ed strings, where do you put those files exactly?
Posted on 3/30/12 1:23 PM in reply to Alexei Vidmich.