50 Shades of Liferay (E-book)

About Book

About Book

This book is recommended for Java-developers, which want to start development with Liferay, and also for web-developers and portal administrators.

Required Skills:

Although those skills are not required, they’re desirable. The mentioned below tools will be used in book as examples.

  • Java (Core, EE)
  • Database - MySQL
  • Application server - Apache Tomcat
  • Build tools - Ant/Maven
  • Frontend (HTML/CSS/JS)
  • IDE - Intellij IDEA
  • OS - Windows7/Ubuntu

Online Reading



50 Shades of Liferay

Part 1 - Liferay Introduction


Author Vitaliy Koshelenko Copyright © 2015

About Book

This book is recommended for Java-developers, which want to start development with Liferay, and also for web-developers and portal administrators.

Required skills:
  • Java (Core, EE)
  • Database - MySQL
  • Application server - Apache Tomcat
  • Build tools - Ant/Maven
  • Frontend (HTML/CSS/JS)
  • IDE - Intellij IDEA
  • OS - Windows7/Ubuntu

Although those skills are not required, they’re desirable. The mentioned above tools will be used in book as examples.


First chapter of book explains how to download, install and configure Liferay. It also explains how to configure development environment in Intellij IDEA IDE.

Main concepts of Liferay portal are covered in the second chapter. This is theoretical chapter, explaining how Liferay works without deeping inside development process. But this information is required to know before you start development with Liferay.

Chapters 3-6 are practical ones, they have instructions how to create your first portlet, theme, layout and hook.

Chapters 7-9 are dedicated to themes development.



My name is Vitaliy Koshelenko, I’m a Liferay developer at AimProSoft company.

I have been working with Liferay for almost 5 years already, including portlets development, hooks, themes, layouts development, Liferay customization, migration from previous versions and integration with external services.

When I started working with Liferay, it seemed quite difficult and incomprehensible for me. Even small tasks took too much time, especially those ones, which required modifications in Liferay’s internal code. Most of time was spend for searching required information - due to lack of Liferay-specific knowledge and experience in Liferay development. Although there is official Liferay documentation (https://dev.liferay.com) as well as specifications of portlet technology (https://jcp.org/en/jsr/detail?id=286), it’s quite hard to find what you need. In most cases you just become drown inside endless Liferay forum threads, Wiki pages, tutorials instead of finding the solution you need.

There is no either good practical guide for beginners with step-by-step instructions for creation first portlet, theme, etc., or theoretical tutorial explaining in a few words how Liferay actually works.

So, I decided to write this book to help new developers quickly understand main concepts of Liferay structure, see how it works with simple examples and begin development with Liferay. I’ll try to make it easy and understandable, but at the same time practical and useful.

Hope, my efforts will not be wasted, and this book will help you in understanding Liferay.

It is my contact info:

Skype: vitaliy.koshelenko

E-mail: v.koshelenko@aimprosoft.com

Profile at Liferay community: https://www.liferay.com/web/vet.kosh/profile

Profile at Liferay JIRA: https://issues.liferay.com/secure/ViewProfile.jspa?name=v.koshelenko

You may contact me, if you have some questions, suggestions, recommendations.


Nothing better in the world,
Than implementing Liferay code...

Why '50 shades'?

Because when you start Liferay development, it seems perversion and masochism for you, but once you get used to it, things become better.

Why Liferay?

Before you start development of new site, you ask yourself - which tool to use for this? You can either create new site from scratch, or use some ready solutions (CMS).

If you create site from scratch, you spend time for implementing things, which have already been actually implemented: authentication, roles/permissions mechanism, content management, etc. They are already integrated into existing CMS, tested and are being successfully used by many companies. In this case, you “re-invent a bicycle” yourself.

If you’re using CMS, you have less freedom and you’re forced to use some conventions that are being used there, but at the same you have a lot of built-in functionality, which you may use in your project.

Personally I prefer 2nd way, especially for large systems development. But making choice which CMS to use should be also responsible, and project requirements should be taken into account.

After analyzing some existing CMS on Java (Liferay Portal, Magnolia, OpenCMS, Apache Lenya), we decided, that Liferay is the best option for enterprise portal development.

It provides developers the following features:

  • authentication (with ability to configure LDAP/Facebook sign-in, etc.)
  • content aggregation (web-page is generated from separate independent parts - so-called 'portlets', which are assembled together into a single page)
  • roles and permissions management
  • personalization - due to content aggregation and roles/permissions management one and the same page can be shown differently for different users
  • dynamic content management - portlets can be added to a page on-the-fly, dropped or moved without code changes and server restarts
  • content separation - content in Liferay belongs to some site inside a portal, which restricts access to it for site members only
  • a lot of ready-for-use portlets - like Web Content, Wiki, Blog, Document Library, Message Boards, Asset Publisher, etc.
  • powerful administration tools

Chapter 1. Installation and Configuration

At the moment of writing this book the latest stable Liferay version is 6.2-ce-ga4. Installation and configuration issues are described in this section.

1.1. Download Liferay

To download Liferay visit Liferay’s official site: https://www.liferay.com.

Click Download, then choose Bundled with Tomcat, click Download again:


After clicking Download the latest stable Liferay version will be downloaded automatically (after 5 seconds).

To choose the version you need, and also to download sources and documentation, you may click on Liferay Portal link (without waiting for automatic downloading):

Liferay Portal

then click Files link:


then click Liferay Portal link:

Files portal

Now choose the Liferay version (the latest stable one is 6.2-ce-ga4 at the moment):

Liferay version

You’ll be redirected to this page http://sourceforge.net/projects/lportal/files/Liferay Portal/6.2.3 GA4/.

Now you need to download Liferay (1), Liferay sources (2) and Liferay documentation (3) from here:

Files to download

You’ll get the following files in Downloads:

Downloaded files

Copy those files to your Liferay’s directory (D:/Work/Liferay/[Project-name] on Windows, /home/{user}/Work/Liferay/[Project-name] on Linux), and unpack Liferay (liferay-portal-tomcat-6.2-ce-ga4-20150416163831865.zip).

Now you have all required Liferay files and you’re ready to start it.

1.2. First Startup

We have already downloaded Liferay files, now we are starting it.

Go to tomcat/bin folder inside unpacked Liferay (liferay-portal-6.2-ce-ga4/tomcat-7.0.42/bin).

To start Liferay on Windows just run 'startup.bat' file, and see logs in console output.

To start Liferay on Linux, run from console:


then go to tomcat-7.0.42/logs directory and watch logs:

tail -f catalina.out

After normal startup the following message should appear in logs: INFO: Server startup in […] ms


After starting server open this URL in browser: http://localhost:8080 (if it has not opened automatically). You’ll be prompted to configure Liferay portal:


Leave everything as default here, remove Add Sample Data flag to speed-up configuration process, press Finish Configuration. After this click Go to My Portal, agree with Terms of Use, create new password for user, answer reminder question, and you’ll be redirected to Liferay home page:

Home page

Now you’re done, Liferay is started up and configured. You may use it.

1.3. Liferay Configuration

We have already started up Liferay with the default configuration settings. However, this configuration has the following disadvantages for the real projects:

  • not enough allocated memory
  • working with built-in database (Hypersonic)

Now we’ll fix it.

Adding allocated memory

Liferay is quite resource-consuming portal, that’s why we need to add allocated memory size. To do this edit setenv.bat file on Windows (or setenv.sh on Linux) and change values for -Xmx and -XX:MaxPermSize parameters:


If you have enough RAM, it’s recommended to set those values to 4096m, otherwise - to 2048m. Less values are not recommended.

Configuring database

Liferay works with built-in Hypersonic database by default. It’s normally to use it for demo projects, but it’s not recommended to use it on production. To change database settings - edit Liferay’s config file liferay-portal-6.2-ce-ga4/portal-setup-wizard.properties, and add the following properties:

jdbc.default.driverClassName=com.mysql.jdbc.Driver jdbc.default.url=jdbc:mysql://localhost:3306/[DB_NAME] jdbc.default.username=root jdbc.default.password=[PASSWORD]

where [DB_NAME] - database name, [PASSWORD] - MySQL password.

Your config file will be like this:

DB config


Make sure, you have specified correct values for database name (1) and MySQL password (2).

Restart Liferay to apply those changes.

1.4. IDE Configuration

We have already started Liferay and made some configuration enhancements for it. But we were starting it from console. And it’s not good for the development process, as you actually need to debug your code. So, we’ll need to configure our Liferay in IDE and run it from inside IDE in Debug mode. This section explains how to do this.

You may use different IDEs for Liferay development.

Some people prefer Liferay IDE, based on Eclipse (https://www.liferay.com/downloads/liferay-projects/liferay-ide). It simplifies Liferay development and deployment process, and has special plugins for portlets/themes development, etc. But I don’t use it, as I don’t like Eclipse products at all.

Other people use NetBeans or some other IDEs.

Personally I prefer using Intellij IDEA (https://www.jetbrains.com/idea/). Although it’s not Liferay-specific, development process is pretty clean and simple inside it.

Now I’ll explain how to configure Liferay in Intellij IDEA IDE.

Download IDEA

If you still don’t have IDEA installed, download it from here: https://www.jetbrains.com/idea/download/ (the latest version is 14.1 at this moment). Download Ultimate Edition (as Community Edition doesn’t have enough features for development):

DB config

Keep in mind, that it’s paid product.

Create new project

Start IntelliJ IDEA and create new project in it:

New project

Click Next, specify project name, and click Finish:


You’re done, new project has been created.

Create new Application Server in 'Settings' menu

Now we’ll create new application server for our Liferay in IDEA. Press Settings button (1) in Toolbar, and create new Tomcat server, as illustrated here:

App server

Now choose tomcat folder inside Downloaded Liferay:

App server

Specify name fow newly created application server (based on project name), and press Ok:

App server

Application server should have been created after these steps.

Configure Server in 'Run/Debug Configurations' menu

Now we’ll configure our Liferay server in IDEA. Go to Run -> Edit Configuration… menu (or press appropriate icon in Toolbar), and add new Tomcat server:


Specify server name (based on project name), and choose Application server (created on previous step):


On Startup/Connection tab (1) add (3) CATALINA_BASE (4) Environment variable with path to Liferay’s tomcat folder (5) for Run and Debug (2). Then press Ok (6):


Basic Liferay configuration in IDEA is finished at this point, and you’re ready to start it.

Startup Liferay from IDEA

Start Liferay in Debug mode from IDEA. Press Debug button for this (or press Shift+F9 hotkey):


Watch logs in Output window in IDEA, make sure everything is Ok, and start development with Liferay.

Chapter 2. Liferay Basics

We have already reviewed Liferay installation/configuration issues and starting it from inside Intellij IDEA. Now we’ll go through the main concepts of Liferay structure, without delving into internal implementation details.

2.1. What is Liferay?

Liferay is a platform written on Java, intended for web-development, and which provides a lot of ready-for-use solutions for sites creation. It is a web-portal with capabilities for users management, roles and permissions management, and also pages/content, applications management.

Liferay has a lot of built-in applications (portlets) - such as, Blogs, Message Boards, Wiki, Calendar, etc. In most case Liferay development is development of separate applications (portlets, themes, layouts) and their composition into a single site (portal). In some cases (when you need to modify/extend Liferay’s default behavior) Liferay-hooks are developed.

All these questions are described in more details later in this book.

2.2. Liferay’s Page Structure

After starting Liferay server and going to it’s home page, you see, that it has the following page structure:

Liferay page

As you see from here, Liferay page consists from the following parts:

1) DockBar - contains menu for Liferay administration, site navigation menu, notifications menu, profile management menu.

2) MenuBar - menu for content management. Provides capabilities for adding/editing pages, and also applying different themes/layouts for pages, adding portlets to pages, page permissions management, etc.

3) NavigationBar - navigation menu. It contains pages and sub-pages (only 1st level by default) for the current site. Only those pages are displayed in this menu, which are not marked as ‘hidden’, and on which current user has sufficient permissions.

