Oracle9iAS Portal Developer Kit
Adding Extra Render Modes

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 some of the ManagedRenderers that are included in the PDK-Java Framework, namely FileRenderer, JspRenderer and Servlet20Renderer.

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. For more detailed information on the PDK-Java 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 the each, additional render mode. You will:

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

  1. Create a directory on your file system to store your HTML and JSP files.

    Remember the name of this directory as you will need it later, for example C:\MyProvider\htdocs\MyFirstPortlet. If you followed the article How to Build a Java Portlet, it will be below the location of your XML provider definition.

  2. 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>
    <P>RenderManager has invoked the FileRenderer based on the .html extension.</P>

  3. Save the file as help.html in the directory created in Step 1.

    Remember this filename as you will need it later.

  4. 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" import = "oracle.portal.provider.v1.*,oracle.portal.provider.v1.http.*" %>

<%
    PortletRenderRequest pr =
        (PortletRenderRequest)request.getAttribute(HttpProvider.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>
<P>RenderManager has invoked JspRenderer based on the .jsp extension.</P>

  5. Save the file as about.jsp in the directory created in Step 1.

    Remember this filename as you will need it later.

  6. 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.v1.*;
import oracle.portal.provider.v1.http.*;

public class MyShowDetailsServlet extends HttpServlet 
{

  public void doPost(HttpServletRequest request, HttpServletResponse response)
      throws ServletException, IOException
  {
    PrintWriter out = response.getWriter();
    PortletRenderRequest pr =
        (PortletRenderRequest)request.getAttribute(HttpProvider.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 Servlet20Renderer.</P>");
  }

}

  7. 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. For example:  C:\MyProvider\MyClasses

  8. Verify that jsdk.jar is included in the CLASSPATH.  If not, you will need to add it manually.

    For example, set CLASSPATH = %CLASSPATH%;C:\iAS\Apache\Jsdk\lib\jsdk.jar

  9. Follow the steps outlined in the How to Build a Java Portlet article to compile the Java Servlet into a location on the Oracle HTTP Server's classpath, for example C:\MyProvider\MyClasses.

    If you used the sample provided, the result should be a file called MyShowDetailsServlet.class in the above location. You will need this class name later.

We are now ready to update the XML provider definition and configure the Oracle HTTP Server to expose our 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.

    For example C:\MyProvider\provider.xml.

  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="2.0"?>
<!DOCTYPE provider [
 <!ENTITY virtualRoot "/MyProvider/">
 <!ENTITY physicalRoot "C:\MyProvider\htdocs\">
]>

<provider class="oracle.portal.provider.v1.http.DefaultProvider">

   <session>true</session>

   <portlet class="oracle.portal.provider.v1.http.DefaultPortlet">
      <id>1</id>
      <name>MyFirstPortlet</name>
      <title>My first portlet</title>
      <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.v1.RenderManager">
         <contentType>text/html</contentType>
         <appPath>&virtualRoot;MyFirstPortlet</appPath>
         <appRoot>&physicalRoot;MyFirstPortlet</appRoot>
         <showPage class="MyCustomRenderer"/>
         <helpPage>help.html</helpPage>
         <aboutPage>about.jsp</aboutPage>
         <showDetailsPage class="oracle.portal.provider.v1.http.Servlet20Renderer">
            <servletClass>MyShowDetailsServlet</servletClass>
         </showDetailsPage>
      </renderer>
   </portlet>

</provider>

  3. Save the updates to provider.xml.

Notice that we define two XML entities representing the server relative and filesystem paths to our htdocs directory, virtualRoot and physicalRoot. These are needed by RenderManager to locate our newly created HTML and JSP files. Using this configuration we can then point to the HTML and JSP files using those entities as we have done in the appPath and appRoot declarations. This configuration facilitates easy addition of portlets to the XML provider definition. For more detailed information on RenderManager, including extra configuration options, refer to the JavaDoc.

One final point to note about the sample XML provider definition above, is that the virtualRoot entity implies that requests to http://your.server.name/MyProvider/ are served from C:\MyProvider\htdocs. This can be accomplished by setting your Oracle HTTP Server's document root to this location, or by aliasing the /MyProvider/ URL to that directory. It is the latter option we now go on to configure, as this is by far the most flexible.

CONFIGURING YOUR WEBSERVER

These steps describe how to configure the Oracle HTTP Server only. If you are using a third party listener, please take the appropriate steps.

  1. Stop the Oracle HTTP Server.

  2. Alias the URL /MyProvider/ to point to C:\MyProvider\htdocs:

    1. Open the file httpd.conf located in <Oracle 9iAS Home>\Apache\Apache\conf.
    2. In the Aliases section, add the following:

      3. Alias /MyProvider/ "C:/MyProvider/htdocs/"
<Directory "C:/MyProvider/htdocs/">
    Options Indexes MultiViews
    AllowOverride None
    Order allow,deny
    Allow from all
</Directory>

    3. Save the updates to httpd.conf.

  3. Start the Oracle HTTP Server.

  4. Test the new alias, by opening a new browser window and entering the URL http://your.server.name/MyProvider/.

    A directory listing of C:\MyProvider\htdocs should be displayed. If you wish to restrict access to this URL, consult the Oracle HTTP Server documentation.

  5. Access your provider's test page by entering the URL http://your.server.name/servlets/MyProvider to verify that your XML provider definition contains no errors.

VIEWING THE PORTLET

To view the new render modes you must ensure that your updated XML provider definition is re-parsed. If you have stopped and restarted your Webserver in the steps above, then this will automatically be the case. To accomplish re-parsing without stopping your Webserver, ensure your servlet alias is given the init arg auto_reload=true and refresh the Oracle9iAS Portal's portlet repository.

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: