Using the WPCP Portlets By Gregory Melahn (melahn@us.ibm.com), Robert Will (willrc@us.ibm.com) March 2003

Abstract The WebSphere® Portal content publishing (WPCP) Portlets allow you to use WPCP authoring functions and display published content from inside WebSphere Portal. For example, using these portlets, you can create instances of Personalization Rules, publish them, and display runtime content that is selected by these rules. The WPCP Portlets consist of three sets of portlets

1. IFRAME Portlets that expose each full frame of the WPCP Web user interface as a portlet. These portlets allow you to manage access to individual WPCP capabilities us ing portal groups and access control. They also allow you to control the navigation and look and feel of the WPCP functions. These portlets only run in browsers that support IFRAME.

2. Simple portlets for adding and publishing portal content without loading or navigating the full WPCP Web user interface. These portlets do not require IFRAME support.

3. A portlet for displaying content within your portal with or without rules. These portlets do not require IFRAME support.

Deploying the Portlets Unzip the file WPCPPortlets.zip. This file contains

1. WPCPPortlets.war: This is the portal application containing the portlets 2. WPCPPortlets.xml: This is an xmlaccess file you can use to install the war

file 3. WPCPPortletsPatch.zip: This is a set of fixes to WPCP that will enable

the portlets 4. NewsTemplates.zip: This is a set of sample WPCP templates you can use.

The portlets are delivered in a single portal application named the “WPCP Portlets Application” in the file WPCPPortlets.war. This war file can be installed in the usual way using the Portal Administration portlets. Alternatively, the application can be deployed using the file WPCPPortlets.xml. This xml file will deploy the war and create a useful set of places and pages allowing you to access the portlets. To use this file, place the WPCPPortlets.xml file in the portal bin directory (e.g. d:\WebSphere\PortalServer\bin) and place the war file in the portal install directory (e.g. d:\WebSphere\PortalServer\install). Then edit the xml file so that

the wpsadmin name used throughout the document corresponds to the format for your installation. The exact format of the name you use can be obtained by selecting the Show ID action in the Manage Users portlet, as illustrated.

Then run the following command from the x:\WebSphere\PortalServer\bin command line: xmlaccess WPCPPortlets.xml wpsadmin:wpsadmin localhost/wps/config Where wpsadmin:wpsadmin is a user:password on your portal that is given manage and delegate authority to all the places and pages created during deployment. After installing the WPCP Portlets, locate the PublishPortlet folder within the installed portlets directory. The directory is typically called something like: C:\WebSphere\AppServer\installedApps\WPCPPortlets_WPS_PA_803.ear\WPCPPortlets.war Move that folder to the WPCP install directory (typically something similar to C:\WebSphere\AppServer\installedApps\wcm.ear\wcm.war). Unzip the WPCPPortletsPatch.zip file into this directory to apply the needed patches. If you want to use the sample template, unzip NewsTemplates.zip and import these files into your WPCP project. Note: The inline feature of these templates can be enabled by using alt-e while in edit or preview mode. Note: If you plan on using the sample CompanyNews content type, then you need to register the Story resource collection. See the section later in this document on defining your own content types for a discussion on registering resource collections.

The Portlets The following portlets are provided: Portlet Name Type Description Content Authoring Create, edit, and publish content Tasks Authoring Manage workflow tasks Personalization Authoring Create rules and campaigns Preview Authoring Preview the result of rules and campaigns Reports Authoring Report on content effectiveness Administration Authoring Manage the WPCP authoring server Personalized Content Runtime Displays summary and detail views of

published content Add Content Authoring Quickly add a single content item. Publish Content Authoring Quickly publish new and changed content. Choose Project Authoring Change your current project.

The Authoring IFRAME Portlets These portlets provide all the WPCP Authoring function as a set of the IFRAME portlets. Each of the portlets shows one of the WPCP frames that you see in the WPCP Web interface. For example, here is what the Content portlet displays.

When you execute these portlets, the authenticated session is shared between Portal and WPCP. This allows you to log in once to the portal and not have to log in again when you access WPCP using the portlets. For example, if you logged into the Portal as ‘tara’, and then accessed a page using the Content portlet, you would be logged in as ‘tara’ to WPCP also. This does require that the user ‘tara’ in this example was also defined as a WPCP user (using, for example, the WPCP Administration portlet!).

Configuring the Portlets The Authoring portlets can be configured by both the Portal administrator and the end user. The following settings are available to portal administrators while they are managing the portal application or the individual portlets. Attribute Name Description Default Customization

Level Initialization Level

hostname The hostname of the authoring server.

The fully qualified host name where you installed the portal server.

