Sample Portlets

SampleForm: Interactive Form Portlet

Overview: Steps for Creating the SampleForm Portlet

The SampleForm portlet is an interactive portlet that accepts free-form input from the user. When the user clicks Submit Form, the portlet displays the entered text back to the user.

SampleForm is a local portlet that runs inside the portlet container. It was developed using a JavaBean, which places values in the PortletContext object so that the values are available to the JSP page. The HttpServletRequestor HttpSession object could be used for this purpose. However, the PortletContext object is unique to the portlet and is not shared with other processes. Therefore, using it avoids collisions that could cause attribute values to be overwritten.

To create the SampleForm portlet, follow these steps:

Create the portlet configuration and source directories.
Create the portlet deployment descriptor (portlet.xml).
Create the display page (SampleForm.jsp).
Create the action class (DisplayAction.java).
Create a JavaBean to return user input (ExampleBean.java).
Create a title and description for the portlet.
Compile portlet code.
Create the PAR file and deploy and test the portlet.

Note: Before you begin developing the SampleForm portlet, ensure that the SAS Metadata Server is running so that metadata can be accessed during the configuration and deployment processes. [cautionend]

Step 1: Create the Portlet Configuration and Source Directories

Follow these steps to create a source directory structure for building the portlet:

Create a configuration directory for the portlet named SampleForm under the SAS-configuration-directory/Lev1/CustomAppData directory. This directory is referred to as portlet-configuration-directory in the code and descriptions for this portlet.
Copy the contents of the testportlet directory to the SampleForm directory.
Create a source code directory for the portlet named Source under the SAS-configuration-directory/Lev1/CustomAppData/SampleForm directory. This directory is referred to as portlet-source-directory in the code and descriptions for this portlet.

Edit the custom.properties file in the SampleForm directory as follows.

Note: Be sure to substitute the full pathnames from the steps above in the install.currprod.config.dir= and testportlet.install.dir= argument values. [cautionend]

# If you change the value "testportlet", make sure to rename in all properties 
# here as well as in the custom_config.xml.
config.currprod.12byte=testportlet

# Change the value of this property to be the name of your web application.
config.currprod.legalname=Form Portlet Sample

# The value of this property should be the location where the configuration 
# files are placed.  Make sure to change the level directory based on your 
# installation and make sure to rename testportlet if the value of 
# config.currprod.12byte changes above.
install.currprod.config.dir=portlet-configuration-directory

# Do not change the value of this property.  The name might be changed if you 
# change the value of config.currprod.12byte above.
webappsrv.testportlet.server=server

# Change the value of this property to be the location of your portlet's source 
# code and configuration files.  The name might be changed if you change the 
# value of config.currprod.12byte above.
testportlet.install.dir=portlet-source-directory

# Change the value of this property to be the name of you par, war, and ear 
# file.  The name might be changed if you change the value of 
# config.currprod.12byte above.
webapp.testportlet.archive.name=sample.form

# Change the value of this property to be the context root of your web 
# application and the name of the portlet.  The name might be changed if you 
# change the value of config.currprod.12byte above.
webapp.testportlet.contextroot=SampleForm

# Change the value of this property to be the versioned name of your web 
# application.  This property is only used for remote portlets.  The name might 
# be changed if you change the value of config.currprod.12byte above.
webapp.testportlet.display.name=Form Portlet Sample

From the SAS-configuration-directory/Lev1/CustomAppData/SampleForm directory, run the following configuration script to create the source directory structure for building the portlet:
```
cfg createLocalPortletDirectories -Dmetadata.connection.passwd="password"
```
For the password value, you must supply the unrestricted user password for your SAS installation.

Note: You can specify the password either in clear text or in encoded form. For information about generating the encoded form, see "The PWENCODE Procedure" in Encryption in SAS.
Review the customconfig.log file that was created in the SAS-configuration-directory/Lev1/CustomAppData/SampleForm directory to determine whether any errors occurred.

Step 2: Create the Portlet Deployment Descriptor

The portlet deployment descriptor is an XML file that provides all of the information that the SAS Information Delivery Portal needs to deploy one or more portlets. The following example shows the contents of the portlet deployment descriptor file for the SampleForm portlet. For more information about portlet deployment descriptor files, see Creating a Portlet Deployment Descriptor.

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE portlets SYSTEM "http://www.sas.com/idp/portlet.dtd"> 
<portlets>

   <local-portlet name="@webapp.testportlet.contextroot@"
         title="Form Portlet Sample">
      <localized-resources locales="en" />

      <deployment scope="user" autoDeploy="false" userCanCreateMore="true" />

      <init-param>
         <param-name>display-page</param-name>
         <param-value>SampleForm.jsp</param-value>
      </init-param>

      <portlet-path>/sample/portlets</portlet-path>

      <portlet-actions>
         <portlet-action name="display" default="true">
            <type>sample.form.DisplayAction</type>
         </portlet-action>
      </portlet-actions>
   </local-portlet> 
</portlets>

Store this portlet deployment descriptor source text in a file named portlet.xml.orig in the portlet-source-directory/Configurable/pars/sample.form directory. The testportlet scripting facility performs name/value pair substitution on this file to produce the portlet.xml file.

Step 3: Create the Display Page

JSP pages are the presentation components of portlets. The following example shows the code for the SampleForm portlet's display page. This JSP page uses SAS custom tags, which require a license for SAS AppDev Studio software. For more information, see Creating the Presentation JSP Page. If SAS AppDev Studio software is not licensed at your site, you must substitute equivalent HTML or JSP coding instead.

<%-- Copyright (c) 2009 by SAS Institute Inc., Cary, NC 27513 --%> 
<%@ page language="java" import="com.sas.portal.portlet.PortletContext,
      com.sas.portal.common.PortletConstants" 
    contentType="text/html;charset=UTF-8" %> 

<%@taglib uri="http://www.sas.com/taglib/sas" prefix="sas"%> 

<%-- This portlet echoes user input back to the portlet display. --%> 

<% PortletContext context = (PortletContext)
   request.getAttribute(PortletConstants.CURRENT_PORTLET_CONTEXT ); 
%> 

<sas:Form id="form" name="form" method="POST"
   action="<%= (String) context.getAttribute(\"formExample_baseURL\")%>"> 

<table border="0"> 

<tr>
<td align="right">Enter a value:</td>

<td><sas:TextEntry id="userInput" /></td> 
</tr> 

<tr>
<td align="right">You typed:</td>

<td><%=(String) context.getAttribute("formExample_userInput") %></td> 
</tr> 

</table> 

<sas:PushButton id="submit"
 text="Submit Form" type="submit" /> 

</sas:Form>

Store this JSP code in a file named SampleForm.jsp in the portlet-source-directory/Static/pars/sample.welcome/SampleWelcome/content directory.

Step 4: Create the Action Class

The SampleForm portlet has its own action class, DisplayAction. The following example shows the source code for the DisplayAction class. For more information, see Creating Action Classes.

/** Copyright (c) 2009 by SAS Institute Inc., Cary, NC 27513.
 * All Rights Reserved.
 */ 
package sample.form; 

import java.util.Enumeration; 
import java.util.HashMap; 

import javax.servlet.http.HttpServletRequest; 
import javax.servlet.http.HttpServletResponse; 

import org.apache.commons.beanutils.BeanUtils; 

import com.sas.portal.portlet.HTMLPortletAction; 
import com.sas.portal.portlet.NavigationUtil; 
import com.sas.portal.portlet.PortletContext; 

/**
 * Action for the Form Example Portlet. This prepares the URL
 * that is assigned to the form's action within the portlet's JSP.
 * It also populates a bean with the parameters from the JSP form.
 *
 */ 
public final class DisplayAction extends HTMLPortletAction {

   public DisplayAction() {
   }

   /**
   * Prepare the URL for the form used in the portlet.
   * Returns the value of "SampleForm.jsp".
   *
   * @param request The HtppServletRequest associated with the 
   * method invocation
   * @param response HttpServletResponse associated with the 
   * method invocation
   * @param context PortletContext mapped to the request path
   *
   * @return java.lang.String - representing a valid 
   * URL.
   */
   public String service(HttpServletRequest request,
         HttpServletResponse response, PortletContext context)
         throws Exception{
   
      super.service(request, response, context);
      
      // Prepare the base URL for setting on the form in the JSP.
      // The "display" is the value used in portlet.xml for this 
      // action. 
      String baseURL = NavigationUtil.buildBaseURL(context, request,
         "display");
      context.setAttribute("formExample_baseURL", baseURL); 
      
      // Make a new ExampleBean. Alternatively, this could be made 
      // once in the portlet initializer class, then you manage 
      // its properties in the action.
      ExampleBean bean = new ExampleBean();
      
      // The BeanUtils class populates any bean with all the 
      // parameters from the form.
      HashMap map = new HashMap();
      Enumeration names = request.getParameterNames();
      while (names.hasMoreElements()) {
      
         String name = (String) names.nextElement();
         
         map.put(name, request.getParameterValues(name));
      }
      BeanUtils.populate(bean, map);
      
      // Put the userInput into the portlet context so we can get it out
      // in the JSP.
      context.setAttribute("formExample_userInput", bean.getUserInput());
      
      return "SampleForm.jsp";
   } 

	private static final long serialVersionUID = 1L;

}

Create a directory named sample under the portlet-source-directory/Static/pars/sample.form/SampleForm/source directory, and then create a directory named form under the portlet-sourcedirectory/Static/pars/sample.form/SampleForm/source/sample directory. Store the class source code in a file named DisplayAction.java in the portlet-source-directory/Static/pars/sample.form/SampleForm/source/sample/form directory.

Step 5: Create a JavaBean to Return User Input

