Sample Portlets

SampleWelcome: Localized Display Portlet

Overview: Steps for Creating the SampleWelcome Portlet

The SampleWelcome portlet displays localized text using the user's locale (language and country) preference and is not interactive. The SampleWelcome portlet is a local portlet that runs inside the portlet container.

To create the SampleWelcome portlet, follow these steps:

Create the portlet configuration and source directories.
Create the portlet deployment descriptor (portlet.xml).
Create the display page (Welcome.jsp).
Create the actions class (WelcomeAction.java).
Create resource bundles to support different locales.
Create translated portlet titles and descriptions to support different locales.
Compile portlet code.
Create the PAR file and deploy and test the portlet.

Note: Before you begin developing the SampleWelcome 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 configuration and source directory structure for building the portlet:

Create a configuration directory for the portlet named SampleWelcome 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 into this new SampleWelcome directory.
Create a source code directory for the portlet named Source under the SAS-configuration-directory/Lev1/CustomAppData/SampleWelcome 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 SampleWelcome 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=Welcome 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.welcome

# 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=SampleWelcome

# 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=Welcome Portlet Sample

From the SAS-configuration-directory/Lev1/CustomAppData/SampleWelcome directory, run the configuration script with the following arguments 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/SampleWelcome 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 SampleWelcome 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="Welcome Portlet Sample">

      <localized-resources locales="de,en" />

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

      <initializer-type>
         com.sas.portal.portlets.JspPortlet.JspPortletInitializer
      </initializer-type>

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

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

      <portlet-actions>
         <portlet-action name="display" default="true">
            <type>sample.welcome.WelcomeAction</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.welcome 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 source code for the SampleWelcome portlet's JSP page. For more information about portlet display pages, see Creating the Presentation JSP Page.

<%-- Copyright (c) 2009 by SAS Institute Inc., Cary, NC 27513 --%>

<%@ page language="java" contentType= "text/html; charset=UTF-8" %>

<%@ taglib uri="http://java.sun.com/jsp/jstl/fmt" prefix="fmt"%>

<fmt:message key="welcome.msg1.txt"/> 
<br> 
<fmt:message key="welcome.msg2.txt"/>

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

Step 4: Create the Action Class

The SampleWelcome portlet has its own action class, WelcomeAction, which provides support for localizing messages. This class extends com.sas.portal.portlet.HTMLPortletAction, which contains code to correctly display character sets other than Latin1 when the SAS Information Delivery Portal displays the portlet in preview mode.

The following example shows the source code for the WelcomeAction class. For more information about action classes, see Creating Action Classes.

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

import com.sas.portal.portlet.HTMLPortletAction; 
import com.sas.portal.portlet.NavigationUtil; 
import com.sas.portal.portlet.PortletContext; 
import javax.servlet.http.HttpServletRequest; 
import javax.servlet.http.HttpServletResponse; 

/**
 * Action for the SampleWelcome Portlet. This prepares the localized resource
 * bundles for use by the JSTL tags within the portlet's JSP.
 * @version 1
 */ 
public final class WelcomeAction extends HTMLPortletAction {

   public WelcomeAction() {
   }

   /**
    * Configure the JSTL localization context for use in the SampleWelcome
    * portlet. Returns the value of "display-page" from the portlet's
    * XML descriptor.
    *
    * @param request The HttpServletRequest 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); 
      
      NavigationUtil.prepareLocalizedResources(
         "sample.welcome.res.Resources", request, context);
      
      // This comes from the portlet.xml.
      String url = (String) context.getAttribute("display-page"); 
      return url;
   } 

   private static final long serialVersionUID = 1L;
}

Create a directory named sample under the portlet-source-directory/Static/pars/sample.welcome/SampleWelcome/source directory, and then create a directory named welcome under the portlet-source-directory/Static/pars/sample.welcome/SampleWelcome/source/sample directory. Store the class source code in a file named WelcomeAction.java in the portlet-source-directory/Static/pars/sample.welcome/SampleWelcome/source/sample/welcome directory.

Step 5: Create the Resource Bundles

Resource bundles provide translated text that is displayed inside the SampleWelcome portlet. The portlet's WelcomeAction.class calls the NavigationUtil.prepareLocalizedResources() method to create a JSTL localization context based on the user's locale preference. This context enables the JSTL tags in Welcome.jsp to use the appropriate resource bundle to display the text.

Note: For information about localizing the portlet's title and description, see Step 6: Create Translated Titles and Descriptions. [cautionend]

Create the following resource files for the SampleWelcome portlet:

Resources_de.properties (for German)

# This is where you put key/value pairs for message strings that need to 
# be localized. 
## These are the messages for the Welcome portlet 
welcome.msg1.txt=Willkommen bei SAS Information Delivery Portal. 
welcome.msg2.txt=Schauen Sie sich um!

Resources_en.properties (for English)

# This is where you put key/value pairs for message strings that need to 
# be localized. 
## These are the messages for the SampleWelcome portlet 
welcome.msg1.txt=Welcome to the SAS Information Delivery Portal. 
welcome.msg2.txt=Take a look around!

Create a directory named res under the portlet-source-directory/Static/pars/sample.welcome/SampleWelcome/source/sample/welcome directory. Store these resource bundles in files named Resources_de.properties and Resources_en.properties in the portlet-source-directory/Static/pars/sample.welcome/SampleWelcome/source/sample/welcome/res directory.

Step 6: Create Translated Titles and Descriptions

Translated titles and descriptions for the SampleWelcome portlet are stored in display resource files. See Creating Display Resources Files for more information about display resource files.

The following display resource files are required for the SampleWelcome portlet:

portletDisplayResources_de.properties (for German)

portlet.title=Begrüßungs-Portlet Muster 
portlet.description=Begrüßungs-Portlet Muster

portletDisplayResources_en.properties (for English)

portlet.title=Welcome Portlet Sample 
portlet.description=Welcome Portlet Sample

Store these files with the specified names in the portlet-source-directory/Static/pars/sample.welcome/SampleWelcome/classes directory.

Step 7: Compile Portlet Code

The action class that was defined in Step 4 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 SampleWelcome 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.welcome 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 the file named servlet-api.jar that ships with the application server into the portlet-source-directory/Static/lib directory.

Note: The portlet-source-directory/Static/lib directory is where you store any custom or third-party JAR files that are not defined in the SAS picklist but that are needed to compile the custom portlet.
From the SAS-configuration-directory/Lev1/CustomAppData/SampleWelcome 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/SampleWelcome 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 SampleWelcome 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/SampleWelcome 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 will be created in the SAS-configuration-directory/Lev1/Web/Applications/SASPortlets4.2/Deployed directory with the name sample.welcome.par.
Review the customconfig.log file in the SAS-configuration-directory/Lev1/CustomAppData/SampleWelcome 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 SampleWelcome 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