# Installation and Upgrade Guide

# Additional Configuration Steps

The steps listed in this chapter are provided for your information; they are not required.

- Modify Existing Portlet Applications
- Create New Portlet Applications
- Add Support for Shared Sessions
- Add Tag Library Support
- Build Stylesheet Templates
- Use SSL
- Use Application Server Values for getRemoteUser(), getUserPrincipal(), and isUserInRole()
- Access User Information
- Support Editing Pages (Edit Mode)

## Modify Existing Portlet Applications

The portlets provided with the JSR-168 Consumer can be customized. To customize the existing portlets, follow the steps below:

1. Create a new Web application for your portlets.
2. Extract the portlet application WAR file, if necessary.
3. Place the JSR-168 Consumer jar files into the WEB-INF/lib directory of your new portlet application. These include the following files:

   commons-beanutils.jar commons-codec-1.3.jar commons-collections.jar commons-digester-1.5.jar commons-httpclient-3.0-rc1.jar commons-logging.jar edk.jar jsr168tags.jar | googleapi.jar log4j.jar openfoundation.jar oreilly.jar pthome.jar ptportletcontainer.jar xalan.jar xerces144.jar

4. The web.xml file must include `servlets`, `servlet-mappings`, `context listener`, and `tag libraries`. Use ptjsr168/1.1/devkit/WEB-INF/web.xml as a template. Elements must be added in the proper order, or the application will not start. See your application server documentation for the required ordering of elements in the web.xml document.
5. Restart the application server as needed.

## Create New Portlet Applications

The default installation includes a WEB-INF directory for creating new portlet applications in ptjsr168/1.1/devkit/. To create an application from this directory, follow the instructions below:

1. Create a directory for your new Web application.
2. Add the /WEB-INF folder from ptjsr168/1.1/devkit/ to the new application. If you want to add any new portlet classes (subclassing GenericPortlet), add them to the WEB-INF/classes directory in your new application and add a portlet.xml file to the /WEB-INF directory. Add additional jsp pages and servlets if they are required for your application.
3. Deploy using the instructions for your application server.

## Add Support for Shared Sessions

The sample portlets in the JSR-168 Consumer package do not require shared sessions, but it is a best practice to configure shared sessions since the JSR-168 spec requires that sessions are shared per context.

Note: | The JSR-168 Consumer portlets cannot be configured to share sessions in versions of the portal prior to 6.0.

To configure support for shared sessions, complete the steps below.

1. In the Remote Server editor, add the context to the Remote Server Base URL, for example http://myserver:7001/PtPortletContainer. (Create a Remote Server for each context.)
2. In the Web Service - Remote Portlet editor, go the Advanced Settings page and select "Share sessions with other Portlets on the same Remote Server."

## Add Tag Library Support

To add Tag Library support, add the following line to the web.xml file after `servlet-mappings` and `session-config`:

    <taglib>

    <taglib-uri>http://java.sun.com/portlet</taglib-uri>
    <taglib-location>/WEB-INF/lib/jsr168tags.jar</taglib-location>

    </taglib>

Note: | Make sure the jsr168tags.jar in the ptjsr168/1.1/devkit/WEB-INF/lib directory is added to the WEB-INF/lib directory.

## Build Stylesheet Templates

Follow the steps below to build any modified stylesheets.

1. Unzip the ptjsr168_image.zip file to the /ptimages directory on the machine that hosts the Image Service.
2. Go to /ptimages/tools/cssmill and execute the following batch file (you must have the permissions to execute the file):

- Windows: make_all.bat
- Unix/Linux: make_all.sh (To modify permissions, use the `chmod` command.)

## Use SSL

SSL is used in the PortletURL call `setSecure()`, and in the `transport-guarantee` element of the `security-constraint` element of portlet.xml.

To use SSL, open the jsr168.properties file in <PT_HOME>/ptjsr168/1.1/settings/config and set the appropriate values for `httpport` and `httpsport`. SSL must be enabled on the application server and a valid certificate must be installed. If you use a `transport-guarantee` in portlet.xml, the portlet will redirect to the configured SSL port in jsr168.properties.

For both `setSecure()` and `transport-guarantee`, make sure to include the full SSL address up to the war file name in the gateway space (e.g., https:my_server:7002/my_war).

## Use Application Server Values for getRemoteUser(), getUserPrincipal(), and isUserInRole()

By default, the JSR-168 Consumer does not use the values from the application server for the security-related calls `getRemoteUser()`, `getUserPrincipal()`, and `isUserInRole()`. Instead, it uses the logged-in portal user for `getRemoteUser()` and `getUserPrincipal()`, and activity rights for `isUserInRole()`. Only the activity rights configured on the Advanced Settings page of the Web Service object are examined for `isUserInRole()`.

To use the application server values for these methods, open the jsr168.properties file in <PT_HOME>/ptjsr168/1.1/settings/config and change the portalRemoteUser key to false. Changes will take effect when you restart your application server.

Note: | The application server will always return null for `getRemoteUser()` and `getUserPrincipal()` unless the user has logged into the application server.

## Access User Information

To access User Information settings from the portal, follow the steps below.

1. Define the user attributes in the WEB-INF/portlet.xml file. For example:

    <user-attribute>

    <description>User Phone</description>
    <name>user.business-info.telecom.telephone.number</name>

    </user-attribute>

If a user attribute is not defined in the portlet.xml file, it will not be read.

2. Map the attribute to User Information from the portal in the file <PT_HOME>/ptjsr168/1.1/settings/config/userattributes.properties. For example:

    user.business-info.telecom.telephone.number=phone

The first value is the name used by the JSR168 Consumer; the second value is the name of the User Information property in the portal.

3. Restart the application server to implement your changes to userattributes.properties.
4. Add the property to the User Information Property Map in the portal. In this example, the property is "phone" (case-sensitive). To add a property, go to portal administration and click Select Utility | User Profile Manager and select User Information - Property Map. (For details, see the portal online help or the Administrator's Guide for AquaLogic Interaction.)
5. Configure the Web Service to send the User Information to the remote server. On the User Information page of the Web Service editor, add User Information settings that match the values mapped in the userattributes.properties file. To complete the example above, you would enter "phone" on the User Information page.

To complete the example and view the User Information in a portlet, follow the steps below:

1. Navigate to the Web application that hosts the JSP portlet. Open the includePortlet.jsp file and add the following to the user properties String values:

    String phone = (String) map.get("user.business-info.telecom.telephone.number");

Add the following to display in the jsp page:

    phone is <%=phone%>

2. Log in to the portal and click My Account. Enter a phone number and click Finish.
3. Add the RSS portlet to a portal page and confirm that the phone number you entered appears.

## Support Editing Pages (Edit Mode)

To display a page in edit mode, add edit to the action of the form as shown below. (For a complete example, see IncludePortletEdit.jsp, shipped with PtPortletContainer.)

    <form name="form1" method="post" action=<portlet:actionURL portletMode="edit"/>>

To close the window, set the mode back to view in `processAction` in the portlet, as shown below.

    public final void processAction(ActionRequest req, ActionResponse res) throws PortletException, IOException

        {

             //do whatever processing is needed for multiple pages

             //when processing is done, set the mode back to view

                res.setPortletMode(PortletMode.VIEW);

        }