Oracle9iAS Portal Developer Kit
 Adding Extra Render Modes to Java Portlets

PDK Release 2 (9.0.2 and later) - Java

In the previous article How to Build a Java Portlet, you learned how a portlet requires a PortletRenderer controller object to generate the portlet's visual representation in the various render modes it supports. You were shown that by choosing RenderManager as the PortletRenderer for your portlet, you could easily add support for the basic Show render mode by 'plugging in' a custom ManagedRenderer for this mode. This article builds on the previous one by demonstrating how easy it is to 'plug in' other ManagedRenderers to make your portlet also support the Help, About and Show Details render modes. The example uses one of the ManagedRenderers in the PDK Framework, namely ResourceRenderer.

Once you have completed this article, you will be able to implement any render mode using RenderManager as the principles are the same. For example, even though this article does not describe how to implement the Preview mode in detail, you will understand how to do so, as the process is the same.

To learn about the extra requirements for rendering the special Edit and Edit Defaults render modes, refer to the article Adding Customization to Java Portlets. For more detailed information on the PDK runtime classes used in this article, refer to the JavaDoc.

ASSUMPTIONS

  1. You have followed through and understood the article How to Build a Java Portlet.

  2. All the assumptions in the above article apply here too.

IMPLEMENTING EXTRA RENDER MODES

Your first task is to create implementations that provide content for each, additional render mode. You will:

This above example set has been chosen to illustrate the variety of features available with the PDK when using RenderManager. When developing your own portlets, you may choose to follow different schemes.

  1. Using your favorite text editor, create a HTML file that displays content in a HTML table cell.

    For now, just include a message indicating that the user is viewing the Help mode. 

    <P>This is the <I>help</I> mode of your first portlet!</P>

  2. Save the file as help.html into the directory you created whilst following the article How to Build a Java Portlet.

Remember this filename as you will need it later.

  1. Next, create a simple JSP to display content for the About mode.

    You may write your own JSP, or use the sample provided below which outputs a personalized greeting to the logged in user. 

    <%@ page language = "java" %>
<%@ page import = "oracle.portal.provider.v2.render.PortletRenderRequest" %>
<%@ page import = "oracle.portal.provider.v2.*,oracle.portal.provider.v2.http.*" %>

<%
    PortletRenderRequest pr =
        (PortletRenderRequest)request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    String user = pr.getUser().getName();
%>

<P>Hi <%= user %>!</P>
<P>This is the <I>about</I> mode of your first portlet.</P>

  2. Save the file as about.jsp into the same directory as help.html (see Step 2).

    Remember this filename as you will need it later.

  3. Next, write a simple Java Servlet to display content for the Show Details mode.

    You may write your own Java Servlet, or use the sample provided which outputs a personalized greeting to the logged in user. 

    import java.io.*;
Import javax.servlet.*;
Import javax.servlet.http.*;

Import oracle.portal.provider.v2.*;
Import oracle.portal.provider.v2.http.*;
Import oracle.portal.provider.v2.render.PortletRenderRequest;

public class MyShowDetailsServlet extends HttpServlet 
{

  public void doPost(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException
  {
    PrintWriter out = response.getWriter();
    PortletRenderRequest pr =
        (PortletRenderRequest)request.getAttribute(HttpCommonConstants.PORTLET_RENDER_REQUEST);
    String user = pr.getUser().getName();
    out.println("<P>Hi " + user + " !</P>");
    out.println("<P>This is the <I>show details</I> mode of your first portlet.</P>");
    out.println("<P>RenderManager has invoked ResourceRenderer.</P>");
  }
}
  4. Save as MyShowDetailsServlet.java, or use your own name if preferred.

    Remember the name of the directory where the file is saved as you will need this later.

  5. Verify that the servlet API is is included in the CLASSPATH.  If not, you must add it manually.

    For example if you have an Oracle 9i Application Server installed:

    set CLASSPATH = %CLASSPATH%;C:\iAS\Apache\Jsdk\lib\servlet.jar

  6. Follow the steps outlined in the article How to Build a Java Portlet to compile the Java Servlet.

    If you used the sample provided, the result should be a file called MyShowDetailsServlet.class in the same location as MyShowDetailsServlet.java.

We are now ready to update the XML provider definition, add the portlet to a provider and install that provider into OC4J to expose the portlet's new functionality.

UPDATING THE XML PROVIDER DEFINITION

When you want to expose additional render modes you must update your XML provider definition as follows:

To expose the Help, About and Show Details modes we have implemented for this example, we need to include the following XML elements at Portlet level:

Configuring RenderManager involves registering 'pages' to handle the additional modes. By following the article How to Build a Java Portlet you already have 'showPage' which renders requests for the Show mode.

Follow these steps to update your XML provider definition:

  1. Using your favorite text editor, open the XML provider definition created by following the article How to Build a Java Portlet.

  2. Update the file as shown below.

    Note: All additions to provider.xml created in the article How to Build a Java Portlet are shown in bold. 

    <?xml version="1.0" encoding="ISO-8859-1" standalone="yes"?>
<?providerDefinition version="3.1"?>

<provider class="oracle.portal.provider.v2.DefaultProviderDefinition">


   <session>true</session>

   <portlet class="oracle.portal.provider.v2.DefaultPortletDefinition">
      <id>1</id>
      <name>MyFirstPortlet</name>
      <title>My first portlet</title>
      <ShortTitle>MyFirstPortlet</ShortTitle>
      <description>My first ever portlet, implementing extra render modes!</description>
      <timeout>10</timeout>
      <timeoutMessage>Timed out waiting for MyFirstPortlet</timeoutMessage>
      <hasHelp>true</hasHelp>
      <hasAbout>true</hasAbout>
      <showDetails>true</showDetails>
      <renderer class="oracle.portal.provider.v2.render.RenderManager">
         <contentType>text/html</contentType>
         <showPage class="MyCustomRenderer"/>
         <helpPage>help.html</helpPage>
         <aboutPage>about.jsp</aboutPage>
         <showDetailsPage>/servlet/MyShowDetailsServlet</showDetailsPage>
      </renderer>
   </portlet>

</provider>

  3. Save the updates to provider.xml.

CONFIGURING OC4J

To update your portlet's provider and install that provider into OC4J, see the article "Packaging and deploying Your Provider".

VIEWING THE PORTLET

To view the new render modes you must ensure that your updated XML provider definition is re-parsed. To do this, restart OC4J and refresh the Portal page containing your portlet

If you have not already added MyFirstPortlet to a Portal page, do so now and then view that page to see the new Help, About and Show Details modes you have added.

Revision History: