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 :

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
  • : Packaging the project
  • Liferay-hook.xml : Extending the default Liferay functionalities

Where these files are located ?

Structure of a portlet

Let’s detail each file !

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 :

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:

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 :

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 :

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

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.


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 :

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

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 :

Is to use the Jboss implementation of Expression Language.
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

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.