IBM Lotus Web Content Management Rendering Portlet Documentation:

Transcription

1 Lotus Lotus Web Content Management Version 6.1 Version 6 Release 1 IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

2

3 Lotus Lotus Web Content Management Version 6.1 Version 6 Release 1 IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

4 Note Before using this information and the product it supports, read the information in Notices on page A-1. This edition applies to version 6, release 1 of Lotus Web Content Management/WebSphere Portal (product number 5724-E76) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation 2000, US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Overview Setting up the JSR 286 Web Content Viewer Installation prerequisites Installing the portlet Adding the portlet to a page Enabling support for Web content pages Enabling support for Web content page templates 2-2 Enabling support for search seedlist Enabling support for dynamic portlet display titles 2-3 Uninstalling a portlet Undoing skin modifications for dynamic portlet titles Disabling support for Web content pages Deleting the Web module Working with Web content pages Web Content page templates Creating a Web content page Dynamic Web content page selection Working with the JSR 286 Web Content Viewer Using the JSR 286 Web Content Viewer Using the dynamic portlet display feature Customizing error messages Coordination with other portlets Differences with the existing Web content rendering portlet Usage of authoring tool components URL generation using PathCmpnt and URLCmpnt tags Previewing content on Web content pages Leveraging the standard search seedlist 1.0 feature Enabling a Web content site for search Using the custom metadata field search support Using portal site analysis with the JSR 286 Web Content Viewer Enabling site analysis logging Understanding the site analysis log Notices A-1 Trademarks A-3 Copyright IBM Corp. 2000, 2009 iii

6 iv : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

7 Overview The IBM Lotus Web Content Management Rendering Portlet provided with this package is a solution which updates and improves how the rendering of Web content is performed in IBM WebSphere Portal. While the existing Web Content Viewer portlet (referred to in the WebSphere Portal documentation as a "rendering portlet") has evolved throughout several versions to implement sophisticated Web content rendering functions, it is still based on the deprecated IBM Portlet API. By contrast, the new JSR 286 Web Content Viewer has been entirely redeveloped based on the Java Portlet Specification 2.0 (JSR 286). In addition to the benefits afforded by JSR 286, the JSR 286 Web Content Viewer in this package also enables other features for Web content management, such as a new Web content portal page type and support for the standard search seedlist 1.0 format. The JSR 286 Web Content Viewer was developed to address several key issues that have surfaced from discussions with our customers. Specifically this updated portlet focuses on the following areas: v Performance: The portlet provides optimized rendering logic, does not require sessions for rendering, and can leverage the portlet fragment cache. v Integration: The new concept of Web content pages has been introduced in WebSphere Portal to allow closer alignment between the portal's page navigation and the content structure within your Web content libraries. v Ease-of-use: The portlet includes a redesigned Edit Shared Settings and Configure portlet mode that allows easier and faster configuration of the portlet. In addition to the focus areas described above, the IBM Lotus Web Content Management Rendering Portlet package includes the following benefits and features: v You can attach Web Content Management sites and site areas to portal pages. v The JSR 286 Web Content Viewer does not need to be configured on Web content pages because it renders the default content attached to the page. v Site designers can create templates that predefine Web content page layouts with portlets and content authors, and then create Web content pages based on the templates. v Sessions are no longer required for rendering Web content for both anonymous and authenticated portal users. v Broadcasting of content links to the corresponding Web content pages is more flexible. v You can generate site analysis output to help measure how often a content item is visited. v The portlet uses standard search seedlist 1.0 format for better integration with search crawlers. v You can view Web content search results within the portal context and Web content pages. v The portlet supports the portal Web 2.0 theme. v You can restrict configuration settings in the Configure portlet mode, so that the settings cannot be changed in the Edit Shared Settings mode. v Communication between the JSR 286 Web Content Viewer and other portlets has been improved through the use of a public render parameter. v The display title for the portlet supports multiple languages. Copyright IBM Corp. 2000,

8 1-2 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