4) Portlets - separate functional modules in Liferay, which may be added to a page, and which represent a part of portal’s page view. Each portlet may have different permissions settings, so users with different roles may see different portlets on the same portal pages.

2.3. Liferay Pages

We have just reviewed Liferay’s page structure. Now we’ll discuss Liferay pages in more details.

What is Liferay Page?

Liferay page (also called 'layout') is a separate portal page, which has it’s own URL, set of portlets on it, theme, layout, permissions settings, etc. Each page in Liferay belongs to some site, has it’s owner, permissions set, and displays information rendered by portlets on this page.

Page Management

To create a new Liferay page, you need to either use MenuBar for this, or to do it from inside Site Pages menu ('Admin' -> 'Site Administration' -> 'Pages' from Dockbar).

Here is example of adding page from MenuBar:

Add page

Click on + icon (1), Page tab (2), specify page name (3), choose layout for page (4), and press Add Page (5) button. New page will be created.

For advanced page management go to Admin -> Site Administration -> Pages from Dockbar. You’ll see the following:

Site pages

Here you can perform page management. You can do the following:

  • change page order using drag-and-drop
  • add new pages
  • add child pages for current page
  • delete page (to delete some page you need to be currently on some other page)
  • modify permissions on page
  • specify page name and URL for a page
  • make page hidden to hide it from navigation menu
  • change page type and layout
  • specify custom settings for a page (custom fields, SEO settings, etc.)

For example, to add child page for some already existing page - select this page in the pages list at the left, click Add Child Page button (1), specify page name (2), and click Add Page:

Add child page

If you go back to site home page, you’ll see that subpage is displayed in the navigation menu:

Sub page

If you edit this subpage, and mark Hide from Navigation Menu flag, you’ll see, that page will no longer be displayed in the navigation.

Page Types

Liferay has different types of pages. The default one is Layout - it’s standard, empty by default page, which is displayed in navigation menu. Portlets may be added to such page, themes and layouts may be also applied to this type of page. In most cases this page type is used.

But there are different page types, here are they:

  • Link to a Page of This Site - as the name says, this is a link to some page within site. Page of this type doesn’t have it’s own content, it’s used to redirect to some other page within the same site by clicking on this page in navigation menu
  • Link to URL - this is similar to previous type, but may refer to a page of some other site within portal, or even to some external URL
  • Panel - this type of page is used to work with different portlets on one and the same page. When you set page type to Panel in Site Pages menu, you can specify which applications (portlets) will be available on this panel page:

Panel page

When you go to panel page, you’ll see, that it contains two parts: list of available applications in the left section, and selected application in the right one:

Panel page

This type of page may be used, if you need to work with different portlets. In this case you don’t need to create pages and add portlets you need to those pages - all the portlet you need are already on panel page. Panel page type doesn’t allow to select page layout and to add applications to a page.

Embedded - it’s a Liferay page, which contains IFrame, which displays content from specified URL. When you select Embedded page type, you may specify URL to display:

Add page

When you go to embeded page, you’ll see that this URL is displayed withing IFrame on this page:

Embedded display

Adding portlets to embedded page and changing it’s layout is also not allowed (as with panel pages).

Public and Private pages

In Site Pages menu we see, that there are Public Pages and Private Pages:

Private public pages

Here is the difference between them:

Public Pages Private Pages
Accessible by all users by default (regardless of their membership in site) Accessible only by site members
Have the following URL structure: http://{host}:{port}/web/{site-name}/{page-friendly-url} Have the following URL structure: http://{host}:{port}/group/{site-name}/{page-friendly-url}