None ApplicationSettings

context The context root of the authoring server.

wps/wcp ApplicationSettings ApplicationSettings

height The height (in pixels) of the portlet

600 PortletData ApplicationSettings

scrolling Whether scrolling is supported

no PortletData ApplicationSettings

width

The width (in pixels or as a percentage) of the portlet

100% PortletData ApplicationSettings

For example, since height and width can be set in PortletData, a user can configure the Content portlet to have a height of 500 pixels and a width of 50% by completing the form in edit mode as follows.

The Quick Content Portlets The following figure shows a portal page with instances of the Quick Content Portlets. One for adding "Company News", one for adding “IBM News”, one for publishing the content, and one for changing your project.

For add, the content type is in the text and the optional thumbnail shows what the content looks like. The following figure shows what might happen when the user chooses "Add" for IBM News.

The specifics depend on the customer supplied Add template. The Add template can be used to add a structured item, a file or both. The Add template can be the same as the Add template used in the full WPCP interface. The Add template appears in a pop-up window and goes away when Save is selected, leaving the user on the original portal page. Added content is not automatically published. For publish, the user selects the publish button. The user interface shows the server name(s) to publish to. After the publish button is clicked, the user sees which item(s) were published as shown below.

Adding content and publishing content are relative to the user’s current project and edition. When the user selects change project, the following window is displayed.

The user can then choose the appropriate edition under the desired project and then click the “Work On” button to switch to that project and edition. The window does not close automatically, but can be closed by the user. Note: the Change Project window requires IE 5.5 (or higher) or Netscape 6.2. Config Mode After placing the portlet on a page, use the configuration mode to set the following values for the Add Content portlet.

There are two required values. Hostname—This value should be filled in automatically and not need to be set. If it isn't set automatically, then set this to the fully qualified name of the server where you've installed the Portal Server and WPCP. Note: setting hostname to a server other than the server where you installed the Portal Server and WPCP is not supported. Context—Set this value to the context that you set when you installed WPCP. The typical value is /wps/wcp. The rest of the values need to be set either in the configuration mode or the edit mode. Values set in the edit mode will override the values set in the configuration mode, but you should set the values here if you want to have default values.

Content Name—Set this value to the display name you want to show up in your portlet instance. The portlet will put this into the "Click the button below..." line. Since publish might publish multiple content types, you can set this to something generic or to "Company News and IBM News" Thumbnail URI—Set this value to the URI of the optional thumbnail to help the user pick the right portlet if there are multiple types of content that they'll be adding. The URI must include everything except the host name. For example, /wps/wcp/PublishPortlet/ibmnewsthumb.gif Add Template Name—Set this value to the URI of the Add template for this content type. The URI must include everything except the hostname. For example, /wps/PortalContent/templates/IBMNews/Add.jsp For the Publish Content portlet, all the settings are the same as for the Add Content portlet, except that Add Template Name is not required and Publish Server Name is required as shown below.

Publish Server Name—Set this value to a comma separated list of servers that you want to have this portlet instance publish to. Note that for the same instance of the WPCP Portlets application, these values are shared between the Add, Publish and Change Project portlets and do not have to be entered twice. However, additional values (such as Publish Server Name if you configure the Add Content portlet first) need to be entered. The Change Project portlet only requires the hostname, context and thumbnail URI properties as shown below.

Edit Mode After setting the default values for the portlet application using the configure mode, you can customize instances of the portlet by using edit mode. For example, to create additional portlets for adding different types of content, you would set most of the values once using configure mode of the Add Content portlet, and then set the instance specific data for “IBM News” in the edit mode as shown below.

Usage Notes and Limitations for the Quick Content Portlets 1) The add and publish portlets should work with any browser, but have been tested only with Netscape 4.7, Netscape 6.2 , IE 5.5 and IE 6. The Change Project portlet has been tested only with Netscape 6.2, IE 5.5, and IE 6. 2) All EZ Content users must be WPCP users (registered using the WPCP Administration Add User interface). All the actions (add and publish) are relevant to each user's current Project, Edition and Workspace. Typically this means that:

• Either each user sets their project using the Change Project portlet (This requires that the user have a IE 5.5 or above or Netscape 6.2.), or

