50 Shades of Liferay (E-book)

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):

Keep in mind, that it’s paid product.

Create new project

Start IntelliJ IDEA and create new project in it:

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:

Now choose tomcat folder inside Downloaded Liferay:

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

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.

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:

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:

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

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

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

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,

then select the users you need, click on Save:

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:

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:

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:

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

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

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.

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:

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.

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.

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':

Click on Next, specify groupld and artifactld

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

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:

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

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

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).

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

We will get such structure:

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

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:

In FireBug we examine URL forms.

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:

path="portlet.login.login"

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.

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:

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

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

We change jsp according to requirements:

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

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

After creating the theme we have the 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:

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

In this file we see the following:

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:

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

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

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

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

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:

5. Assign our own styles for the theme.

Add the new file aimprosoft.css:

and register it in main.css:

Deploy the theme and look what is the result:

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):

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

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

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)

MACROS_BODY

#end

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.

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',

but a user without this role - can not.

(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).

Custom attribute can be gained in the topic via expandoBridge:

$entity.getExpandoBridge().getAttribute("[ATTR_NAME]"),

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:

After that we will get an multicolored menu:

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.

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

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:

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

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):

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.

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

Now we specify the styles for color schemes.

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

and specify various colors of background:

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

2. Orange Color Scheme