Page management for private pages is the same as for public pages (which was covered earlier). If you create private page, you’ll see, that it’s Friendly URL contains /group/ in it’s URL instead of /web/ (as it was for public pages):

Private page


Those private/public friendly URLs settings are configured in portal.properties:

layout.friendly.url.private.group.servlet.mapping=/group layout.friendly.url.public.servlet.mapping=/web

and may be changed in portal-setup-wizard.properties file.

If you try to access some private page being not logged in (for example, /group/guest/), you’ll be redirected to the default public page in the same site (/web/guest/ for the default Liferay site) with full-screened (in maximized mode) Sign In portlet on it (1). Once you sign in, you’ll be redirected back to the private page which you originally requested (it’s URL is stored in redirect parameter (2) in the URL):

Private page

but only in case when you’re a member of the site and have sufficient permissions to view this page. Otherwise, if you can not see this page - 'Not Found' exception will be shown to you:

Not found

(the same exception is shown if page really doesn’t exist).

You can quickly navigate to public/private pages of your sites from the Dockbar menu:

Navigate pages

User’s pages

Each user in Liferay can have his own personal site - a set of public pages (called 'My Profile') and set of private pages (called 'My Dashboard').

My Profile My Dashboard
Accessible by all users Accessible only by owner (and portal administrator)
Have the following URL structure: http://{host}:{port}/web/{screen-name}/{page-friendly-url} Have the following URL structure: http://{host}:{port}/user/{screen-name}/{page-friendly-url}

It’s similar to site public/private pages, but here user’s screen name is used in URL instead of site group friendly URL, and /user/ prefix is used for private pages (instead of /group/).

My Profile (1) and My Dashboard (2) are accessible from Dockbar:

Profile dashboard

My Profile pages:


My Dashboard pages:


As with site pages, page management for My Profile and My Dashboard is available from 'Admin' -> 'Site Administration' -> 'Pages' menu in Dockbar

Mange profile

Here you can manage pages for My Profile (1) and My Dashboard (2) in the same way, as you do this for site public/private pages.

When you create new user - both public (profile) and private (dashboard) pages are created for him automatically in the default Liferay configuration. To disable automatic creation of public/private pages for user, the following properties may be used in 'portal-setup-wizard.properties':

layout.user.public.layouts.auto.create=false layout.user.private.layouts.auto.create=false

To disable public/private pages at all, you may use:

layout.user.public.layouts.enabled=false layout.user.private.layouts.enabled=false

You may also specify your custom structure of created public/private page for user by overwriting those properties:

Layout props

If you need to create more than one page for user - you may also specify which LAR to use:

Export/Import pages

Liferay provides capability to import/export site pages with a help of LAR files (Layout ARchives). If you need to copy your site pages to some other Liferay instance - you may create .LAR file by exporting pages from your site, and then import this file to target Liferay instance.

To create LAR file, you need to press Export button from inside Site Pages (if you need to export private pages - click on Private Pages tab before):


Export popup will be opened, where you can specify export settings - name of exported LAR file, choose which pages and which content to export.

Here I specify which pages to include into the LAR file being created:

lar pages

(this feature will appeared in 6.2 only)

After LAR has been created, you may download it:

Lar download

To import LAR file, click on Import button (assuming, you’re already inside Site Pages menu for the site you need):


Upload LAR file in the opened Import popup:


Click on Continue, select import options, click on Import:


Make sure, that import process has finished successfully:

Import success

After this all pages and content from the LAR file should be available in the site where you uploaded this LAR file.

Layout Templates

Layout Templates (layouts) define the displaying of the portlets on the page. By default Liferay contains ten layouts.

To change the page layout we should click on Edit in the MenuBar, select the desired layout and click on Save.


After applying the layout to the page the portlets can be moved in it according to the structure of the selected layout.

In most cases it is enough for developing the layouts, that are provided by default. But in some cases the portlets should be placed in certain layout, but the acceptable layout is hasn’t included in the set. To do this, you can write a custom layout (or download the ready from MarketPlace).

Sometimes, instead of a custom layout we can use the portlet Nested portlets.

More about the Layout Templates read in this book later.

Liferay Themes

Liferay Themes (themes) - are liferay applications, that allow us to define the structure and look-and-feel for Liferey pages.

If layouts define only the structure for portlet layout, then the themes allow us to determine the structure of the entire portal page (including dockbar, header, content, footer, etc.), as well as css-rules for it.

By default, there are two themes in Liferay (Welcome and Classic).

You can change the theme for a page through the MenuBar (Edit → Look and Feel)


In the menu Site Pages we can specify the theme as for the entire site (for all private or all public pages), as well for specific pages.

More about the Liferay Themes development read in this book later.

2.4. Liferay Sites

What is Liferay site?

Liferay Site (in earlier Liferay versions called Community) is one of the fundamental term in Liferay. From the page management point of view it’s a set of public and private pages (see previous section). Except pages, site has also proper content (Web Content articles, Document and Media documents, Wiki pages, etc.), and own members (user, user groups or organizations).

Default sites in Liferay

There are two pre-defined sites in Liferay by default. When we were working with page management in previous section - we were working with Liferay’s default site - 'Liferay'. There is also another site 'Global'. When you go to 'Sites' menu inside Control Panel, you’ll see them:


Here are differences between them:

Liferay site Global Site
It has own pages and members of the site It doesn’t have pages and members
Site content is accessible only within this site Site content is global, i.e. accessible from any other site

Default Liferay site may be used in portals, which don’t have content/pages separation between different parts of portal (sites). So, if your portal will have only one site - you may use the pre-defined Liferay site.

Global site is used to store shared content. Content in Liferay (web content, documents, blogs, etc.) belongs to some site inside portal. By default this content is accessible only inside this site. If you want to make some content shared between different sites - you may upload it to Global site, and then refer to it from other sites.

Sites management

Sites can be created: + for organization - herewith a site can have a set of public/private pages and content + for user or user group - in this case it is a set of public/private pages only (without content and members) + separately - in this case a site can have a set of public/private pages, content and members of a site (users/organizations/user groups)

The site can be created as blank one (Add → Blank Site) or via Site Template.

Site Template consists of Page Templates.

We will create a page template: Page Template → Add. We will point a name as CalendarPage. Then go Action → Edit for created page template and select Open Page Template:

Page template

We will add a portlet to the Calendar page and select 1-coloumn layout, as a result we will get:

Page template

After that we will create SiteTemplate (Site Templates → Add). We will assign a name as CalendarSite, we will get as a result:

Site template

We will add a new page to the section Pages, selecting herewith the created earlier Page Template:

Add page

Then we will create a new layout, using created Site Template: Sites → Add → Calendar Site.

The configuration of pages/portlets, that is specified in Site Temaplate will be applied to the created site.


When creating a site template you can specify the pages (public or private), to which the template will be applied, and whether the template changes will change automatically the created site.

To add the site members it is necessary to select Site Membership in the Users section, then select Users, click on Assign Users,

Site members

then select the users you need, click on Save:

Site users

Similarly, the organization and user groups can be specified as site members.

LIFERAY configuration

The facilities for configuration / administration Liferay are located on the 'Configuration' tab in the Control Panel:


2.5. Liferay Applications Management

By default Liferay contains a large number of applications (portlets) for different purposes (for example, Wiki, Blog, Message Boards, WebContent, etc.).

To add a portlet to the page you need select Applications from the MenuBar, and then select the appropriate portlet. After clicking Add the portlet will be embedded to the page.

Portlets can be instanceable (can be added to a page several times) and not-instanceable (can be added only once). Each portlet has its own unique ID.

For instanceable portlets for providing their uniqueness, portlet namespace is written additionally to ID (for each portlet on the page the unique portlet namespace is generated).

After adding a portlet to a page, you can assign it the configuration settings and right of the access (permissions). Here, for example, the form for specifying permissions for Calendar portlet.


To display/hide this portlet for certain role it is necessary to check/uncheck the flag View (opposite the role).

The visual settings for portlet displaying it is possible to specify in 'Look and Feel' menu.

You can specify a custom title for the portlet, display/hide the borders, prescribe the custom css rules for portlet:

Look and Feel

The portlets on a page can be moved by drag-and-drop (according to the selected layout).

The list of all installed applications can be viewed in Control Panel -> Apps


Here you can activate/deactivate or remove the desired application.

On the Install tab, you can set the desired application (via upload war/lpkg file or via URL).

To install an application from the Liferay MarketPlace is necessary to go to Store on the Apps tab and log in (if you don’t have an account - register on liferay.com before).

After selecting the desired application click on Purchase. After that it should be displayed on the tab 'Purchased':


Click on Install, and the application will be installed.

Developing own portlets is discussed in this book later.

2.6. Liferay Administration

For Liferay administering we sould go Admin → Control Panel.

Portal Instances

Portal instance (or company) - it is a separate instantiation of the portal. By default, one company liferay.com is created in Liferay:

Portal Instance

They are used for differentiation of data (users, organizations, content, etc.) between different companies.

For this purpose, almost in the every liferay-table the field companyId exists, that determines the belonging to the company.

Mainly, single company is used (that is created by default).

Users and Organizations

In Liferay users are created in Users and Organizations → Add → User:


Users have the opportunities: + to login Liferay + to have their own website (set of public and/or private pages) + to be memebers of the organizations/websites/user groups + to have certain roles, which give them certain permissions (access rights)

Organization – is Liferay structural unit, uniting the users (users can be organization members).

The organization can have its own website (a set of public and/or private pages).

Organizations have a hierarchical structure (some organizations can be sub-organizations of the others).

Organizations can be of two types: Regular Organization (it is usual organization) and Location (it differs from the usual in that has the fields for entering a names of a country and a region).Organizations can be of two types: Regular Organization (it is usual organization) and Location (it differs from the usual in that has the fields for entering a names of a country and a region).

Example organization:


To add a user to the organization, we should go to Actions → Assign Users, then go to the tab Available and select the required users and click on Update Association:

Add user org

To add a subsidiary, we should press Add Regular Organization (or Add Location) of the current organization:

Add child

Add child

Website of the organization can have its own content (documents, web content, wiki pages, etc.):

Org site

The User Groups

The user group – is also Liferay structural unit, uniting the users.

Users can be user group members.

User group can have a set of public and private pages.

User Group

But, unlike the organization, user group site can not have the content (documents, web-content, etc.).