• Each new user must navigate to the full WPCP once and set themselves to the correct project. (This can be done using the other WPCP portlets, specifically the WPCP Administration page where the user selects "project" and "base" and Work On. This isn't done frequently and can be a pretty easy cookbook set of instructions. This requires that the user have a IE 5.5 (or higher) or Netscape 6.2., or

• All the content being managed via EZ Content is in the default project In general, it is simplest to use the default project for the content managed with these portlets. While you still need to add each user to WPCP, each new user doesn't have to log on to WPCP just to change their default project to another project. 3) All publishes done with EZ Content are incremental publishes of the current user's project. This means if 5 people add content and one clicks Publish, all 5 items are published. The other 4 people's publishes won't fail, but nothing will be published. This might be confusing to those users. 4) Authorities (to add and/or publish) are managed via WPCP ACLs. Which portlets show up for each user (what content types and/or the ability to see the publish portlet) are controlled via Portal groups. The Runtime Portlet This portlet allows you to display published content. The architecture of the portlet allows you to show both summary and detailed views. Which mode (summary or detail) the portlet uses is determined by the presence of the contentID request parameter. If the parameter is not present, such as when the portlet is first displayed, the portlet displays a summary view. If the parameter is present, such as when the user has selected a single piece of content from a summary view, the portlet displays details about the content. You can configure how each of these views is rendered by supplying a set of JSPs™. For example, you can supply a JSP named mysummary.jsp with your own company logo that links to a JSP named mydetails.jsp that shows details about the selected content, as illustrated below.

mysummary.jsp Item 1 Item 2 Item 3

Personalized Content Portlet

1

2

mydetails.jsp Item 1 details

3

Personalized Content Portlet Control Flow

4

contentID=“Item 1” contentID=“null”

Writing Summary JSPs Your Summary JSP is the JSP that the personalized content portlet will use to display a summary list of content. You will want to change the summary JSP in order to show the appropriate summary information for each content type. For example, for news articles, you might want to show the title and for products, you might want to show the product name and price. A summary JSP can take two forms. One form uses only a resource collection name to display content. The other form uses both a resource collection name and a customer defined content spot class, which is in turn mapped to a personalization rule via a campaign. In both cases, an instance of a content spot is passed to the JSP in a request scoped bean named contentSpot. In both cases, the summary JSP uses the getRuleContent method of this bean to access an array of resources to display. When writing a summary JSP that uses just a resource collection name, you will always use the same useBean tag to define the generic content spot to your page. <jsp:useBean class="com.ibm.contentpublishing.resources.PortalContentSpot" id="contentSpot" scope="request"> When writing a summary JSP that uses a customer-defined content spot class, you will use a useBean tag to define your specific content spot to your page. <jsp:useBean class="CompanyNews.GetStories" id="contentSpot" scope="request"> In either case, your JSP will then cast each resource instance from the array obtained from getRuleContent to the customer-defined type. For example, in this code fragment, the resource from the array is cast to the customer defined type CompanyNews.Story. CompanyNews.Story p = (CompanyNews.Story)contentArray[contentIndex]; Once the resource has been cast this way, the resource getters can then be used to get at the resource content to display. In most cases, you will want each item listed in your summary JSP to link back to the personalized content portlet in order to show the details for each selected item. To do this, you include the following lines in your display loop. <A HREF='<portletAPI:createURI> <portletAPI:URIParameter name='contentID' value='<%= java.net.URLEncoder.encode(p.getId()) %>'/> </portletAPI:createURI>'> <%=p.getThetitle()%> </A> In this example, we display the news article’s title (p.getThetitle()). What you display is up to you, however, you must pass the content id back in a request parameter named contentID.

An example of both kinds of Summary templates, CompanyNews/SummaryView_usingCollection.jsp and CompanyNews/SummaryView_usingContentSpot.js, are included in the WPCPPortlets.war file. When to use a specific content spot (and corresponding rules) is up to you. If you just want to show all the content, or a specific number of content items, and if just sorting by modified date and filtering out expired content is sufficient, then there is no need to use a rule. If you want to target the content based on additional metadata, then you need to create a content spot and corresponding rules.

Writing Detail JSP[i7]s As already mentioned, a detail JSP shows the content of an individual resource. This resource is passed to the JSP in a request parameter named contentItem. This bean can be accessed using a usebean tag as shown in the following fragment. Then, the getters of this bean can be used to access the details of the resource. <jsp:useBean class="CompanyNews.Story" id="contentItem" scope="request"></jsp:useBean> To pass control back to the summary portlet (step 4 in the illustrated control flow), the detail JSP can use a Portlet tag to access the URI that invoked the JSP, as in the following example. <A HREF='<portletAPI:createURI></portletAPI:createURI>'>Back</A> An example of a detail JSP, CompanyNews/DetailView_usingContentSpot.jsp, is included in the WPCPPortlets.war file. CompanyNews The sample JSPs use the CompanyNews class (also included in the WPCPPortlets.war file). In most cases, you will be using your own content types, however, if you want to try these portlets with CompanyNews, you will need to define a DB table with a name of nullid.CompanyNews and the following schema:

contentid – character 13 thetitle – varchar 250 thebody – varchar 2000 author – varchar 250 topic – varchar 25 image – varchar 250 modifieddate – date creationdate – date expirationdate – date

While you can use the personalized content portlet with any content schema you define, if you use modifieddate and expirationdate for your last modified date and expiration date respectively, then you can use the default values for this portlet. Further, if you use the names thetitle and thebody for the title or name and detail text respectively, then you can use the summary and detail JSPs by only changing the one line that casts the content type to your defined class. Of course, for existing content types or even new content types where these names don’t make sense, you can and should use whatever property names best fit your needs.

Configuring the Portlet The Personalization Content portlet is highly configurable. The following settings are available.

Attribute Name Description Default Customization Level

Initialization Level

contentspot

The name of the content spot that will determine the list of resources to display in the summary view

Null PortletSettings PortletSettings

collectionname

The name of the resource collection that will be queried to determine the list of resources to display in the summary view

Story PortletSettings PortletSettings

detailjsp

The name of the jsp that will display details about a resource

CompanyNews/DetailView.jsp

PortletSettings PortletSettings

expirationdateproperty

The name of the resource property that contains the expiration date for this content type. If this property is omitted, then all content is shown independent of any expiration date.

null PortletSettings None

helpjsp

The name of a jsp that will be used to provide end user help.

CompanyNews/DisplayHelp.jsp

PortletSettings PortletSettings

portletparms

A list of parameters, separated by spaces, the user can specify and save in portlet data

Topic PortletSettings PortletSettings

querylimit

The maximum number of elements to show in a result set.

20 PortletSettings PortletSettings

sortproperty

The name of the resource property that contains the sort value for this content type. When specified, content is sorted ascending by this property. If this property is omitted, then the content is not sorted.

null PortletSettings None

summaryjsp The name of the jsp that will display

CompanyNews/SummaryView.jsp

PortletSettings PortletSettings

summary data.

windowtitle The name to be used in the Portlet window title.

News PortletData PortletSettings

New instances of the Personalized Content portlet can be added to a page as you would for any portlet. After adding the portlet, you use the edit settings to change the content type being displayed, the name of the summary, detail, and help JSPs to use, and the name of any parameters that are unique to any rules that this portlet might. For example, if you wanted to display IBM News (the NewsStory collection), then after adding a new instance of the portlet to a page, you would use edit to set the following portlet data.

The resulting page should look something like this.

Two important parameters are the expiration date column name and the modified date column name. These parameters can be used to provide some basic control over what is displayed in the portlet without having to write a rule. The expiration date column name specifies the name of your resource class’ expiration date property. If this field is not null, then the portlet will only display content for which the expiration date has not passed. The modified date column name specifies the name of your resource class’ modified date property. If this field is not null, the portlet will sort the resulting content by modified date, with the newest content first. Expiration date and modified date can be specified or omitted independent of each other. If both are omitted, then all the content within the specified collection is shown up to the limit value specified. You can use rules to achieve additional flexibility. The rules you use can use a variety of data points including portlet data. The portletparms parameter is used for specifying a list of portlet data parameters that your rules might require. For example, if the administrator has configured the portlet (by modifying the attribute portletparms in the portlet settings) to show the properties Topic and Industry, the portlet instances (in edit mode) can then be used to set values for Topic and Industry (as shown in the Edit form above). These values can then be used within rules (prefixed with PortletSetting.) as shown in the following figure.

How to create a portlet using your own rules is discussed later. Using Your Own Content Type In the preceding example of adding IBM News, we assumed that the summary, detail, and help JSPs, as well as the resource collection classes, had already been deployed. In this section we will discuss how to create your own resource classes and JSPs. There are a couple of ways you can do this. As long as the end result is that the summary and detail JSPs, as well as the resource classes end up in the portlet Web application, and the resource collection is defined to the runtime server, it will work. We are going to describe what we think is the simplest method, assuming that you already have a working knowledge of WPCP and even might have some of your own content types defined. For our example, we will assume that you already have defined a WSAD project for your WPCP project and that you already have a database table defined for your content. In this example, the table is nullid.ibmnews. Create a new folder for your new content type under the source folder of your project, for example, IBMNews and run the WPCP content wizard to create the IBMNews resource classes. This will create the IBMNews.NewsStory resource classes and hrf file. Copy the JSPs from your deployed portlet (or expanded war file) CompanyNews folder into the /webApplication/IBMNews folder. Note: you will get a compile error on the JSPs because they reference com.ibm.contentpublishing.resources.PortalContentSpot . You can ignore this error, our add the class to your WSAD project’s class path. Edit SummaryView_usingCollection.jsp to change the resource class name from CompanyNews.Story p = (CompanyNews.Story)contentArray[contentIndex]; to