The SampleForm portlet uses a JavaBean to place values in the PortletContext object so that the values are available to the JSP page.

The HttpServletRequestor HttpSession object could be used for this purpose. However, the PortletContext object is unique to the portlet and is not shared with other processes. Therefore, using it avoids collisions that could cause attribute values to be overwritten.

The following example shows the source code for the JavaBean:

/** Copyright (c) 2009 by SAS Institute Inc., Cary, NC 27513.
* All Rights Reserved.
*/ 
package sample.form; 

public final class ExampleBean { 

   /**
   * Sets the user's input to this property. If input
   * is null, it is changed to "" so that getUserInput()
   * never returns null.
   *
   * @param input
   */ 
   public void setUserInput(String input) {
      if (input == null) {
         input = "";
      }
      this.input = input; 
   } 
      
   /**
   * Returns the user's input or "".
   *
   * @return String
   */ 
   public String getUserInput() {
      return input; 
   } 
   
   private String input = ""; 
}

Store the source code for the JavaBean in a file named ExampleBean.java in the portlet-source-directory/Static/pars/sample.form/SampleForm/source/sample/form directory.

Step 6: Create a Title and Description for the Portlet

The title and description for the SampleForm portlet are stored in a display resource file. See Creating Display Resources Files for more information about display resource files.

Create the following display resource file for the SampleForm portlet:

portlet.title=Form Portlet Sample 
portlet.description=Form Portlet Sample

Store this text in a file named portletDisplayResources.properties in the portlet-source-directory/Static/pars/sample.form/SampleForm/classes directory.

Step 7: Compile Portlet Code

The action class that was defined in Step 4 and the JavaBean that was defined in Step 5 must be compiled before the portlet can be used. SAS 9.2 uses a Versioned JAR Repository to manage the JAR files that ship with SAS products. The testportlet scripting facility integrates with the Versioned JAR Repository by requiring a picklist to define which JAR files are used for compiling the portlet and building the WAR file. If your portlet requires additional JAR files, they must also be added to the picklist.

Follow these steps to compile the SampleForm portlet:

Create a picklist for this sample portlet. As a starting point, copy the SAS Information Delivery Portal picklist file from the SAS-installation-directory/SASInformationDeliveryPortal/4.2/Picklists/wars/sas.portal directory into the portlet-source-directory/Picklist/pars/sample.form directory.

Note: After a SAS maintenance release is applied at your site, you must copy the updated picklist file and repeat the building and deploying of PAR and EAR files for all custom portlets.
Copy any custom or third-party JAR files that are not defined in the SAS picklist but that are needed to compile the custom portlet into the portlet-source-directory/Static/lib directory. For this sample portlet, you must copy the file named servlet-api.jar that ships with the application server into the portlet-source-directory/Static/lib directory.
From the SAS-configuration-directory/Lev1/CustomAppData/SampleForm directory, run the configuration script with the following arguments to compile the Java class:
```
cfg compileLocalPortlet -Dmetadata.connection.passwd="password"
```
For the password value, you must supply the unrestricted user password for your SAS installation.

Note: You can specify the password either in clear text or in encoded form. For information about generating the encoded form, see "The PWENCODE Procedure" in Encryption in SAS.
Review the customconfig.log file in the SAS-configuration-directory/Lev1/CustomAppData/SampleForm directory to determine whether any errors occurred.

Step 8: Create the PAR File and Deploy and Test the Portlet

The last step in developing the SampleForm portlet is to archive its files into a PAR file and deploy the new portlet. The PAR file includes all of the portlet's supporting files, including the files created in Steps 2 through 7. To create the PAR file and deploy the portlet, follow these steps:

Stop the Web application server on which the SAS Information Delivery Portal is deployed so that development of the new portlet will not affect the running system.
From the SAS-configuration-directory/Lev1/CustomAppData/SampleForm directory, run the configuration script with the following arguments:
```
 cfg buildPortletArchive -Dmetadata.connection.passwd="password"
```
For the password value, you must supply the unrestricted user password for your SAS installation.

Note: You can specify the password either in clear text or in encoded form. For information about generating the encoded form, see "The PWENCODE Procedure" in Encryption in SAS.

The portlet archive file is created in the SAS-configuration-directory/Lev1/Web/Applications/SASPortlets4.2/Deployed directory with the name sample.form.par.
Review the customconfig.log file in the SAS-configuration-directory/Lev1/CustomAppData/SampleForm directory to determine whether any errors occurred.
Rebuild the sas.portal4.2.ear file using the SAS Deployment Manager. This step is required because the sas.portal4.2.ear file contains files associated with each portlet.
Manually redeploy the sas.portal4.2.ear file into the Web application server.
Start the Web application server on which the SAS Information Delivery Portal is deployed. The SampleForm portlet should now be available to the portal.

It is a good practice to deploy new portlets into a staging area (that is, a test installation of the SAS Information Delivery Portal) for verification and testing before deploying them into a production environment.

Top of Page