GateIn tutorial: how to create a Portlet

This tutorial will show you how to develop some basic portlets using GateIn portal along with some basic background for those that are new to Portlets.

A portlet is a pluggable user interface component that provides specific content, which could be a service or information from existing systems. Portlets provide the user interface of the portal by accessing distinct applications, systems, or data sources and generating markup fragments to present their content to portal users.

A typical example of a portlet can be a eather portlet that provides weather information for a city by accessing a Search Engine, or a facebook Portlet which shows recent messages that you have received.

So the primary responsibility of a portlet is to generate a markup fragment (such as HTML, XML, or WML), which is then displayed on a portal page within a window,called a portlet window. A portal page usually displays multiple portlets in distinct port-let windows, each with its own title and set ofbuttons to change its look and feel, set its preferences, and maximize, minimize, or remove the window.

Difference with Servlets: Unlike Servlets where the user interface isn’t componentized a portlet is responsible for generating the user interface specific to one visual component.

The responsibility of displaying the complete portal page remains of the portal server, which aggregates fragments generated by portlets and displays them in the portlet windows on the portal page. This division of responsibility makes it possible for a portlet to focus on generating its own user interface.

Libraries needed to run GateIn portlet application

The main dependency that you need when working with Maven and Portlets is:
{codecitation class=”brush: xml; gutter: true;”}
      <dependency>
          <groupId>javax.portlet</groupId>
          <artifactId>portlet-api</artifactId>
          <version>2.0</version>
          <scope>provided</scope>
      </dependency>
{/codecitation}      
If you are compiling your GateIn Project using Eclipse, you need to provide the following import in order to compile your Portlets. (It is part of the GateIn distribution).
gatein tutorial gatein tutorial gatein tutorial gatein tutorial
So create a new Java Dynamic Web project and add a Java class named HelloWorldPortlet to it:
{codecitation class=”brush: java; gutter: true;”}
package com.sample;

import java.io.IOException;
import java.io.PrintWriter;

import javax.portlet.ActionRequest;
import javax.portlet.ActionResponse;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.ProcessAction;
import javax.portlet.RenderMode;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

public class HelloWorldPortlet extends GenericPortlet {

    @RenderMode(name = “view”)
    public void showTime(RenderRequest request,
            RenderResponse response) throws
            PortletException, IOException {
            PrintWriter out = response.getWriter();
            out.println(“Hello! Time is “+new java.util.Date().toString());
    }

}
{/codecitation}

A portlet class must implement the javax.portlet.Portletinterface, directly or indirectly. The portlet API has a GenericPortlet abstract class that implements the Portletinterface and provides a default implementation for its methods. Developers will usually subclass the GenericPortletclass and override one or more methods to provide a specific implementation.

The @RenderMode annotation for the showTime method informs that this method will use the portlet’s VIEW mode

The getWriter() method of RenderResponse is similar to the getWriter() method of HttpServletResponse, which returns a PrintWriterobject. 

The following table discusses about Portlet modes and the content generated in those modes

VIEW A portlet generates content that reflects the current state of the portlet instance.
This content carries business value. The GenericPortletclass provides the doView method, which is used to support the VIEW mode. It’s mandatory for portlets to support VIEW mode.
EDIT A portlet generates content that allows users to personalize the content and behavior of the portlet. This content doesn’t carry any business value; it’s meant for users to specify their preferences. The GenericPortletclass provides the doEdit method, which is used to support the EDIT mode.
HELP A portlet generates content that shows help information. This content doesn’t carry any business value; it’s meant to provide users with information on how to use the portlet. The GenericPortletclass provides the doHelp method, which is used to support the HELP mode.

Finally, before deploying your Portlet you need to provide a configuration file named portlet.xml:

{codecitation class=”brush: xml; gutter: true;”}

<?xml version=”1.0″ encoding=”UTF-8″?>
<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>
        <portlet-name>HelloWorld</portlet-name>
        <portlet-class>com.sample.HelloWorldPortlet</portlet-class>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>view</portlet-mode>
        </supports>
        <portlet-info>
            <title>Hello World portlet</title>
        </portlet-info>
    </portlet>
</portlet-app>

{/codecitation}

This file needs to be placed into the WEB-INF folder of your Web application and contains the Portlets which are used by your applications (just like the web.xml does for your Servlets) and their rendering mode.


Deploy your first GateIn portlet application

In order to deploy your first portlet you need to follow these steps:

At first deploy the web application WAR file just as an ordinary Web application.

gatein tutorial gatein tutorial  gatein tutorial  gatein tutorial

 

 Log in as an Administrator user

 

 

Go to to Group > Administration > Application Registry to import the custom portlets that form part of the portlet application.

The Application Registry shows all the portlets that have been imported into the GateIn portal. Import the deployed portlets by clicking the Import Applications button shown in the following picture.

gatein tutorial jboss gatein

Once that your portlets has been installed, it will appear in the Category panel.
gatein tutorial gatein tutorial gatein tutorial gatein tutorial
Now login with an User to the GateIn Portal

gatein tutorial jboss example gatein

And add a New Page to the base portal:

jboss gatein example tutorial gatein

Choose a path of your like (while reflects the path on the Menu) and enter a Node Name which will display in the Menu:
portlet_load
Now Drag and Drop into the page the HelloWorld portlet we have just created.
portlet_loadpage2

You should see that now your page contains the HelloWorld portlet as shown by the following picture:

portlet_loadpage3

Now you save your work and check that your Portlet is working, by navigating to the Upper Menu.
gatein tutorial gatein jboss tutorial gatein

Now recall your first GateIn portlet from the upper menu: Home > HelloTime:

gatein tutorial gatein tutorial gatein jboss example demo


Creating a portlet using JSPs

So here’s a more complex example where we will use JSP pages to handle some interaction between the Portlet views.

This application will display the result of a simple Math addition, making use of PortletContext to navigate between the pages of the application.

As first step create a new Web application named for example formexample.

Next add a class to it named FormPortlet:

{codecitation class=”brush: java; gutter: true;”}
package com.sample;

import java.io.IOException;
import java.io.PrintWriter;

import javax.portlet.ActionRequest;
import javax.portlet.ActionResponse;
import javax.portlet.GenericPortlet;
import javax.portlet.PortletException;
import javax.portlet.ProcessAction;
import javax.portlet.RenderMode;
import javax.portlet.RenderRequest;
import javax.portlet.RenderResponse;

public class FormPortlet extends GenericPortlet {

    @RenderMode(name = “view”)
    public void display(RenderRequest request, RenderResponse response) throws PortletException, IOException {

          if (request.getParameter(“result”) != null) {
              getPortletContext().getRequestDispatcher(“/output.jsp”).include(request, response);
          }
          else {
              getPortletContext().getRequestDispatcher(“/form.jsp”).include(request, response);
          }
    }

    @ProcessAction(name = “calculateAction”)
    public void nameAction(ActionRequest request, ActionResponse response) throws PortletException {
        int number1=Integer.parseInt(request.getParameter(“number1”));
        int number2=Integer.parseInt(request.getParameter(“number2”));

        response.setRenderParameter(“result”, String.valueOf(number1+number2));
    }
}
{/codecitation}
As you can see, this Portlet uses the PortletContext to navigate between JSP pages.

 The concept of a PortletContext is similar to a ServletContext: it provides access to the environment in which the portlet is running. In the case of portlets, the environ-ment is the portlet application to which the portlet belongs, and the portlet container in which the portlet is running.

In our example, the PortletContext retrieves the PortletRequestDispatcher which defines the following methods to include content generated by a resource or forward request to a resource:

include: This method includes the content generated from the resource in the portlet response.
forward: This method forwards the request for generating content to another resource.

Let’s add two JSP pages to our Project so it will be easier to understand the flow. This is form.jsp which contains a basic form, collecting two numbers as request parameter:
{codecitation class=”brush: xml; gutter: true;”}
<%@ taglib uri=”http://java.sun.com/portlet_2_0″ prefix=”portlet” %>

<portlet:defineObjects/>

<div>
  <div class=”portlet-section-header”>Calculator Machine</div>
  <br/>
  <div class=”portlet-section-body”>
    <form action='<portlet:actionURL name=”calculateAction”/>’ method=”post”>
      <span class=”portlet-form-label”>Enter two numbers</span>
      <input class=”portlet-form-input-field” type=”text” name=”number1″/>
      <input class=”portlet-form-input-field” type=”text” name=”number2″/>

      <input class=”portlet-form-button” type=”Submit” value=”Calculate Sum”/>
    </form>
  </div>
  <br/>
</div>
{/codecitation}
At first, notice the <defineObjects> tag is used to introduce scripting variables in the JSP page. Then you can use implicit Portlet objects such as the renderRequest object which is used to obtain the current portlet mode and window state information.
Next pay attention to tge actionURL tag which can be used in the form action attribute (or in in hyperlinks as well) to send an action request to a portlet when a user clicks on it. This will recall the FormPortlet’s calculateAction.

Next jsp is output.jsp which will merely display the result which will be contained into the result request variable.
{codecitation class=”brush: xml; gutter: true;”}
<%@ taglib uri=”http://java.sun.com/portlet_2_0″ prefix=”portlet” %>

<portlet:defineObjects/>

<div>
  <div class=”portlet-section-header”>Calculator Machine</div>
  <br/>
  <div class=”portlet-section-body”>Result: <%=renderRequest.getParameter(“result”) %></div>
  <br/>
  <a href=”<portlet:renderURL portletMode=’view’ />”>Reset</a>
  <br/>
</div>

Nothing new here, just notice the Reset hyperlink below that is used to restart the application. The only missing piece is portlet.xml which follows here:

{codecitation class=”brush: xml; gutter: true;”}
<?xml version=”1.0″ encoding=”UTF-8″?>
<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>
        <portlet-name>FormPortlet</portlet-name>
        <portlet-class>com.sample.FormPortlet</portlet-class>
        <supports>
            <mime-type>text/html</mime-type>
            <portlet-mode>view</portlet-mode>
        </supports>

        <portlet-info>
            <title>FormPortlet</title>
        </portlet-info>
    </portlet>
</portlet-app>
{/codecitation}
Now load the Portlet using in the Application Registry as shown in the earlier example, and add a new page containing this portlet.
Here’s the expected output:

gatein example gatein tutorial gatein jboss

Once you click on the “Calculate Sum” button, the outout.jsp page will appear:

gatein example gatein tutorial gatein jboss

For the sake of brevity there are no validation controls on the numbers entered- we leave this as an exercise to the reader. Enjoy GateIn!

Download the formportlet example Eclipse Project.

Found the article helpful? if so please follow us on Socials