IBMNews.NewsStory p = (IBMNews.NewsStory)contentArray[contentIndex]; If you want to display a property of your content other than “thetitle”, change <%=p.getThetitle()%> as well. In the DetailView JSP, change the class name on the useBean tag to IBMNews.NewsStory. Change the detail properties (thetitle and thebody) as appropriate for the details you want to display for your content type. If you want, you can also change the DisplayHelp JSP. Next, if you don’t have a WPCP project set up, create a new WPCP project based on your war file. We’ll summarize the process here.

1. Export your project as a war file (MyPortletContent.war). 2. Install your MyPortletContent.war file as a Web application on your WPCP

authoring server, start the Web application and regen the application server’s plugin. Be sure to specify the same context you specified when you created your WSAD project.

3. Using the WPCP Administration UI (either with the full Web UI or the IFRAME portlets that you just installed), create a new WPCP project based on the MyPortletContent Web application that you just installed. It is easiest if you specify your WSAD workspace directory for the MyPortletContent project as the input/export directory when creating the project.

4. Switch to the newly created project and import the files from WSAD. If you have WPCP running on the same server that you are serving content from, then this import will register the NewsStory resource collection and you do not have to explicitly register the resource later.

5. wpcp-ize the web.xml file as you would for any WPCP project. Next, you need to define the resource collection to the runtime portal server. How you do this will depend on whether you are using the WPCP author portlets on this server or just using the display portlets. If you are using the authoring portlets on the same server as the display portlets, and you created a WPCP project in the previous step, then the resources are already registered. If this is just a runtime system, then you can use PZNLOAD or the WPCP Resource console to define the resource collections. Define a publish server, and use the ContextRoot parameter, specifying the context root of the Web application defined when you installed the WPCP Portlets, for example http://willrc.raleigh.ibm.com/wps/PersAdmin/publishtarget?ContextRoot=wps/WPS_PA_1001 Publish your project. This will place your class files and JSPs into the portlet on the target server and publish any instances of IBM News that you might have created. Finally, create a new instance of the Personalized Content portlet and configure it as discussed earlier.

If you have content within the corresponding database table, it will be displayed. Otherwise, you’ll have to author content using the WPCP authoring portlets or the Quick Content portlets and publish the content to your portal server. The following figure shows the new portlet along side the original Company News portlet.

Using Rules for Greater Flexibility In order to use a rule within CompanyNews or your own content portlet, the first step is to create a content spot. We will create a content spot for our newly created IBM News NewsStory. Select the appropriate source folder, right mouse click and choose New à Content Spot as shown below.

Set the content type to IBMNews.Story and make up an appropriate name for the content spot (such as GetIBMNews) as shown below, and then click on Finish to create the content spot GetIBMNews.

Modify the SummaryView_usingContentSpot.jsp’s useBean tag as follows <jsp:useBean class="IBMNews.GetIBMNews" id="contentSpot" scope="request"> Modify the line that casts each resource instance as follows IBMNews.NewsStory p = (IBMNews.NewsStory)contentArray[contentIndex]; Now switch back to your WPCP project and do the following: .

1. Create a rule to select the content. For example, select content whose NewsStory.Topic is equal to current RequestAttributes.PortletSetting.Topic

2. Map your content spot GetIBMNews to your rule. 3. Publish your rule and campaign 4. Update the portlet settings to change the summaryjsp to the summary JSP that

uses your content spot, and specify the name of the content spot you created as shown below. (Alternatively, you can make another copy of the portlet in order to set these parameters.)

5. Finally, specify the Topic to match for each portlet instance as discussed earlier.

Summary Using the authoring portlets, WPCP users can access authoring function from inside the Portal. Using the Personalization Content portlet, end users can access content published from WPCP. These portlets are customizable by both the Portal administrator and the user.

Trademarks

Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

ActiveX, Microsoft, Windows, Windows NT(R), and the Windows logo are trademarks or registered trademarks of Microsoft Corporation in the United States, or other countries, or both.

UNIX is a registered trademark of The Open Group.

Linux is a registered trademark of Linus Torvalds.

Other company, product, and service names, which may be denoted by a double asterisk(**), may be trademarks or service marks of others.

Notices

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AND ANY ASSOCIATED CODE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OR CONDITIONS OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Copyright International Business Machines Corporation 2003. All rights reserved. US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.