9 Setting up the JSR 286 Web Content Viewer Before you can begin working with the JSR 286 Web Content Viewer, you must install the portlet and then enable the portlet to work with the portal. Installation prerequisites Before installing the JSR 286 Web Content Viewer, review the software requirements. v WebSphere Portal and Web Content Management V6.1, fix pack 3 v Lotus Web Content Management cumulative interim fix 23 (CF23) for V PM02697 v Lotus Web Content Management interim fix PM05948 (see fixes directory) Interim fixes can be downloaded from the IBM Fix Central support web site. Translation note: The IBM Lotus Web Content Management Rendering Portlet included with this package provides only an English translation. Other languages are not supported. Installing the portlet Before you can add the JSR 286 Web Content Viewer portlet on a portal page, you must install the portlet. As with other portlets, perform the installation using the portal's administration portlets. Before installing a portlet, be aware of the following requirements: v An administrator must have the Manager role on the portal to install portlets, so ensure that you log in with a user ID that has Manager role access rights. v You cannot install a portlet more than once. If you want two instances of a portlet application or portlet, use the copy command to create a second instance. During the installation, the portlet state is set to active, and a new rule is automatically added to Access Control that defines the user who installed the portlet as the owner, granting management access for that portlet. The user must assign the appropriate user roles to the desired users and groups, so that these users and groups can access and use that portlet. 1. Log in to the portal as an administrator. 2. Click Administration in the tool bar. 3. Under Portlet Management in the navigation tree, click Web Modules. 4. Click Install. 5. Enter the location of the ilwwcm-localrenderingportlet-jsr.war file or click Browse to find the location of the ilwwcm-localrenderingportlet-jsr.war file. 6. Click Next. 7. Click Finish. After the installation finishes, a message appears at the top of the screen indicating a successful installation. If there are any problems during the process, an error message appears in the Manage Web Modules page. Click the View Details link to examine the error log. Note: There are special considerations to be made when deploying portlets in a clustered environment. Refer to Managing portlets in your cluster in the WebSphere Portal information center. Copyright IBM Corp. 2000,

10 Adding the portlet to a page By default, portlet applications and portlets are set to an active state after installation. After installing the JSR 286 Web Content Viewer, you can add the portlet to a portal page. Portlets are added to the page by submitting a search and then selecting from the list of available portlets. Only portlets available in the portlet list can be placed on the selected page. Once you place a portlet in a row or column, you cannot modify the row or column without removing all portlets from that outlined container. 1. Log in to the portal as an administrator. 2. Click Administration in the tool bar. 3. Under Portal User Interface in the navigation tree, click Manage Pages. 4. Navigate to the page where you want to add a portlet. 5. Click the Edit Page Layout icon (small pencil) next to the page name. 6. Click Add Portlets. 7. In the list of available portlets, click the box next to the portlet title Web Content Viewer (JSR 286) to select the portlet, then click OK. You can also search for the portlet title if the list of portlets is long. 8. Click OK. 9. Click Done. Enabling support for Web content pages Web content pages provide the ability to easily attach a site or site area to a portal. Before you can use this feature, you must enable support for Web content pages in the portal. 1. Log in to the WebSphere Application Server administrative console ( hostname.example.com:10027/ibm/console). 2. Click Resources Resource Environment Resource Environment Providers. 3. Click WP ConfigService. 4. Under Additional Properties, click Custom Properties. 5. Click New, and enter the property name wcm.pages.enabled. 6. Set the string value to true. 7. Click OK, and save the changes to the master configuration. 8. Restart the portal. Ensure that you can use Web content page templates by following the instructions in Enabling support for Web content page templates. Enabling support for Web content page templates To create new Web content pages based on template pages, you need to define a label in your portal page structure that serves as the root node for the templates. All pages created under this label are considered to be template pages. 1. Log in to the portal as an administrator. 2. Click Administration in the tool bar. 3. Under Portal User Interface in the navigation tree, click Manage Pages. 4. Click Content Root, and then click New Label. 5. Enter a title for the new label, and click OK. 6. Under Portal Settings in the navigation tree, click Custom Unique Names. 7. Navigate to the new label you created, and click the Edit icon. 2-2 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

