Creating Liferay Themes
Themes are hot deployable plugins unique to a site served by the portal. With themes, you can alter the user interface so completely that it’s difficult or impossible to tell that the site is running on Liferay.
Liferay provides a well organized, modular structure to its themes. Themes follow the same philosophy as Liferay configuration: they are modifications, or differences from the default. Because of this, every line of markup and every style has a default value that your theme can fall back on if you have chosen not to customize it. In other words, your theme inherits the styling, images, and templates from any of the built-in themes. This saves you time and keeps your themes smaller and less cluttered, because your theme contains only its own resources, using defaults for the rest, like emoticon graphics for the message boards portlet.
Liferay themes are easy to create. You can start by making changes only in the CSS files. When you need to customize themes more extensively, you can change the HTML.
If you hope to become a theme customization guru, there are several technologies you should know:
- CSS: Create a new theme simply by modifying a CSS file.
- Velocity: Customize the markup generated by the theme.
- XML: Some theme settings are specified in XML.
To follow the examples in this guide, you should be familiar with the command line or the Liferay IDE.
Let’s create a theme!
Creating a Theme Project
The theme creation process is nearly identical to the portlet creation process that we covered in Developing Apps with Liferay IDE. Our theme will be named Deep Blue, so the project name (without spaces) is deep-blue, and the display name (which can have spaces) is Deep Blue. Let’s create the theme using Liferay Developer Studio first, and then with the terminal.
Using Developer Studio:
Go to File → New → Liferay Project.
Fill in deep-blue for the Project name and Deep Blue for the Display name.
Select the Liferay Plugins SDK and Portal Runtime you’ve configured.
Select Theme for your Plugin type.
Select a theme parent. Your theme inherits the parent theme’s styling as a base from which to build your theme. In addition to the _styled theme, you can choose to inherit from the _unstyled theme, which contains no styling. There’s also the classic theme that has a smooth look and feel and works well. For now, select _styled as the theme parent.
Select your theme’s framework. You can select the Freemarker or Velocity template frameworks for your theme. Or you can select JSP as your theme’s framework.
Figure 11.1: Make sure to select the Theme plugin type for your theme.
With Developer Studio, you can create a new plugin project, or if you already have a project, create a new plugin in an existing project. A single Liferay project can contain multiple plugins.
Using the terminal: Navigate to the
themes directory in the Plugins SDK and enter the appropriate command for your operating system:
In Linux and Mac OS X, enter
./create.sh deep-blue "Deep Blue"
In Windows, enter
create.bat deep-blue "Deep Blue"
Now there’s a blank theme in your
themes folder, which the Plugins SDK automatically named by appending “-theme” to your project name. Right now your theme is empty. Your next step is to set a base theme that serves as the default for your theme.
Setting a Base Theme
All themes in Liferay are built on top of two base themes, named _unstyled and _styled. Your newly created theme is based on these by default, but they contain very limited styling. You can take advantage of an existing theme’s styling by setting the theme of your choice as the base for your theme.
Base themes are added in layers. First _unstyled is added, giving you the core of the theme, then _styled, providing the most basic elements. When you set a different base theme, it’s added on top of _styled and overrides the default styling wherever there are differences. After the base themes are added, your own custom styling is added on top.
By default, themes are based on the _styled theme, which provides only basic styling of portlets. If you open the
build.xml file in your theme’s directory, you see the following code:
<project name="deep-blue-theme" basedir="." default="deploy">
<import file="../build-common-theme.xml" />
<property name="theme.parent" value="_styled" />
theme.parent property determines the theme your theme inherits its styling from. In addition to the _styled theme, you can choose to inherit from the _unstyled theme, which contains no styling. This makes more work for you, but offers full flexibility to design your CSS files from scratch.
You can also use the default Liferay theme Classic as a parent theme. You’ll start with a look and feel that’s already smooth and works well. But since so much is already done for you, there’s less flexibility when building your design. It’s a compromise between creating a theme as quickly as possible versus having full control of the result. It’s your choice, and another example of the flexibility Liferay offers.
To specify a base theme, edit the
build.xml file for your theme and change _styled in
<property name="theme.parent" value="_styled> to the name of any existing theme that’s installed or in your Plugins SDK.
Now that your base theme is set, let’s deploy the theme to your portal instance.
Deploying the Theme
If you’re already familiar with portlet deployment from reading Developing Apps with Liferay IDE, theme deployment will be a piece of cake! You can deploy your theme in Developer Studio or the terminal.
Deploying in Developer Studio: Click and drag your theme project onto your server.
Figure 11.2: Drag and drop your theme onto the server.
Upon deploying, your server outputs messages indicating your plugin is read, registered, and available for use.
Reading plugin package for deep-blue-theme
Registering themes for deep-blue-theme
1 theme for deep-blue-theme is available for use
Deploying in the terminal: Open a terminal window in your
themes/deep-blue-theme directory and enter
A BUILD SUCCESSFUL message indicates your theme is now being deployed. If you switch to the terminal window running Liferay, within a few seconds you will see the message
1 theme for deep-blue-theme is available for use.
Let’s apply your theme to a page:
Go to your web browser and log in to the portal.
Click the Edit button from the left side menu.
Click the Look and Feel tab, select Deep Blue beneath the Available Themes heading, and click Save.
Now that you’ve built and deployed a theme, let’s study theme anatomy.
Anatomy of a Theme Project
Custom themes are created by layering your customizations on top of one of Liferay’s built-in themes.
The structure of a theme separates different types of resources into easily accessible folders. Here’s the full structure of our Deep Blue theme:
_diffs/ (subfolders not created by default)
_diffs folder that’s created inside the
docroot directory of your theme is important; this is where you place your theme’s code. The
_diffs folder must mirror the parent theme’s directory structure. Since you’ll only customize the parts of your theme that differ from the parent theme, place only the folders and files you’ll customize there.
The other folders inside
docroot were copied over from the parent theme in your Liferay bundle when you deployed your theme. Use these files as the basis for your modifications. For example, to customize the navigation, copy
deep-blue-theme/docroot/templates/navigation.vm into the
deep-blue-theme/docroot/_diffs/templates folder (you may have to create this folder first). You can then open this file and customize it to your liking.
For custom styles, create a folder named
css inside your
_diffs folder and place a single file there called
custom.css. This is where you’ll define all your new styles. Because
custom.css is loaded last, styles defined here override any styles in the parent theme.
It’s a best practice to add your styles only to the
custom.css file. This keeps all of your changes in one place and makes future upgrades easier, because you won’t have to manually modify your templates to add support for new Liferay features.
Whenever you modify your theme in Developer Studio, redeploy it by right-clicking your theme (located underneath your server), then selecting Redeploy from the menu.
Figure 11.3: Redeploying your theme in Developer Studio is the same as entering the
ant deploy command for an already deployed plugin.
Alternatively, redeploy your theme by opening a terminal, navigating to
themes/deep-blue-theme and entering the command
Wait a few seconds until the theme deploys, then refresh your browser to see your changes.
Would you rather see your changes immediately, rather than having to redeploy to make your changes visible? Let’s talk about Liferay Developer Mode to learn how.