Creating Liferay Themes

Themes are hot deployable plugins which can completely transform the look and feel of the portal. Theme creators can make themes to provide an interface that is unique to the site that the portal will serve. Themes make it possible to change the user interface so completely that it would be difficult or impossible to tell that the site is running on Liferay. Liferay provides a well organized, modular structure to its themes. This allows the theme developer to be able to quickly modify everything from the border around a portlet window to every object on the page, because all of the objects are easy to find. Additionally, theme developers do not have to customize every aspect of their themes: if the plugin SDK is used, themes become only a list of differences from the default theme. This allows themes to be smaller and less cluttered with extraneous data that already exists in the default theme (such as graphics for emoticons for the message boards portlet).

There is a themes folder inside the plugins SDK where all new themes reside. To create a new theme, you run the following command in this folder:

ant -Dtheme.name=<project name> -Dtheme.display.name="<theme title>" create

For example:

ant -Dtheme.name=newtheme -Dtheme.display.name="My New Theme" create

This command will create a blank theme in your themes folder.

Theme Concepts

Custom themes are based on differences between the custom code and the default Liferay theme, called Classic. You will notice that there is a _diffs folder inside of your custom theme folder. This is where you will place your theme code. You only need to customize the parts of your theme that will differ from what is already displayed in the Classic theme. To do this, you mirror the directory structure of the Classic theme inside of the _diffs folder, placing only the folders and files you need to customize there.

For example, to customize the Dock (a necessary component of all themes), you would copy just the dock.vm file from your Liferay installation (the Classic theme is in <Tomcat_Home>/webapps/ROOT/html/themes/classic) into your theme's _diffs/templates folder. You can then open this file and customize it to your liking. For example, you might want to change the welcome message to something else, like "Quick Links."

For custom styles, we recommend you create a css folder and place a single file there called custom.css. This is where you would put all of your new styles and all of your overrides to the default Liferay styles. It is best to do it this way because of the order in which the .css files are loaded. Custom.css is loaded last, and so anything inside this file will be guaranteed to override any styles that are in any of the other style sheets.

Anatomy of a Theme

The folders in themes are designed to be easy to navigate and understand. Currently, this is what the new directory structure looks like:

/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
/WEB-INF
/META-INF

You can copy any of these files from the default custom theme to your _diffs folder in order to customize that portion of the theme.

JavaScript

Liferay now includes the jQuery JavaScript library, and theme developers can include any plugins that jQuery supports. The $ variable, however, is not supported (for better compliance with different portlets). Inside of the javascript.js file, you will find three different function calls, like this:

jQuery(document).ready(
function() {
//Custom javascript goes here
}
);
Liferay.Portlet.ready(
function(portletId, jQueryObj) {
//Custom javascript goes here
}
);
jQuery(document).last(
function() {
//Custom javascript goes here
}
);

• jQuery(document).ready(fn);

When this gets passed a function (it can be a defined function, or an anonymous one like above), the function gets executed as soon as the HTML in the page has finished loading (minus any portlets loaded via ajax).

• Liferay.Portlet.ready(fn);

When this gets passed a function (it can be a defined function, or an anonymous one like above), the function gets executed after each portlet has loaded. The function that gets executed receives two variables, portletId and jQueryObj. portletId is the id of the current portlet that has loaded, and jQueryObj is the jQuery object of the current portlet element.

• jQuery(document).last(fn);

When this gets passed a function (it can be a defined function, or an anonymous one like above), the function gets executed after everything—including AJAX portlets—gets loaded onto the page.

Besides theme-wide JavaScript there is also support for page specific JavaScript. The Page Settings form provides three separate JavaScript pieces that you can insert anywhere in your theme. Use the following to include the code from these settings:

$layout.getTypeSettingsProperties().getProperty("javascript-1")
$layout.getTypeSettingsProperties().getProperty("javascript-2")
$layout.getTypeSettingsProperties().getProperty("javascript-3")

The content of the JavaScript settings fields are stored in the database as Java Properties. This means that each field can only have one line of text. For multi-line scripts, the newlines should be escaped using \, just as in a normal .properties file.

Settings

Each theme can define a set of settings to make it configurable.

The settings are defined in the liferay-look-and-feel.xml using the following syntax:

<settings>
<setting key="my-setting" value="my-value />
...
</settings>

These settings can be accessed in the theme templates using the following code:

$theme.getSetting("my-setting")

