What Is a Portlet, Part 2
Pages: 1, 2, 3, 4, 5

Adding Support for Edit Mode

As discussed in the first article in this series, portlets use a concept of portlet modes to indicate what the user is doing. The portlet specification defines three modes:

1. VIEW: For activities related to the expected functionality of your portlet.
2. EDIT: For configuration activities.
3. HELP: For displaying help.

We will take the HelloWorld.zip sample portlet developed in the first installment and modify it to enable the EDIT mode.

1. Change your HelloWorld.java file like this:

   public class HelloWorld extends GenericPortlet{
   protected void doView(RenderRequest request,
   RenderResponse response) 
   throws PortletException, IOException{
     response.setContentType("text/html"); 
     response.getWriter().println("Hello World Portlet");
    }
   protected void doEdit(RenderRequest request, 
   RenderResponse response) 
   throws PortletException, IOException {
     response.setContentType("text/html");
     response.getWriter().println(
       "Hello World Portlet- Edit Mode");
    }
   }

   In order to enable EDIT mode, we have to override the doEdit() method in HelloWorld.java. The doEdit() method gets called when the portlet is opened in EDIT mode, and supposed to generate markup. Inside of the doEdit() method, we first want to declare that the content type is text/html, and then write a one-line message informing user that he or she is accessing the HelloWorld Portlet in EDIT mode.

2. Change the portlet.xml file like this.

   <supports>
     <mime-type>text/html</mime-type>
     <portlet-mode>VIEW</portlet-mode>
     <portlet-mode>EDIT</portlet-mode>
   </supports>

   This change in portlet.xml will inform the portlet container that the HelloWorld portlet supports EDIT mode in addition to VIEW mode. Adding the <portlet-mode>EDIT<portlet-mode> subelement to the <supports> element is what accomplishes this. The <supports> element tells the container two things: the HelloWorld portlet can generate text/html-type content, and that for text/html content, it supports VIEW and EDIT modes.

In addition to the pre-defined VIEW, EDIT, and HELP modes, the portlet specification allows portlets to take advantage of vendor-specific portlet modes. For example, IBM's WebSphere portal server has the concept of a CONFIG mode, which allows an administrator to configure the portlet. To use this, you can declare a custom CONFIG mode in your portlet.xml and add the corresponding doConfig() method in your HelloWorld.java method (actually it requires a few more steps, described in the portlet specification). As a result, when the HelloWorld portlet is deployed on IBM's WebSphere Portal Server, it will display an icon for CONFIG mode in addition to the other modes. But if this portlet is deployed on some other portlet container, the user won't be able to enter CONFIG mode.

Using JSP to Display Help

One of the problems with the HelloWorld sample portlet is that we are generating markup inside of Java code, specifically in the HelloWorld.java class. This approach is not acceptable for developing an industrial-strength portlet. In that case, you may want to keep your business logic inside of the Java code and pass control to a JSP page for markup generation. Portlet Specification 1.0 says that portlet container should be J2EE-1.3-compliant. A portlet can pass control to either a servlet or a JSP for markup generation. Portlets use a concept of a RequestDispatcher, similar to the class of the same name in the servlet API. Lots of work is going on to port popular servlet-based MVC frameworks to the portlet environment, such as the Struts, JSF, and Spring frameworks.

Now we will change our HelloWorld portlet to do two things: enable HELP mode, and use the Help.jsp page for generating markup. Follow these steps.

1. Create \html\Hello.jsp under the Web Content folder. Add only one line in this file, saying "Help.jsp - HelloWorld Portlet in Help mode."

2. Change HelloWorld.java to add the doHelp() method, like this:

   protected void doHelp(RenderRequest request, 
   RenderResponse response) 
   throws PortletException, IOException {
    PortletRequestDispatcher dispatcher = 
       getPortletContext().getRequestDispatcher
           ("/html/helloworld.jsp");
    dispatcher.include(request, response);
   }

   In this method, you first get the handle to PortletRequestDispatcher by passing it the path of JSP that you want to use for markup generation. Next, you pass control to that JSP by calling the include() method of the PortletRequestDispatcher.

Portlets generate markup fragments that are aggregated in a portal page document. Because of this, there are some rules and limitations in the markup elements generated by portlets. Portlets should conform to these rules and limitations when generating content.

1. Portlets should not use tags that impact content generated by other portlets or that may even break the entire portal page. Inclusion of such a tag invalidates the whole markup fragment.
2. Portlets generating HTML fragments must not use the following tags: base, body, iframe, frame, frameset, head, html, or title.
3. Portlets generating XHTML and XHTML-Basic fragments must not use the following tags: base, body, iframe, head, html, or title.

Pages: 1, 2, 3, 4, 5

Next Page