11 8. In the Unique name field, enter wps.content.template.root, and click OK. Enabling support for search seedlist 1.0 If you want to use Portal Search to crawl your Web content, you must enable seedlist 1.0 support for the Portal Search crawler. 1. Log in to the portal as an administrator. 2. Click Administration in the tool bar. 3. Create the WCM_FORMAT parameter for the search service. a. Under Search Administration in the navigation tree, click Manage Search. b. Click Search Services, and click the Edit icon for the search service that you are using. c. Enter WCM_FORMAT in the Parameter key field, and enter 1.0 in the New parameter value field. d. Click Add Parameter, and then click OK. 4. Create a new search collection. a. Click Manage Search Search Collections. b. Create a new search collection for your Web content. Be sure that the new search collection uses the portal search service edited in the previous steps. 5. Enable search support for Web Content Management. a. Log in to the WebSphere Application Server administrative console ( hostname.example.com:10027/ibm/console). b. Click Resources Resource Environment Resource Environment Providers. c. Click WP ConfigService. d. Under Additional Properties, click Custom Properties. e. Click New, and enter the property name wcm.config.seedlist.version. f. Set the string value to 1.0. g. Click New, and enter the property name wcm.config.seedlist.servletpath. h. Set the string value to /seedlist. i. Optional: Click New, and enter the property name wcm.config.seedlist.metakeys, and set the string value to a comma-delimited list of your own metadata (for example, <metakey1, metakey2>). See Leveraging the standard search seedlist 1.0 feature on page 7-1 for more details on that parameter. j. Click OK, and save the changes to the master configuration. k. Restart the portal. Enabling support for dynamic portlet display titles To enable the dynamic title function of the JSR 286 Web Content Viewer, you must update the portal skin that is used to render the portlet on a page. Currently the portlet title of standard portlets can only be changed dynamically during runtime using JavaScript. To accomplish this, the corresponding Document Object Model (DOM) element that contains the portlet title must be uniquely identifiable for each portlet on the page that uses dynamic titles. The file that controls the portlet title in the skin is Control.jsp and is located in the wp_profile_root/ installedapps/node_name/wps.ear/wps.war/skins/html/skin_name directory (where skin_name is name of the skin, which is configured on the page). To enable the static title to be replaced later at runtime, the title needs to be wrapped within the skin using the HTML elements <span> or <div>. The element must be uniquely identifiable by using the id Setting up the JSR 286 Web Content Viewer 2-3

12 attribute because it might appear multiple times on a portal page. In your portlet skin, locate the portlettitle tag that retrieves the static portlet title, and surround it with a <span> HTML element. Here is an example for the default IBM skin: <span id="title.<portal-skin:portletid/>"> <portal-skin:portlettitle> <portal-fmt:problem bundle="nls.problem"/> </portal-skin:portlettitle> </span > Note: The <portlal-skin:portletid> JSP tag is part of the JSP tag libraries provided with the portal. More information about the JSP tag libraries can be found in Tags used by the portal JSPs in the WebSphere Portal information center. Uninstalling a portlet To uninstall the JSR 286 Web Content Viewer, you must not only uninstall the portlet but also update the portal configuration to remove changes made when deploying the portlet. Undoing skin modifications for dynamic portlet titles If you enabled the ability to display dynamic portlet titles for any skins, you must undo the skin modifications you made to those skins. Open the Control.jsp file for each modified skin and delete the <span> HTML element that is highlighted in the sample given below. Important: Do not delete the tags inside the <span> element. <span id="title.<portal-skin:portletid/>"> <portal-skin:portlettitle> <portal-fmt:problem bundle="nls.problem"/> </portal-skin:portlettitle> </span> Disabling support for Web content pages As part of the uninstallation for the JSR 286 Web Content Viewer, disable the support for Web content pages. 1. Disable the wcm.pages.enabled property. a. Log in to the WebSphere Application Server administrative console ( hostname.example.com:10027/ibm/console). b. Click Resources Resource Environment Resource Environment Providers. c. Select WP ConfigService. d. Under Additional Properties, click Custom Properties. e. Click the property wcm.pages.enabled. f. Set the string value to false. g. Click OK, and save the changes to the master configuration. h. Restart the portal. 2. Because the label created in the portal to host the Web content page templates is no longer required, you can delete it. a. Log in to the portal as an administrator. b. Click Administration in the tool bar. c. Under Portal User Interface in the navigation tree, click Manage Pages. d. Click Content Root. e. Locate the label with the unique name wps.content.template.root, and click the Delete icon. 2-4 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

13 f. Click OK. Deleting the Web module Complete the uninstallation process by deleting the Web module for the JSR 286 Web Content Viewer. The action of deleting the Web module from the portal removes all instances of the JSR 286 Web Content Viewer portlet that have been placed on portal pages. Moreover, all files and resources related to the portlet are removed from the portal. 1. Log in to the portal as an administrator. 2. Click Administration in the tool bar. 3. Under Portlet Management in the navigation tree, click Web Modules. 4. Locate ilwwcm-localrenderingportlet-jsr.war in the list of Web modules, and click the Delete icon. 5. Click OK. Setting up the JSR 286 Web Content Viewer 2-5

14 2-6 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