User groups don’t have a hierarchical structure.

Roles and Permissions

Roles in Liferay intended for determination of users permissions (access rights) to certain objects (content, pages, portlets, etc.). These roles can be assigned to users to provide them with requredaccess rights.

In Liferay 14 roles have already been created by default:


If necessary, we can create our own custom roles.

The roles can be: + Regular Role (general role) – granted to user for entire portal + Site Role (role for site) – granted to user for the site + Organization Role (organizational role) – granted user for the entire organization

The same user can have different roles in different sites/organization. For example, theuser ca be admin in one organization, but at the same time he can be usual user in another one.

To add a role to a user, we should go to Edit User and select the required roles:

User roles

To assign the permissions for the role, we should select Actions → Define Permissions for this role, then select the required permissions and click on Save.

For example, for created role Organization Publisher we select the permissions, required for content management.


Users with this role will have the appropriate access rights.

Chapter 3. First Portlet

We got to know installation/startup Liferay in the previous chapters, and also basic principles of work with it. Now we write our first Liferay portlet.

3.1. Creating new module in IDEA

Create a new module 'hello-world' by using of Maven archetype.

To do it, go File → New Module…, select Maven, check 'Create from archetype' and select 'liferay-portlet-archetype':

Maven Archtype

Click on Next, specify groupld and artifactld

New Module

Click on Next, setup Maven (if it was not setup formerly):

New Module

Click on Next, specify the way to the module and click on Finish.

Maven will create the structure of the project automatically.

After that, add Maven profile. To do it, create the file settings.xml in the folder $HOME$/.m2:

Settings Maven

Select this created profile on the tab Maven in IDEA. After that Maven will pull up the necessary dependencies.

3.2. Sructure of the created module

After creating the module with using Maven archetype, we will have as a result the module 'hello-world' with such structure:

Project structure

Chapter 4. First Theme

Perform all nicely...

Now we will write our first Liferay theme.

4.1. Creating new module in IDEA

We will create the new module 'aimprosoft' with using of 'Maven archetype'. To do it, go File → New Module…, select Maven, check 'Create from archetype' and select 'liferay-theme-archetype':


Specify groupld and artifactld:


Check Maven settings, specify location of module with the theme.

Structure of the theme will be created automatically.

We will create a theme on the basis of standard Liferay classic theme. To do it, copy all files *.vm from ROOT/html/themes/classic/templates, and also copy js, css, images folders. We will get such structure:

Theme structure

After compiling we get the ready theme, the same as the classic one.

We will change:

  • layout in portal_normal.vm
  • styles in custom.css
  • images favicon.png and thumbnail.png
  • of necessity navigation.vm (for changing of navigation)
  • portlet.vm (for changing of portlets)

In init_custom.vm we can specify our own variables, which we will be able to use later in portal_normal.vm. List of all predefined variables is located in the file /ROOT/html/themes/_unstyled/templates/init.vm.

After necessary changes we should recompile the theme and apply it to necessary pages.

Chapter 5. First Layout

Perform all straightly...

Now we will write our first Liferay theme.

Similar to portlet and theme, we will create a new module for layout:



We get such module structure:

Layout structure

We will create 1-3-column layout, that has such structure:


We will do it on the basis of existing 1_2_columns_i layout (file/ROOT/layouttpl/custom/1_2_columns_i.tpl). Copy content of this file in 1-3-column.tpl. Change layout in oder to there in the buttom were three columns instead of two ones. Change layout so that in the buttom were three columns instead of two:


The same is done for the file 1-3-column.wap.tpl.

Recompile layout and apply to the required page:


Chapter 6. First Hook

My hands are doing hooks...

Hook is needed for changing the standart Liferay functionality.

6.1. Which hooks do exist?

Types of hooks:

  • on portal.properties - for redefinition properties of the portal (which are specified in /ROOT/WEB-INF/lib/portal-impl.jar!/portal.properties). Not all portal properties can be re-specified via hook, it is possible only for described in /ROOT/dtd/liferay-hook_6_2_0.dtd properties
  • on language-properties - for redefinition properties in Resource Bundle (/ROOT/WEB-INF/lib/portal-impl.jar!/content/Language.properties)
  • on indexer (indexer-post-processor)
  • on service
  • on struts action
  • on servlet-filter
  • on jsp page (jsp-hook) - it allows us to change Liferay jsp-page

In this section we will create hook on jsp-page (out of login portlet).

6.2. Creating module for hook

As previously, we create a new module via Maven archetype:



We will get such structure:


6.3. Formulation of the problem

Suppose, we should display in bold 'Login to AimProSoft' in the 'Sign In' portlet, and then after login - 'Welcome to AimProSoft'.

6.4. Defining JSP-page, for which hook should be installed

One of the main technology that is used in Liferay, is Struts.

Therefore, it is possible to define which jsp in which portlet is used via struts action (file /ROOT/WEB-INF/struts-config.xml).

To do it, go on Login portlet:

Login Portlet

In FireBug we examine URL forms.

URL Form

As we see, one of the parameters in this URL is struts_action=/login/login.

We should find the appropriate action in struts-config.xml:


We examine path for forward:


Using this path we should find the required jsp in file /ROOT/WEB-INF/tiles-defs.xml:


That is, required jsp for hook - is /portlet/login/login.jsp.

6.5. Creating hook on JSP

One of the main technology that is used in Liferay, is Struts.

Therefore, it is possible to define which jsp in which portlet is used via struts action (file /ROOT/WEB-INF/struts-config.xml).

To do it, go on Login portlet:

Login Portlet

In liferay-hook.xml we register custom-jsp-dir:

Custom JSP

We create the folder custom inside of webapp, and put into it /ROOT/html/portlet/login/login.jsp:


We change jsp according to requirements:

Login Portlet

Then we delpoy the hook via Maven and check what we have as result:


Chapter 7. More about Themes

Perform all more nicely...

In the fourth chapter we created our first Liferay-theme. Now we consider the themes development more detail.

7.1. Themes structure

After creating the theme we have the structure:

Theme structure

/css - css-files of the theme

/images - images, that are used in the theme

/js - js-files of the theme

/templates - folder with templates for theme consists of such files:

  • init_custom.vm - in this file custom velocity-variables are created, which then can be used in the theme template. Variables are specified via command #set ($name = value). Usually a name of a variable begins with the sign '$'. In the classic theme we see how the value of the variable $css_class is changing:

Init vm

List of all predefined variables is located in the file ROOT/html/themes/_unstyled/templates/init.vm:

Init file str

In this file we see the following:

Init file cont

All variables which are asserted in this file, you can use in your themes.

  • navigation.vm - in this file is defined the template for menu of the navigation in the theme. In the classic theme has already been created the navigation for pages and subpages of first level.


It is possible to use this file as a basic for navigation development in our own themes.

  • portal_normal.vm - in this file is created a template of the theme. If we open a template for classic theme, we will see that it has the following structure:

TPortal normal

Dockbar is displayed above, then wrapper follows, consisting of header, content and footer.

The logotype, site name and navigation are placed in the header (only for logged users).

Breadcrumb and the portlets are displayed in the content.

The standard caption 'Powered By Liferay' is displayed in the footer.

  • portal_pop_up.vm - template for pop-up
  • portlet.vm - template for portlet has such structure


Portlets are displayed on the portal page according to this template.

/WEB-INF - folder with the configuration files

  • liferay-plugin-package.properties - description properties of the theme
  • web.xml - deployment descriptor

7.2. Creating own theme

After getting acquainted with theme structure, we create own theme ‘aimprosoft-theme’ on basis of classic theme:

1. Change standard inscription 'Powered By Liferay' to 'Powered By AimProSoft' in portal_normal.vm

Pow by

2. Replace favicon.png and thumbnail.png files on logotype of our theme:

Pow by

3. Change the color of the background. To do it, add the variable $bodyBackground: #f19a1a; in the file css/_aui_variables.css:

Pow by

4. We do so that the inscription 'Developed by AimProSoft' will be displayed in each portlet. To do that, we change the file templates/portlet.vm:

Portlet mod

5. Assign our own styles for the theme.

Add the new file aimprosoft.css:

Aim css

and register it in main.css:

Main CSS

Deploy the theme and look what is the result:


7.3. Changing navigation

In the classic theme the navigation displays the pages and subpages of the first level. We do so, that the subpages of the second level will be dispalyed in the our theme.

To do that, edit the file navigation.vm and add there the nested iteration for passing the subpages of the second level (similarly the iteration for passing the subpages of the first level):

Nav sub child

Add also the css-styles for subpages of the second level:

Nav css

Add some pages/subpages and see what we have as a result:

Nav display

7.4. Embedding the portlets into the theme

The portlets can be added to a page in a conventional manner, or can be embedded into a theme. In this case, the portlet will be displayed on the pages of such theme by default.

The portlet is embedded into the theme via the command:


where PORTLET_ID – is id of the necessary portlet.

We add to our theme the Language portlet to be able to change the language (do it in portal_normal.vm):


If we recompiling the theme, we will see that the Language portlet will be added to the header of the theme (but will be displayed with the title/borders and it is not beautifully). To fix this, remove the portletSetupShowBorders via $velocityPortletPreferences:

Show borders

Also assign the styles for this portlet:

Lang css

After redeploying of the theme we will see that Language portlet is displayed normally on the right in the header:

Lang portlet

Now on the pages of our theme we can easily change the language.

Similarly to this, you can add any other portlet. ID of required portlet can be defined in the interface com.liferay.portal.util.PortletKeys:

Portlet keys

7.5. Using VELOCITY-macros

Now we consider the use of velocity-macros in the template of a theme.

What is the VELOCITY-macro?

Velocity-macro admits the creation of the iterative fragment of the template, that then can be reused. Also, it can take one or more parameters that can be used in this fragment of the template.

Macro in Velocity is created by using the command:

#macro(macros_name param1 … paramN)



Then it can be called as:

#macros_name(arg1 … argN)

The parameters (and, accordingly, the arguments) can be absent.

How velocity-macros are used in Liferay?

During the development the template of the theme we have already used the macros that was created in Liferay by default, for example:

1. dockbar:


2. breadcrumb:


These macros have been declared in the file /ROOT/WEB-INF/lib/portal-impl.jar!/VM_liferay.vm:


and can be used during the theme development.

Development of the own velocity-macro