For example, say we need to create two themes that are exactly the same except for some changes in the header. One of the themes has more details while the other is smaller (and takes less screen real estate). Instead of creating two different themes, we are going to create only one and use a setting to choose which header we want.

While developing the theme we get to the header. In the portal_normal.vm template we write:

if ($theme.getSetting("header-type") == "detailed") {
#parse("$full_templates_path/header_detailed.vm")
} else {
#parse("$full_templates_path/header_brief.vm")
}

Then when we write the liferay-look-and-feel.xml, we write two different entries that refer to the

same theme but have a different value for the header-type setting:

<theme id="beauty1" name="Beauty 1">
<root-path>/html/themes/beauty</root-path>
<templates-path>${root-path}/templates</templates-path>
<images-path>${root-path}/images</images-path>
<template-extension>vm</template-extension>
<settings>
<setting key="header-type" value="detailed" />
</settings>
<color-scheme id="01" name="Blue">
<css-class>blue</css-class>
<color-scheme-images-path>
${images-path}/color_schemes/${css-class}
</color-scheme-images-path>
</color-scheme>
...
</theme>
<theme id="beauty2" name="Beauty 2">
<root-path>/html/themes/beauty</root-path>
<templates-path>${root-path}/templates</templates-path>
<images-path>${root-path}/images</images-path>
<template-extension>vm</template-extension>
<settings>
<setting key="header-type" value="brief" />
</settings>
<color-scheme id="01" name="Blue">
<css-class>blue</css-class>
<color-scheme-images-path>
${images-path}/color_schemes/${css-class}
</color-scheme-images-path>
</color-scheme>
...
</theme>

Color Schemes

Color schemes are specified using a CSS class name, with which you can not only change colors, ut also choose different background images, different border colors, and so on.

In your liferay-look-and-feel.xml (located in WEB-INF), you would specify the class names like so:

<theme id="my_theme" name="My Theme">
<root-path>/my_theme</root-path>
<templates-path>${root-path}/templates</templates-path>
<images-path>${root-path}/images</images-path>
<template-extension>vm</template-extension>
<color-scheme id="01" name="Blue">
<css-class>blue</css-class>
<color-scheme-images-path>
${images-path}/color_schemes/${cssclass}
</color-scheme-images-path>
</color-scheme>
<color-scheme id="02" name="Green">
<css-class>green</css-class>
</color-scheme>
</theme>

Inside of your css folder, create a folder called color_schemes. Inside of that folder, place a .css file for each of your color schemes. In the case above, we would could either have just one called green.css and let the default styling handle the first color scheme, or you could have both blue.css and green.css.

Now, inside of your custom.css, you would place the following lines:

@import url(color_schemes/blue.css);
@import url(color_schemes/green.css);

You can identify the styling for the CSS by using prefixes. In blue.css you would prefix all of your css styles like this:

.blue a {color: #06C;}
.blue h1 (border-bottom: 1px solid #06C}

And in green.css you would prefix all of your CSS styles like this:

.green a {color: #06C;}
.green h1 (border-bottom: 1px solid #06C}

Portal predefined settings

The portal defines some settings that allow the theme to determine certain behaviors. So far there are only two predefined settings but this number may grow in the future.

• portlet-setup-show-borders-default

If set to false, the portal will turn off borders by default for all the portlets. The default is true.

Example:

<settings>
<setting key="portlet-setup-show-borders-default" value="false" />
</settings>

This default behavior can be overridden for individual portlets using:

• liferay-portlet.xml

• Portlet CSS popup setting

• bullet-style-options

The value must be a comma separated list of valid bullet styles to be used. The default is an empty list. The navigation portlet will not show any option in the portlet configuration screen.

Example:

<settings>
<setting key="bullet-style-options" value="classic,cool,tablemenu" />
</settings>

The bullet styles referred to in the setting are defined in any of the CSS files of the theme following this pattern:

.nav-menu-style-{BULLET_STYLE_OPTION} {
... CSS selectors ...
}

Here is an example of the HTML code that you would need to style through the CSS code. In this case the bullet style option is cool:

<div class="nav-menu nav-menu-style-cool">
<h3><a href="/web/guest/community">Community</a></h3>
<ul class="layouts">
<li class=""><a class="" href="/web/guest/community/documentation">Documentation</a></li>
<li class=""><a class="" href="http://wiki.liferay.com" target="_blank"> Wiki</a></li>
<li class=""><a class="" href="/web/guest/community/forums"> Forums</a></li>
</ul>
</div>

Using your CSS skills and, if desired, some unobtrusive Javascript it's possible to implement anytype of menu.