15 Working with Web content pages A Web content page is a portal page that displays Web content from a site or site area by mapping the page to the Web content site structure in your Web Content Management system. When you add the JSR 286 Web Content Viewer to a Web content page, the portlet automatically renders the default content of the attached site or site area. In addition to displaying the default content, the JSR 286 Web Content Viewer provides a dynamic broadcasting option that selects the best matching Web content page when selecting links to other content items. Prerequisite: Before you can use this new feature, you need to enable it. Refer to Enabling support for Web content pages on page 2-2 for details. Web Content page templates To simplify the creation of Web content pages, it is possible to define pre-configured pages that can be used as templates when creating new Web content pages. Prerequisite: Before you can start to define your template pages, you need to create a page label that serves as the root node for all of your template pages. Refer to Enabling support for Web content page templates on page 2-2 for details. To create a new template page, navigate to the root page label you created and add a new portal page under this label. As with any portal page, you can configure the template page and add any pre-configured portlets you wish. Whenever a new Web content page is created from a template, the page layout, portlets on it, and the configuration of the portlets is copied to the new Web content page. Important: When a new Web content page is created, no reference to the template page used to the page is maintained. This means that all changes that you apply to a template page after Web content pages have been created from this template are not propagated to any other Web content pages that already exist. Although it is not recommended, it is possible to use existing Web content pages as template pages for new Web content pages. But you must take special care with regards to the sharing of public render parameters. Because a public render parameter is used to broadcast the context of links to other content items to the Web content page used to render the linked content item, the sharing of this parameter is limited to one specific Web content page. Otherwise all other pages containing the JSR 286 Web Content Viewer would also render the same content item after a broadcast to another page. To prevent this, by default Web content pages control the parameter sharing though the use of a unique parameter sharing scope page configuration parameter. The topic Public render parameters in the WebSphere Portal information center contains more information about public render parameter and the sharing scope. If you want to use a Web content page as template page for new Web content pages, you should either remove the param.sharing.scope parameter from the template page parameters or be aware of the implication of sharing the public wcm context render parameter across Web content pages. If no sharing scope page parameter is found on the template page used to create a new Web content page, a new unique value is used to automatically add the sharing scope parameter to the new Web content page during creation. Another aspect that must be considered when using a Web content page as a template page is the fact that the new dynamic broadcasting feature selects the first page found that is associated with the site or site area where a selected content item resides. Using a Web content page as a template page could result in selecting the template page as the page to display a content item. Creating a Web content page Create a new Web content page and associate it with a Web Content Management site or site area. Copyright IBM Corp. 2000,

16 The simplest way to create a Web content page is to use the administration portlet provided in portal, and that is the process described here. Alternatively, you can also attach content from a Web content site or site area on any existing portal page using the Advanced options section in the page properties. Doing this will essentially make the portal page a Web content page. This also means that a unique public render parameters sharing scope is set on the page if no scope was defined yet. 1. Log in to the portal as an administrator. 2. Click Administration in the tool bar. 3. Under Portal User Interface in the navigation tree, click Manage Pages. 4. Click New Web Content Page. 5. Enter a title for the new page. 6. Optional: Enter a friendly URL that is displayed as part of the URL whenever you go to that page. The friendly URL is intended to be concise and easy to read and remember. It can also be useful to give the page a friendly URL that matches the title of the site area that is attached to the page. 7. In the Web Content Options sections, select a site or site area to associate with the page. 8. Optional: Choose a template page or select the No template option. 9. Click OK. Dynamic Web content page selection The JSR 286 Web Content Viewer provides a link broadcasting feature that leverages the Web Content Management context that is attached to a Web content page, using that context to dynamically look up the best matching Web content page to render the linked content item. When the JSR 286 Web Content Viewer is configured to use the Dynamically select a web content page link broadcasting option and a user selects a link to a content item, several tests are performed to determine which Web content page should be used to render the selected item. The same mechanism is used when previewing Web content on Web content pages or when selecting search results produced from the search seedlist 1.0 feature. 1. An ordered list with all parent site areas and sites of the selected content item is created. If the selected item itself is a site or site area, it is part of that list. The order in the list matches the order in the Web Content Management content hierarchy with the topmost parent (site) being the last item in the list and the direct parent of the selected item (or the item itself) being the first item. 2. Based on this ordered list, a lookup is performed to find the Web content page that the current user has access to and that is mapped to the first site areas or sites that has a page mapping. If multiple pages are found that map equally well to the same site or site area, the first one found is selected, unless the current page is among the pages found, in which case the current page is used. 3. If a Web content page can be determined in the previous test, the selected content item is rendered on this page. If no page could be found, the Web Content Management servlet is used to render the item. Note: To render a content item, the dynamically selected target page needs to contain at least one JSR 286 Web Content Viewer that has been configured to receive links from other portlets. 3-2 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

17 Working with the JSR 286 Web Content Viewer After you have installed the JSR 286 Web Content Viewer and added it a page, you can specify various configuration settings to customize the behavior and appearance of the portlet. The individual aspects of the JSR 286 Web Content Viewer that you can configure include the following: v Selecting content to display. v Profiling the Web Content Viewer portlet. v Defining custom portlet titles. v Defining inter-portlet communication settings. v Locking configuration settings and defining default values. Using the JSR 286 Web Content Viewer The JSR 286 Web Content Viewer is used to display local Web content on portal pages. The actual content to be rendered can be defined in the Edit Shared Settings or Configure mode of the portlet. For detailed information on individual configuration settings, refer to the online help provided with the JSR 286 Web Content Viewer. To configure the content to be rendered by the JSR 286 Web Content Viewer, select one of the following options from the drop-down menu located in the portlet title bar. v Select Edit Shared Settings to specify settings for all users of this instance of the portlet. Changes you make in the Edit Shared Settings mode are not reflected in other instances of the portlet. v Select Configure to specify settings for all users of all instances of the portlet, regardless of the page on which the portlet instance appears. You can also lock some settings, so that these locked settings cannot be changed in the Edit Shared Settings mode of the portlet. Note: Once the configuration settings of a portlet have been saved through the Edit Shared Settings mode, the default Configure mode settings are overwritten for this instance of the portlet. Any changes you make in the Configure mode will no longer affect this instance of the portlet. To restore an individual setting of the portlet to its Configure mode default value, click the Reset link next to the setting in the Edit Shared Settings mode. If you want to restore all settings to their Configure mode values, you will need to delete the portlet from the page and add it again. Using the dynamic portlet display feature With the JSR 286 Web Content Viewer, you can dynamically set the portlet title, which is displayed in the portlet title bar. Before setting the portlet title for the first time, you must update the skin used by the portlet. For detailed information, refer to Enabling support for dynamic portlet display titles on page 2-3 The portlet title can be set in the portlet's Configure mode or Edit shared settings mode. You can specify the title text either with a static phrase or with a resource bundle, which allows the portlet title to be displayed in different languages. Note: The dynamic title is not supported with the PortalWeb2 theme. 1. Select either Configure or Edit shared settings from the drop-down menu located in the portlet title bar. Copyright IBM Corp. 2000,

18 2. Select a title option. v Select Use default title to display the title that was set for the portlet in the portal administration. v Select Set the following title, and enter a title that should be used for all languages. If the input field is left empty, the default title is used. To explicitly set the title to be empty, you must enter a blank. v Select Select from Resource bundle, and enter the fully qualified name of the Java resource bundle that is used to set the title, depending on the user's language (for example, com.mycompany.myapplication.myresourcebundlename). The structure of the resource bundle must follow the specification defined by the Java java.lang.resourcebundle class. The key that is used to look up the title in the resource bundle is javax.portlet.title. The resource bundle must be located in a directory that is part of the classpath of the JSR 286 Web Content Viewer. The preferred way to do this is to create a new shared library that contains the custom resource bundle files using the WebSphere Application Server administrative console. Creating a new shared library that contains the resource bundle allows a clean separation of the custom resource bundle code from the base WebSphere Portal code. After creating a shared library, you need to add it to the classpath of WebSphere Portal application server classloader. For details about creating shared libraries and adding shared libraries to the classloader's classpath, refer to the Shared library collection topic in the WebSphere Application Server information center. Customizing error messages If an error occurs during rendering, the JSR 286 Web Content Viewer shows an error screen. The default error screen provides a standard error message, which is shown on every type of error, and a more detailed error message. The detailed error message provides information about the cause of the error and is displayed when you click the View details link. You can customize the default error screen, and you can create your own custom JSP file that is used to display error messages. 1. Create a customized error JSP file. a. Copy the original error.jsp file from wp_profile_root/installedapps/node_name/ PA_WCMLRingPortJSR286.ear/ilwwcm-localrende.war/jsp/html directory to create your custom error JSP file. Almost everything in the original JSP file can be changed according to your requirements. The essential part that should be retained in your error JSP file, if it is intended to display the actual cause, is: <%-- use errorbean from request --%> <jsp:usebean id="errorbean" scope="request" type="com.ibm.portal.portletui.messages.statusmessagebean" /> <% String msg = errorbean.getmessage(); %> The variable msg contains the message of the error. In the original error.jsp this message is only displayed in a separate popup window when a user selects View details link. In some cases it might not be desired to show this message to a user. 2. Configure the JSR 286 Web Content Viewer to use the customized error JSP file. a. Log in to the portal as an administrator. b. Click Administration in the tool bar. c. Under Portlet Management in the navigation tree, click Portlets. d. Locate the Web Content Viewer (JSR 286) portlet. e. Click Configure Portlet. f. Edit the value of the parameter ERROR_JSP, and set the path to your customized error JSP file as the parameter value. Storing JSP files: You can store JSP files in one of two locations: 4-2 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

19 v Within the wp_profile_root/installedapps/node_name/pa_wcmlringportjsr286.ear/ilwwcmlocalrende.war directory of your server. When storing JSP files in this directory, enter the path to your custom error JSP relative to the directory. v Within any other Web application running on the portal. When referencing JSP files in another Web application, use the following path: contextpath;jsppath. For example: /wps/customapplication;/jsp/error.jsp. g. Click OK, and then click OK again. Coordination with other portlets The JSR 286 Web Content Viewer provides support for a public render parameter, which allows coordination with other portlets and can be used to set the Web content item that should be rendered by the rendering portlet. The public render parameter as defined by the Portlet Specification 2.0. The fully qualified name of the public render parameter that is supported by the JSR 286 Web Content Viewer is The value of the public render parameter must be a valid path to a Web content item that should be rendered by the portlet. Note: The JSR 286 Web Content Viewer only honors the public render parameter if it is configured to receive links from other portlets. Working with the JSR 286 Web Content Viewer 4-3

20 4-4 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

21 Differences with the existing Web content rendering portlet There are some important differences and limitations between the JSR 286 Web Content Viewer and the existing standard Web Content Viewer portlet that is based on the IBM portlet API. Usage of authoring tool components When rendering authoring tool components in the JSR 286 Web Content Viewer, you must account for some changes in the way placeholder tags are specified and in the way users navigate to pages containing authoring tool components. Authoring tool element design In general, you use placeholder tags to display authoring tool elements: <a href="<placeholder tag="href"/>"> <Placeholder tag="name"/> </a> Using the link displayed by the rendering portlet for the authoring tool element sample given above causes the authoring user interface to open in the current Web browser window, browser tab, or within an IFrame. If the authoring tool element will be rendered by the JSR 286 Web Content Viewer and if the placeholder tag is of type href as seen above, the end attribute of the placeholder tag must be set in the element design to contain &ispopup=false. <a href="<placeholder tag="href" end="&ispopup=false" />"> <Placeholder tag="name"/> </a> If the authoring user interface accessed through the authoring tool element is opened in a new Web browser window, browser tab, or within an IFrame, it is not necessary to specify end="&ispopup=true", because true is the presumed default value. Note: Specifying ispopup in the end attribute of the placeholder tag does not interfere with rendering in the standard Web Content Viewer portlet. Further information on the design of authoring tool elements is available in the Authoring tools element design examples topic in the WebSphere Portal information center. Page navigation and authoring tool components Currently when a user clicks on a link that refers to an authoring tool component and the link is rendered in the JSR 286 Web Content Viewer, the user is redirected to a portal page hosting the authoring portlet rather than opening the authoring user interface within the rendering portlet itself. When the user finishes working in the authoring user interface, the user has to navigate back to the new rendering portlet manually to see the changes. Because of this behavior it is recommended that you adapt the design of your authoring tool elements to open the authoring user interface in a new browser window. In this way the user does not need to navigate back to the previously shown rendering portlet and must only close the popup window and refresh the rendering portlet manually to see the changes. Copyright IBM Corp. 2000,

22 URL generation using PathCmpnt and URLCmpnt tags There are some special considerations to keep in mind when using URLCmpnt and PathCmpnt tags to create URLs to other Web content items from within your content. Using the URLCmpnt tag The URL component tag URLCmpnt can be used to create URLs to content items in a presentation template. If the attribute mode="portal" is set, the content item is displayed through a content viewer portlet. URLs to the JSR 286 Web Content Viewer differ from URLs to the standard Web Content Viewer rendering portlet. When the URLCmpnt tag is used in content rendered in the JSR 286 Web Content Viewer, the tag creates URLs in an updated format that the portlet understands. When the tag is used from a standard rendering portlet, the tag creates URLs in the older format. This means that the URLCmpnt tag cannot be used to link from the standard Web Content Viewer to the JSR 286 Web Content Viewer or vice versa. Using the PathCmpnt tag The path component is used to create the base part of a URL in Web content. Typically, the base part is extended by some string that identifies the content to be displayed. If the path component is used inside the context of a JSR 286 Web Content Viewer, the generated URL has the updated URL format and thus cannot be displayed with the existing standard Web Content Viewer. Adding query parameters to URLs The standard Web Content Viewer uses regular URL parameters to get information about which content to display. TheJSR 286 Web Content Viewer does not support URL parameters, since this would be against the JSR 286 portlet specification. Instead the JSR 286 Web Content Viewer makes use of render parameters to specify the content to be displayed. Typically render parameter handling is done by the portlet internally. But in some cases an application developer needs to be aware of how render parameters are handled for example when creating a custom JSP file to be used with a Web Content Management JSP component. When the JSP component is processed in the context of the standard Web Content Viewer, request parameters can be directly read from the request object. However, in the context of the JSR 286 Web Content Viewer, this is no longer possible. In this case the parameter must be read from the RenderingContext object in the Web Content Management API. The RenderingContext object provides the method getrequestparameters for this purpose. Note: Adding URL parameters to a regular portal URL will not affect the JSR 286 Web Content Viewer. For this purpose you must use the URLCmpnt or PathCmpnt tag. Additional URL query parameters, like those used with the standard Web Content Viewer, can be appended to the URLs generated by these tags. 5-2 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

23 Previewing content on Web content pages If you have enabled support for Web content pages, you can preview content items in the authoring portlet as they will appear on Web content pages. Before attempting to preview content, ensure that Web content pages are enabled, as described in Enabling support for Web content pages on page 2-2. Before the introduction of Web content pages, a content item could only be previewed as a standalone web page, which was as a predefined local or remote portal page that contained the standard Web Content Viewer. With the introduction of Web content pages, you can now preview a content item as part of a Web content portal page, showing the content item in a more accurate context. The content item is previewed on the Web content portal page that is associated with the content items site or site area. Important: It is essential that there be a JSR 286 Web Content Viewer on the associated Web content page and that the portlet is configured to receive links from other portlets. Previewing content items on Web content pages does not work with the standard Web Content Viewer portlet. 1. Enable the preview function in the authoring portlet. This step only needs to be done once. a. Select either Edit Shared Settings or Configure from the drop-down menu located in the title bar of the authoring portlet. b. In the Previewing Options section, select Allow authors to preview content dynamically in a Web Content portal page. c. Click OK. 2. Preview content as a Web content page. a. Select a content item in the authoring portlet. b. Click Preview, and then select Preview as a Web Content portal page. A new browser window opens displaying the content item on its associated Web content page. Limitation: Currently you can only preview content, site areas, and sites on Web content pages. Other Web content item types, such as components or presentation templates, cannot be previewed as Web content pages. Also, the JSR 286 Web Content Viewer cannot be used to preview Web content with the Preview as local portal page or Preview as a remote portal page preview options. Copyright IBM Corp. 2000,

24 6-2 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

25 Leveraging the standard search seedlist 1.0 feature The search feature included in the JSR 286 Web Content Viewer package leverages the standard seedlist 1.0 format and allows you to search for Web content using the Search Center. It also makes use of Web content page type to render content found in the search results on the corresponding Web content page. Support is also provided to include custom metadata fields from the Web content item into the search results. Enabling a Web content site for search After setting up search seedlist support, you can update your Web Content Management sites to use the search service and search collection you created. Before configuring your sites in the authoring portlet, you must enable seedlist 1.0 support for the Portal Search crawler. For detailed information, refer to Enabling support for search seedlist 1.0 on page Open the authoring portlet, and edit the site that you want to enable for the search crawler. 2. Select Searchable in the Search section of the site form. 3. Select the search service and the search collection you created for seedlist 1.0 support. 4. Enter a valid user ID and password. 5. Save the site. Note: The content source created when a site is made searchable uses the credentials of the user entered here. Only items to which the specified user has read access or above will be included in the search. A manager or administrator may need to edit an existing site and enter their user name and password to enable all items in a site to be searchable. The next time the search collection is updated, the content on this site will be added to the search collection. Using the custom metadata field search support With the JSR 286 Web Content Viewer package, custom metadata fields specified on content items are added to the search seedlist as metadata information. Add the names of the text element from your content that should be included in the search results to the wcm.config.seedlist.metakeys property, as described in Enabling support for search seedlist 1.0 on page 2-3. If you want to add more than one text element, separate them with commas. The name of the text element on your content item that should be included in the search seedlist must match the name configured for this configuration key. For example, set wcm.config.seedlist.metakeys=language,region in the WP ConfigService resource environment provider, and add a Web Content Management text component with the name language to a content item or authoring template. In your content item you can enter the value german into the text component for the language. After saving the content item, the search crawler will add the value german into a metadata field called language within the search seedlist. Then you can filter the search results based on your metadata information. Copyright IBM Corp. 2000,

26 7-2 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

27 Using portal site analysis with the JSR 286 Web Content Viewer The JSR 286 Web Content Viewer implements site analysis logging, which enables you to gather usage statistics of each instance of the rendering portlet. While site analysis logging works with the SiteAnalyzerPortletLogger logger for the standard Web Content Viewer portlet as well as for the JSR 286 Web Content Viewer, the JSR 286 rendering portlet leverages the enhanced logging capabilities of WebSphere Portal that have been introduced with the interim fix PK Enabling site analysis logging To take advantage of the site analysis logging available for the JSR 286 Web Content Viewer, you need to configure the WP SiteAnalyzerLogService service and activate the SiteAnalyzerJSRPortletLogger service. 1. Log in to the WebSphere Application Server administrative console ( hostname.example.com:10027/ibm/console). 2. Click Resources Resource Environment Resource Environment Providers. 3. Click WP SiteAnalyzerLogService. 4. Configure the WP SiteAnalyzerLogService service by defining the logging options. v Site analysis log file name v Backup log file name v Date format v Name of the encoding to use for the output file v Interval at which the log file is backed up v Names of cookies that should be logged Detailed steps and appropriate parameters for this configuration are described in the Configuring WebSphere Portal for site analysis logging topic in the WebSphere Portal information center. 5. Activate the SiteAnalyzerJSRPortletLogger logger through the WP SiteAnalyzerLogService by defining the parameter SiteAnalyzerJSRPortletLogger.isLogging and by setting the parameter value to true. 6. Save your changes, and restart the portal. Understanding the site analysis log The site analysis log uses the NCSA Combined log format, which is a combination of NCSA Common log format and three additional fields: the referrer field, the user_agent field, and the cookie field. The IBM WebSphere Portal site analysis log is: PortalServer_root/log/sa_date_time.log where PortalServer_root is the WebSphere Portal root directory and date_time is the date and time the file was created. The current (active) log file is named sa.log. Note: The WP SiteAnalyzerService might be configured to use different filenames. The following example displays a sample entry in the site analysis log as it is written by the JSR 286 Web Content Viewer if the SiteAnalyzerJSRPortletLogger is enabled jdoe [22/Nov/2008:22:11: ] "GET /Portlet/5_8000CB1A00U6B02NVSPH1G20G1/ Web_Content_Viewer_(JSR_286)/Web%20Content%2fTestSite01%2fTestSiteArea01 %2fTestContent01?PortletPID=5_8000CB1A00U6B02NVSPH1G20G1&PortletMode=view&PortletState=normal Copyright IBM Corp. 2000,

28 &RequestType=render&PUBLIC_CONTEXT=%2fWeb%20Content%2fTestSite01 %2fTestSiteArea01 %2fTestContent01 HTTP/1.1" " 6_8000CB1A00UR402F0JC25U1O25/MyPage" "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-us; rv: ) Gecko/ Firefox/ " "JSESSIONID=0000JwIm04xm7btVLwzCj9Qo-uj:-1" The table describes each field of the log format: Field in the Example Log Field Name and Explanation host The IP address of the HTTP client that sent the request - rcf931 The identifier used to identify the client making the request. If the client identifier is not known, the field is set to the hyphen character (-). jdoe username The user ID for the client. If the user ID is not known, the field is set to the hyphen character (-). [22/Nov/2008:22:11: ] date:time timezone The date and time of the HTTP request. "GET /Portlet/[...] HTTP/1.1" request The HTTP method, the URI of the requested resource, and the version of HTTP used by the client. The URI is composed of the following elements: v The identifier Portlet. v v v v The ID of the JSR 286 Web Content Viewer instance that is requested. The administrative name of the JSR 286 Web Content Viewer (Note: This name is always the same unless the portlet has been cloned.). The context path of the rendered Web Content Management item encoded in UTF-8. A query string containing the following parameters: PortletPID The ID of the JSR 286 Web Content Viewer instance that is requested PortletMode The mode in which the portlet is rendered. Note that the JSR 286 Web Content Viewer writes log entries only in its view mode. PortletState The portlet window state RequestType The request type (note that the JSR 286 Web Content Viewer writes log entries only for render requests), This is followed by a list of all request parameters that are available to the JSR 286 Web Content Viewer instance as UTF-8 encoded key-value-pairs. 200 statuscode The HTTP status code for the request. -1 bytes The number of bytes of data transferred from the client as part of the request. A value of -1 indicates that the number of bytes is unknown. " 6_8000CB1A00UR402F0JC25U1O25/MyPage" "Mozilla/5.0 [...]" referrer The referrer in case of portlet site analysis log entries identifies the portal page on which the JSR 286 Web Content Viewer instance is rendered. user_agent The type of Web browser used by the client. 8-2 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

29 Field in the Example "JSESSIONID=0000JwIm04xm7btVLwzCj9Qo-uj:-1" Log Field Name and Explanation cookies The name and value of a cookie that was sent to the client browser as part of the request. If multiple cookies were sent, the list is delimited by the semicolon character. Using portal site analysis with the JSR 286 Web Content Viewer 8-3

30 8-4 : IBM Lotus Web Content Management Rendering Portlet Documentation: Installing and Using the JSR 286 Web Content Viewer

31 Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo , Japan 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 "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 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. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: Copyright IBM Corp. 2000, 2009 A-1