Earlier in this chapter we added to this theme Language portlet. Now we do it with the help of the velocity-macro.

We take out the code for displaying Language portlet into separate macro (call it 'language_portlet') in init_custom.vm:


Now we can use the created macro in the template of the theme:


As we can see, after creating macro for Language portlet, we can use it just as well as #dockbar () or #breadcrumbs (). It reduces code of theme template and admits reuse it.

More elaborate Velocity-macro

Now we develop more elaborate Velocity-macro.

Earlier in this chapter we have changed the navigation menu in the theme so that it displays the pages of second level. We did this by using a nested cycle. But suppose that it will need to display the pages of the third, fourth level, etc. Then we have to write a nested cycle for each level of nesting.

Not to do so, it is possible to use a recursion. Similarly to the recursion on jsp, it is possible to develop a velocity-macro, that will take the current page as a parameter, display the current level of the drop-down menu, and call itself for each of the subpages. Thus, the macro will call itself and display the next level of the menu as long as the subpages will be there.

Add the macro for the navigation in init_custom.vm:


As we can see, the macro takes the parameter $nav_elem and calls itself for each of $nav_elem_child.

Now we use this macro in the navigation:


Also, we fix up the css-styles for navigation:


Add subpages of the several levels of nesting:


And look at the result:


As we can see, with the help of the developed macro the submenu is displayed for any level of nesting pages.

7.6. Using Liferay-services in theme

Now we consider the use of Liferay-services in a theme.

What is Liferay-services?

Liferay-services – classes that allow to work with liferay models (create, retrieve from the database, save, etc.). For each [Entity] model in Liferay its own [Entity] Service was created.

Liferay-services can be used in your theme by using the service locator:

#set($myService = $serviceLocator.findService("[Entity]Service"))

After obtaining the service by such way, it is possible to call its methods for receiving the required values in the theme.

For example, we can obtain the service for users and for the layout in the following manner:


In Liferay the services can be local and remote.

Local services:

  • Classes com.liferay.portal.service.[Entity]LocalService
  • Do not contain the checking of permissions before calling

Remote services:

  • Classes com.liferay.portal.service.[Entity]Service
  • Before the call, they check permissions , and put the PrincipalException if the user does not have enough permissions for method calling

It is better to use local services for avoiding the appearance of PrincipalException.

Example of Liferay-services

We will do it so that the page '/administration' will be displayed in the navigation only for users of 'Aim ProSoft' organization, which have there the role 'AimproSoft Admin'.


In navigation.vm for checking we use the variable $isAimAdmin that was declared in init_custom.vm.


Here the checking isAimAdmin for the page '/administration' is executed. That is, only users with the role 'Aim ProSoft Admin' will be able to see this page.

After deployment we see that 'AimProSoft Admin' can see the page 'Administration',


Here the checking isAimAdmin for the page '/administration' is executed. That is, only users with the role 'Aim ProSoft Admin' will be able to see this page.

After deployment we see that 'AimProSoft Admin' can see the page 'Administration',

Ser role

but a user without this role - can not.

Ser role

(P.S. The same functional can be realized via display of the permissions on the page; here it was so done for demonstration of capabilities of using the services in the theme).

7.7. Using the custom attributes

Custom attribute can be gained in the topic via expandoBridge:


where $entity - an entity, of it attribute we should receive (it can be user, organization, page, etc.), "[ATTR_NAME]" - the attribute name.

For the page we create custom attribute "bgColor" (for setting the page color in the navigation menu):



Now, in the 'Manage Pages' we can specify the value of a custom attribute for the different pages:


Then, we change the navigation using a custom attribute for the background color:

Nav color

After that we will get an multicolored menu:


Chapter 8. Color Schemes

Add the colors...

8.1. What is the color schemes?

Color Scheme - is one of the variants of Liferay-theme (that has its proper colors, styles, borders, etc.). For the same theme the several color schemes can be developed.

8.2. Color schemes for CLASSIC theme

Color schemes for theme are specified in the file liferay-look-and-feel.xml. For classic theme we see the following:

color scheme

As we see, for theme 'classic' were created three color schemes: Default, Dark and Light. When we go to 'Look and Feel' and select 'Classic' theme, we will see, that three color schemes are available for this theme:

color scheme

Applying the different color schemes for classic theme, we will get the different styles for theme.

8.3. Creating our own COLOR SCHEMES

For created theme 'aimprosoft-theme' we will create two color schemes: orange and blue.

We create the file liferay-look-and-feel.xml (on basis of classic scheme):

color scheme

Here we described two color schemes for aimprosoft-theme, indicating for each of them css-class and basic path to images.

In the folder aimprosoft-theme/src/main/webapp/images/color_schemes we will create the folders for each of color schemes. We will deposit the file thumbnail.png in each of these folders.

color scheme

After recompiling of the theme we will see that the two color schemes became available for 'aimprosoft-theme':

color scheme

Now we specify the styles for color schemes.

We create the files css/color_schemes/blue.css and css/color_schemes/orange.css:

color scheme

and specify various colors of background:

color scheme

color scheme

Similarly we can specify another styles inside of classes .blue and .orange.

We apply the created color schemes and check the result.

1. Blue Color Scheme

color scheme

2. Orange Color Scheme

color scheme