Understanding Liferay portlet configuration files

Radouane ROUFID

9 years ago

After creating and deploying a Liferay Portlet in the previous post, we will take time now to understand the basic Liferay files, especially these following :

Portlet.xml
Liferay-portlet.xml
Liferay-display.xml
Liferay-plugin-package.properties
Liferay-hook.xml
Web.xml
Faces-config.xml

These files are automatically generated if you use the eclipse Liferay Plugin and are located under WEB-INF folder.

In brief :

Portlet.xml : Defining the Portlet (JSR-286 attributes)
Liferay-portlet.xml : Registering the Liferay portlet
Liferay-display.xml : Adding the Portlet to a category
Liferay-plugin-package.properties : Packaging the project
Liferay-hook.xml : Extending the default Liferay functionalities

Where these files are located ?

Let’s detail each file !

Table of contents

1 1- Portlet.xml
2 2- Liferay-portlet.xml
3 3- Liferay-display.xml
4 4- Liferay-plugin-package.properties
5 5- Liferay-hook.xml
6 6- Web.xml
7 7- Faces-config.xml

1- Portlet.xml

The first important file is the portlet.xml where we define the standard JSR-286 portlet configuration. In this file, we define and describe our portlet (the name of the portlet, what class handles invocations to the portlet…). Bellow, the basic configuration :

<?xml version="1.0"?>

<portlet-app xmlns="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd http://java.sun.com/xml/ns/portlet/portlet-app_2_0.xsd" version="2.0">

<portlet-name>helloWorldPortlet</portlet-name>

<display-name>helloWorldPortlet</display-name>

<portlet-class>javax.portlet.faces.GenericFacesPortlet</portlet-class>

<init-param>

<name>javax.portlet.faces.defaultViewId.view</name>

<value>/views/view.xhtml</value>

</init-param>

<expiration-cache>0</expiration-cache>

<mime-type>text/html</mime-type>

</supports>

<portlet-info>

<title>helloWorldPortlet</title>

<short-title>helloWorldPortlet</short-title>

<keywords>helloWorldPortlet</keywords>

</portlet-info>

<security-role-ref>

<role-name>administrator</role-name>

</security-role-ref>

<security-role-ref>

<role-name>guest</role-name>

</security-role-ref>

<security-role-ref>

<role-name>power-user</role-name>

</security-role-ref>

<security-role-ref>

<role-name>user</role-name>

</security-role-ref>

</portlet>

</portlet-app>

Properties definition:

Portlet-name
Defines the name of the porlet. Must be unique in the Liferay Project Plugin.
Display-name
The name of the portlet that will be displayed in the Liferay Portal. The portlet display-name can be different of the portlet-name and don’t need to be unique.
Portlet-class
Defines the Fully Qualified Name (FQN) of the portlet class that handles invocations to the portlet.
Init-param
Specifies the initialization parameters of the portlet. For example, the default page view.
Expiration-cache
Specify the cache expiration time of the Portlet. Value in seconds and -1 indicates that the cache never expires.
Supports
Supported mime-type. Supports also indicates the portlet modes a portlet supports for a specific content type. All portlets must support the view mode.
Portlet-info
Defines the Portlet informations.
Security-role-ref
Defines the security level of the Portlet. In Another word, which role can access/see the Portlet.

2- Liferay-portlet.xml

After the Portlet definition in the Portlet.xml comes the Portlet registration. The Portlet registration is done in the Liferay-portlet.xml file in which we tell the Liferay Portal to use the Portlet we defined.

Many properties are definable in this file : Css and Js files required for the Portlet, if whether the portlet can appear multiple times on a page or not, trigger a job for scheduling and much more. A complete listing of this file’s settings is in its DTD in the definitions folder in the Liferay Portal source code.

The default content of liferay-portlet.xml is as below:

<?xml version="1.0"?>

<!DOCTYPE liferay-portlet-app PUBLIC "-//Liferay//DTD Portlet Application 6.2.0//EN" "http://www.liferay.com/dtd/liferay-portlet-app_6_2_0.dtd">

<liferay-portlet-app>

<portlet-name>helloWorldPortlet</portlet-name>

<requires-namespaced-parameters>false</requires-namespaced-parameters>

<ajaxable>false</ajaxable>

<header-portlet-css>/css/main.css</header-portlet-css>

</portlet>

<role-mapper>

<role-name>administrator</role-name>

<role-link>Administrator</role-link>

</role-mapper>

<role-mapper>

<role-name>guest</role-name>

<role-link>Guest</role-link>

</role-mapper>

<role-mapper>

<role-name>power-user</role-name>

<role-link>Power User</role-link>

</role-mapper>

<role-mapper>

<role-name>user</role-name>

<role-link>User</role-link>

</role-mapper>

</liferay-portlet-app>

Understand the default properties

