Portlet Modes in Liferay

Portlet modes is a state in which portlet can generate its content.  Portlet can run in different portlet modes which is one of the key difference between portlet and servlet.

Portlet mode represents a task being executed by portlet. Content of portlet will be different for each portlet modes.

It’s portal job to instruct portlet in which mode it should run. Portlet modes can be changed on the fly programatically (in action phase only). You can define how may modes a portlet can support in its configuration file (portlet.xml).

Portlet Modes in Liferay

 

In this article, I will be showing various portlet modes and how to declare it.

Portlet Modes

To achieve portability, portlet specification (JSR-168) defines following portlet modes which are available across all the portal implementations (Liferay, Web Spear, Oracle portal etc).

  • View
    • In this mode, portlet renders the content for its main functionality.
  • Edit
    • This mode is generally used for configuration (setting preferences)
  • Help
    • Portlet can display brief information about it in this mode.

Out of these three, View mode is a default and mandatory for all portlets and that make sense because portlet executes its main functionality in view mode. Edit and Help are optional.

On top of these, Liferay provides additional modes which are available to the portlets deployed on Liferay portal as blow

  • About
  • Config
  • Edit default
  • Edit guest
  • Print
  • Preview

All modes provided by Liferay are optional. Portlet modes may be restricted to specific user roles.

For example, View and Help are available to guest user. However Edit is only available to user with Portal / Site Administrator role.

The process of defining portlet modes covers in 4 step.

Step 1: Declare Portlet Modes

By default all portlets render in view mode. You no need to declare it explicitly.

If your portlet needs multiple modes, you have to explicitly guide to portal about it. You can define how many modes a portlet can supports in its configuration file called portlet.xml.

Let’s take an example of Liferay MVC Portlet. I gave portlet class as com.opensource.techblog.portlet.ModeDemoPortlet.java. Once created, it looks like below snapshot.

Project Structure - Portlet Modes in Liferay

Its portlet.xml should looks like below snippet.

Quick observation:

You no need to shout “Hey, my portlet will render in view mode so here is the declaration” because our smart Liferay portal will silently understand it.

You can see, by default we haven’t define any modes because view is a default (understandable) one.

To declare other modes, you need to make small change in portlet.xml as below.

Explanation:-

  • Just below mime-type, we defined 3 modes – view, edit and help.
  • It tells to portal that this portlet can support all those modes.
  • I have declared view as one of the supported mode but even if you don’t declare it, portlet by default supports it.
  • pay the special attention –  portlet-mode element must be below mime-type or else it will give error.

 

Step 2: Define JSP corresponds to each Portlet Modes

Since the content of each portlet modes is different, you must have to provide separate JSP for each one of them. In above example, create edit.jsp and help.jsp at same level of view.jsp.

You can define the content you wish your portlet shows in edit mode in edit.jsp and help mode in help.jsp. You are free to give any name to these jsp and stored to any location under docroot.

Thumb rule is, you need to define one JSP for each mode.

 

Step 3: Set one to one mapping of Portlet Modes to JSP

We have defined what modes a portlet can support. We also defined what content (JSP) a portlet should render for each mode. The last thing is to map these JSPs to respective modes.

This mapping can be defined in portlet configuration file – portlet.xml as below.

Explanation:-

  • Portlet initial parameter (init param) will do this mapping.
  • These init param are processed while portlet is loaded by portlet container.
  • You can see by default it has mapping for view.jsp.
  • For view mode, the name of init param is view-template and the value is JSP (with relative path).
  • For edit and help modes, the init param name would be edit-template and help-template respectively.
  • The value would be corresponding JSP with its relative path from docroot.
  • For simplicity, I kept view.jsp, edit.jsp and help.jsp directly under docroot. If you wish, you can put them in any path for example folder called html under docroot.
  • In that case you need to define the value of init param as /html/view.jsp, /html/edit.jsp etc.

Step 4: Define method corresponding to each mode in Portlet class.

So far, you saw the declaration of portlet modes, their JSPs and mapping but don’t you feel you should ask a question – hey, who will call these JSP and where can I put the code before calling these JSP ?

And the answer is the methods corresponds to each modes in portlet class which would fill this gap in this flow.

open your portlet class and add following methods in it.

Explanation:-

  • doView is a method for view mode. Similarly doEdit is for edit and doHelp is for help mode.
  • These methods are originally declared in MVCPortlet class which is a parent class of your custom portlet.
  • You can override these method in your custom portlet. If you haven’t override, liferay will call respective methods from MVCPortlet class.
  • At the end of each method, I did make a super method call. Any guess what is the reason ?

Why you need to call a super method at the end of each method corresponds to portlet modes

  • I haven’t put super method call at the end of each method accidentally. It has specific purpose.
  • I asked  a question in beginning of Step 4 that how the JSP corresponding to each portlet modes is called.
  • You can observed that I haven’t define any code to redirect to JSP in our custom portlet class then who will call these JSPs.
  • The answer is – redirection to corresponding JSP is happening in each super method.

How ? Let’s see by taking an example of super.doView() method.

Observation:

  • internally doView() method makes a call to include() method with viewTemplate, renderRequest and renderResponse as parameters.
  • viewTemplate is a protected instance variable which is initialized in init() method of MVCPortlet.
  • init() method represents initialization phase of portlet and it’s called only once by portlet container when portlet is instantiate.
  • open init() method and you will find below code in that.

Observation:

  • Apart from viewTemplate various other protected instance variable like aboutTemplate, configTemplate etc are assigned a value.
  • _getInitParameter() is used to assigned value to each of them.
  • _getInitParameter() method reads init parameter defined in portlet.xml file.
  • For example _getInitParameter(“view-template”) reads “view-template” init parameter from portlet.xml and assign its value to viewTemplate instance variable.
  • In step 3 we have defined JSP path for each mode as an init parameter. i.e “view-template” parameter has value “/view.jsp“.
  • It means _getInitParameter(“view-template”) return the path of view.jsp (“/view.jsp in our case) and assigned to viewTemplate variable.
  • In other words, viewTemplate holds the path of JSP (defined in portlet.xml ) which represent the view mode.
  • Similarly each instance variable holds the path to corresponding JSP defined in portlet.xml as an init parameter.

Now open include() method which is called from doView() method. You will see one more overloaded method – include() is called which has following code.

Explanation:

  • Value of viewTemplate from include() method is referred as “path” parameter in this method.
  • This “path” is then passed to RequestDispatcher which will make a call to JSP (referred by path).

I took an example of only 3 methods. In case if you wish you can override other methods corresponds to each mode (defined by Liferay) i.e. doAbout, doConfig, doDispatch, doEditDefaults, doEditGuest, doPreview, doPrint etc as per below screenshot.

Other Liferay specific Portlet modes - Portlet modes in Liferay

Let’s put all building block together. Conclusively, below cheat-sheet gives you brief about portlet modes.

Portlet-Modes

 

Summing UP

  • Portlet can have multiple modes. By default it supports View mode.
  • Defining a portlet mode is 4 step process
    • declare mode (in portlet.xml)
    • Define JSP corresponding to each portlet modes(content)
    • Define mapping of JSP to portlet mode in portlet.xml in form of init parameter
    • Override method specific to portlet mode and write you customer logic there.
  • While overriding a method in your portlet class, make sure you put call to its super method at the end or else it will not find corresponding JSP.

Share This Post

2 Comments - Write a Comment

Post Comment