Portlet-name
The portlet-name element defines the canonical name of the portlet. This needs to be the same as the portlet-name given in portlet.xml.
Icon
Relative Path to an image that will be used as an icon for this portlet.
Instanceable
Indicates if the Portlet can be used more than once on the same page or not. False is the default value.
Requires-namespaced-parameters
The portlet will only process namespaced parameters. The default value is true.
Ajaxable
If the portlet can be displayed via Ajax or not. Default value is true.
Header-portlet-css
The path to the .css file for this portlet to be included in the header of the page.
Footer-portlet-css
The path to the .js file for this portlet, to be included at the end of the page.
Css-class-wrapper
The name of the CSS class that will be injected in the DIV that wraps this portlet
Role-mapper
Mapping of the roles defined in portlet.xml and the existing roles in the Liferay Portlet. For example, if the portlet acess is restricted to only Administrator (by adding Security-role-ref in the portlet.xml), and the corresponding role in the Liferay portal is : Admin, so in the liferay-portlet.xml we must add the following lines :

1
2
3
4

<role-mapper>
<role-name>Administrator</role-name>
<role-link>Admin</role-link>
</role-mapper>

3- Liferay-display.xml

The aim of this file is to organize the deployed portlets to categories in the Add -> Application window. The default content is :

<?xml version="1.0"?>

<!DOCTYPE display PUBLIC "-//Liferay//DTD Display 6.2.0//EN" "http://www.liferay.com/dtd/liferay-display_6_2_0.dtd">

</category>

</display>

the “id” of the “portlet” property must match the portlet-name defined in the portlet.xml file.

Without the definition, portlets will be organized under the “category.sample” category.

Liferay Portlet category – Radouane Roufid

If you want to hide a deployed portlet from the Add -> Application window, declare it under the “category.hidden” category in the Liferay-display file.

A system portlet (the property system set to true in the liferay-portlet.xml) will not appear under a category even if the liferay-display.xml is well configured.

4- Liferay-plugin-package.properties

This file is about the plugin packaging. It covers a set of properties allowing you to set informations about your plugin, specify required jars by the plugin, specify contexts dependency and so one. Below an example of content :

name=helloWorldPortlet

module-group-id=RoufidPortlet

module-incremental-version=1

tags=Java,Computer science,demo,www.roufid.com

short-description=JSF Liferay Portlet Short description

change-log=Creating the portlet Last changes made

page-url=http://www.liferay.com

author=Radouane Roufid

licenses=LGPL

portal-dependency-jars=\

jstl-api.jar,\

Properties definition :

name
The display name of the plugin
module-group-id
Module group identifier for the plugin
module-incremental-version
The Starting version number of the plugin. Incremented by 1 every time the plugin is modified
tags
Tags categorizing the plugin
short-description
Short description
long-description
Long description
change-log
Comment of the last changes made
author
Author
portal-dependency-jars
Specify all JARs the plugin requires. These JARs are copied from Liferay Portal’s “lib” folder to the deployed plugin’s “lib” folder during deployment.
required-deployment-contexts
Specify other plugins that depend on deployment of this plugin. Some plugins require this in order to rely on services and features provided by other plugins.

5- Liferay-hook.xml

In this file, you can create hooks. What is a hook ? A hook is a tool allowing you to extend the Liferay portal core features. By creating a hook, you will have the ability to override some of the native Liferay functions as for example, performing custom actions on portal startup or user login, overwriting or extending portal JSPs, replacing a portal service with custom implementation and updating struts actions, servlet filters, and servlet filters mappings.

You can see all portal properties that can be overridden via a hook in the liferay-hook_6_2_0.dtd.

In the basic portlet project that we created before, there is a hook that overrides the default Language properties file by setting :

<?xml version="1.0"?>

<!DOCTYPE hook PUBLIC "-//Liferay//DTD Hook 6.2.0//EN" "http://www.liferay.com/dtd/liferay-hook_6_2_0.dtd">

<hook>

<language-properties>Language_en_US.properties</language-properties>

</hook>

6- Web.xml

Since we use JSF with Liferay portlet a web.xml file is generated. It’s the deployment descriptor that describes resources and configuration of the application and how the web server uses them to serve web requests.

Bellow a short explanation of each property :

<context-param>

<param-name>com.sun.faces.expressionFactory</param-name>

<param-value>org.jboss.el.ExpressionFactoryImpl</param-value>

</context-param>

Is to use the Jboss implementation of Expression Language.

<context-param>

<param-name>javax.faces.PROJECT_STAGE</param-name>

<param-value>Development</param-value>

</context-param>

Project stage property that defines the current state of the project. This parameter allow JSF to be more verbose and show better error messages according to the project stage. Possible values are :

Development,
Production,
SystemTest,
UnitTest

<servlet-name>Faces Servlet</servlet-name>

<servlet-class>javax.faces.webapp.FacesServlet</servlet-class>

<load-on-startup>1</load-on-startup>

</servlet>

Instantiate the FacesServlet on the startup of the application.

7- Faces-config.xml

File generated and used by JSF for multiple purposes. Faces-config can be used to set up navigation rules, declare beans if you don’t want to use annotation, register validators and so on.