Atg portal devguide
Upcoming SlideShare
Loading in...5
×
 

Atg portal devguide

on

  • 677 views

Atg portal devguide

Atg portal devguide

Statistics

Views

Total Views
677
Views on SlideShare
677
Embed Views
0

Actions

Likes
0
Downloads
25
Comments
0

0 Embeds 0

No embeds

Accessibility

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    Atg portal devguide Atg portal devguide Document Transcript

    • Version 10.2 Portal Development Guide Oracle ATG One Main Street Cambridge, MA 02142 USA
    • ATG Portal Development Guide Product version: 10.2 Release date: 04-30-13 Document identifier: PortalDevelopmentGuide1304221916 Copyright © 1997, 2013 Oracle and/or its affiliates. All rights reserved. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited. The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing. If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable: U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government. This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group. Portions of this product may contain the following: EditLive Authoring Software Copyright © 2004 Ephox Corporation. All rights reserved. Some code licensed from RSA Security, Inc. Some portions licensed from IBM, which are available at http://oss.software.ibm.com/icu4j/. This product may include software developed by the Apache Software Foundation (http://www.apache.org/). Spell checking software from Wintertree Software Inc. The Sentry Spell Checker Engine © 2000 Wintertree Software Inc. This product also includes software developed by the following: Free Software Foundation, GNU Operating System, Incanto, JSON.org, JODA.org, The Dojo Foundation, Adobe Systems Incorporated, Eclipse Foundation and Singular Systems. The software is based in part on the work of the Independent JPEG Group. This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services. For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/ topic/lookup?ctx=acc&id=docacc. Access to Oracle Support: Oracle customers have access to electronic support through My Oracle Support. For information, visit http:// www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired. The MIT License Copyright (c) 2007 FlexLib Contributors. See: http://code.google.com/p/flexlib/wiki/ProjectContributors
    • Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
    • ATG Portal Development Guide v Table of Contents 1. Introduction ..................................................................................................................... 1 Portals and Gears .......................................................................................................... 1 What Is a Portal? ................................................................................................... 1 What Is a Gear? .................................................................................................... 1 Gear Definitions and Gear Instances ........................................................................... 2 PAF Services ........................................................................................................ 2 PAF Administration Pages ........................................................................................ 2 Security Levels ..................................................................................................... 3 Gear Implementation Overview ........................................................................................ 3 Other Resources ........................................................................................................... 4 Portal Administration Guide ..................................................................................... 4 Helloworld Example Gear and Portlet ......................................................................... 5 ATG Documentation Set .......................................................................................... 5 API Documentation ............................................................................................... 5 2. Portal Requests and the Filter Chain ........................................................................................ 7 Portal Context .............................................................................................................. 7 GearContext ........................................................................................................ 8 The Portal Request ........................................................................................................ 8 HTTP Parameters and Request Headers ....................................................................... 8 Request Path Elements ........................................................................................... 8 Gear Servlet Request .............................................................................................. 9 Portal Objects ...................................................................................................... 9 Mapping Hostnames and URLs to Portals ................................................................... 10 Object Lookup .................................................................................................... 11 The Portal Response ..................................................................................................... 11 Response URIs .................................................................................................... 11 GearServletResponse ............................................................................................ 11 The Portal Filter Chain ................................................................................................... 11 Portal Filter Chain Elements ............................................................................................ 13 Portal Server Filter ............................................................................................... 13 Gear Filter .......................................................................................................... 14 Display Filter ...................................................................................................... 15 Device Filter ....................................................................................................... 15 DeviceOutput Filter .............................................................................................. 16 Portal Filter ........................................................................................................ 16 Community Filter ................................................................................................. 17 Page Filter ......................................................................................................... 18 Access Filter ....................................................................................................... 18 Offline Filter ....................................................................................................... 19 ATG Dynamo 5 Style Attributes ............................................................................... 19 Page Template Dispatch Servlet ....................................................................................... 20 3. The Portal Page Structure ................................................................................................... 21 How Gear Rendering Works ............................................................................................ 21 Portal Templates .......................................................................................................... 22 Page Template .................................................................................................... 22 Layout Template .................................................................................................. 26 Gear Title Template .............................................................................................. 29 Wireless Templates ....................................................................................................... 30 The Shared Deck Template ..................................................................................... 30 The Full Deck Template ......................................................................................... 30 4. Gears and the Portal Application Framework ............................................................................ 31
    • vi ATG Portal Development Guide How Portal Pages Are Rendered ...................................................................................... 31 How the PAF Processes Page Requests ....................................................................... 31 Tag Libraries and Gear Development ................................................................................ 32 Link URLs .................................................................................................................. 32 URL Usage ......................................................................................................... 33 Form Handling ............................................................................................................ 33 Gear Form Handling ............................................................................................. 33 Gear Configuration Form Handling ........................................................................... 33 JSP Form Handling ............................................................................................... 35 Configuring Gears to Work with Persistent Data Repositories ................................................... 35 Keeping Gears Synchronized with Each Other ...................................................................... 36 Performance Recommendations ...................................................................................... 36 Avoid Inefficient Java Methods ................................................................................ 36 Additional Performance Resources ........................................................................... 37 5. Portal Security ................................................................................................................. 39 Security Roles ............................................................................................................. 39 Predefined Security Areas .............................................................................................. 39 Security Tags .............................................................................................................. 40 Role Test Tags ..................................................................................................... 40 Role Test Methods ............................................................................................... 41 includeOnly Tag .................................................................................................. 42 Include Filter .............................................................................................................. 42 J2EE Security .............................................................................................................. 43 Secure Socket Layer Security .......................................................................................... 44 6. Designing a Gear .............................................................................................................. 45 Gear Modes ............................................................................................................... 45 Display Modes ............................................................................................................ 46 Device Outputs ........................................................................................................... 46 Matrix of Gear Modes, Display Modes, and Device Outputs ...................................................... 47 User Interface Look and Feel Recommendations ................................................................... 47 Minimum Gear Sizing Rules .................................................................................... 47 Gear Dimensions ................................................................................................. 47 Portal and Gear Roles ................................................................................................... 48 Gear Alerts ................................................................................................................ 48 Gear Administration Considerations .................................................................................. 48 Localization Considerations ............................................................................................ 49 Creating Configurable, Localizable Content in Gears ...................................................... 49 Localized Gear Names and Descriptions ..................................................................... 50 Extending an Existing Gear ............................................................................................ 50 Example: A Discussion Forum Gear ................................................................................... 51 Roles ................................................................................................................ 51 Choosing Display Modes ....................................................................................... 51 7. Creating Gear Page Fragments ............................................................................................. 55 HTML Considerations .................................................................................................... 55 Layout Considerations ................................................................................................... 56 Accessibility Recommendations ....................................................................................... 56 Page Elements ............................................................................................................ 56 Tag Library Declaration ......................................................................................... 56 DSP Page Initialization .......................................................................................... 57 Gear Environment Initialization ................................................................................ 57 Gear Configuration Page Fragments .................................................................................. 58 Developing Install Configuration Pages ...................................................................... 59 Developing Initial, Instance, or User Configuration Pages ................................................ 61
    • ATG Portal Development Guide vii Example: A Document Exchange User Configuration Page ............................................... 63 Message Handling in Page Fragments ............................................................................... 64 I18nMessageProcessor .......................................................................................... 64 Adding Messages ................................................................................................ 64 Message Handling Example .................................................................................... 65 Avoiding Gear Instance Conflicts ...................................................................................... 66 Naming Conventions ............................................................................................ 66 Wireless Gear Page Fragments ........................................................................................ 66 Wireless Markup Language ..................................................................................... 67 Wireless Device Emulator ....................................................................................... 67 8. Gear Packaging and Deployment .......................................................................................... 69 Gear Manifests ............................................................................................................ 69 The Gear Manifest File Format ................................................................................. 70 Wireless Gear Deployment Considerations .......................................................................... 72 Gear Assembly .................................................................................................... 72 Gear Manifest ..................................................................................................... 72 9. Developing and Deploying Portlets ....................................................................................... 73 Portlets and Gears ....................................................................................................... 73 Comparison of Portlets and Gears ............................................................................ 73 Developing a Portlet .................................................................................................... 74 Helloworld Portlet ................................................................................................ 74 Portlet Class ....................................................................................................... 74 Portlet Deployment Descriptor File ........................................................................... 75 Web Application Deployment Descriptor .................................................................... 76 Portlet JSPs ........................................................................................................ 77 Helloworld Servlet Beans ....................................................................................... 78 Portlet Deployment Tool ................................................................................................ 78 Running the Portlet Deployment Tool ....................................................................... 79 Portlet Deployment Tool Arguments ......................................................................... 79 10. Web Services for Remote Portlets ........................................................................................ 81 WSRP Overview ........................................................................................................... 81 Producer Overview .............................................................................................. 82 Consumer Overview ............................................................................................. 86 Producer Administration ................................................................................................ 92 Starting Up the Producer ....................................................................................... 92 Producer Database Configuration ............................................................................. 92 Using the Producer Administration UI ........................................................................ 92 Importing Portlet Descriptions ................................................................................ 93 Consumer Administration .............................................................................................. 93 Starting Up the Consumer Module ........................................................................... 94 Consumer Database Configuration ........................................................................... 94 Using the Consumer Administration UI ...................................................................... 94 Adding a New Producer to a Consumer ..................................................................... 94 Modifying Producer Information .............................................................................. 97 Deleting a Producer ............................................................................................. 97 Configuring a ProxyPortlet Instance .......................................................................... 97 11. Adding Gear Alerts .......................................................................................................... 99 Alerts Overview .......................................................................................................... 99 Alert Services Provided by the PAF and Baseline Gears .......................................................... 100 Baseline Gear Events ........................................................................................... 100 Baseline Gear Scenario Templates ........................................................................... 101 PAF Events ....................................................................................................... 101 Adding Custom Alert Messages to Gears .......................................................................... 102
    • viii ATG Portal Development Guide Sample GearMessage Extension ............................................................................. 103 Adding GearMessagePublisher to the Gear ................................................................ 105 Sample Sending Code ......................................................................................... 106 Sample dynamoMessagingSystem.xml File ................................................................ 106 Adding the Alerts Element to the Gear Manifest File .................................................... 107 Creating a Resource Bundle Properties File ................................................................ 108 Creating an E-mail Template File ............................................................................ 109 Creating an Alert Instance Configuration Form ........................................................... 109 Extending the Scenario User Interface ...................................................................... 110 Configuring a Scenario ........................................................................................ 112 Adding Alert Channels ................................................................................................ 112 Configuring an AlertChannel Component ................................................................. 113 AlertHandlerInterface .......................................................................................... 114 Registering the New Alert Channel ......................................................................... 115 Configuring Alert Channel Preferences ..................................................................... 115 Source Handlers and Target Handlers .............................................................................. 116 Source Handlers ................................................................................................ 116 Target Handlers ................................................................................................. 116 Administrative Alerts and Framework Alerts ...................................................................... 117 12. Creating a Custom Portal ................................................................................................. 119 Creating a New Portal ................................................................................................. 119 Copying the Portal Template ................................................................................. 119 Editing Portal Framework Files ............................................................................... 120 Setting Up the Portal Database .............................................................................. 122 Starting Up Your Custom Portal Module ................................................................... 122 Further Customization ......................................................................................... 122 Customizing Portal Appearance ..................................................................................... 123 Manifest File Formats for Customizing Portal Appearance .............................................. 123 Manifest File Headers .......................................................................................... 124 Color Palette Manifests ........................................................................................ 124 Stylesheet Manifests ........................................................................................... 125 Page Template Manifests ...................................................................................... 126 Layout Template Manifests ................................................................................... 127 Gear Title Template Manifests ................................................................................ 128 Customizing Portal Authentication .................................................................................. 129 Authentication Pages .......................................................................................... 129 Specifying Authentication Page Locations ................................................................. 129 A. Portal Manifest Reference .................................................................................................. 131 Portal Manifest Elements .............................................................................................. 131 <portal-manifest> Element ................................................................................... 131 Gear Manifest Elements ............................................................................................... 132 <gear-definitions> Element ................................................................................... 132 <gear-definition> Element .................................................................................... 132 <servlet-context> Element .................................................................................... 133 <gear-modes> Element ....................................................................................... 133 <gear-mode> Element ........................................................................................ 133 <display-modes> Element .................................................................................... 134 <display-mode> Element ..................................................................................... 134 <dimensions> Element ........................................................................................ 134 <dimension> Element ......................................................................................... 134 <error-handling> Element .................................................................................... 135 <instance-parameters> Element ............................................................................. 136 <user-parameters> Element .................................................................................. 136
    • ATG Portal Development Guide ix <alerts> Element ............................................................................................... 136 <alert-message> Element ..................................................................................... 136 Page Template Manifest Elements ................................................................................... 137 <page-templates> Element ................................................................................... 137 <page-template> Element .................................................................................... 137 Layout Template Manifest Elements ................................................................................ 139 <layout-templates> Element ................................................................................. 139 <layout-template> Element .................................................................................. 139 Gear Title Template Manifest Elements ............................................................................. 141 <gear-title-templates> Element .............................................................................. 141 <gear-title-template> Element ............................................................................... 141 Color Palette Manifest Elements ..................................................................................... 143 <color-palettes> Element ..................................................................................... 143 <color-palette> Element ...................................................................................... 143 <images> Element ............................................................................................. 143 <image> Element .............................................................................................. 143 <entity> Element ............................................................................................... 144 <color> Element ................................................................................................ 144 Color Palette Example ......................................................................................... 144 Stylesheet Manifest Elements ........................................................................................ 145 <styles> Element ............................................................................................... 145 <style> Element ................................................................................................ 145 The Portal Manifest DTD .............................................................................................. 147 B. PAF Tag Library Reference ................................................................................................. 151 paf:layout ................................................................................................................ 152 paf:titlebar ............................................................................................................... 152 paf:hasRole ............................................................................................................... 152 paf:hasCommunityRole ................................................................................................ 153 paf:hasGearRole ......................................................................................................... 153 paf:renderTab ............................................................................................................ 154 paf:defaultTab ........................................................................................................... 154 paf:currentTab ........................................................................................................... 154 paf:encodeURL .......................................................................................................... 155 paf:context ............................................................................................................... 155 paf:include ............................................................................................................... 156 Index .............................................................................................................................. 157
    • x ATG Portal Development Guide
    • 1 Introduction 1 1 Introduction This document provides guidelines for developing portals and “gears” that can be easily integrated into ATG’s Portal Application Framework (PAF). The ATG Portal Administration Guide also focuses on the ATG Portal solution. Portals and Gears What Is a Portal? A portal is a collection of Web content, services, and people. Portals control access through registration, authentication, and security levels. Portals contain member subsets known as communities, which can also be customized and administered independently of the larger portal. Portals can be used to build online communities, to facilitate collaboration among portal members, for Enterprise Application Integration (EAI), and for aggregating content and tools from diverse sources into an easily accessible location. What Is a Gear? A gear is a Web utility or content area presented to a portal user within a portal page. Stock tickers, discussion forums, document exchange repositories, or news headline areas are examples of gears. Many gears allow the user to customize their content or appearance. Gears are also configurable by a community leader, who can change settings that are applicable for a particular community. For example, a discussion group gear might have membership policy settings that only the community leader can change. Gears can integrate syndicated content and services as well as enterprise content and applications. To a developer, a gear is a small Web application consisting of the JSP files, Java classes, and data or content that comprise the service a portal user sees. The gear retrieves dynamic content and displays it on the portal page. Gears use many common services provided by the Portal Application Framework. Gears are separately installable, and their layout on a Web page is customizable. They have different display modes, which reflect their size and appearance. Gears also have different gear modes, which reflect the functional mode a gear is in. Finally, gears can be configured for output on various devices (such as a browser or a wireless device). Gears generally have a set of associated permissions as well. In the case of a discussion forum gear, for example, there might be security surrounding who can read, post to, or lead a forum. A properly designed gear deploys easily into the Portal Administration Framework. Once this is accomplished, the gear can be customized by a portal administrator, a community leader, or an end-user.
    • 2 1 Introduction Gears and Portlets Portlets are the Java standard for portal components (JSR 168). ATG Portal supports the JSR 168 standard. You can deploy any standards-compliant portlet on ATG Portal. You can develop portal components as portlets, for full portability, or as gears. Gear Definitions and Gear Instances A gear definition is the generic definition of a gear that is registered a single time in the PAF. A gear instance is a version of the gear definition that is customized for or used in a community. Thus, a portal will have a single definition of a gear, but can have several instances of the same gear. Gear instances can be shared among communities. Gear settings that can be changed on a per instance basis are called instance parameters. PAF Services The PAF is the infrastructure for developers to create, deploy, and administer gears and their related communities, pages, and layouts. The PAF also enables portal users and administrators to customize the gears on their portal pages. The changes users and community leaders make to a gear are stored in a database. The PAF includes portal page layout templates and utilities for administering portal security and determining which gears are made available to users. The PAF provides a variety of services to facilitate gear functionality and implementation. These services include: • Caching — Gear content is stored in order to improve performance. • Error-handling — Presenting helpful error messages in a format that reflects the look and feel of the portal. • Logging — Recording and analysis of user activity. • Navigation — Structuring gear page parameters in a way that makes pages readily accessible. • Nucleus components — Access to other ATG components. • Repositories — Data persistence. • Security — Login, logout, and user authentication. • User Customization — Accepting and retaining user customization settings. PAF Administration Pages The Portal is administered through a series of HTML pages that are made available when you install ATG Portal. These pages make it possible for you to: • Add gears • Add color palettes • Add portal page templates • Add gear layout templates • Add region fragments • Add gear title templates
    • 1 Introduction 3 • Add stylesheets • Set user privileges • Administer communities • Specify default content • Specify default layouts • Specify default colors For information on installing, using, and administering ATG Portal, refer to the ATG Portal Administration Guide. Security Levels You will need to build access control checks into your gears to ensure that various gear administration and other portal privileges as well as page and gear content are restricted to those to whom you have assigned the appropriate roles. ATG Portal recognizes the following access control levels: Security Level Description Portal Administrator Installs the portal software; adds new gears, colors, and layouts to portal; creates community folders, adds communities, manages gear folders Community Leader Adds members to a community; adds and removes gears and pages; sets default colors and layouts for each page Community Member Typically has read/write permissions within community. Community leaders can set security as desired. Community Guest Typically has read-only permissions within community. Community leaders can set security as desired. Registered User A registered, logged-in portal user. Anonymous User A non-registered or non-logged-in portal user. For additional information on access control tags, refer to the Gears and the Portal Application Framework (page 31) chapter of this manual. For additional information on portal and community administration, refer to the Community Administration chapter of the ATG Portal Administration Guide. Gear Implementation Overview The implementation of a gear will vary widely, depending on what the gear is intended to do. This section provides an overview of the steps involved in the implementation process. With the exception of the first step and final steps, many of these steps do not need to take place serially. For example, the page development and the Java class development can occur concurrently, though clearly they must be coordinated with each other.
    • 4 1 Introduction 1. Plan your gear by deciding what it should have in terms of: • functionality • gear modes • display modes • device outputs • alerts • JSP pages • Java classes • custom tag libraries 2. Select or develop the portal page, possibly by using the templates supplied with ATG Portal, such as <ATG10dir>/Portal/paf/starter/portal/paf-dar/portal/templates/page/html/shared.jsp. If you use the page templates provided with ATG Portal, then you do not need to develop a new portal page template. (This is a portal implementation task, but it is closely related to the gear implementation process.) For an example of a container JSP page, see The Portal Page Structure (page 21) chapter in this manual. 3. Develop the gear page fragments. For examples of portions of gear page fragments, see the Creating Gear Page Fragments (page 55) chapter in this manual. 4. Develop the Java classes, persistent storage, and custom tag libraries or Nucleus components needed to carry out the back-end functionality required by the gear. 5. Develop the gear manifest XML file needed to register your gear with the PAF. For information on the required XML format, refer to the Gear Packaging and Deployment (page 69) chapter in this manual. 6. Package, deploy, and register your gear. For information on packaging, deployment, and registration refer to the Gear Packaging and Deployment (page 69) chapter in this manual and to the Portal Administration chapter in the ATG Portal Administration Guide. For an example that illustrates packaging and deployment see the Gear Installation Examples chapter of the ATG Portal Administration Guide. 7. Test your gear and revise as needed. Other Resources Portal Administration Guide In addition to this manual, the ATG Portal Administration Guide explains gear registration, gear and portal configuration, security, and administration.
    • 1 Introduction 5 Helloworld Example Gear and Portlet The Portal-Examples module includes a sample gear called helloworld. You can use it as a starting point to experiment with building and deploying your own gears. The helloworld gear includes source files, instructions, and build scripts that demonstrate all the steps necessary to add your own gears to your Portal Application Framework. These files are included in the ATG Portal installation. This gear is placed in the <ATG10dir>/Portal/helloworld directory. See the ATG Portal Administration Guide for more information. ATG Portal also includes a sample portlet called helloworld. The helloworld portlet is located in the <ATG10dir>/Portlet/helloworld directory. ATG Documentation Set Because the Portal module is integrated with the Oracle ATG Web Commerce platform, many of the application development procedures and techniques are not unique to ATG Portal and are documented elsewhere in the ATG Documentation Set. All of the development practices, services, and methodologies documented elsewhere can be used in portal development. Consequently, the ATG Portal documents are not a standalone documentation set. In this manual, there are many pointers (either links or cross-references, depending on whether or not you are reading this online) to the major resources available in other parts of the ATG Documentation Set. You will also need to consult the documentation for the application server on which you are running ATG Portal. API Documentation The ATG Platform API Reference provides Javadoc explaining the accessor methods and properties made available by the PAF tag library and by all published ATG Java classes.
    • 6 1 Introduction
    • 2 Portal Requests and the Filter Chain 7 2 Portal Requests and the Filter Chain ATG Portal is implemented as a J2EE Web application, using Java Servlet Technology. When a portal user enters the portal, an HTTP request is made to a Web server. The request is received by the Web server and handed off to the Portal container. The Portal container creates and initializes a portal context for the request. The Portal container may optionally authenticate the client and fire events or alerts. The request is handled by a series of servlet filters known as the Portal Filter Chain. Each filter in the chain handles a specific task for the request and passes the request to the next filter. At the end of the Portal Filter Chain, the Portal request is dispatched to its target, typically a JSP or Servlet. The target servlet generates content to send back to the portal user via the response object, using Portal gears and other portal assets. (The process of rendering the page is covered in the Gears and the Portal Application Framework (page 31) chapter.) Once the Portal container is finished with the response, control of the response is handed back to the Web server. This chapter describes the Portal context, response and request and the Portal Filter Chain. It includes the following sections: Portal Context (page 7) The Portal Request (page 8) The Portal Response (page 11) The Portal Filter Chain (page 11) Portal Filter Chain Elements (page 13) Portal Context The PortalContext is an object that represents a portal in a particular state, using these properties: portal page community displayMode ATG Portal includes a request-scoped component that makes Portal objects accessible as properties of a Nucleus component. This component, /atg/portal/PortalContext, provides access to Portal objects through these properties. You can use the PortalContext properties to access the state of the portal associated with the request. Access to these properties in the PortalContext enables you to, for example, use targeting rules like “Users whose PortalContext.community is Tennis.” Each attribute of the PortalContext is set by an element of the Portal Filter Chain.
    • 8 2 Portal Requests and the Filter Chain GearContext The GearContext interface extends PortalContext. Its getGearMode method provides access to the gear mode. The GearContext also provides access to the community, display mode, page, and portal made available by the PortalContext. Each gear renders in a particular GearContext. You can access the current GearContext from a gear by accessing the GEARSERVLETREQUEST attribute, part of the HttpServletRequest. To create your own GearContext you can use the GearContextImpl class The Portal Request The Portal request object encapsulates all the information contained in a client request. The Portal request implements atg.portal.servlet.PortalServletRequest, which is a subinterface of javax.servlet.http.HttpServletRequest. Some of the information in the Portal request is directly transmitted from the client using the HTTP protocol. Other information is derived from data encoded in the HTTP request by the Portal Filter Chain. HTTP Parameters and Request Headers HTTP protocol parameters and request headers can be accessed by the original HTTP request. The following methods exist in the HTTPServletRequest to access these elements: getHeader getHeaders getHeaderNames getParameter getParameterNames getParameterValues Refer to Java Servlet Technology, v.2.3 (Servlets) for information on access to HTTP protocol parameters and request headers. Request Path Elements Request path elements of the original HTTP request may be accessed by the Portal request. The context path, servlet path and path info are obtained from the original request URI and exposed via the Portal request. The following methods exist in the PortalServletRequest to access this information: getContextPath getServletPath getPathInfo getPortalContextPath getPortalServletPath getPortalPathInfo For example, suppose the Portal Context is set as follows:
    • 2 Portal Requests and the Filter Chain 9 Portal Context Path /portal Portal Servlet Path /*.jsp Page Template Context Path /templates Page Template Servlet Path /html/shared.jsp In such a case, a request for /portal/myportal/home.jsp results in the following path elements: contextPath /templates servletPath /html/shared.jsp pathInfo null portalContextPath /portal portalServletPath /myportal/home.jsp portalPathInfo null Gear Servlet Request The gear request object encapsulates all information from a portal that a gear might need when the gear is rendered. The atg.portal.servlet.GearServletRequestImpl class implements the GearServletRequest interface. This single interface extends the GearContext, HttpServletRequest, PortalContext, PortalServletRequest, and ServletRequest interfaces and thus makes available all the applicable portal, gear, and request attributes, including: Gear GearMode GearSession GearSessionId Community DisplayMode Page Portal Portal Objects Various portal objects may be accessed by the Portal request. These objects can be accessed by request attributes or by PortalServletRequest methods. The atg.portal.servlet.Attribute interface defines constants for the PortalServletRequest attributes. The full name of each of the request attributes defined by Attribute.CONSTANT_NAME (for example, Attribute.COMMUNITY), but for simplicity we refer to the request attributes by their constant names in this chapter.
    • 10 2 Portal Requests and the Filter Chain Object Description Request Attribute Constant PortalServletRequest Method Portal Base-level object that describes a portal. Provides access to role management and portal objects. PORTAL getPortal Community A collection of users and content who share a common purpose. The community might be a company department, such as a human resource department, or it might be a group of users with a common interest, such as a softball community. COMMUNITY getCommunity Page A page is a component of a community that allows for the arrangement of content. Content is arranged in regions and gears. PAGE getPage DisplayMode An object indicating the mode the portal should render in. Modes include full, shared and popup. DISPLAYMODE getDisplayMode Device An object encapsulating information about the portal client device. Contains information about preferred MIME types and user agent. DEVICE getDevice Mapping Hostnames and URLs to Portals ATG Portal includes a component, /atg/portal/framework/PortalObjectResolver. The PortalObjectResolver maps hostnames or URL fragments to portals. The page dispatcher can refer to the PortalObjectResolver in order to route the request to the appropriate portal, based on the hostname or URL fragment mapping. The portal names are specified in the /atg/portal/framework/PortalManager component. You can configure this behavior using the following PortalObjectResolver properties: Property Description hostToPortalMap A mapping between hostnames and portal names. These mappings override URL mappings. The form for this map is: host_name=portal_id,host_name2=portal_id2 urlToPortalMap A mapping of URL fragments to portal names. The form for this map is: url=portal_id,url2=portal_id2. The URL fragment must not contain any / characters.
    • 2 Portal Requests and the Filter Chain 11 Object Lookup Access to objects outside the scope of the portal may be accessed using the request’s lookup method. The following name-spaces are available. dynamo:/ java:/ The Portal Response The Portal response object encapsulates all information returned to the client. The Portal response implements atg.portal.servlet.PortalServletResponse, which is a subinterface of javax.servlet.http.HttpServletResponse. Information is transmitted to the client via HTTP headers and the message body of the response. The Portal response can set HTTP response headers. The response also provides a number of convenience methods to redirect and send errors in the response. Refer to Java Servlet Technology, v2.3 (Servlets) for information on these convenience methods and on setting HTTP response headers. Response URIs The response provides support for the encoding of Portal-specific URIs. The response object can encode URIs, for example, to change the portal’s display mode or to request a specific portal or community page. The following methods exist in the PortalServletResponse to support the encoding of Portal-specific URLs: String encodePortalURL(String url) Encodes a portal URL with the session ID and portal-specific parameters String encodePortalURL(String url,PortalContext context) Encodes a portal URL with the specified portal context. This lets you change the PortalContext associated with the request. GearServletResponse The gear response object extends the ServletResponse, HttpServletResponse, and PortalServletResponse interfaces, adding the encodeGearURL method, which encodes a return gear URL, encoding session ID and gear-specific parameters and, optionally, a gear context. The Portal Filter Chain The Portal Filter Chain is a sequence of servlet filters that accept the incoming HttpServletRequest and HttpServletResponse objects, modify them with Portal-specific attributes, and dispatch them for servicing. Servlet filters are a standard element in Java Servlets 2.3.
    • 12 2 Portal Requests and the Filter Chain The Portal Filter Chain is configured in the Web application’s deployment descriptor file, which is found in WEB- INF/web.xml. A standard Portal Filter Chain is defined in the deployment descriptor for the default Portal, located at <ATG10dir>/Portal/paf/paf-dar/portal/WEB-INF/web.xml. For many Portal applications, the standard Portal Filter Chain will work as-is and can be copied into your Web application’s deployment descriptor. However, the Portal Filter Chain is open, and the elements of the standard Portal Filter Chain can be replaced, removed, or supplemented, depending on the needs of your application. The deployment descriptor file uses the standard DTD for J2EE Web applications, http://java.sun.com/dtd/web- app_2_3.dtd . A portal filter is configured in a <filter> tag, with various parameters configured in <init- param> tags. For example, the first filter in the Portal Filter Chain is configured like this: <filter> <filter-name>PortalServerFilter</filter-name> <display-name>PortalServerFilter</display-name> <description>Responsible for wrapping the HttpServletRequest and HttpServletResponse objects.</description> <filter-class>atg.portal.servlet.PortalServerFilter</filter-class> <init-param> <param-name>loggingDebug</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>loggingWarning</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>loggingError</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>loggingInfo</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>portalServletRequestFactory</param-name> <param-value>ctx:dynamo:/atg/portal/servlet/PortalServletFactory </param-value> </init-param> <init-param> <param-name>portalServletResponseFactory</param-name> <param-value>ctx:dynamo:/atg/portal/servlet/PortalServletFactory </param-value> </init-param> <init-param> <param-name>wrapping</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>initD5StyleAttributes</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>portalServletRequestName</param-name> <param-value>PortalServletRequest</param-value> </init-param> </filter> Each Portal filter has logging parameters that correspond to the logging levels of Nucleus components:
    • 2 Portal Requests and the Filter Chain 13 loggingDebug loggingWarning loggingError loggingInfo The other parameters of the Portal filters are described in the Portal Filter Chain Elements (page 13) section. Filters are assigned a filter mapping in the deployment descriptor, which maps the filter to a URL pattern in the request. Each element of the standard Portal Filter Chain has a URL pattern of /*, which means that each request is passed to each element of the chain in the order they are listed in the deployment descriptor. Your Web application may need to be customized with other filter mappings. Portal Filter Chain Elements The standard ATG Portal Filter Chain consists of the following filter elements: Portal Server Filter (page 13) Gear Filter (page 14) Display Filter (page 15) Device Filter (page 15) DeviceOutput Filter (page 16) Portal Filter (page 16) Community Filter (page 17) Page Filter (page 18) Access Filter (page 18) Offline Filter (page 19) In addition, this chapter describes the Page Template Dispatch Servlet (page 20), which is not a part of the Portal Filter Chain, but which handles many Portal requests. Portal Server Filter Filter Class Name: atg.portal.servlet.PortalServerFilter This filter wraps the incoming HttpServletRequest and HttpServletResponse objects with PortalServletRequest and PortalServletResponse objects respectively. This filter also determines the property values for portalContextPath, portalServletPath and portalPathInfo. This filter should always be at the head of the filter chain. Here are the request attributes set by the Portal Server Filter. These attributes are defined in the atg.portal.servlet.Attribute interface.
    • 14 2 Portal Requests and the Filter Chain Request Attribute Constants Description PORTALSERVLETREQUEST A reference to the PortalServletRequest object. PORTALSERVLETRESPONSE A reference of the PortalServletResponse object. PORTALCONTEXTPATH A string representing the context path of the portal. Equivalent to the context path of the HttpServletRequest. PORTALSERVLETPATH A string representing the servlet path of the portal. Equivalent to the servlet path of the HttpServletRequest. PORTALPATHINFO A string representing the path info of the portal. Equivalent to the path info of the HttpServletRequest. Portal Server Filter Parameters The following init parameters can be used to control the behavior of the Portal Server Filter: Parameter Description portalServletRequestFactory A reference to a component that creates PortalServletRequest objects. portalServletResponseFactory A reference to a component that creates PortalServletResponse objects. wrapping A boolean that determines whether the filter should wrap the HttpServletRequest/HttpServletResponse with the PortalServletRequest/PortalServletResponse and pass them down the filter chain. Defaults to false, which means that the HttpServletRequest and HttpServletResponse are passed on. initD5StyleAttributes Sets request attributes compatible with the ATG Dynamo 5 portal product. portalServletRequestName The name of a nucleus component to bind PortalServletRequest to. Defaults to / PortalServletRequest. Gear Filter The gear filter determines which gear a request pertains to. The gear filter is invoked in the Portal Filter Chain after the PortalServerFilter. It is responsible for setting up the gearId and gearMode query parameters used when encoding gear URLs with the encodeGearURL method. These default to paf_gear_id and paf_gm and are set by the gearIdParameterName and gearModeParameterName init parameters, respectively.
    • 2 Portal Requests and the Filter Chain 15 Display Filter Filter Class Name: atg.portal.servlet.DisplayFilter The display filter is used to set the request’s DISPLAYMODE attribute. The Display Filter determines the display mode of the request by examining the displayMode query parameter. If the displayMode query parameter does not exist, the display mode is set to the default display mode. The display mode may be either full or shared. See Display Modes (page 46) in the Designing a Gear chapter. The following attribute is set when the filter is invoked: Attribute Description DISPLAYMODE A reference to the DisplayMode object. Display Filter Parameters The following init parameters can be used to control the behavior of the Display Filter: Parameter Description defaultDisplayModeName The name of the default display mode for the portal. Defaults to shared. displayModeParameterName The name of the display mode query parameter. Defaults to paf_dm. initD5StyleAttributes Sets request attributes compatible with the ATG Dynamo 5 portal product. Device Filter Filter Class Name: atg.portal.servlet.DeviceFilter The Device Filter creates and initializes the Portal request’s DEVICE attribute. The mimeTypes property is derived from the HTTP accept header. The preferred MIME type is determined by matching the Device Filter’s mimeTypePreferences parameter to one of the accept headers, using a regular expression. For example, if the mimeTypePreferences parameter in the Device Filter is set to: text/html text/vnd.wap.wml text/xml And the request contains the following accept headers: text/* image/jpeg
    • 16 2 Portal Requests and the Filter Chain image/png image/* */* then the preferred MIME type will be text/html. The following attribute is set when the filter is invoked. DEVICE A reference to the Device object. Device Filter Parameters The following init parameter can be used to control the behavior of the Device Filter: Parameter Description Default mimeTypePreferences A list of MIME types to serve, ordered by MIME-type preference. text/html text/vnd.wap.wml application/vnd.wap.wml text/xml application/xml application/xhtml+xml DeviceOutput Filter Filter Class Name: atg.portal.servlet.DeviceOutputFilter The Device Output Filter initializes the request’s DeviceOutput object. The DeviceOutput can be either HTML or WML. See Device Outputs (page 46) in the Designing a Gear chapter. In addition to the standard logging level parameters, the Device Output Filter has a single init parameter, which you should not need to modify: Parameter Description deviceOutputFactory The Nucleus address of the DeviceOutputFactory component. Default: ctx:dynamo:/atg/portal/framework/DeviceOutputFactory Portal Filter Filter Class Name: atg.portal.servlet.PortalFilter The Portal Filter is used to set the request’s PORTAL attribute. The Portal Filter determines the portal the request belongs to by examining the portalId query parameter. If a portalId query parameter does not exist, the Portal Filter uses the PortalManager component to determine the PORTAL attribute.
    • 2 Portal Requests and the Filter Chain 17 The following attribute is set when the filter is invoked: PORTAL A reference to the Portal object. Portal Filter Parameters The following init parameters can be used to control the behavior of the Portal Filter: Parameter Description portalManager A reference to the PortalManager component. portalIdParameterName The name of the portal id query parameter. Defaults to paf_portalId. Community Filter Filter Class Name: atg.portal.servlet.CommunityFilter The Community Filter sets the request’s COMMUNITY attribute. The Community Filter determines the community a request belongs to by examining the communityId query parameter. If a communityId query parameter does not exist, the Community Filter uses the Portal’s PortalObjectResolver to resolve the community. The following attribute is set when the filter is invoked. COMMUNITY A reference to the Community object. Community Filter Parameters The following init parameters can be used to control the behavior of the Community Filter: Parameter Description portalManager A reference to the PortalManager component. communityIdParameterName The name of the community ID query parameter. Defaults to paf_commnuityId. initD5StyleAttributes Sets request attributes compatible with the ATG Dynamo 5 portal product.
    • 18 2 Portal Requests and the Filter Chain Page Filter Filter Class Name: atg.portal.servlet.PageFilter The Page Filter sets the request’s PAGE attribute. The Page Filter determines the page a request belongs to by examining the pageId query parameter. If a pageId query parameter does not exist, the Page Filter uses the Portal’s PortalObjectResolver to resolve the page. The following attribute is set when the filter is invoked. PAGE A reference to the Page object. Page Filter Parameters The following init parameters can be used to control the behavior of the Page Filter: Parameter Description portalManager A reference to the PortalManager component. pageIdParameterName The name of the page ID query parameter. Defaults to paf_pageId. initD5StyleAttributes Sets request attributes compatible with the ATG Dynamo 5 portal product. Access Filter Filter Class Name: atg.portal.servlet.AccessFilter The Access Filter checks the permissions of the PORTAL, COMMUNITY and PAGE attributes of the request. If the request has the correct permissions, the request is passed on. If the permissions are incorrect, the access filter directs the request to the appropriate login or access denied pages. Access Filter Parameters The following init parameters can be used to control the behavior of the Access Filter: Parameter Description methodName The method used to dispatch requests. Defaults to forward. defaultLoginTemplateContextURI The context URI to use for the login template. defaultLoginTemplatePathURI The path URI to use for the login template. defaultAccessDeniedTemplateContextURI The context URI to use for the access denied template.
    • 2 Portal Requests and the Filter Chain 19 Parameter Description defaultAccessDeniedTemplatePathURI The path URI to use for the access denied template. profileName The location of the profile object. d5StyleAccess A boolean used to configure the access filter to use ATG Dynamo 5 style access. Offline Filter The Offline Filter checks whether the community is currently offline. If the community is offline the request is directed to the offline page. If the community is not offline the request is passed down the filter chain. Filter Class Name: atg.portal.servlet.OfflineFilter Offline Filter Parameters The following init parameters can be used to control the behavior of the Offline Filter: Parameter Description methodName The method used to dispatch requests. Defaults to forward. defaultOfflineTemplateContextURI The context URI to use for the offline template. defaultOfflineTemplatePathURI The path URI to use for the offline template. offline If true, turns all communities offline. Defaults to false. d5StyleOffline A boolean used to configure the offline filter to use ATG Dynamo 5 style offline handling. The Portal request passes down the Portal Filter Chain and is transformed along the way. At the end of the Portal Filter Chain, the Portal request is dispatched to its target, typically a JSP or Servlet. ATG Dynamo 5 Style Attributes Version 5.x of ATG Portal used a different set of attributes. The following attributes were set in version 5.x: atg.portal.framework.RequestAttributes.ORIGINAL_REQUEST_URI atg.portal.framework.RequestAttributes.RESPONSE atg.portal.framework.RequestAttributes.COMMUNITY atg.portal.framework.RequestAttributes.PERSONALIZED_COMMUNITY atg.portal.framework.RequestAttributes.PAGE atg.portal.framework.RequestAttributes.PERSONALIZED_PAGE atg.portal.framework.RequestAttributes.DISPLAY_MODE
    • 20 2 Portal Requests and the Filter Chain If your portal application needs to make use of these attributes, you can set the initD5StyleAttributes init parameter of the Portal Server Filter, Display Filter, Community Filter, and Page Filter to true. Page Template Dispatch Servlet Servlet Class: atg.portal.servlet.PageTemplateDispatcherServlet The Page Template Dispatch Servlet is a servlet, not a filter, and is not part of the Portal Filter Chain. Once the Portal Filter Chain has finished handling and transforming the Portal request, the request is dispatched to its target. If no particular page file is specified in the request or if the request is not diverted first (for example, by the Offline Filter or Access Filter), then the request will be dispatched to the Page Template Dispatch Servlet. The Page Template Dispatch Servlet is responsible for dispatching the request to the community’s page template. The COMMUNITY, DISPLAYMODE, and DEVICE attributes will have been set by filters in the Portal Filter Chain. These request attributes are used by the Page Template Dispatch Servlet to determine the location of the page templates. Once the page template has been determined, the Page Template Dispatch Servlet forwards the request to the page template for processing. The Page Template Dispatch Servlet is configured in the Web application’s deployment descriptor file, just as each element of the Portal Filter Chain is, but using a <servlet> tag rather than a <filter> tag. By default, the servlet mapping of the Page Template Dispatch Servlet uses a URL pattern of /, which maps to the default servlet. Page Template Dispatch Servlet Parameters The following init parameters can be used to control the behavior of the Page Template Dispatch Servlet: Parameter Description methodName The method used to dispatch requests. Defaults to forward. defaultDisplayModeName The name of the display mode to use if none was set. Defaults to shared. defaultDeviceOutputName The name of the device output to use if none was set. Defaults to htmlURL.
    • 3 The Portal Page Structure 21 3 The Portal Page Structure Understanding the portal page template and auxiliary files that are used provides important information for customizing a portal or for understanding the context in which gears are rendered. If you use the page templates provided with ATG Portal, then you do not need to develop new portal page templates, but you will still need to understand the portal page template context. In addition, to change the look and feel of your portal pages, you will need to edit the default templates (after making backup copies). For a listing and description of the provided template files, see the Portal Configuration chapter of the ATG Portal Administration Guide. For more detailed information on customizing a portal, see the Creating a Custom Portal (page 119) chapter of this manual. For information on the PAF tags that appear in the code samples in this chapter, see Appendix B, PAF Tag Library Reference (page 151) and the Gears and the Portal Application Framework (page 31) chapter. This chapter includes the following sections: How Gear Rendering Works (page 21) Portal Templates (page 22) Wireless Templates (page 30) How Gear Rendering Works Gears are rendered using a nested set of pages and page fragments. A page calls a layout, using the <paf:layout/> tag. This element renders one of several page layouts, based on attributes of the request. The page layout consists of a table with a variable number of cells. Each cell renders gear contents using a region element embodied in the region.jspf page fragment. The region fragment uses the following elements to actually render the contents of the gear; <paf:context var="gearContext" type="${gearContextType}"/> <c:set target="${gearContext}" property="gear" value="${gear}"/> <c:set target="${gearContext}" property="gearMode" value="${gearMode}"/> <paf:include context="${gearContext}"/> The page, layout, and region elements are described in more detail in the Portal Templates (page 22) section of this chapter.
    • 22 3 The Portal Page Structure Portal Templates The portal page consists of a combination of template files. A full set of these files, referred to here as template files, is included with the ATG Portal installation. The default storage directory for the template files is the templates folder in <ATG10dir>/Portal/paf/start-portal/portal.war. You can make a backup copy of the files in this archive and then supplement or edit them to supply your own pages, headers, graphics, background images, regions, etc. By doing this, you can change the appearance of your portal pages and insert your own portal branding. Note that there is also a folder named <ATG10dir>/Portal/templates. The templates in that folder are there for backwards compatibility with ATG Dynamo 5. They should not be used as a basis for page development in the ATG platform. This section explains and provides code samples of each of the various template files: • Page Template (page 22) • Layout Template (page 26) • Gear Title Template (page 29) Page Template The page template functions as a container page for gear rendering. The page template provided for a shared page (a page that renders several gears) is shared.jsp. For a full page (a page that renders a single gear), the provided file is called full.jsp. Typically, the page template file is responsible for several things, including: • Providing a consistent header, footer, or sidebar for the portal • Rendering the page’s layout, which is typically done with a Layout Template (page 26) • Configuring page style with a cascading stylesheet • Presenting portal-level navigation Page Template Example As an example of a page template, let’s look at shared.jsp, which illustrates some of the main functionality carried out by a page template in the case of a portal page shared by several gears. Tag Library Declaration This element makes available two standard Java tag libraries and two ATG tag libraries. The ATG portal/ paf1_3 tag library is described in this guide; see Appendix B, PAF Tag Library Reference (page 151). The ATG dspjspELTaglib1_0 is described in the ATG Page Developer's Guide. <%@ taglib prefix="paf" uri="http://www.atg.com/taglibs/portal/paf1_3" %> <%@ taglib prefix="dsp" uri="http://www.atg.com/taglibs/daf/dspjspELTaglib1_0" %> <%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %> <%@ taglib prefix="fmt" uri="http://java.sun.com/jstl/fmt" %> Internationalization Initialization This element makes available the resource bundle used for localizing user messages on the page.
    • 3 The Portal Page Structure 23 <fmt:setBundle var="templatesbundle" basename="atg.portal.templates"/> Page and Environment Initialization The next sets of elements initialize the DSP page environment and the portal page environment. The dsp:page element invokes the JSP handler, which calls the ATG servlet pipeline. Next, we get the Portal Servlet Request and Portal Servlet Response attributes, and then set the community, page, community name, and page name, based on the values in the Portal Servlet Request. <dsp:page> <c:set var="PORTALSERVLETREQUEST"><%= Attribute.PORTALSERVLETREQUEST %></c:set> <c:set var="PORTALSERVLETRESPONSE"><%= Attribute.PORTALSERVLETRESPONSE %></c:set> <c:set var="portalServletRequest" value="${requestScope[PORTALSERVLETREQUEST]}"/> <c:set var="portalServletResponse" value="${requestScope[PORTALSERVLETRESPONSE]}"/> <c:set var="community" value="${portalServletRequest.community}"/> <c:set var="page" value="${portalServletRequest.page}"/> <c:set var="communityName" value="${community.name}"/> <c:set var="pageName" value="${page.name}"/> The next set of elements sets visual style elements, based on properties in the page’s colorPalette property. <c:set var="bodyTagData" value="${page.colorPalette.bodyTagData}"/> <c:set var="pageTextColor" value="#${page.colorPalette.pageTextColor}"/> <c:set var="pageBackgroundColor" value="#${page.colorPalette.pageBackgroundColor}"/> <c:set var="gearTitleTextColor" value="#${page.colorPalette.gearTitleTextColor}"/> <c:set var="gearTitleBackgroundColor" value="#${page.colorPalette.gearTitleBackgroundColor}"/> <c:set var="communityPages" value="${portalServletRequest.communityPages.pages}"/> The next element sets the URL for a stylesheet, encoding it with the relevant portal request attributes, so that the page ID, community ID, display mode, etc., can be passed to the stylesheet: <c:set var="cssURL" value="${community.style.CSSURL}"/> <c:if test="${cssURL != null}"><paf:encodeURL var="cssURL" url="${cssURL}"/> </c:if> The next elements use the paf:encodeURL element to set the URLs for links off of the page. The adminURL link leads to the Community Administration, for those users that are authorized to use it. The customizeURL link leads to the page customization interface, if the user is authorized to customize this page. The loginURL and logoutURL lead to authorization pages.
    • 24 3 The Portal Page Structure <c:set var="contextPath"><%= request.getContextPath() %></c:set> <paf:encodeURL var="adminURL" url="/portal/settings/community_settings.jsp"/> <paf:encodeURL var="customizeURL" url="/portal/settings/user.jsp"/> <paf:encodeURL var="loginURL" url="${contextPath}/userprofiling/login.jsp"/> <paf:encodeURL var="logoutURL" url="${contextPath}/userprofiling/logout.jsp"/> The next element imports the Profile object: <dsp:importbean var="profile" bean="/atg/userprofiling/Profile"/> Outer HTML Tags Now that the page is initialized with the necessary declarations of taglibs, variables, etc., the next elements begin the HTML elements of the page, beginning with the <head> element: <html> <head> <title><c:out value="${communityName}"/> - <c:out value="${pageName}"/> </title> <link rel="stylesheet" type="text/css" href='<c:out value="${cssURL}"/>' src='<c:out value="${cssURL}"/>'/> </head> HTML Body The body of the page begins by creating a table, with the community name in the left portion of the header. <body <c:out value="${bodyTagData}" escapeXml="false"/> > <%-- -- Header --%> <table border="0" cellpadding="1" cellspacing="0" width="100%"> <tr> <td valign="top" bgcolor='<c:out value="${pageTextColor}"/>'> <table border="0" width="100%" cellpadding="3" cellspacing="0"> <tr> <%-- -- Left Header --%> <td valign="top" align="left" bgcolor='<c:out value="${pageBackgroundColor}"/>'> <font color='<c:out value="${pageTextColor}"/>'> <b><c:out value="${communityName}"/> - <c:out value="${pageName}"/></b><br/>
    • 3 The Portal Page Structure 25 The next section uses a security tag, paf:hasCommunityRole, to display a link to the Community Administration only if the user’s role is either a community leader or a portal administrator. See Security Tags (page 40) in the Portal Security chapter for more information. <paf:hasCommunityRole roles="leader,portal-admin"> <a href='<c:out value="${adminURL}"/>'> <fmt:message key="page-label-administer" bundle="${templatesbundle}"/> </a><br/> </paf:hasCommunityRole> The next element tests whether this community allows users to customize pages. If so, it displays a link to the customization page. <c:if test="${community.allowPersonalizedPages == true && profile.transient == false}" > <a href='<c:out value="${customizeURL}"/>'> <fmt:message key="page-label-customize" bundle="${templatesbundle}"/> </a> </c:if> The next section of the header tests whether the user is logged in. If so, a logout link is displayed. If no, a login link is displayed. <td valign="top" align="right" bgcolor='<c:out value="${pageBackgroundColor}"/>'> <font color='<c:out value="${pageTextColor}"/>'> <c:choose> <c:when test="${profile.transient == false}"> <fmt:message key="page-message-logged-in" bundle="${templatesbundle}"/> <b><dsp:valueof bean="Profile.login"/></b><br/> <a href='<c:out value="${logoutURL}"/>'> <fmt:message key="page-label-logout" bundle="${templatesbundle}"/></a> </c:when> <c:otherwise> <a href='<c:out value="${loginURL}"/>'> <fmt:message key="page-label-login" bundle="${templatesbundle}"/></a><br/>&nbsp; </c:otherwise> </c:choose> </font> </td> Rendering Community Page Tabs The next section displays a tab for each page in the community. The c:forEach element iterates through the pages in the community and sets the URL for the page.
    • 26 3 The Portal Page Structure <c:forEach var="communityPage" items="${communityPages}"> <paf:context var="portalContext"/> <c:set target="${portalContext}" property="page" value="${communityPage}"/> <paf:encodeURL var="communityPageURL" context="${portalContext}" url="${portalServletRequest.portalRequestURI}"/> The c:forEach element uses three tags from the PAF tag library to render a tab for each page in the community. The parent paf:renderTab encloses a paf:currentTab element, which is rendered if the page object passed to the parent renderTab tag is the currently rendering page, and a paf:defaultTab element, which is rendered if the page object passed to the parent renderTab tag is not the currently rendering page. The result is to highlight the tab for the current page. Each tab includes a link to the URL for the community page. <paf:renderTab page="${portalContext.page}"> <paf:defaultTab> <td bgcolor='<c:out value="${gearTitleBackgroundColor}"/>' nowrap><nobr> <font size="-1">&nbsp;&nbsp;<a href="<c:out value="${communityPageURL}"/>"> <font color="<c:out value="${gearTitleTextColor}"/>" > <c:out value="${communityPage.name}"/></font></a> &nbsp;&nbsp;</font></nobr> </td> </paf:defaultTab> <paf:currentTab> <td bgcolor='<c:out value="${gearTitleTextColor}"/>' nowrap><nobr> <font size="-1">&nbsp;&nbsp; <b><a href="<c:out value="${communityPageURL}"/>"> <font color="<c:out value="${gearTitleBackgroundColor}"/>"> <c:out value="${communityPage.name}"/></font></a></b> &nbsp;&nbsp;</font></nobr> </td> </paf:currentTab> </paf:renderTab> Rendering the Layout Template The page layout template is invoked using this element from the PAF tag library: <paf:layout/> Which page layout to render is determined based on the page’s display mode, device, and URL. The page layout template does the actual work of rendering the gears on the page. See the Layout Template (page 26) section for a description of how to create and use a layout template. Layout Template The layout template specifies the structure of the area within the page template in which the gears are rendered. The layout template is included by the page template by means of a tag (paf:layout) rather than as a file include. The layout template structures the gear area by means of a table with a single row. Each cell within the
    • 3 The Portal Page Structure 27 row corresponds to a column in the gear area of the page. For example, three cells would mean a three-column gear area. Within each cell, a name and a region rendering fragment for the column are specified. There are four layout templates provided in ATG Portal: • 100.jsp (one column) • 75_25.jsp (two columns—left, wide; right, narrow) • 25_75.jsp (two columns—left, narrow; right, wide) • 25_50_25.jsp (three columns—narrow, wide, narrow) In addition, you can create your own custom layout templates and make them available within the administration utilities by means of a layout template manifest. See Customizing Portal Appearance (page 123): Layout Template Manifests (page 127) in the Creating a Custom Portal chapter for more information about creating layout template manifests. Layout Template Example The following code sample comes from the layout template named 25_75.jsp. The layout consists of an HTML table with a single row. Each cell within the row includes a region fragment, region.jspf, using this element: <%@ include file="region.jspf" %> The region fragment renders the gear’s content. See Region Rendering Fragment (page 28) in this chapter for more information. As in the page template, the layout template begins by importing the tag libraries and Java packages used in the layout. <%@ page import="java.io.*,java.util.*,atg.portal.servlet.*, atg.portal.framework.*,java.util.*" errorPage="/error.jsp"%> <%@ taglib prefix="paf" uri="http://www.atg.com/taglibs/portal/paf1_3" %> <%@ taglib prefix="dsp" uri="http://www.atg.com/taglibs/daf/dspjspELTaglib1_0" %> <%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %> Next, we set the portal request and response and other variables. <c:set var="PORTALSERVLETREQUEST"><%= Attribute.PORTALSERVLETREQUEST %></c:set> <c:set var="PORTALSERVLETRESPONSE"><%= Attribute.PORTALSERVLETRESPONSE %></c:set> <c:set var="portalServletRequest" value="${requestScope[PORTALSERVLETREQUEST]}"/> <c:set var="portalServletResponse" value="${requestScope[PORTALSERVLETRESPONSE]}"/> <c:set var="page" value="${portalServletRequest.page}"/> <c:set var="regionMap" value="${page.regions}"/> The next section begins the table that defines the page layout. <center> <table border="0" width="96%" cellpadding="0" cellspacing="0"> <tr>
    • 28 3 The Portal Page Structure The first cell is defined. It is allocated 25% of the page’s width, and includes the region rendering fragment. <td valign="top" width="25%"> <c:set var="gears" value="${regionMap['25_75_Left'].gears}"/> <%@ include file="region.jspf" %> </td> Region Rendering Fragment A layout template can use a region fragment to render the contents of a column in the gear area of the page. From an HTML perspective, a region fragment corresponds to the contents of a table cell defined within the containing layout template. A region fragment contains the code that obtains a list of gears to render in the column and renders the gears. ATG Portal provides a region rendering fragment named region.jspf. This region fragment contains the code that obtains a list of gears to be rendered in the region, and then iteratively renders each gear in the list, along with the gear’s title bar, pre-treatment, and post-treatment. The first section of region.jspf makes the Portal Servlet Request and Portal Servlet Response attributes available, as well as setting visual style parameters. <c:set var="PORTALSERVLETREQUEST"><%= Attribute.PORTALSERVLETREQUEST %></c:set> <c:set var="PORTALSERVLETRESPONSE"><%= Attribute.PORTALSERVLETRESPONSE %></c:set> <c:set var="portalServletRequest" value="${requestScope[PORTALSERVLETREQUEST]}"/> <c:set var="portalServletResponse" value="${requestScope[PORTALSERVLETRESPONSE]}"/> <c:set var="community" value="${portalServletRequest.community}"/> <c:set var="gearTextColor" value="#${page.colorPalette.gearTextColor}"/> <c:set var="gearBackgroundColor" value="#${page.colorPalette.gearBackgroundColor}"/> The next section uses a c:forEach element to iterate through all of the gears to be displayed in the region: <c:forEach var="gear" items="${gears}"> For each gear, we: 1. Render a title bar, using the paf:titlebar tag: <paf:titlebar gear="${gear}"/> 2. Optionally dispatch the gear for pre-treatment, using: <paf:titlebar gear="${gear}" type="pre"/> 3. In a table, render the content of the gear: <% pageContext.setAttribute("gearContextType",GearContext.class); pageContext.setAttribute("gearMode",GearMode.CONTENT); %> <paf:context var="gearContext" type="${gearContextType}"/> <c:set target="${gearContext}" property="gear" value="${gear}"/> <c:set target="${gearContext}" property="gearMode" value="${gearMode}"/>
    • 3 The Portal Page Structure 29 <paf:include context="${gearContext}"/> 4. Optionally dispatch the gear for post-treatment, using: <paf:titlebar gear="${gear}" type="post"/> Note that using a <paf:titlebar> element to include a title bar from another file or to dispatch the gear for pre- or post-treatment can be less efficient than inlining the code for the title bar or pre- or post-treatment. However, using the <paf:titlebar> element lets you separate this display element from the gear rendering code, which may make it easier to maintain or change your portal application. Gear Title Template There are three types of gear title templates: one for displaying a gear title bar, one for displaying HTML to be rendered immediately before gear output (gear pre-treatment), and one for displaying HTML output to be rendered immediately after gear output (gear post-treatment). One of each type of gear title template is provided: • titlebar.jsp • titlebar-pre.jsp • titlebar-post.jsp Gear Title Template Example The following code samples come from the titlebar.jsp file. The title bar displays the gear name and optional Edit, About, and Help links. <table border="0" width="100%" cellpadding="0" cellspacing="0"> <tr> <td valign="top" bgcolor="<c:out value="${gearTitleBackgroundColor}"/>" width="78%"> <font color="<c:out value="${gearTitleTextColor}"/>"> <c:out value="${gearName}"/> </font> </td> <td align="right" bgcolor="<c:out value="${gearTitleBackgroundColor}"/>" width="22%"> The next section optionally displays an Edit link for the gear, if the gear has been configured to be customizable by the user: <c:if test="${showEdit ==true}"> <% gearContext.setGearMode(GearMode.USERCONFIG); %> <a href="<%= gearServletResponse.encodeGearURL (gearServletRequest.getPortalRequestURI(),gearContext) %>"> <font color="<c:out value="${gearTitleTextColor}"/>"> <fmt:message key="titlebar-control-edit" bundle="${templatesbundle}"/></font></a> </c:if>&nbsp; The next section optionally displays an About link for the gear:
    • 30 3 The Portal Page Structure <c:if test="${showAbout == true}"> <% gearContext.setGearMode(GearMode.ABOUT); %> <a href="<%= gearServletResponse.encodeGearURL (gearServletRequest.getPortalRequestURI(),gearContext) %>"> <font color="<c:out value="${gearTitleTextColor}"/>"> <fmt:message key="titlebar-control-about" bundle="${templatesbundle}"/></font></a> </c:if>&nbsp; The next section optionally displays a Help link for the gear: <% gearContext.setGearMode(GearMode.HELP); %> <c:if test="${showHelp == true}"> <a href="<%= gearServletResponse.encodeGearURL (gearServletRequest.getPortalRequestURI(),gearContext) %>"> <font color="<c:out value="${gearTitleTextColor}"/>"> <fmt:message key="titlebar-control-help" bundle="${templatesbundle}"/></font></a> </c:if> Wireless Templates A wireless portal template consists of a deck of sequential screens. The content of these screens resides in JSP files that you create. These files differ from ordinary JSP files, however, in that their contents are written in WML. A set of WML portal template files is included in ATG Portal. These template files can be found in <ATG10dir>/ Portal/paf/start-portal/paf-dar/portal/templates/page/wml. You can make a backup copy of the files in this archive and then supplement or edit them to supply your own pages. The Shared Deck Template The shared deck template, templates/page/wml/shared.jsp, provides the initial deck of screens for a wireless portal, usually consisting of the title page and the gear menu infrastructure. A wireless user will use this page to select and navigate to one of the available gears. If a wireless gear has only a shared display mode, it is rendered only within the shared deck template. If the gear also has a full display mode, the full display mode is rendered within a full deck template. The Full Deck Template The full deck template, wml/full.jsp is used to render gears in their full mode. If a gear does not have a full mode, then it does not need to use the full deck template.
    • 4 Gears and the Portal Application Framework 31 4 Gears and the Portal Application Framework This chapter covers an assortment of topics related to the way in which gears interact with the PAF. It is important to keep these in mind as you develop your gears. How Portal Pages Are Rendered The Portal Requests and the Filter Chain (page 7) chapter describes how portal requests are routed through the Portal Filter Chain. At the end of the Portal Filter Chain sits the Page Template Dispatch Servlet, which is responsible for dispatching the request to the community’s page template for processing. Gears are rendered on a portal page by means of a RenderPreparedGear tag, which is invoked from the portal layout template. How the PAF Processes Page Requests The following is an overview description of the way in which the PAF handles page requests. 1. The user requests a portal page in the portal context path. 2. The request is processed by the Portal Filter Chain, elements of which set portal request attributes, including the PORTAL, COMMUNITY, PAGE, DISPLAYMODE, and DEVICE. 3. The PageTemplateDispatchServlet determines which page to forward the request to by examining the portal request attributes. If the URL specifies the page parameters, then the page is routed directly to that page; otherwise, the community’s default page is used. 4. The .jsp page or Servlet associated with the requesting output device, gear mode, and display mode is processed. (This involves examining the context parameters for the request.) 5. The layout is rendered in the page template. 6. When the PAF encounters a region definition within the layout template of the resulting page, it retrieves the gears that should be rendered. 7. The content of each gear is determined by the gear renderer tags, which take input values for such parameters as community, page, region, profile, locale, gear, etc. These tags are described in the remainder of this chapter. 8. The gears and their content are rendered in the appropriate layout template for the requested output device.
    • 32 4 Gears and the Portal Application Framework Tag Libraries and Gear Development The functionality specific to the PAF is available by means of the PAF Tag Library. The PAF Tag Library is described in Appendix B, PAF Tag Library Reference (page 151) and The Portal Page Structure (page 21) chapter in this manual. Portal pages can use any valid JSP tag library. For more information about tag libraries, see the ATG Page Developer's Guide. Link URLs Links in a portal page typically need to pass information. There are several techniques you can use in constructing a link, including: • paf:encodeURL JSP tag • PortalServletResponse.encodePortalUrl method • GearServletResponse.encodeGearUrl method The paf:encodeURL tag encodes a portal URL, encoding session ID and portal-specific parameters. The tag takes the following parameters: id This required parameter stores the resultant encoded portal URL. url The URL to encode. Defaults to the requested URI if not specified. Optional. portalContext An object representing the portal in a particular state. Defaults to the currently rendering portal state if not specified. Optional. gearContext An object representing a particular state of the gear and portal. Optional. The following example illustrates the use of this tag to encode a URL that puts the portal in full display mode. <% fullPortalContext = new PortalContextImpl(portalContext); fullPortalContext.setDisplayMode(DisplayMode.FULL); %> <paf:encodeURL id="fullURL" portalContext="<%= fullPortalContext %>"> <a href="<%= fullURL %>">full</a> </paf:encodeURL> The example below shows how one might create a link to a gear rendering in “help” mode, using the GearServletResponse.encodeGearUrl method. <% GearContext currentGearContext = (GearContext) request.getAttribute(Attribute.GEARSERVLETREQUEST);
    • 4 Gears and the Portal Application Framework 33 GearContextImpl gearContext = new GearContextImpl(currentGearContext); gearContext.setGearMode(GearMode.HELP); %> ... ... <a href="<%= gearServletResponse.encodeGearURL(myURL,gearContext) %>">help</a> URL Usage Often, gears rely on the portal page templates and the PAF to provide gear mode changes. For example, a portal page typically renders a gear with a border, which is controlled by the gear title template rather than by the gear itself. Within the border there is often an Edit link used to change the gear mode from content to userConfig. You may need to use a link to make changes to the internal state of a gear, rather than changes to a gear’s mode or display mode. This kind of change is not directly supported by PAF-defined parameters and must be handled internally by the gear. For example, a discussion forum gear might need to have such parameters as forumID, topicID, startRange, action (thread_list, topic_list, etc.). Form Handling It is important to keep the following form handling considerations in mind as you plan your gears. Gear Form Handling Directing Form Input Most forms within gears should ensure that the action of the form is the current page. For example: <dsp:form action="<%= gearServletRequest.getPortalRequestURI() %>"> Gear Configuration Form Handling Configuration Modes A gear can have up to four configuration modes: • UserConfig • InstanceConfig • InstallConfig
    • 34 4 Gears and the Portal Application Framework • InitialConfig These modes display forms that allow users, community leaders, and portal administrators to set a gear’s configuration parameters. A gear developer needs to create a link to a UserConfig form. The remaining three configuration forms are invoked by the PAF’s administration utilities as needed. Configuration Parameters Gear configuration parameters are values that control the function or display of the gear. The following list indicates just a few examples of the many possible configuration parameters: • What types of users can edit documents • How many posts to display in a discussion • Which repository to store data in • How often to update values PAF Configuration Parameters The PAF provides support for simple (String) configuration parameters, which are defined and registered within the PAF by means of the gear manifest XML file. If your gear requires more complex parameters (for example a list of forums a user is subscribed to), then you will need to implement these within the gear (for example, by means of a custom persistence implementation). Accessing Configuration Parameters Configuration parameters can be accessed by methods made available by the GearEnvironment object created by the InitializeGearEnvironment tag. The following methods provide access to instance parameters: public String getGearInstanceParameter(String pName) (Returns null if the instance parameter is not found.) public void setGearInstanceParameter(String pName, String pValue) The following methods provide access to user parameters: public String getGearUserParameter(String pName) public void setGearUserParameter(String pName, String pValue) When you request configuration parameter values and the parameter has not been set, then a default value will be returned. Default values can be obtained or set with the following methods: public String getGearUserDefaultValue(String pName) public void setGearUserDefaultValue(String pName, String pValue) For more information, refer to the gear interfaces under the atg.portal.framework package in the ATG Platform API Reference.
    • 4 Gears and the Portal Application Framework 35 GearConfigFormHandler An extensible Gear Configuration form handler, atg.portal.framework.GearConfigFormHandler, is provided with the PAF. This form handler can be used for setting gear instance parameters or user parameters. The Alert, Document Exchange, Repository View, and HTML Content (Screenscraper) gears each include examples of classes that extend the GearConfigFormHandler, including source code. For instructions on implementing gear configuration forms, refer to the Gear Configuration Page Fragments (page 58) section in the Creating Gear Page Fragments (page 55) chapter. For Javadoc on the GearConfigFormHandler class, see the ATG Platform API Reference. JSP Form Handling If you use a JSP form that directly manages and accesses request parameters, you should take steps to ensure that no data loss is caused by two or more gears using the same parameter names. The PAF provides the gearEnv.getGear().getId() method that supplies a unique ID that a gear can use as an identifier. These identifiers can be included in well-known request parameters (for example, a hidden form field). Consequently, when the gear checks to see if it should process form input, it can determine whether its unique identifier was included in the request parameters. If it was not included, the gear can ignore the incoming parameter. If it was included, the gear can process the form. For example, you might include the gear id in a hidden field as follows: <input type="hidden" name="submit_gear_id" value="<%= gearEnv.getGear().getId() %>"/> Then on the next page you could test to make sure the value of the submit_gear_id gear parameter matches the current gear id before you begin processing the other form parameters, as follows: String myGearId = env.getGear().getId(); String submittedGearId = request.getParameter("submit_gear_id"); If ((submittedGearId != null) && (submittedGearId.equals(myGearId))) { ... } If a gear includes a multipart form (file upload) and other gears need access to the contents of the multipart form, then the gears needing access to the information can be identified by the unique gear identifiers described above. However, in the case of a multipart form, it is preferable to include the gear identification parameter in a query argument so that it can be examined without decoding the multipart form. Configuring Gears to Work with Persistent Data Repositories If your gear needs to store data persistently, you may use EJBs or configure a SQL Repository and then access the repository via JNDI in Nucleus. Most deployments will have multiple application servers running to distribute the user load. Your gears must ensure data consistency and integrity between the repositories in each server. This can be accomplished by
    • 36 4 Gears and the Portal Application Framework implementing optimistic locking using the version property or by setting an explicit cache integrity mode. See the SQL Repository Caching chapter in the ATG Repository Guide. Keeping Gears Synchronized with Each Other The PAF renders gears serially (one after the other) so you need to keep that in mind when designing your message passing. A gear rendered earlier in the page can not see messages posted from a gear later in the page until the page is refreshed. Some ways you can share data among gears are the following: • Bundle the related gears into a single Web application and use the session or application J2EE context. • Use request attributes. The limitation of this is that the classloader policies of the J2EE specifications can only guarantee primitive object types (Strings, Integers, etc.) • Use a back-end persistence layer, such as EJBs or Repositories. • Use a container-specific mechanism. In the case of ATG, this would mean adding an object (for example, a globally or session-scoped component) and accessing it through JNDI. • Use Java Messaging System (JMS) messaging. Performance Recommendations Avoid Inefficient Java Methods There are some Java methods that are not suitable for use in a Web server application. These include: java.net.URLEncoder.encode() This method is quite inefficient. It is slow and uses a lot of memory. Instead, use the method atg.servlet.ServletUtil.escapeURLString() to perform the same function 10 times faster and with much less memory allocated. java.util.Date.toString() In at least some JDK versions, this is a synchronized method that takes a fair amount of CPU time. Instead, use a method like the following to format a Date more efficiently: StringBuffer sb = new StringBuffer(NumberFormat. fixedWidth( (date.getMonth()+1), 2)); sb.append("/"); sb.append( NumberFormat.fixedWidth(date.getDate(), 2) ); sb.append("/");
    • 4 Gears and the Portal Application Framework 37 /* need to cut the 100's of Year ex. if it is 102 for 2002 */ sb.append( NumberFormat.fixedWidth((date.getYear()%100), 2) ); return ( sb.toString() ); Additional Performance Resources For additional material on programming efficiently and troubleshooting performance problems, refer to the performance-related chapters in the Installation and Configuration Guide for your application server.
    • 38 4 Gears and the Portal Application Framework
    • 5 Portal Security 39 5 Portal Security The PAF provides the infrastructure to enable you to develop access control for portal and gear content, communities, pages, and gears. This is done primarily by means of Access Control Lists (ACLs). In addition, the PAF lets you log and audit access to gear objects. The gear developer can restrict access to content within a portal page by using access control tags. The gear developer can also programmatically access PAF security functionality by using the PAF Tag Library’s Permissions Methods. Security Roles The PAF recognizes six distinct categories of user: • Anonymous User • Registered User • Community Guest • Community Member • Community Leader • Portal Administrator Every portal user belongs to at least one of these categories. These groups also generally correspond to varying levels of access, features, and functionality. Users with higher security roles implicitly hold lower roles as well. For example, a community leader is also a community member and community guest (but not a portal administrator). For administrative information on portal security (restricting access to communities, pages, and gears), refer to the Portal Access Control chapter of the ATG Portal Administration Guide. Predefined Security Areas Some areas of the PAF have predefined security areas that are not customizable, as described in the following table.
    • 40 5 Portal Security Area Base URL Description Portal Administration /portal/admin Manages portal-wide configuration issues, including gear installation and configuration. Only users with the portal-admin role can access. Community Administration /portal/settings Manages community-specific configuration settings. Only portal administrators and community leaders can access. Security Tags ATG Portal includes several access control tags in the PAF tag library and Java methods that are of interest to both gear developers and to portal page developers. For additional information on the tags and their underlying Java classes, refer to the ATG Platform API Reference. Role Test Tags The following tags render the body of the tag if the user has one of the roles indicated by the comma-separated list of role paths specified by the roles attribute. • hasRole (page 40) • hasCommunityRole (page 41) • hasGearRole (page 41) A role test can be negated by prepending the role path with an exclamation point (!). The roles list specifies an “or” relationship. For example, if you set the roles attribute like this: roles="member,!leader" then the body will render if the user is either a member or not a leader. If a barrier attribute is specified, and its value is true, this will redirect the user to a login or access denied page rather than filtering the tag body content. Note that you shouldn’t use the barrier attribute within a gear, since redirection is not allowed within a gear. hasRole The hasRole tag tests for specified global roles. If the user is logged in and has one of the global roles defined by the roles attribute, the body of the tag is evaluated. If the user is not logged in, or does not have the role, the body is skipped. Example: [tag library declaration] ...
    • 5 Portal Security 41 <dsp:page> <paf:hasRole roles="/portal-admin,!/employees/sales"> ... [page contents] ... </paf:hasRole> </dsp:page> hasCommunityRole The hasCommunityRole tag tests for a specific role. If the user is logged in and has one of the roles defined by the roles attribute for the community, the body of the tag is evaluated. If the user is not logged in, or does not have the role for the community, the body is skipped. Example: [tag library declaration] ... <dsp:page> <paf:hasCommunityRole roles="leader,page-manager" barrier="true"> ... [page contents] ... </paf:hasCommunityRole> </dsp:page> hasGearRole The hasGearRole tag tests for a specific role. If the user is logged in and has one of the roles defined by the roles attribute for the gear, the body of the tag is evaluated. If the user is not logged in, or does not have the role for the gear, the body is skipped. Example: [tag library declaration] ... <dsp:page> <paf:hasGearRole roles="gear-reader,gear-writer" barrier="true"> ... [page contents] ... </paf:hasGearRole> </dsp:page> Role Test Methods ATG Portal includes several methods that check for user roles. isPortalAdministrator Method The Portal.isPortalAdministrator method tests to see if the user has a Portal Administrator role. If the user is logged in and is a Portal Administrator, then the method returns a value of true and the body of the tag is
    • 42 5 Portal Security evaluated. If the user is not logged in, or is not a Portal Administrator, the method returns a value of false and the body of the tag is skipped. For example: <core:if value="<%= gearEnv.isPortalAdministrator() %>"> Your content here </core:if> hasRole Methods The Community.hasRole and Gear.hasRole methods test to see if the user has a specified role in the current community or gear. If the user is logged in and has the appropriate role, then the method returns a value of true and the body of the tag is evaluated. If the user is not logged in, or does not have the appropriate role, the method returns a value of false and the body of the tag is skipped. includeOnly Tag This tag has been deprecated in favor of the Include Filter (page 42). The tag can be used within gear content pages to deny page rendering if the page wasn’t invoked via a JSP include directive. This restricts users from bypassing the security tests of the Page Dispatcher Servlet and accessing content by typing in the direct URL to the JSP document. This tag should be used following taglib imports but prior to any other page content. Attributes: None Body: None Example: <%@ taglib uri="/paf-taglib" prefix="paf" %> ... <paf:includeOnly/> <dsp:page> <paf:InitializeGearEnvironment id="gearEnv"> ... Include Filter The PAF’s Access Filter (page 18) and security role tags can prevent users from navigating to content they shouldn’t see. In addition, you can prevent users from reaching gear content by directly entering URLs using the Include Filter. The Include Filter is a servlet filter that denies access to requests that are not include directives from portal pages, except in specified cases. This is used to secure gears from outside access. To use the Include Filter, use an IncludeFilter filter element in your gear’s web.xml file. For example: <filter> <filter-name>IncludeFilter</filter-name> <display-name>IncludeFilter</display-name> <description>Responsible for security gear contents from outside access.
    • 5 Portal Security 43 </description> <filter-class>atg.portal.servlet.IncludeFilter</filter-class> <init-param> <param-name>allowedUrlPatterns</param-name> <param-value>/images/*</param-value> </init-param> </filter> <filter-mapping> <filter-name>IncludeFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> The Include Filter has an init parameter named allowedUrlPatterns. This parameter determines which URL patterns are allowed external access to the gear contents. Typically, you’d include images in the allowedUrlPatterns parameter. Some gears also need access to their installation, instance, and user configuration pages. The <filter-mapping> element in the Include Filter definition determines which requests the filter applies to. Generally, you want to set this filter mapping to handle all requests, as in the example in this section. J2EE Security The extent to which you can use standard J2EE security mechanisms in conjunction with the PAF depends on the purposes for which you are using the different security mechanisms. Because J2EE supports only static roles, the normal J2EE access control mechanisms cannot be used in conjunction with the PAF’s dynamic community-related access control levels (community leader, community member, and community guest). For these roles, you should use the PAF-supplied tags and methods. However, you may want to define your own roles, assign them to users, and use them to control access to Web applications available through your gear’s web.xml definitions. You may also want to use the roles to programmatically determine access using the hasRole() method exposed by the J2EE Principal object. The PAF contains one such predefined role: portal-admin. This role may be assigned and used according to ordinary J2EE security mechanisms. If you do use J2EE page security mechanisms, you can enable the <login-config> specifier to use the PAF login and error pages as follows: <login-config> <auth-method>FORM</auth-method> <realm-name></realm-name> <form-login-config> <form-login-page> /portal/userprofiling/html/login.jsp </form-login-page> <form-error-page> /portal/access/html/accessDenied.jsp </form-error-page> </form-login-config> </login-config>
    • 44 5 Portal Security Secure Socket Layer Security If you want to implement Secure Socket Layer (SSL) security for a particular community within your portal, you can do this by using the HTTPS protocol (instead of HTTP) when forming the URL. However, if there are links between secure and non-secure communities, SSL will apply to the entire portal. You may also wish to implement SSL security for the Portal Administration interface. See the documentation for your application server for information about deploying Web applications that use SSL.
    • 6 Designing a Gear 45 6 Designing a Gear This chapter steps through the process of making the decisions that affect the design of a gear. It is important to make these decisions before you begin implementing the gear. For an overview of the process of building a gear, see the Gear Implementation Overview (page 3) section of the Introduction chapter. There are three important concepts that comprise the high-level design of a gear: Gear Modes (page 45) Display Modes (page 46) Device Outputs (page 46) Each of these concepts is used to determine the correct content to render as a gear for a user’s request. Any gear you develop will need at least one Gear Mode, Display Mode, and Device Output, but the actual number of each that the gear has ultimately depends on the design decisions you make for the gear. This chapter also discusses other considerations in gear design: Gear Alerts (page 48) You will need to determine whether your gear will need to send alerts when certain actions occur. Gear Administration Considerations (page 48) You may need to design how a gear is configured for different portal contexts. Localization Considerations (page 49) If your gears will need to be localized for use in different languages or regions, you will need to plan accordingly. Extending an Existing Gear (page 50) The easiest way to create a new gear is to copy and extend an existing gear. The final section of this chapter is an example of gear design: Example: A Discussion Forum Gear (page 51). Gear Modes Gear modes reflect the functional mode a gear is in. A gear can have one or more of the following seven gear modes:
    • 46 6 Designing a Gear Gear Mode Description About Information about the gear (for example, author, copyright, and version). Content The main or primary presentation of the gear. Help Help information for the gear. Preview A mode for administrators or community leaders to view the presentations of the gear. Initial Configuration Options that are set when the gear is first created in a community. Typically, these are set by the community leader. Instance Configuration Administrative customization options, which configure a gear for a particular community. Often these are gear appearance or community membership settings. Typically, these are set by a community leader. User Configuration Gear personalization options (for example, entering stock quotes in a stock ticker or ZIP Codes in a weather gear). These are always set by portal end users. Display Modes Display modes reflect the size and appearance of a gear. Most gears will have both of the available display modes: Shared Appears when the gear is on a portal page with other gears. Full Page Appears when a user follows a link that presents the gear on a page by itself. (For example, when a user clicks on the headline of a news story.) You can specify only one page fragment per display mode. However, you can include any number of page fragments within that page fragment and use the internal logic of the gear to decide which one to render. For example, a discussion forum gear might require two full-page views in content mode—one to display the subject line of all the threads and postings in a forum and one to display the contents of a single message in a forum. Device Outputs A gear’s Device Outputs reflect the type of devices on which a gear will be rendered. At present, there are two Device Output options:
    • 6 Designing a Gear 47 • HTML for Web browsers • WML for Wireless Markup Language wireless devices Matrix of Gear Modes, Display Modes, and Device Outputs As part of your planning, you should decide how the matrix of gear modes, display modes, and device outputs will map to page fragments. For example, if you have a news gear that provides content in full and shared mode for browsers and full mode for wireless devices and has instance and user configuration modes for browsers, the matrix might look like this: Gear Mode Display Mode Device Output Page Fragment Content Full HTML newsFull.jsp Content Shared HTML newsShared.jsp Content Full WML newsFull.wml Instance Configuration Full HTML newsInstanceConfig.jsp User Configuration Full HTML newsUserConfig.jsp User Interface Look and Feel Recommendations Because most gears will be sharing a portal page with other gears and residing in a column in a portal page, and because browsers are not always maximized, it is important to keep gears compact and clean. If a gear has a lot of functionality, content, or forms, consider breaking the functionality or content up between multiple page fragments or tabs. Minimum Gear Sizing Rules You should optimize your gear HTML for the most commonly used resolution for your target audience. For example, you might expect consumer monitors to be displaying at 800 x 600 resolution, while most corporate monitors are displaying at 1024 x 768. Gear Dimensions When you register your gear with the PAF, you can specify preferred dimensions for the gear (short, tall, noPreference for height and narrow, wide, noPreference for width). By default, the gears will be added to the first region with matching dimensions on the page’s layout template. Both the layout template and the placement of gears within the layout template are customizable by the Community Leader.
    • 48 6 Designing a Gear Portal and Gear Roles One of the most basic decisions you will make is that of what roles to use or define for the gear and what privileges to give to each of the roles. The pre-defined portal roles are: • Portal Administrator • Community Leader • Community Member • Community Guest • Registered User • Anonymous User The PAF Tag Library provides tags that gear and portal developers can use to check for these roles and to grant or deny access to pages and content accordingly. You can also create additional roles for your gear if you need them, by adding them to profile repository and then using them in your gear code as necessary. For information on the security tags in the PAF Tag Library, refer to the Portal Security (page 39) chapter of this manual. For information on creating roles, refer to the ATG Personalization Guide for Business Users. Gear Alerts You can create alerts that will be sent by your gears and handled by scenarios. You can create scenarios to generate actions based on the alerts. For example, an action might cause an e-mail message to be sent to specified users and a notice to appear in the Alerts gear. As you plan your gear, you need to consider what events you would like to create alerts for and what actions you would like to be carried out. ATG Portal alerts use Java Messaging System (JMS) as their underlying technology. The following Web location contains comprehensive information on JMS: java.sun.com/products/jms For complete information on setting up your gears so that they can send alerts, refer to the Adding Gear Alerts (page 99) chapter of this manual. For information on scenarios, refer to the ATG Personalization Guide for Business Users. Gear Administration Considerations Each gear will be administered by a portal administrator—usually an IT employee who will install and configure the gear. All gear instances will also have community leaders. A community leader could be the same person as the portal administrator, but will frequently be someone different. Gears will need to have administrative views appropriate to their various administrative levels (community leader and user, for example). All administrative views have a full-page display mode. In our discussion gear example, the gear might have an edit link that opens a screen, allowing users to determine which discussion
    • 6 Designing a Gear 49 boards appear on the page. In addition, the community leader might have access to an instance configuration page, as well as to a settings page for the entire community. In planning and developing your gears, it is important to determine what customizations will need to be available at each level (portal administrator, community leader, end-user, etc.) and to design pages to accommodate these customizations. For additional information on forms and form handling for gears, refer to the Form Handling (page 33) section of the Gears and the Portal Application Framework (page 31) chapter of this manual and the Gear Configuration Page Fragments (page 58) section of the Creating Gear Page Fragments (page 55) chapter. For additional information on forms and form handling, refer to the Creating Forms chapter of the ATG Page Developer's Guide and the Working with Forms and Form Handlers chapter of the ATG Platform Programming Guide. Localization Considerations If your gears will need to be localized for use in different languages or regions, you will need to plan accordingly. In particular, you will want to ensure that your gear will be acceptable in any locale (without recompiling), provided that localization data is provided and that dates and currencies, for example, conform to the conventions for a given locale. Fortunately, these goals are attainable with a minimum of additional effort provided that you use particular well-known methods and tools in developing your gears. See the Internationalizing an ATG Web Site chapter of the ATG Platform Programming Guide for more information. In addition, you might want to consider using Jakarta’s i18n Tag Library, an emerging internationalization standard. You can obtain the i18n Tag Library and its documentation from the following location: http://jakarta.apache.org/ Creating Configurable, Localizable Content in Gears If you need to make gear content (text labels or user messages, for example) be both configurable and localizable, you can do this by observing the following guidelines: • Do not put any text that might appear on the screen (labels, user messages, etc.) into a gear instance parameter. Instead, put them in resource bundles. • Make the resource bundle name be a gear parameter. You can have a separate resource bundle for each gear instance if you want. • Be sure not to change the response locale, so that the locale and charset specified by the PageDispatcherServlet are preserved. Once you have set up your gears in this manner, you would then specify a particular resource bundle and locale in your gear page fragments. For example: <%@ taglib prefix="fmt" uri="http://java.sun.com/jstl/fmt" %> <fmt:bundle basename=my.portal.Resources/> <fmt:message id="finishButton" key="finishButton"/>
    • 50 6 Designing a Gear Localized Gear Names and Descriptions You can localize the names and descriptions of gears using the localized-names and localized- descriptions elements in the gear manifest. Use a separate localized-name and localized-description element for each locale you want to support. For example: <gear-definition> <localized-names> <localized-name locale="en_GB">Localised Gear</localized-name> <localized-name locale="fr_FR">Gear Sondage</localized-name> </localized-names> ... </gear-definition> Extending an Existing Gear The easiest way to create a new gear is to copy an existing gear to extend or customize it. However, if you want to continue using the original gear, you must take some important steps in keeping the new gear from conflicting with the original gear. 1. Start with a complete copy of the gear from its source tree. 2. J2EE application names must be unique. You must change the name of the gear in the gear definition manifest file, which is found at the top level of the gear module directory. For example, the gear definition manifest file for the Document Exchange Gear is found at <ATG10dir>/Portal/docexch/docexch- manifest.xml. Change the name in the name attribute of the <gear-definition> tag. 3. Java classes for the new gear should be packaged separately from those for the original gear. Rename the Java source tree directory structure and edit the source to change the package definition statements at the top of each source file. Of course, you will also have to make any Java code changes required by your new gear’s different functionality. 4. ATG configuration files in the CONFIGPATH should be separated. Rename the directories in the CONFIGPATH that hold properties files for your new gear. 5. Edit the properties files for the new gear, changing the $class properties to point to the new gear’s Java package names. Change any properties that point to other components to use the new component pathnames. 6. Edit any pages used by the gear. You will need to make the following changes: • If any pages import or use components, edit them to use the new component pathnames. • In pages that use <input type=submit or img> tags, change the input tag’s name attribute to be unique. • If any of the pages use JavaScript, then you might have to alter the JavaScript to use unique references. 7. Change the servlet context to reflect the name of the new gear. The servlet context appears in: • The gear definition manifest file, in the <servlet-context> tag
    • 6 Designing a Gear 51 • The deployment descriptor file (application.xml), in the <context-root> tag 8. Modify the database schema, adding any database tables used by the extended gear. Change the scripts in the gear’s sql directory to create the new tables. 9. In the repository used by the gear, edit the repository definition file to use the new table names. For example, the repository definition file for the Discussion Gear is located at: <ATG10dir>/Portal/discussion/config/atg/portal/gear/discussion/ discussionRepository.xml Example: A Discussion Forum Gear As a means of illustrating what is involved in planning a gear, this section will present a brief example of a discussion forum gear and highlight some of the decisions you will encounter. Many portals have discussion forums that enable members to discuss various topics by posting messages and replying to messages posted by others. The discussions are typically “threaded” or sorted and presented according to subject and order in which they were posted. Roles One of the most basic decisions you will make is that of what roles to use or define for the discussion forum. A forum will generally need at least two roles, one for the leader and one for everyone else. You may also decide to create a third role by differentiating between those who have permission to post and those who have permission only to read. Assuming you have three roles, the privileges assigned to them might look something like this: Role Privileges Leader Add, delete, or rename forums Specify the presentation of the shared view Specify who can be a Poster and who can be a Reader Poster Initiate or reply to threads Reader Read posts Choosing Display Modes A second basic decision you will need to make concerns Display Modes. In particular, you will need to decide how many views the discussion forum will have, what kind of views they will be, and what they will look like.
    • 52 6 Designing a Gear There are two Display Modes: Shared Display Mode The Display Mode of a gear when it is sharing a portal page with other gears Full Page Display Mode A Display Mode of a gear when it is using the entire page to show its contents In some cases, there will be only one shared view of a gear. In other cases, there will be more (for example, there may be a different view for members of a particular community). In most cases, there will be more than one full- page view of a gear (for example, content mode views like Message Content and Full-Page Message/Thread List or administrative views like User Configuration or Instance Configuration). In our forum discussion example, you might have the following content-mode views: View Display Mode Description Forum List Shared A shared-page listing of forums Partial Message/Thread List Shared A shared-page listing of the message/thread list Full-Page Message/Thread List Full-Page A full-page listing of the message/thread list Message Content Full-Page The full content of a message Shared- Page Message/Thread List The following illustration shows a portion of a shared-page message/thread list. Full- Page Message Content List The following illustration shows what a full-page message content list might look like.
    • 6 Designing a Gear 53
    • 54 6 Designing a Gear
    • 7 Creating Gear Page Fragments 55 7 Creating Gear Page Fragments As part of the process of designing a gear, you should decide how the matrix of gear modes, display modes, and device outputs will map to page fragments, so you will know what page fragments you need to create. For an example of this exercise, refer to the table in the Matrix of Gear Modes, Display Modes, and Device Outputs (page 47) section of the Designing a Gear (page 45) chapter in this manual. The next step is creating the page fragments that make up the presentation of the gear. This chapter describes some important considerations in developing gear page fragments. It includes the following sections: HTML Considerations (page 55) Layout Considerations (page 56) Accessibility Recommendations (page 56) Page Elements (page 56) Gear Configuration Page Fragments (page 58) Message Handling in Page Fragments (page 64) Avoiding Gear Instance Conflicts (page 66) Wireless Gear Page Fragments (page 66) HTML Considerations Because gears appear as parts of a portal page (and more specifically, within an HTML table cell), you should not treat the HTML tags for the gear as you would for a freestanding HTML page. Because they would be redundant, you should not use the following HTML tags within your gear page documents: • <html></html> • <header></header> • <body></body> • <title></title> • <meta></meta> • <frameset></frameset>
    • 56 7 Creating Gear Page Fragments Layout Considerations A portal page will usually consist of a header area, footer area, and a content area. The gears will reside within regions in the content area. The number and width of the regions will be selectable from a portal administration page. When a gear is rendered in full display mode, it occupies the entire space between the header and the footer. When a gear is rendered in shared display mode, it will share the space between the header and footer with other gears. You need to design your gear with appropriate dimensions to function in shared or full display mode. Accessibility Recommendations We recommend that you create gear HTML so that it complies with the Web Content Accessibility Guidelines of the World Wide Web Consortium (W3C). The primary features of the accessibility guidelines are summarized at the following Web location: http://www.w3.org/TR/WAI-WEBCONTENT Page Elements Page fragments have several important elements you need to include to enable tag functionality: • Tag Library Declaration (page 56) • DSP Page Initialization (page 57) • Gear Environment Initialization (page 57) Tag Library Declaration In order for a page fragment to use the functionality provided by any tag library, you must begin the page with a reference to the tag library or libraries you want to use. For example: <%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %> <%@ taglib prefix="fmt" uri="http://java.sun.com/jstl/fmt" %> <%@ taglib prefix="portlet" uri="http://java.sun.com/portlet" %> <%@ taglib prefix="dspel" uri="http://www.atg.com/taglibs/daf/dspjspELTaglib1_0 %> <%@ taglib prefix="dsp" uri="http://www.atg.com/taglibs/daf/dspjspTaglib1_0" %> <%@ taglib prefix="paf" uri="http://www.atg.com/taglibs/portal/pafTaglib1_3" %>
    • 7 Creating Gear Page Fragments 57 In most cases you will at least need the declarations for the pafTaglib shown above. DSP Page Initialization If you need access to ATG functionality in your page fragment, you must surround your page fragment with <dsp:page> and </dsp:page> tags. Page fragments enclosed in these tags are able to access ATG functionality. For example: <dsp:page> <%!-- GEAR SPECIFIC JSP GOES HERE --%> </dsp:page> Gear Environment Initialization In order to access the data and functionality made available by the PAF, your page should obtain the GearServletResponse and the GearServletRequest. For example: <% //Obtain request/response GearServletResponse gearServletResponse = (GearServletResponse)request.getAttribute(Attribute.GEARSERVLETRESPONSE); GearServletRequest gearServletRequest = (GearServletRequest)request.getAttribute(Attribute.GEARSERVLETREQUEST); %> This makes available the following PAF functionality: • Color palette information • Gear instance parameters • Gear user parameters • Current gear instance • Current community • Current URL • Current user’s roles If your gear page fragments contain references to subsidiary page fragments, then whether or not you need to declare the tag libraries in a particular subsidiary page fragment for a gear depends on how the page fragment is included in its containing page fragment. If the page is included at compile time (using <%@ include ... %>), then you do not need to supply the includes for that page fragment. If, however, the gear page is included as output (using jsp:include or dsp:include), then you would need to initialize the tag libraries within that gear page, since it is essentially a complete JSP page. For additional information on the PAF Tag Library, refer to Appendix B, PAF Tag Library Reference (page 151) in this manual.
    • 58 7 Creating Gear Page Fragments Gear Configuration Page Fragments Gear configuration pages enable the gear developer, portal administrator, community leader, or portal user to customize various aspects of the way the gear works. There are four types of gear configuration, each of which has a corresponding gear mode: Install Configuration installConfig High-level administrative customization; default values of gear parameters (for example, determining whether a gear will be configurable at lower levels or specifying a source for a content feed). Install configuration is available only to Portal Administrators and is displayed in the Portal Administration. Initial Configuration initialConfig Options that are set when the gear is first created in a community. Typically, these are set by the community leader. The initial configuration page for a gear is displayed in the Community Administration. Instance Configuration instanceConfig Administrative customization options, which configure a gear for a particular community. Often these are gear appearance or community membership settings. Typically, these are set by a community leader. The instance configuration page for a gear is displayed in the Community Administration. User Configuration userConfig Gear personalization options (for example, selecting stock ticker symbols in a stock ticker or ZIP Codes in a weather gear). These are always set by portal end users The user configuration page for a gear is displayed in the portal community page. All four configuration types are used for setting gear parameters and can be used for any additional configurations you need in your gear. All types are optional; if you do not create a configuration page for one of the types, then no link will be created to go to that mode. Gear parameters are defined in the gear manifest XML file as in the example below. (For information on the gear manifest XML file format, refer to the Gear Packaging and Deployment (page 69) chapter of this manual.) Gear parameters all must have String names and String values but the String values can be parsed into whatever type you want at the time you use them. In the following example, the value is parsed into an int when it is needed. <parameter name="maxFileSize"> <default-value> 1 </default-value> </parameter> Note that in some cases, different configuration modes can reuse similar configuration files. In many situations, you can use the same code when a gear is created (Initial Configuration) as when changing configuration parameters thereafter (Instance Configuration). ATG Portal includes a form handler class named atg.portal.framework.GearConfigFormHandler that is useful in making many configuration pages for gears. The GearConfigFormHandler can set user gear parameters and instance gear parameters, and it can set default values or override values. You can subclass GearConfigFormHandler to provide other configuration functionality. See the ATG Platform API Reference for
    • 7 Creating Gear Page Fragments 59 atg.portal.framework.GearConfigFormHandler for more information about using this class. See also the examples that use GearConfigFormHandler in the next few sections. Developing Install Configuration Pages The following procedure explains how to develop Install Configuration pages for your gears. This procedure differs from the procedure for developing Initial, Instance, or User Configuration pages. For information on developing Initial, Instance, or User Configuration pages, see the section Developing Initial, Instance, or User Configuration Pages (page 61). 1. Surround the page content with the hasRole tag to prevent users other than a portal administrator from accessing this page. For example: <%@ taglib uri="/paf-taglib" prefix="paf" %> <paf:hasRole roles="portal-admin"> <%!--INSTALL CONFIGURATION FORM PAGE CONTENT GOES HERE --%> </paf:hasRole> 2. Import your form handler. For example, if you create a subclass of the GearConfigFormHandler that you have named MyConfigFormHandler, you would import it as follows: <%@ taglib uri="/dsp" prefix="dsp" %> <dsp:importbean bean="/atg/portal/gear/MyConfigFormHandler"/> If you need additional functionality in the form handler, you can extend the class. 3. Set the gear definition request attribute to the value passed to you by the PAF. <%request.setAttribute(atg.portal.framework.RequestAttributes. GEAR_DEFINITION,(String) request.getParameter("paf_gear_def_id") );%> 4. Set up the default values needed by your form using <dsp:setvalue> tags to set values in your form handler: <dsp:setvalue bean="MyConfigFormHandler.paramType" value="instance"/> <dsp:setvalue bean="MyConfigFormHandler.settingDefaultValues" value="true"/> <dsp:setvalue bean="MyConfigFormHandler.paramNames" value="displayColumnHeaders displayTitle displayDescription displayAuthor authorPropertyName authorDisplayProp1 authorDisplayProp2 displayCreateDate dateStyle timeStyle displayStatus resourceBundle"/> Note how the paramNames property takes a space-delimited list of the names of all the parameters that should be set in this form. 5. Create your configuration form. The form should submit to the current page. You would use the following markup to begin and end the form: <dsp:form method="post" action="<%= request.getRequestURI() %>"> <%!-- CONFIGURATION FORM PAGE CONTENT GOES HERE --%> </dsp:form> 6. You already set your form’s default values in step 5, using <dsp:setvalue> tags. Now, protect your form handler against back button usage by reiterating the property settings you set in step 5, using hidden form fields:
    • 60 7 Creating Gear Page Fragments <dsp:input type="hidden" bean="MyConfigFormHandler.paramType" value="instance"/> <dsp:input type="hidden" bean="MyConfigFormHandler.settingDefaultValues" value="true"/> <dsp:input type="hidden" bean="MyConfigFormHandler.paramNames" value="displayColumnHeaders displayTitle displayDescription displayAuthor authorPropertyName authorDisplayProp1 authorDisplayProp2 displayCreateDate dateStyle timeStyle displayStatus resourceBundle"/> 7. Create the hidden fields necessary for navigation and form processing. The form handler’s successUrl property should be set to the value passed to you in the paf_success_url request parameter by the framework. <dsp:input type="hidden" bean="MyConfigFormHandler.successUrl" value='<%= request.getParameter("paf_success_url") %>'/> Since you are creating an Install Configuration page, you are setting default instance variables. Use a GearConfigFormHandler to set the settingDefaultValues and paramType properties as follows: <dsp:input type="hidden" bean="MyConfigFormHandler.settingDefaultValues" value="true"/> <dsp:input type="hidden" bean="MyConfigFormHandler.paramType" value="instance"/> As in every gear page, you must set the following parameters. Note, though, in Install Configuration you are working with a gear definition whereas in other configuration modes you are working with a gear, so you must take care to set the paf_gear_def_id parameter instead of paf_gear_id as you will in nearly every other gear page you develop. <input type="hidden" name="paf_dm" value="<%=gearEnv.getDisplayMode()%>"/> <input type="hidden" name="paf_gm" value="<%=gearEnv.getGearMode()%>"/> <input type="hidden" name="paf_gear_def_id" value="<%=gearEnv.getGearDefinition().getId() %>"/> 8. Create the form’s input fields. Use <dsp:input> tags because they need to be processed by the DSP form handler. Get the default values for the form fields from the form handler: <dsp:input type="text" bean="MyConfigFormHandler.values.myParam" /> 9. Create the form’s Submit button. Use a <dsp:input> Submit button because it will submit to a DSP form handler and it should submit to the handleConfirm as in the following example: <dsp:input type="submit" value="Submit" bean="MyConfigFormHandler.confirm"/> If you have a multipage form you may want to collect values on several pages and submit them all on the last page. GearConfigFormHandler provides a handleCollectValues method to help you do that. Use a button like this if you take that approach on a multipage form: <dsp:input type="submit" value="Continue" bean="GearConfigFormHandler.collectValues"/>
    • 7 Creating Gear Page Fragments 61 Developing Initial, Instance, or User Configuration Pages The following procedure explains in detail how to develop Initial, Instance, or User Configuration pages for your gears. This procedure differs from the procedure for developing Install Configuration pages, which is described in the section Developing Install Configuration Pages (page 59). 1. As with any gear page fragment, use the InitializeGearEnvironment tag to initialize your gear environment. For example: <%@ taglib uri="/paf-taglib" prefix="paf" %> <paf:InitializeGearEnvironment id="gearEnv"> <%!--CONFIGURATION FORM PAGE CONTENT GOES HERE --%> </paf:initializeGearEnvironment> 2. Import your form handler. For example, if you plan to use the GearConfigFormHandler that is provided with the Portal module, you would import it as follows: <%@ taglib uri="/dsp" prefix="dsp" %> <dsp:importbean bean="/atg/portal/gear/GearConfigFormHandler"/> If you need additional functionality in the form handler, you can extend the GearConfigFormHandler class. 3. Set up the default values needed by your form using <dsp:setvalue> tags to set values in your form handler: <dsp:setvalue bean="GearConfigFormHandler.paramType" value="instance"/> <dsp:setvalue bean="GearConfigFormHandler.settingDefaultValues" value="false"/> <dsp:setvalue bean="GearConfigFormHandler.paramNames" value="property1 property2 property3"/> 4. Create your configuration form. The form tag action method differs depending on the type of configuration. For Initial and Instance Configuration, you should use request.getRequestURI(). For User Configuration, use gearEnv.getOriginalRequestURI() to get the URI you want to go to. For Initial and Instance Configuration, your form tag should look like this: <dsp:form method="post" action="<%=request.getRequestURI() %>"> <%!-- CONFIGURATION FORM PAGE CONTENT GOES HERE --%> </dsp:form> For User Configuration, your form tag should look like this: <dsp:form method="post" action="<%=gearEnv.getOriginalRequestURI()%>"> <%!-- CONFIGURATION FORM PAGE CONTENT GOES HERE --%> </dsp:form> 5. Create the hidden fields necessary for navigation and form processing. The form handler’s successUrl property should be set to the value passed to you in the paf_success_url request parameter by the framework. <dsp:input type="hidden" bean="GearConfigFormHandler.successUrl" value='<%= request.getParameter("paf_success_url") %>'/> As in every gear page, you must set the following parameters. Note, that the setting of paf_gear_id is necessary in every mode (except in Install Configuration, where only a gear definition exists).
    • 62 7 Creating Gear Page Fragments <input type="hidden" name="paf_dm" value="<%=gearEnv.getDisplayMode()%>"/> <input type="hidden" name="paf_gm" value="<%=gearEnv.getGearMode()%>"/> <input type="hidden" name="paf_gear_id" value="<%=gearEnv.getGear().getId() %>"/> In Instance Configuration pages, you must also pass through the paf_community_id and paf_page_id parameters for navigation after form processing. <input type="hidden" param="paf_community_id" value="<%=request.getParameter("paf_community_id") %>"/> <input type="hidden" param="paf_page_id" value="<%=request.getParameter("paf_page_id") %>"/> The GearConfigFormHandler can set user gear parameters and instance gear parameters, and it can set default values or override values. Since you are not creating an Install Configuration page, you are not setting default instance variables, so you would set settingDefaultValues to false and set paramType to instance for all modes except User Configuration, where you would set it to user, as in the following example: <dsp:input type="hidden" bean="GearConfigFormHandler.settingDefaultValues" value="false"/> <dsp:input type="hidden" bean="GearConfigFormHandler.paramType" value="instance|user"/> <dsp:input type="hidden" bean="GearConfigFormHandler.paramNames" value="property1 property2 property3"/> 6. Create the form’s input fields. Use dsp:input tags because they need to be processed by the DSP form handler. Get the default values for the form fields from the gearEnvironment, as follows: <dsp:input type="text" bean="GearConfigFormHandler.values.myParam" value='<%= gearEnv.getGearInstanceParameter("myParam") %>'/> 7. Create the form’s Submit button. Use a dsp:input Submit button because it will submit to a DSP form handler and it should submit to the handleConfirm method, as in the following example: <dsp:input type="submit" value="Submit" bean="GearConfigFormHandler.confirm"/> If you have a multipage form you may want to collect values on several pages and submit them all on the last page. GearConfigFormHandler provides a handleCollectValues method to help you do that. Use a button like this for such a multipage form. <dsp:input type="submit" value="Continue" bean="GearConfigFormHandler.collectValues"/> 8. Add error handling to your form page, as described in the Developing Install Configuration Pages (page 59) section.
    • 7 Creating Gear Page Fragments 63 Example: A Document Exchange User Configuration Page To illustrate what a JSP page fragment might look like, the following code sample shows an abbreviated configuration page for a document exchange gear. This page is designed to appear when the user clicks an Edit link on the gear’s shared view. It uses a subclass of GearConfigFormHandler named DocExchConfigFormHandler. <%@ taglib uri="/dsp" prefix="dsp" %> <%@ taglib uri="/paf-taglib" prefix="paf" %> <paf:InitializeGearEnvironment id="gearEnv"> <dsp:importbean bean="/atg/portal/gear/docexch/DocExchConfigFormHandler"/> <%-- set default values --%> <dsp:setvalue bean="DocExchConfigFormHandler.paramType" value="instance"/> <dsp:setvalue bean="DocExchConfigFormHandler.settingDefaultValues" value="true"/> <dsp:setvalue bean="DocExchConfigFormHandler.paramNames" value="fullListPageSize property1 property2 property3"/> <%-- start form --%> <dsp:form method="post" action="<%= pafEnv.getOriginalRequestURI() %>"> <%-- 2 hidden params indicate we are setting user-specific parameter values --%> <dsp:input type="hidden" bean="DocExchConfigFormHandler.successUrl" value="<%= pafEnv.getOriginalRequestURI() %>"/> <dsp:input type="hidden" bean="DocExchConfigFormHandler.paramType" value="user"/> <dsp:input type="hidden" bean="DocExchConfigFormHandler.settingDefaultValues" value="false"/> <input type="hidden" name="paf_gear_id" value="<%=pafEnv.getGear().getId()%>"/> ... How many documents would you like to see on each page of the full page listing?<br> Full List Page Size: <dsp:input type="text" size="5" bean="DocExchConfigFormHandler.values.fullListPageSize"/> ... <%! -- ADDITIONAL SETTINGS GO HERE --%> ... <dsp:input type="submit" value="Finish" bean="DocExchConfigFormHandler.confirm"/> &nbsp;&nbsp;&nbsp; <input type="submit" value="Cancel"/> ... </dsp:form>
    • 64 7 Creating Gear Page Fragments </paf:InitializeGearEnvironment> Message Handling in Page Fragments Many times you will want your portal pages to generate messages to users. For example, pages with form elements typically need to display error or success messages. It is important to handle these messages in a way that permits them to be localized. I18nMessageProcessor ATG Portal includes a class named atg.portal.admin.I18nMessageProcessor that is useful for handling messages generated by pages. The I18nMessageProcessor collects the messages generated. It can then use the page’s request to determine the locale and the resource bundle to generate the appropriate localized message. ATG Portal includes two I18nMessageProcessor components, named /atg/portal/admin/ FailureMessageProcessor and /atg/portal/admin/SuccessMessageProcessor. These components are identical except in name; using two of them lets you handle and render success and failure messages separately. Configure your form handler to use these two I18nMessageProcessor components by setting these two properties, which exist in classes that extend I18nFormHandler or PortalGenericFormHandler: failureMessageProcessor=/atg/portal/admin/FailureMessageProcessor successMessageProcessor=/atg/portal/admin/SuccessMessageProcessor The I18nMessageProcessor has a localizeMessages method. This method takes any pending messages in the I18nMessageProcessor and formats them, based on the locale of the request passed to the localizeMessages method. You can then extract the localized messages and output them. Using a centralized message processor allows you to redirect between pages indiscriminately and not have to worry that messages might get lost. With message processors in no case will they get lost, although they may get deferred if you redirect to a page that doesn’t contain message rendering code. In that case the messages will be rendered the next time the user reaches a page that does have rendering code. Adding Messages You can add messages to be handled by the I18nMessageProcessor using the following methods in I18nFormHandler or GearConfigFormHandler: addFailureMessage(resourceBundleName, resourceKey, argArray); addSuccessMessage(resourceBundleName, resourceKey, argArray); You can also use a message processor directly outside of a form handler class. You can add messages to be later localized using the I18nMessageProcessor.addMessage() method and add messages that are already localized or that don’t need to be localized using I18nMessageProcessor.addLocalizedMessage().
    • 7 Creating Gear Page Fragments 65 Message Handling Example The following example is a page fragment that renders form success and failure messages. First, we make the I18nMessageProcessor components available: <dsp:importbean bean="/atg/portal/admin/SuccessMessageProcessor"/> <dsp:importbean bean="/atg/portal/admin/FailureMessageProcessor"/> <dsp:getvalueof id="failureMessageProcessor" idtype="atg.portal.admin.I18nMessageProcessor" bean="FailureMessageProcessor"> <dsp:getvalueof id="successMessageProcessor" idtype="atg.portal.admin.I18nMessageProcessor" bean="SuccessMessageProcessor"> Next, we invoke the localizeMessages method in the I18nMessageProcessor components. <% failureMessageProcessor.localizeMessages(request, response); successMessageProcessor.localizeMessages(request, response); %> The next step is to get the success messages and output them, using the core:ForEach tag. <%-- Previous submission success/failure reporting --%> <dsp:getvalueof id="successMessages" idtype="java.util.List" bean="SuccessMessageProcessor.messages"> <core:ForEach id="successIterator" values="<%=successMessages%>" castClass="String" elementId="successMessage"> <img src='<%= dmpage.getRelativeUrl("/html/images/info.gif")%>'> &nbsp;&nbsp;<font class="info"><%=successMessage%></font><br> </core:ForEach> </dsp:getvalueof> We get the failure messages and output them in the same way. <%-- failureMessages --%> <dsp:getvalueof id="failureMessages" idtype="java.util.List" bean="FailureMessageProcessor.messages"> <core:ForEach id="failureIterator" values="<%=failureMessages%>" castClass="String" elementId="failureMessage"> <img src='<%=dmpage.getRelativeUrl("/html/images/error.gif")%>' > &nbsp;&nbsp;<font class="error"><%=failureMessage%></font><br> </core:ForEach> </dsp:getvalueof><%-- failureMessages --%> Finally, we clear all the messages from the two I18nMessageProcessor components. <% failureMessageProcessor.clear();
    • 66 7 Creating Gear Page Fragments successMessageProcessor.clear(); %> </dsp:getvalueof><%-- successMessages --%> </dsp:getvalueof><%-- failureMessages --%> Avoiding Gear Instance Conflicts If you are using the DSP Tag Library in developing your gears, you need to take precautions to avoid conflicts among multiple gear instances on the same page. To do so, observe the following guidelines: • Perform as much form-related functionality as possible on a full-page view. During the full-page view only one gear instance will be interacting with any request-scoped Nucleus component. Only on a shared view can you have more than one gear instance interact with the same request scoped component. • Session scoped Nucleus components will always be shared among all gear instances for the life of the user’s session. • All global scoped Nucleus components will be shared across all gear instances across all sessions. • When you need to use a form handler on a shared view page, don’t set any gear instance specific information in properties of the form handler using the <dsp:setvalue> tag. Instead, pass this information in hidden fields. If you use setvalue tags, then the last setvalue on the page will overwrite previous setvalue tags. • If you are performing anything related to the gear environment from a form handler, pass the environment- related parameters to the form handler in hidden fields and re-create the GearEnvironment object in your form handler using these parameters. Naming Conventions Database Tables If gears you are developing require database tables, it is important to take steps to prevent the possibility of different gears using the same table names. We recommend using prefixes in the table names to indicate which gear will be accessing these tables. Doing so will help database administrators manage the portal data. Java Class Instance Naming With a standalone Java application, Java class instance naming conflicts are not a problem. However, with a portal the Page, Session, and Application Contexts will be used by several different gears. Consequently, it is important to keep this in mind when naming class instances for storage in the contexts. Using a prefix that uniquely identifies the gear that is using a class instance is a good way to avoid class instance naming conflicts. Wireless Gear Page Fragments The main difference between wireless output and HTML output has to do with the gear page fragments. The page fragments for wireless output take the form of JSP files, but their content is Wireless Markup Language (WML).
    • 7 Creating Gear Page Fragments 67 Wireless page fragments must be written in WML and placed in a JSP file. Each request must begin with the following contentType declaration: <%@ page contentType="text/vnd.wap.wml" %> If this declaration appears in the page template, then it does not need to be made in the page fragment. A gear may need to implement fewer gear modes for wireless access than it needs for HTML. For example, a gear generally would not need a WML Install Configuration page, since you can assume the gear would be installed and managed by an administrator on an HTML client, rather than a WML client. For information on the wireless page templates, see the Wireless Templates (page 30) section of the Portal Page Structure chapter. Wireless Markup Language The Wireless Markup Language (WML) was developed by the WAP Forum, an organization devoted to the establishment of open standards for wireless data technology. You will need to understand WML in order to develop gears that will produce output for wireless devices. The WAP Forum site includes useful information on WML, including: • WML Specification • WMLScript Specification • WMLScript Libraries Specification Wireless Device Emulator Before you begin developing a gear that will produce output for wireless devices, you will need a wireless device emulator. You’ll use this to view your gears from simulated mobile phones or PDAs. There are a number of emulators for various wireless devices; these emulators are downloadable from various Web sites. For example, you can download the Nokia Mobile Internet Toolkit from the Nokia Web site: forum.nokia.com
    • 68 7 Creating Gear Page Fragments
    • 8 Gear Packaging and Deployment 69 8 Gear Packaging and Deployment This chapter describes how to package and deploy gears. Gears are packaged as J2EE applications, using the directory structure requirements specified in the Java Servlet Specification Version 2.3, which you can download from the following location: java.sun.com/products/servlet/download.html Gear Manifests To register a gear with the PAF, you will need to create an XML manifest file containing data describing the gear. The file will then need to be imported into the PAF using a Portal Administration utility. Registering the gear places the data in the repository and makes the PAF aware of it. This section explains the format of the necessary XML. You may find that the easiest way to create a gear manifest file is to copy a manifest file from one of the ATG Portal’s baseline gears and modify it to suit your needs. Each gear directory under the <ATG10dir>/Portal/ directory contains a manifest file for the gear. While there is no required location or naming convention for your gear manifest files, we suggest you place it in your gear’s top-level directory and call it gearname-manifest.xml. We recommend that you save your gear manifest files after you have imported them into the PAF as they simplify the process of upgrading gears or moving them to another portal. There is a Document Type Definition (DTD) that prescribes the format and content for your gear manifest files. For reference material on the DTD’s elements and a copy of the DTD, see Appendix A, Portal Manifest Reference (page 131). For instructions on registering your gear, refer to the Portal Administration chapter of the ATG Portal Administration Guide. Once you register your gears, you can use the community administration utilities to associate them with particular communities. The gear manifest file enables you to define gears for your portal. A gear definition can include: • Gear Name • Gear Modes • Gear Description
    • 70 8 Gear Packaging and Deployment • Servlet Context • Images • Dimensions (narrow or wide, short or tall) • Display Modes • Instance Parameters • User Parameters The Gear Manifest File Format File Header The file header for a gear manifest file looks like this: <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE portal-manifest PUBLIC "-//Art Technology Group, Inc.//DTD Portal Manifest//EN" "http://www.atg.com/dtds/portal/framework/portal_manifest_1.0.dtd"> <portal-manifest name="NAME" version="1.0" author="AUTHOR"> <!-- BODY OF MANIFEST GOES HERE --!> </portal-manifest> Gear Manifest Example The gear manifest file sets values for the gear. For example, if the <dimensions> setting in the manifest file is specified as wide when the manifest file is imported into the PAF, this does not mean that the gear can only be rendered in a wide column. It simply means that by default it will be placed in a wide column. In particular, note the <servlet-context> setting for the gear. The servlet context is the gear’s URI (considered independently of the portal). The servlet context must match the value of <context-root> in the gear’s Enterprise Application Deployment Descriptor file (application.xml). The following shows an abbreviated gear manifest file for a document exchange gear. <!--FILE HEADER GOES HERE --!> <gear-definitions> <gear-definition name="Document Exchange" version="1.0" author="AUTHOR"> <description>Document Exchange Gear</description> <servlet-context>/gear/docexch</servlet-context> <dimensions> <dimension name="height">noPreference</dimension> <dimension name="width">wide</dimension> </dimensions> <gear-modes> <gear-mode name="content"> <display-modes> <display-mode name="shared"> <device-output name="html">/DocExchShared.jsp</device-output> </display-mode>
    • 8 Gear Packaging and Deployment 71 <display-mode name="full"> <device-output name="html">/DocExchFull.jsp</device-output> </display-mode> </display-modes> </gear-mode> <gear-mode name="userConfig"> <display-modes> <display-mode name="full"> <device-output name="html">/UserConfig.jsp</device-output> </display-mode> </display-modes> </gear-mode> <!-- ADDITIONAL GEAR MODES GO HERE --!> </gear-modes> <instance-parameters> <parameter name="repositoryPath" required="false"> <default-value> /atg/portal/gear/docexch/DocumentRepository </default-value> </parameter> <parameter name="itemDescriptorName" required="false"> <default-value> document </default-value> </parameter> </instance-parameters> <!-- ADDITIONAL INSTANCE PARAMETERS GO HERE --!> <user-parameters> <parameter name="shortListSize" required="false"> <default-value> 3 </default-value> </parameter> <parameter name="fullListPageSize" required="false"> <default-value> 12 </default-value> </parameter> </user-parameters> <!-- ADDITIONAL USER PARAMETERS GO HERE --!> </gear-definition> </gear-definitions>
    • 72 8 Gear Packaging and Deployment Wireless Gear Deployment Considerations Gear Assembly Since the page fragments for HTML output and wireless output will both be in JSP files, avoid file naming conflicts when you assemble your files into a .WAR file (assuming your gear has multiple device outputs). For example, you may want to create an html subdirectory to contain your JSP files with HTML markup and a wml subdirectory to contain your JSP files with WML markup. Otherwise, a wireless gear can be assembled and deployed just like a gear intended for browser output. Gear Manifest A gear intended for wireless output needs to have the wml device output specified in the gear manifest for each gear mode the gear uses, as illustrated in the following code sample: <gear-modes> <gear-mode name="content"> <display-modes> <display-mode name="shared"> <device-output name="html">/html/DocExchShared.jsp</device-output> <device-output name="wml">/wml/DocExchShared.jsp</device-output> </display-mode> <display-mode name="full"> <device-output name="html">/html/DocExchFull.jsp</device-output> <device-output name="wml">/wml/DocExchFull.jsp</device-output> </display-mode> </display-modes> </gear-mode> <gear-mode name="userConfig"> <display-modes> <display-mode name="full"> <device-output name="html">/html/UserConfig.jsp</device-output> <device-output name="wml">/wml/UserConfig.jsp</device-output> </display-mode> </display-modes> </gear-mode> <!-- ADDITIONAL GEAR MODES GO HERE --!> </gear-modes>
    • 9 Developing and Deploying Portlets 73 9 Developing and Deploying Portlets This chapter provides an introduction to portlet development on ATG Portal. For more detailed and advanced information about portlet development, read the portlet specification, http://jcp.org/aboutJava/ communityprocess/review/jsr168/. Portlets and Gears Portlets are components that comply with the Java standard for portal components, as specified by the portlet specification, JSR 168. See http://jcp.org/aboutJava/communityprocess/review/jsr168/. ATG Portal fully supports the JSR 168 portlet standard. You can use the ATG Portlet Deployment Tool (page 78) to take any portlet and deploy it in your ATG Portal application. The portlet will then function in just the same way as an ATG Portal gear. Comparison of Portlets and Gears A gear is a portal component that’s been developed and deployed for the ATG Portal platform. Here are some of the principal differences between gears and portlets: Gears Portlets Organized as a separate J2EE Web application Similar, but not a Web application Can be completely written as JSPs Must include one Java class, the Portlet class Can use ServletFilters May not use ServletFilters If you are designing a new portal component, you need to decide whether to develop it as a portlet or a gear. If you develop it as a gear, you may be able to take advantage of ServletFilters and other features that are not available to portlets. However, if you develop it as a portlet, your new component will be portable and able to run (after processing) on other portal platforms, as well on the ATG Portal.
    • 74 9 Developing and Deploying Portlets Developing a Portlet The principal elements of a portlet are: • Portlet Class (page 74) • Portlet Deployment Descriptor File (page 75) • Portlet JSPs (page 77) This section discusses each of these elements, using the Helloworld sample portlet as an example. ATG Portal includes three sample portlets that you can use as a guide for developing your own portlets: • Helloworld portlet- A bare-bones portlet that displays a text message and a form field that lets you change the text message. • Slot portlet – A portlet that displays an ATG slot, which can render variable content based on targeting rules. • Userprofiling portlet – A portlet that integrates with ATG’s personalization features, offering profile-based login and logout. These portlets can be found in the <ATG10dir>/Portlet directory. Helloworld Portlet The Helloworld Portlet is used to demonstrate how to construct a portlet that integrates with the ATG platform. The Helloworld Portlet demonstrates the use of ATG servlet beans, including form handlers. It displays a property value of one bean and provides a form input to alter the property value. The Helloworld Portlet can be found in the ATG platform distribution at <ATG10dir>/Portlet/helloworld. The helloworld module directory includes the following: helloworld/ HelloWorldPortlet-manifest.xmlPortlet Deployment Descriptor File helloworld.warhelloworld portlet application helloworld.ear config/helloworld configuration path lib/helloworld Java classes META-INF/ATG module manifest file src/source code for HelloWorld servlet beans helloworld/exploded HelloWorld portlet application Portlet Class The portlet deployment descriptor needs to specify a portlet Java class. The ATG platform provides two base classes you can either use as your portlet class or extend in your own subclass: • atg.portlet.GenericPortletService • atg.portlet.DispatchPortlet The GenericPortletService class provides standard methods for a Nucleus component, including support for self-configuration, name resolution, performance profiling and logging.
    • 9 Developing and Deploying Portlets 75 A class derived from GenericPortletService should override the following methods: • startService • handleRender • handleProcessAction • stopService The DispatchPortlet class extends GenericPortletService. You can use DispatchPortlet as your portlet class if, as in most cases, you want your portlet to dispatch to a JSP or other resource. The DispatchPortlet.path property defines the resource the portlet dispatches to. Portlet Deployment Descriptor File The portlet can be configured from portlet init parameters specified in a Web application deployment descriptor. Named init parameters are treated as properties of the portlet. Parameters prefixed with cxt: are looked up using the portlet’s name context. The following example demonstrates how a portlet whose portlet class extends GenericPortletService might be configured in its deployment descriptor: <portlet> <portlet-name>MyPortletService</portlet-name> <portlet-class>com.acme.portlet.MyPortletService</portlet-class> <init-param> <param-name>loggingDebug</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>loggingWarning</param-name> <param-value>false</param-value> </init-param> <init-param> <param-name>loggingError</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>loggingInfo</param-name> <param-value>true</param-value> </init-param> <init-param> <param-name>MyString</param-name> <param-value>foobar</param-value> </init-param> <param-name>Object</param-name> <param-value>ctx:dynamo:/com/Acme/MyFooObject</param-value> </init-param> </portlet> Portlets derived from GenericPortletService can use the lookup method to look up objects by JNDI context. The object’s JNDI context is accessible through the context property. A GenericPortletService can log information using the standard Nucleus logging facilities provided. Support for info, warning, error and debug levels are provided by the service. If a performance monitor is enabled, the portlet collects performance metrics about the handleService method.
    • 76 9 Developing and Deploying Portlets Helloworld Portlet Deployment Descriptor File The Helloworld sample portlet uses the DispatchPortlet class. Here is the deployment descriptor file used by the Helloworld sample portlet, which is located at <ATG10dir>/Portlet/helloworld/helloworld/ helloworld/WEB-INF/portlet.xml: <?xml version="1.0" encoding="UTF-8" ?> <portlet-app xmlns=http://java.sun.com/xml/ns/portlet/portlet-app_1_0.xsd version="1.0" xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xsi:schemaLocation="portlet-app_1_0.xsd"> <portlet> <portlet-name>HelloWorldPortlet</portlet-name> <display-name>Hello World Portlet</display-name> <portlet-class>atg.portlet.DispatchPortlet</portlet-class> <init-param> <name>path</name> <value>/index.jsp</value> </init-param> <supports> <mime-type>text/html</mime-type> <portlet-mode>VIEW</portlet-mode> </supports> <portlet-info> <title>Hello World Portlet</title> </portlet-info> </portlet> </portlet-app> Note how the following parameters are configured: Element Description Value portlet-class The Java class specified as the portlet class atg.portlet.DispatchPortlet path The relative URL of the JSP that the portlet dispatches to. /index.jsp supports MIME type and portlet modes supported by the portlet text/html VIEW Web Application Deployment Descriptor A portlet deployed on ATG Portal is packaged as a separate J2EE Web application and includes a Web application deployment descriptor file (web.xml). The Portlet Deployment Tool automatically generates the Web application, including the deployment descriptor file. Note the following elements in the Helloworld portlet deployment descriptor file, which is located at <ATG10dir>/Portlet/helloworld/helloworld/ helloworld/WEB-INF/web.xml. These elements are added automatically by the Portal Deployment Tool. DynamoServerPageFilter This element of the deployment descriptor file invokes the DAF servlet pipeline. The DAF servlet pipeline (described in the Request Handling with Servlet Pipelines chapter of the ATG Platform Programming Guide) is a
    • 9 Developing and Deploying Portlets 77 series of request-handling servlets. If the current request has not already started the DAF servlet pipeline, the DynamoServerPageFilter routes the request to the servlet pipeline. <filter> <filter-name>DynamoServerPageFilter</filter-name> <display-name>DynamoServerPageFilter</display-name> <description>This filter invokes the dynamo application framework servlet pipeline.</description> <filter-class>atg.filter.dspjsp.PageFilter</filter-class> </filter> NucleusServlet This element starts Nucleus, if Nucleus has not already been started. The NucleusServlet creates an instance of Nucleus and sets it as an attribute of the Web application, making Nucleus services available. <servlet> <servlet-name>NucleusServlet</servlet-name> <display-name>NucleusServlet</display-name> <description>Initializes nucleus in the current web application.</description> <servlet-class>atg.nucleus.servlet.NucleusServlet</servlet-class> <load-on-startup>1</load-on-startup> </servlet> Taglibs In addition, you may want to add elements like these, which make available the ATG dspjsp and dspjspEL taglibs, as well as the Java portlet taglib. These are standard tag libraries that may be valuable in portlet JSPs: <taglib> <taglib-uri>dsp</taglib-uri> <taglib-location>/WEB-INF/tld/dspjspTaglib1_0.tld</taglib-location> </taglib> <taglib> <taglib-uri>atg-dspjspEL</taglib-uri> <taglib-location>/WEB-INF/tld/dspjspELTaglib1_0.tld</taglib-location> </taglib> <taglib> <taglib-uri>http://java.sun.com/portlet</taglib-uri> <taglib-location>/WEB-INF/tld/portlet.tld</taglib-location> </taglib> Portlet JSPs In many cases, a portlet is designed to dispatch to one or more JSPs. This lets you format the presentation of the portlet output in a page. The Helloworld portlet uses a simple page located at <ATG10dir>/Portlet/ helloworld/helloworld/helloworld/html/index.jsp. There is nothing that makes this page different from a non-portlet JSP that uses a form handler. The Helloworld index.jsp page uses the HelloWorldFormHandler. This line in the index.jsp page sets the actionURL variable, which is used in the action attribute of a form tag:
    • 78 9 Developing and Deploying Portlets <c:set var="actionURL"><portlet:actionURL/></c:set> The core of the index.jsp page accesses the HelloWorldFormHandler with the form and input submit tags from the dpsel tag library. <dspel:form method="post" action="${actionURL}"> <table> <tr> <td><label class="portlet-form-label" for="message"> <fmt:message key="label-message"/></label></td> <td><dspel:input iclass="portlet-form-input-field" type="text" bean="HelloWorldFormHandler.message" id="message"/></td> </tr> <tr> <td>&nbsp;</td> <td><dspel:input iclass="portlet-form-button" type="submit" bean="HelloWorldFormHandler.update"/></td> </tr> </table> </dspel:form> Helloworld Servlet Beans Two beans are demonstrated in the Helloworld sample and are described below. The source code for each of these bean classes can be found at <ATG10dir>/Portlet/helloworld/src. HelloWorld Servlet Bean The HelloWorld servlet bean is a session scoped bean. It has a single property named message. The message property is used to hold the messaged rendered in the portlet. The value of the message property defaults to “Hello World”. HelloWorldFormHandler Servlet Bean The HelloWorldFormHandler servlet bean is a request scoped bean. It is used to modify the message property of the HelloWorld servlet bean. For more information about servlet beans, see the ATG Page Developer's Guide Note how the handleUpdate method in the HelloWorldFormHandler takes a PortletRequest and a PortletResponse: handleUpdate(PortletRequest pRequest, PortletResponse pResponse) Portlet Deployment Tool ATG Portal includes a command-line tool to simplify the deployment of a portlet in an ATG Portal application. This tool generates a J2EE Web application and a gear manifest file from the portlet. Once you deploy a portlet using the Portlet Deployment Tool, the portlet will behave just like an ATG Portal Gear and will be available as a
    • 9 Developing and Deploying Portlets 79 gear in the ATG Portal Administration interface. However, note that after you use the Portlet Deployment Tool, do not attempt to modify the portlet by editing its gear manifest file. Instead, make any desired changes in the portlet’s portlet.xml file and redeploy the portlet. The Portlet Deployment Tool can deploy a portlet that is packaged either as a WAR file or exploded WAR directory. The Portlet Deployment Tool expects to find a portlet.xml deployment descriptor file in the WAR’s WEB-INF directory. The portlet.xml file follows the deployment descriptor file format specified by JSR 168. The Portlet Deployment Tool sets the servlet context for the portlet in the deployment descriptor file (application.xml) and gear manifest files as portlet/<file name of the input WAR file>. Running the Portlet Deployment Tool There are Windows and UNIX scripts for running the Portlet Deployment Tool in the <ATG10dir>/home/bin directory: portletDeploymentTool.bat portletDeploymentTool Portlet Deployment Tool Arguments Run the Portlet Deployment Tool with the following arguments: portletDeploymentTool -i <input file> -o <output file> [-w <working directory>][-f] [-c <contextRoot>] [-ear] Argument Description -i Input: the absolute pathname of the portlet’s WAR file or exploded WAR directory. The Portlet Deployment Tool expects to find a portlet.xml file in the WAR’s WEB-INF directory. -o Output: the absolute path of the directory where the portlet should be installed. -w The path of the working directory the tool should use. If you do not explicitly set the working directory, the tool uses the default working directory. The default working directory is ${atg.dynamo.root}/home/data, if atg.dynamo.root is set as an environment variable. Otherwise, the default working directory is the current directory. -c The context root that should be used for the deployed WAR. -f Overwrite: If there is already a portlet with the same name in the location specified by the -o argument, overwrite it. If you do not use this argument, the Portlet Deployment Tool exits and reports an error if it finds that there is already a portlet with the same name in the location specified by the -o argument. -ear Generate an exploded EAR file rather than an exploded WAR file. -debug Generate debug messages.
    • 80 9 Developing and Deploying Portlets Argument Description -info Generate info and debug messages. -warning Generate warning, info, and debug messages. -error Generate error, warning, info, and debug messages. -silent Generate only minimal messages. -usage Generate a usage message.
    • 10 Web Services for Remote Portlets 81 10 Web Services for Remote Portlets Web Services for Remote Portlets (WSRP) is a means to create presentation-oriented web services that can be easily plugged into a portal. Portals can aggregate presentations from many WSRP services, and those services can be made aware of the portal context, including user profiles for personalization, locale awareness, and interactivity. This chapter contains the following sections: WSRP Overview (page 81) Producer Administration (page 92) Consumer Administration (page 93) WSRP Overview WSRP involves two major entities, a producer and a consumer. The producer offers one or more portlets, information on them, and interfaces for interacting with them. The consumer negotiates with the producer and ultimately presents the portlet contents to an end-user. An example of a producer is a weather information service that hosts interactive applications, and a consumer is a portal site that wants to make these applications available to its users. The WSRP specification is defined by OASIS, a non-profit global consortium. It defines a set of interfaces for accessing and managing portlets. Portals can use these interfaces to display remotely-running portlets inside their pages, without any additional programming by the portal developers. To the end-user, it appears that the portlet is running locally within their portal, but in reality the portlet resides in a remotely-running portlet container. The ATG WSRP environment includes a producer, which provides WSRP services, and a consumer, a client portal that aggregates the remote markup fragments provided by the producer(s) into a portal page. Communication between the consumer and producer is based on the standard WSRP interfaces, which allows producers and consumers to interoperate regardless of location and implementation. For more information on WSRP visit the OASIS site at http://www.oasis-open.org. The figure that follows shows a high-level WSRP environment:
    • 82 10 Web Services for Remote Portlets The ATG consumer and producer can be used in either a homogeneous WSRP environment (ATG consumer and ATG producer) or a heterogeneous environment (mix of ATG and third-party consumer and producer). Producer Overview The producer can be viewed as a container environment in which remote portlets reside and execute. The Web service interfaces exposed by the producer allow a WSRP-compliant consumer to discover the capabilities and offerings of the producer and establish a contract with the producer. Note: The remote components must conform to the JSR 168 standard. The WSRP specification defines four interfaces: • Service Description (required) • Markup (required) • Registration (optional) • Portlet Management (optional) Note: The ATG WSRP implementation does not implement the Portlet Management interface; third-party consumers that expect it (specifically Cloning operations) may not function properly. A simple example of how these interfaces are used is: 1. A consumer is made aware of a producer. The consumer requests the producer’s Service Description. 2. The producer response indicates that registration is required, and what information is requested. 3. The consumer registers and again requests the Service Description. 4. Now that the consumer has registered, the Service Description includes a list of offered portlets. 5. The consumer uses the methods of the Markup interface to request content from the producer and provide end-user interactivity. The WSRP specification also defines the data model. The subset of this model that does not change frequently per request or per session is persisted in the GSA repository. The persistent WSRP information in ATG producer includes: • Consumer registration details • Producer service description • Descriptions of producer offered portlets
    • 10 Web Services for Remote Portlets 83 A single producer repository exists for persisting producer-specific information, structured so that it has almost a one-to-one mapping with the structure of the WSRP data-types. Other items are handled by WSRP services located at /atg/wsrp in Nucleus. Service Description The service description provides information about the producer to a consumer that requests it. The information can include: • Descriptions of customModes and customWindowStates • Whether registration is required • Properties to be provided during registration • Portlets offered Each portlet offered by the producer is associated with a detailed PortletDescription containing the portlet’s meta-data and capability information. The ATG producer is shipped with a service description that includes information for the out-of-the-box capabilities and meta-data supported in the ATG producer environment; however it does not include any portlet descriptions. Customers add portlets by importing them using the WSRP administration UI (see Importing Portlet Descriptions (page 93) later in this chapter). Note: The provided service description can be customized through the repository either directly or using the ACC; however this is not recommended. Customized information may be inconsistent with the underlying ATG functionality and features. In particular, do not modify the following parts of the service description: • RegistrationPropertyDescription • CustomModeDescription • CustomWindowStateDescription • RequiresInitCookie. Do not change to none. The following table shows the Contact properties required for registration, which are included in the defaults shipped with the service description: Property Name Type Label Label XmlLang contact.prefix xsd:string Name Prefix en_US contact.givenName xsd:string Given Name en_US contact.familyName xsd:string Family Name en_US contact.middleName xsd:string Middle Name en_US contact.suffix xsd:string Name Suffix en_US contact.company xsd:string Company Name en_US contact.title xsd:string Title en_US
    • 84 10 Web Services for Remote Portlets Property Name Type Label Label XmlLang contact.postal.name xsd:string Address en_US contact.postal.street xsd:string Street en_US contact.postal.city xsd:string City en_US contact.postal.stateprov xsd:string State/Province en_US contact.postal.postalcode xsd:string Postal Code en_US contact.postal.country xsd:string Country en_US contact.postal.organization xsd:string Organization Name (Postal) en_US contact.online.email xsd:string Email en_US contact.online.uri xsd:string URL en_US contact.telecom.telephone.intcode xsd:string Telephone (International Code) en_US contact.telecom.telephone.loccode xsd:string Telephone (Local Code) en_US contact.telecom.telephone.number xsd:string Telephone (Number) en_US contact.telecom.telephone.ext xsd:string Telephone (Extension) en_US contact.telecom.telephone.comment xsd:string Telephone (Comments) en_US contact.telecom.fax.intcode xsd:string Fax (International Code) en_US contact.telecom.fax.loccode xsd:string Fax (Local Code) en_US contact.telecom.fax.number xsd:string Fax (Number) en_US contact.telecom.fax.ext xsd:string Fax (Extension) en_US contact.telecom.fax.comment xsd:string Fax (Comments) en_US contact.telecom.mobile.intcode xsd:string Mobile (International Code) en_US contact.telecom.mobile.loccode xsd:string Mobile (Local Code) en_US contact.telecom.mobile.number xsd:string Mobile (Number) en_US contact.telecom.mobile.ext xsd:string Mobile (Extension) en_US contact.telecom.mobile.comment xsd:string Mobile (Comments) en_US contact.telecom.pager.intcode xsd:string Pager (International Code) en_US
    • 10 Web Services for Remote Portlets 85 Property Name Type Label Label XmlLang contact.telecom.pager.loccode xsd:string Pager (Local Code) en_US contact.telecom.pager.number xsd:string Pager (Number) en_US contact.telecom.pager.ext xsd:string Pager (Extension) en_US contact.telecom.pager.comment xsd:string Pager (Comments) en_US The service description also includes the OfferedPortlets property, a set of portlet descriptions describing the metadata and capabilities for each Portlet offered by the producer. Do not modify the PortletDescription directly in the repository; use the WSRP administration tool for modifications. Registration The optional Registration interface is a way for consumers to provide information to the producer, which uses it to establish a unique identity for and relationship with the consumer. Users can: • Configure whether registration is required. • Generate unique and secure registration handles. • Validate consumer registration requests. • Specify the lifespan of a consumer registration (apart from the deregister operation); invalidates the consumer registration after a specified time-lapse, either from the point when registration was done or last modified, or from the last consumer activity. Consumers must provide contact details as registration properties (see the Service Description (page 83) section). Registration requests that fail to provide this information are rejected. Using the information, a Consumer-Contact instance is created in the ATG environment. The contact information is associated with a registered consumer and has dynamic properties analogous to the User-Profile properties of the ATG personalization module. The producer is packaged with a default set of Contact RegistrationProperties customers can modify, similar to customizing the ATG User-Profile. Markup The required Markup interface includes two methods for obtaining markup fragments and performing actions on remote portlets: getMarkup and performBlockingInteraction. See the WSRP specification for details on these methods. One producer task is to smoothly interact with the JSR168 container and perform render and action requests on the target JSR168 portlet. However, there are fundamental differences between the way a JSR168 container is invoked from a conventional portal application and the way it is invoked from the producer environment: • The conventional portlet invocation mechanism is the HTTPProtocol request/response paradigm. WSRP requests are instead received as method invocations, with inputs passed as method arguments and the response as a return-type of method-invocation. • Once added to the ATG-Portal, a conventional portlet behaves in conjunction with the portal, community, or page to which it was added, particularly for URL generation. In contrast, a WSRP request does not provide or require the Portal Context information for the producer.
    • 86 10 Web Services for Remote Portlets To handle these potential issues, the ATG producer uses a simulated J2EE FilterChain, which is based on the Nucleus service. The FilterChain and Filter components can be found in the Producer Module at /atg/ wsrp/producer/filter. The Producer executes the following scenario: 1. Receive a Markup request. 2. Obtain the associated HttpServletRequest/Response from the underlying Web Service environment. 3. Wrap the request/response in an HttpServletRequestWrapper or HttpServletResponseWrapper instance. 4. Invoke the FilterChain. 5. Synthesize the Web service method response using the state present in the request/response wrapper. The producer is shipped with preconfigured filters in the WSRP servlet filter chain. Customers can add new Filters for specific functionality such as UserContext handling. Do not remove any filters. The FilterChain must always include the first (head) and last (tail) filters. The head filter initializes the request/response with WSRP specific information, and the tail filter delegates the request to JSR168 Container as a Render request. An ActionFilter must also be present, to identify Action requests and appropriately invoke the JSR168 Container. Consumer Overview A WSRP consumer is an intermediary system that communicates with producers and the portlets they offer on behalf of its client (typically a portal). It gathers markup delivered by the remote portlets to be used by the portal and manages the remote portlet providers. The portal then mediates the markup and interaction between end-users and the producer. The consumer provides comprehensive client-side support for the four WSRP interfaces (Service Description, Registration, Markup, and Manage Portlets). Once a standard JSR168 portlet is deployed in ATG, it behaves like any other ATG portal gear. A gear manifest is generated which can be used for adding the portlet to the ATG Portal framework. The ATG consumer is shipped as separate module responsible for communicating with a producer based on the standard WSRP interfaces. It also is responsible for managing the producer and its offered portlets using ATG repositories. All WSRP functionality is encapsulated within the WSRP-ProxyPortlet. WSRP-ProxyPortlet WSRP-ProxyPortlet acts as a proxy for the remotely running portlet. In the ATG portal framework, it behaves like any other ATG gear. It is provided in deployed form in the WSRP.consumer module, and can be added to the Portal Framework. Like any other portlet, the WSRP-ProxyPortlet can have multiple instances, and each instance can be configured to interact with a specific remote producer offered portlet. WSRP-related configuration and management functionality is provided through the following two custom portlet modes of WSRP-ProxyPortlet: • Config. Corresponds to ATG’s installConfig gear mode and is primarily used to configure the proxy portlet in the framework, including: • Registering with producers • Adding and removing the list of available remote portlets from each producer • Getting the latest WSRP PortletDescription for individual remote portlets
    • 10 Web Services for Remote Portlets 87 • Modifying existing registrations • Deregistering with producers • Edit_defaults. Corresponds to ATG’s instanceConfig gear mode. It is used to configure a particular ProxyPortlet instance (or gear instance) to be associated with a particular portlet from any producers with which the consumer registered during installConfig mode. Consumer Portlet Modes The WSRP-ProxyPortlet has a predefined set of portlet modes, which complements the set supported by the ATG consumer. The combined portlet modes supported by the ProxyPortlet fall into two categories: • Modes that are primarily handled by the proxy portlet itself. These modes are required for proxy portlet administration, and their handling is confined to the scope of the ATG proxy portlet. The modes are: • Edit_defaults • CONFIG • Modes whose handling is delegated to a remote WSRP portlet by the proxy portlet, and which are handled by the ATG consumer. These modes may not be present in the supported modes definition of the proxy portlet; instead their support is determined by the proxy portlet itself. The following remote portlet modes are supported by ATG proxy portlet: • VIEW • EDIT • HELP When a JSR168 portlet is deployed to the ATG portal framework, the existing portlet modes for that portlet are mapped to the corresponding gear mode implementation in ATG, and further mapped to WSRP Portlet modes. The following table shows the mapping: JSR168 Portlet Modes ATG Gear Modes WSRP Portlet Modes VIEW CONTENT wsrp: view EDIT USERCONFIG wsrp: edit Edit_defaults INSTANCECONFIG Not Applicable CONFIG INSTALLCONFIG Not Applicable HELP HELP wsrp: help ABOUT ABOUT Not Supported PREVIEW PREVIEW wsrp: preview The portlet modes supported by the consumer can be passed in the RegistrationData; the portal administrator can select the view, edit, help, or preview portlet modes during registration.
    • 88 10 Web Services for Remote Portlets Consumer Window States A window state is an indicator of the amount of portal page space assigned to a portlet’s content; supported states are Normal, Maximized and Minimized. In the ATG portal framework, portlet window states are implemented in as gear display modes. Like Portlet modes, the window states supported by the consumer can be passed in the RegistrationData; the portal administrator can select a WSRP window state from Normal, Minimized, Maximized and Solo during the registration. • The Normal and Minimized window states correspond to Shared display mode. • The Maximized and Solo window states correspond to Full display mode. Consumer UserProfile Items The UserContext structure is a way for the consumer to provide end-user data to the producer, allowing the producer to perform end-user-specific handling. The UserContext data structure consists of the following members: • UserContextKey. A required token supplied by the consumer to uniquely identify the UserContext, and which remains invariant for the duration of a consumer’s registration. The ATG consumer generates a unique UserContextKey based on the registration context passed by it to the producer in the UserContext structure. The producer can use this key as a reference to the user. • UserCategories. An optional array of strings, each of which specifies a producer-defined user category in which the consumer places the end-user relative to the current operation, to be used for personalization. The ATG consumer does not support UserCategories, and they are ignored if offered by a producer. • UserProfile: An optional WSRP structure used to carry information about the end-user. Note that this structure does not carry any user credentials, such as ID or password. The portlet uses the userProfileItems in its metadata to describe the fields it uses to generate markup from this set and any others the consumer indicated were available when it registered. The ATG consumer provides a mapping between the WSRP UserProfile and ATG personalization’s UserProfile attributes. To modify the default mapping, change the userProfileMap property in the /atg/wsrp/consumer/Configuration Nucleus component. The default mapping is described in the table below. Profile Name Field Name ATG Profile Repository Property name/prefix prefix ContactInformation. prefix name/given given User.firstName name/family family User.lastName name/middle middle User.middleName name/suffix suffix ContactInformation. suffix name/nickname nickname "Empty" bdate bdate User.dateOfBirth Gender gender User.gender
    • 10 Web Services for Remote Portlets 89 Profile Name Field Name ATG Profile Repository Property employerInfo/employer employer "Empty" employerInfo/department department "Empty" employerInfo/jobtitle jobtitle ContactInformation. title homeInfo/postal/name name ContactInformation. address1 homeInfo/postal/street street ContactInformation. address2 homeInfo/postal/city City ContactInformation. city homeInfo/postal/stateprov stateprov ContactInformation. state homeInfo/postal/postalcode postalcode ContactInformation. postalCode homeInfo/postal/country country ContactInformation. country homeInfo/postal/organization organization ContactInformation. companyName homeInfo/telecom/telephone/ intcode intcode ContactInformation. phoneNumber homeInfo/telecom/telephone/ loccode loccode ContactInformation. phoneNumber homeInfo/telecom/telephone/ number number ContactInformation. phoneNumber homeInfo/telecom/fax/intcode intcode ContactInformation. faxNumber homeInfo/telecom/fax/loccode loccode ContactInformation. faxNumber homeInfo/telecom/fax/number number ContactInformation. faxNumber homeInfo/telecom/telephone/ext Ext "Empty" homeInfo/telecom/telephone/ comment comment "Empty" homeInfo/telecom/fax/ext Ext "Empty"
    • 90 10 Web Services for Remote Portlets Profile Name Field Name ATG Profile Repository Property homeInfo/telecom/fax/comment comment "Empty" homeInfo/telecom/mobile/intcode intcode "Empty" homeInfo/telecom/mobile/loccode loccode "Empty" homeInfo/telecom/mobile/number number "Empty" homeInfo/telecom/mobile/ext Ext "Empty" homeInfo/telecom/mobile/comment comment "Empty" homeInfo/telecom/pager/intcode intcode "Empty" homeInfo/telecom/pager/loccode loccode "Empty" homeInfo/telecom/pager/number number "Empty" homeInfo/telecom/pager/ext Ext "Empty" homeInfo/telecom/pager/comment comment "Empty" homeInfo/online/email email User.email homeInfo/online/uri Uri "Empty" businessInfo/postal/name name "Empty" businessInfo/postal/street street "Empty" businessInfo/postal/city City "Empty" businessInfo/postal/stateprov stateprov "Empty" businessInfo/postal/postalcode postalcode "Empty" businessInfo/postal/country country "Empty" businessInfo/postal/organization organization "Empty" businessInfo/telecom/telephone/ intcode intcode "Empty" businessInfo/telecom/telephone/ loccode loccode "Empty" businessInfo/telecom/telephone/ number number "Empty" businessInfo/telecom/telephone/ ext Ext "Empty"
    • 10 Web Services for Remote Portlets 91 Profile Name Field Name ATG Profile Repository Property businessInfo/telecom/telephone/ comment comment "Empty" businessInfo/telecom/fax/intcode intcode "Empty" businessInfo/telecom/fax/loccode loccode "Empty" businessInfo/telecom/fax/number number "Empty" businessInfo/telecom/fax/ext Ext "Empty" businessInfo/telecom/fax/comment comment "Empty" businessInfo/telecom/mobile/ intcode intcode "Empty" businessInfo/telecom/mobile/ loccode loccode "Empty" businessInfo/telecom/mobile/ number number "Empty" businessInfo/telecom/mobile/ ext Ext "Empty" businessInfo/telecom/mobile/ comment comment "Empty" businessInfo/telecom/pager/ intcode intcode "Empty" businessInfo/telecom/pager/ loccode loccode "Empty" businessInfo/telecom/pager/ number number "Empty" businessInfo/telecom/pager/ ext Ext "Empty" businessInfo/telecom/pager/ comment comment "Empty" businessInfo/online/email email "Empty" businessInfo/online/uri Uri "Empty" Inner Title Bar In the ATG Portal implementation, the gear title template is responsible for displaying the gear title bar and optional links for Edit, About and Help. For the proxy portlet implementation, the gear title template is not sufficient, therefore the WSRP-ProxyPortlet itself generates HTML for the links for the supported Portlet
    • 92 10 Web Services for Remote Portlets Modes. The HTML is embedded in the markup obtained from the remote portlet. The inner title bar is based on the PortletDescription of the remote portlet for which the WSRP-ProxyPortlet instance is configured. WSRP Remote Portlet – ProxyPortlet Relationship To establish an association between the WSRP-ProxyPortlet instance and the actual remote WSRP portlet, the consumer uses Gear Instance parameters of the WSRP-ProxyPortlet. Whenever the proxy portlet instance is configured for linking with a specific remote portlet available to the consumer, the Gear Instance parameter of the current ProxyPortlet instance stores a unique consumer generated portletDescriptionID, which identifies a specific remote portlet and its associated PortletDescription. This way a given ProxyPortlet instance is able to reach the target PortletDescription and the producer for which it has been configured. Producer Administration This section describes how to manage the WSRP.admin producer module. It includes the following sections: Starting Up the Producer (page 92) Producer Database Configuration (page 92) Using the Producer Administration UI (page 92) Importing Portlet Descriptions (page 93) Starting Up the Producer Before working with the producer, assemble an application that includes the WSRP.producer module, by following the application assembly instruction provided in the ATG Platform Programming Guide. If this producer exposes any existing JSR168 portlets, includes the modules corresponding to those portlets. Then, deploy and start up your application according to the instructions provided in your application server manuals. Producer Database Configuration The ATG producer uses the GSA repository for persistent data storage. Customers must create the Producer schema in their database using the DDL scripts provided at <ATG10dir>/WSRP/producer/sql, and also import the default data into the producer-repository from the file <ATG10dir>/WSRP/producer/ producer_content.xml using the <ATG10dir>/home/bin/startSQLRepository script. Using the Producer Administration UI The ServiceDescription shipped with ATG has an empty list of offered portlets. For tasks such as managing the offered portlet list and consumer registration, use the Producer Administration module’s user interface (WSRP.admin). First, assemble an application that includes the producer module as described in the application assembly instructions in the ATG Platform Programming Guide. Deploy your application to the appropriate location and start it according to the instructions provided in your application server manuals.
    • 10 Web Services for Remote Portlets 93 Once the application is running, you can access the user interface at: http://hostname:port/WSRP/admin. Refer to the ATG Installation and Configuration Guide for default port information. The user must log in with a username and password that has portal administrator role privileges (admin/admin can be used). Features provided by the Producer Administration module include: • View and delete offered portlets in the producer environment. • Import portlet descriptions from ATG-Portals into the ATG-Producer environment. • View and delete current consumer registrations with the producer. Importing Portlet Descriptions Import portlet descriptions using the Portlet Import Wizard. 1. Select a portlet from the list of existing JSR168-portlets in the ATG-Portal. 2. Modify the default PortletDescription. 3. Save the portlet description into the Producer environment. Note: Only gear Instances corresponding to JSR168 portlets present in an ATG Community are available for importing (the Portlet.helloworld and Portlet.slot sample portlets shipped with ATG are strictly JSR168 compliant). Do not import the WSRP-ProxyPortlet required by the Consumer module. Consumer Administration This section provides information on administering the consumer module. It includes the following sections: Starting Up the Consumer Module (page 94) Consumer Database Configuration (page 94) Using the Consumer Administration UI (page 94) Adding a New Producer to a Consumer (page 94) Modifying Producer Information (page 97) Deleting a Producer (page 97) Configuring a ProxyPortlet Instance (page 97)
    • 94 10 Web Services for Remote Portlets Starting Up the Consumer Module To use the ATG consumer in ATG Portal, assemble an application that includes the WSRP.consumer module, by following the application assembly instructions in the ATG Platform Programming Guide. Deploy your application to the appropriate location and start it according to the instructions provided in your application server manuals. Consumer Database Configuration The consumer module uses the GSA repository for persistent storage. Customers must create the Consumer schema in the database using the DDL scripts provided at <ATGdir>/WSRP/consumer/sql. Note: Unlike the producer repository, the consumer repository does not have to be initialized with default data. Using the Consumer Administration UI The consumer functionality is encapsulated by the WSRP-ProxyPortlet in the Consumer module. Before use, the ProxyPortlet must be added to the Portal Framework using the Portal Administration UI. 1. Go to Portal Admin > Gears > New Gear and upload the <ATGdir>/WSRP/consumer/proxyPortlet/ WSRP4ATGProxyPortlet-manifest.xml gear manifest file. 2. Go to Portal Admin > Gear and click the Configure link corresponding to WSRP4ATGProxyPortlet to configure the ProxyPortlet using the installConfig mode. 3. Add the WSRP4ATGProxyPortlet instances to Portal Communities, using the instanceConfig mode of the WSRP4ATGProxyPortlet gear. To do this, go to Portal Admin > Community > Community Gears > Configure (WSRP4ATGProxyPortlet) and click the Additional Configurations link. Each instance must be associated with a fixed Remote-Producer-Offered-Portlet for its markup content. Adding a New Producer to a Consumer The installConfig mode provides the following features for administering consumer relationships with producers: • Registering a consumer with a new WSRP producer (WSRP register operation). • Modifying the consumer’s registration with a producer (WSRP modifyRegistration operation). • Deleting a producer with which the consumer is registered (WSRP deregister operation). • Modifying any of the existing producers with which the consumer is registered (changing the end point URL of any of the WSRP interface, changing Name, Description etc.). • Adding producer-offered portlets to the ATG consumer. • Removing producer-offered portlets from the ATG consumer. • Removing portlets from the ATG consumer (WSRP destroyPortlet operation).
    • 10 Web Services for Remote Portlets 95 To add a new producer and portlets offered by it to the Consumer environment follow the wizard included in installConfig. 1. Provide a name for the producer, to be used in the consumer UI. 2. Specify the remote Producer properties such as Producer-URL. If necessary provide the URLs for each type of WSRP interface (Service Description, Registration, Markup and Portlet Management). 3. If the producer requires registration, the user is provided with the option of modifying the ATG consumer’s default Registration details, such as: • Consumer-Name
    • 96 10 Web Services for Remote Portlets • Consumer-Agent • is-method-GET-supported • Consumer modes • Window-states • User-Scopes • Additional properties. 4. Select the portlets to be added to the consumer environment from the list of portlets offered by this producer.
    • 10 Web Services for Remote Portlets 97 Modifying Producer Information You can modify the following for an existing producer: • Description • Interface-URLs • Registration Properties • Offered-Portlets To modify the producer, use the wizard-based installConfig interface as described in Adding a New Producer to a Consumer. In the first step, select the Modify option for an existing producer from the list provided, then proceed through the wizard. Deleting a Producer To delete a producer and all of its offered portlets from the consumer, use the wizard-based installConfig interface as described in Adding a New Producer to a Consumer. In the list of existing producers, select the Delete option corresponding to the producer name. Configuring a ProxyPortlet Instance Use the instanceConfigMode to associate a ProxyPortlet instance with a specific producer-offered portlet on which it relies for its markup, and to view the PortletDescription corresponding to any of the portlets in the list available for association.
    • 98 10 Web Services for Remote Portlets The instanceConfig user interface displays a list of added portlets is displayed, grouped by producer. An administrator can associate the current ProxyPortlet instance with any portlet in the list, or view the portlet’s PortletDescription.
    • 11 Adding Gear Alerts 99 11 Adding Gear Alerts The PAF provides a service to send alert notifications based on gear events. For example, you might want to have an e-mail sent automatically to all members of a community when a new event is scheduled in the community’s Calendar Gear. The alert notifications can be displayed by the baseline Alerts gear or sent by e-mail. You can also create your own channels to transmit alerts. In all cases, the scenarios configured for each alert type determine who receives the alert notification. The baseline gears have already been developed to provide some default alert behavior. If you want a gear you develop to send alerts, you need to design your gear so that it publishes Java Message Service (JMS) messages and then create a scenario that performs an action when it receives those messages. The following sections of this chapter explain how to enable this functionality: Alerts Overview (page 99) Alert Services Provided by the PAF and Baseline Gears (page 100) Adding Custom Alert Messages to Gears (page 102) Adding Alert Channels (page 112) Source Handlers and Target Handlers (page 116) Administrative Alerts and Framework Alerts (page 117) Alerts Overview Gear alerts are notifications that originate from a gear event, are filtered and targeted by ATG Scenario Personalization, and are presented to their target audience. The gear developer must determine the events within the gear that are significant enough to capture and translate into alerts. When those events take place, the events’ types and properties are translated into a Java message bean. The message bean is then published via the Java Message Service (JMS) and is consumable by any JMS client configured as a listener to that event. The gear developer must configure the Scenario module to listen to and process the messages that the gear publishes. The Scenario module is responsible for receiving the gear messages, performing any filtering that is desired, and determining who should receive the alert notification. The logic for all of this is based on the criteria defined in the scenario segment. Since the scenario segments can perform complex filtering and targeting based on the properties of the gear’s message bean, this process is dynamic.
    • 100 11 Adding Gear Alerts Once the Scenario module has finished its part, it sends the gear message bean and targeting information along to the AlertMgr. The AlertMgr is a global Nucleus component that is responsible for persisting the alert, formatting the alert in a locale-sensitive manner, and sending the alert to the appropriate targets. The AlertMgr persists alerts to the AlertRepository. The AlertRepository is a persistent store and is accessed by the Alerts gear to retrieve alerts that will be displayed by a Web browser. Each gear event that needs to be translated into an alert must register the event type and a ResourceBundle with the AlertMgr. The ResourceBundle contains the event’s unformatted alert text and defines the properties of the gear message bean that will be used to format the alert text into a displayable String. Each ResourceBundle must be translated to the locales that need to be supported. The Alerts Gear is responsible for displaying the appropriate alerts on a page within a Web browser. When a request to display alerts is received by the Alerts Gear, the appropriate alerts are retrieved from the AlertRepository and then formatted by the AlertMgr. The AlertMgr provides an API for formatting the alert based on the request’s locale and the gear message bean properties that have been persisted with the alert. The AlertMgr may also send e-mail alert notifications if desired. The AlertMgr leverages the DPS Targeted Email system to provide this functionality. Each gear event must specify in its ResourceBundle the name of the e-mail template that is to be used to create the targeted e-mail. In addition to gear alerts, ATG Portal generates administrative alerts and framework alerts, which work in basically the same way as gear alerts, but which are generated by the Portal Administration or the PAF. See Administrative Alerts and Framework Alerts (page 117). Alert Services Provided by the PAF and Baseline Gears This section describes the various alert services and alert events that are provided with the PAF and the Portal module’s Baseline Gears. • A pre-configured gear topic destination to which all gears’ messages are published. The destination is JMS- compliant and can be looked up by gears via the Java Naming & Directory Interface (JNDI). • A global Nucleus component named AlertMgr that provides an API to register message types with their ResourceBundle, persist alerts, and generate alerts in a locale-sensitive manner. This component can be looked up via JNDI. • The AlertRepository that holds alerts targeted to communities, organizations, roles, and individuals. • An Alerts gear that is configurable to display alerts to a Web page. • A configurable AlertRepositoryAdmin component responsible for removing expired alerts from the AlertRepository. Baseline Gear Events The following pre-defined alerts are provided with the baseline gears: Calendar Gear • Event Created • Event Deleted
    • 11 Adding Gear Alerts 101 • Event Edited • Event Viewed Communities Gear • Favorite Community Added • Favorite Community removed Discussion Gear • New Forum Added Document Exchange Gear • Document Created • Document Deleted • Document Updated • Document Viewed Poll Gear • Poll Response HTML Content Gear • URL Changed • Related URL Changed Baseline Gear Scenario Templates Some of the baseline gears also define scenario templates that have been configured to send alerts or record events. These can be seen in the ATG Control Center (ACC) in the Scenarios > Scenario Templates window. The following pre-defined scenario templates are provided with the baseline gears: • Calendar Publisher Alerts • Community Page View Recorder • Discussion Alerts • Document Exchange Alerts • Document Viewed Recorder • Event Viewed Recorder • Favorite Communities Recorder • Poll Vote Recorder PAF Events The following pre-defined alerts are provided for PAF events:
    • 102 11 Adding Gear Alerts • Community Gear Added Recorder • Community Gear Alerts • Community Gear Removed Recorder • Community Page Viewed • Gear Added Alert • Gear Removed Alert • Page Gear Added Recorder • Page Gear Alerts • Page Gear Removed Recorder • Profile Updated • Member Subscribe • Member Unsubscribe • Membership Approved • Membership Declined Adding Custom Alert Messages to Gears If you would like your gears to send messages to the PAF when certain events occur, you will need to create the Java code necessary to define messages and publish them to the Java Messaging System (JMS). These messages form the basis of alerts, which can trigger actions through ATG Scenarios. Note: This procedure uses Java classes that are provided with the PAF for convenience. In this example, we use the base class atg.portal.alert.GearMessage because it provides initialization of properties that most gears will need to use in their alerts. However, you can use other approaches to alerts. The only requirement is that your gear publish a JMS message, which can then be used by ATG Scenarios. The following instructions provide a rough overview of the procedure for creating new alert messages in a gear: 1. Determine which alerts you want your gear to send. You need to decide which events trigger an alert and what the alert message should contain. For example, if you are creating a document exchange gear, you might want to send alerts when documents are created, updated, or deleted, and each alert might contain the community, the document ID, the profile of the user, and the page. 2. Create a JavaBean that extends atg.portal.alert.GearMessage for each message format you require. (See Sample GearMessage Extension (page 103) below.) The GearMessage base class provides initialization and access to useful properties (community ID, profile ID, gear ID, and date properties). Each subclass of GearMessage should contain the member variables required to hold the necessary data for the message.
    • 11 Adding Gear Alerts 103 3. In the case of a document exchange gear, for example, you might extend GearMessage by creating the DocExchMessage class to contain all the properties needed by all document exchange messages, such as the author’s name and the document name. You would then create classes that extend DocExchMessage with properties and values that are specific to each message type (for example, DocumentCreatedMessage, DocumentUpdatedMessage, DocumentDeletedMessage). Each message class must have a unique message type string defined. Add code to make the GearMessagePublisher global service component available. (See Adding GearMessagePublisher to the Gear (page 105) below.) GearMessagePublisher is a Nucleus service that makes it easier to publish messages, by handling the initialization of JMS messages, the message destination lookup, and the message publishing. GearMessagePublisher exposes a method called writeMessage(), which can take any serializable object as its argument. 4. Call the GearMessagePublisher.writeMessage() method from the appropriate gear code. (See Sample Sending Code (page 106) below.) 5. Define the message in the ATG Message System by creating a /atg/dynamo/messaging/ dynamoMessagingSystem.xml file in the gear’s CONFIGPATH. (For example, create the <ATG10dir>/ Portal/GEARNAME/config/atg/dynamo/messaging/dynamoMessagingSystem.xml file, where GEARNAME is the name of the gear.) Model the contents of the file after the code shown in Sample dynamoMessagingSystem.xml File (page 106) below. For more information about configuring and using the ATG Message System, see the ATG Message System chapter in the ATG Platform Programming Guide. 6. Create an alerts element in the gear manifest file inside the gear-definition tag. (See Adding the Alerts Element to the Gear Manifest File (page 107) below.) Once you re-upload the gear’s manifest file, this makes the gear’s alerts available for configuration through the Portal Administration. 7. For each message format and language locale, create a resource bundle properties file with the name referenced in the AlertMgr component. (See Creating a Resource Bundle Properties File (page 108) below.) 8. If you want your alerts to send e-mail, create the e-mail template file used in sending e-mail alerts about this event. (See Creating an E-mail Template File (page 109) below.) 9. Provide a form as part of the gear’s Instance Configuration mode that allows a Community Leader to enable or disable alerts for the gear. (See Creating an Alert Instance Configuration Form (page 109) below.) 10.Extend the Scenario user interface to handle your new message types as it does other alert messages. (See Extending the Scenario User Interface (page 110) below.) 11.Using the Scenario module, configure a scenario that will perform the desired response upon receiving a gear alert. (See Configuring a Scenario (page 112) below.) Sample GearMessage Extension In our example case of a document exchange gear, there are two parts to extending the GearMessage class. The first part involves creating the DocExchMessage class, which extends GearMessage for the document exchange gear. The second part is creating a subclass for each message type that the document exchange gear will need to send (for example, DocumentCreatedMessage, DocumentUpdatedMessage, DocumentDeletedMessage).
    • 104 11 Adding Gear Alerts Extending GearMessage for the Gear The following sample shows an example of a Java class called DocExchMessage, which extends the atg.portal.alert.GearMessage class for the purposes of a document exchange gear, as mentioned in Step 2 of Adding Custom Alert Messages to Gears (page 102) above. package atg.portal.gear.docexch; import atg.portal.framework.*; import atg.portal.alert.*; public class DocExchMessage extends GearMessage { //------------------------------------------- // Member variables specific to DocExch Messages //------------------------------------------- /** Document Id **/ private String mDocumentId; /** Document Name **/ private String mDocumentName; //------------------------------------- // Constructors //------------------------------------- public DocExchMessage() { } public DocExchMessage(GearEnvironment pGearEnv, String pMessageType) { super(pGearEnv, pMessageType); } //------------------------------------- // Property Accessors //------------------------------------- public String getDocumentId() { return mDocumentId; } public void setDocumentId(String pDocumentId) { mDocumentId = pDocumentId; } public String getDocumentName() { return MdocumentName; } public void setDocumentName(String pName) { mDocumentName = pName } }
    • 11 Adding Gear Alerts 105 Extending Gear Message for the Message Type The following sample shows an example of a Java class called DocumentCreatedMessage, which simply extends the DocExchMessage class for the DocumentCreated message type. You would create similar additional classes for any other message types (DocumentUpdated or DocumentDeleted, for example). The most important point to notice in the DocumentCreatedMessage class is that it sets the message type for the GearMessage. Each different gear message needs a unique message type string. This string is used to identify the message in the ATG Message System configuration (see step 5 above). The message type string can be anything you choose, but to ensure that it is unique, you may wish to follow a naming scheme similar to a package naming scheme. (In the case of the sample code below, the name atg.portal.gear.docexch.DocumentCreatedMessage happens to be the same as the package name of the class, but this is not required.) package atg.portal.gear.docexch; import atg.portal.framework.*; public class DocumentCreatedMessage extends DocExchMessage { //------------------------------------- // Member variables //------------------------------------- static final String MESSAGE_TYPE = "atg.portal.gear.docexch.DocumentCreatedMessage"; //------------------------------------- // Constructors //------------------------------------- public DocumentCreatedMessage(GearEnvironment pGearEnv) { super(pGearEnv, MESSAGE_TYPE); } } Adding GearMessagePublisher to the Gear The publishing of messages can be handled by the global service component /atg/portal/alert/ GearMessagePublisher, which handles the creation, initialization, and publishing of JMS messages. GearMessagePublisher exposes a method called writeMessage() that takes an object as its argument. This can be any Serializable Java object. The following example illustrates how you might make GearMessagePublisher available within a gear’s form handler. This corresponds to Step 3 of Adding Custom Alert Messages to Gears (page 102) above. InitialContext ctx = new javax.naming.InitialContext(); mPublisher = (GearMessagePublisher) ctx.lookup(getPublisherName()); In the above example, the getPublisherName method (a method you must provide) returns the property equal to "dynamo:/atg/portal/alert/GearMessagePublisher" (the "dynamo:" protocol signifies that the component is a Nucleus component.)
    • 106 11 Adding Gear Alerts Note that if you are using a Nucleus component as a form handler, you can also make the gear publisher available as a property, and use the component’s .properties file to set that property to link to /atg/portal/ alert/GearMessagePublisher. Also note that repeatedly making a JNDI lookup using InitialContext() can impede performance. Consequently, you may want to create the InitialContext once and then always reference that instance. It would also make sense to cache the result of the lookup. PAF provides a utility class, atg.portal.nucleus.NucleusComponents, which does this. The following is an example of how the NucleusComponents class can be used: mPublisher = (GearMessagePublisher) NucleusComponents.lookup(getPublisherName()); Sample Sending Code Once you have extended GearMessage and made GearMessagePublisher available to the code that will send the message, then you just need to add sending code to the location in the gear where the event occurs. The following is an example of the sending code, mentioned in Step 4 of Adding Custom Alert Messages to Gears (page 102) above. //Create DocumentCreated message DocumentCreatedMessage message = new DocumentCreatedMessage(gearEnv); ... //look up the publisher service try { GearMessagePublisher publisher = getPublisher(); If (publisher != null) { publisher.writeMessage(message); } } catch (JMSException jmse) { ... } Sample dynamoMessagingSystem.xml File The following is an example of the dynamoMessagingSystem.xml file mentioned in Step 5 of Adding Custom Alert Messages to Gears (page 102) above. By creating /atg/dynamo/messaging/ dynamoMessagingSystem.xml and placing it in the gear’s CONFIGPATH, it will be parsed by the ATG PatchBay feature. This makes the message available to the Scenario module, so that you can configure scenarios based on the new alert messages. The jms-type value is the type of the message, i.e. the “message type” string passed to the GearMessage constructor. The message-class value is the name of the Java class that implements the message. (As noted previously, in this example the two are the same, but that need not be the case.) The display-name is how the message event will appear in the Scenario module. <?xml version="1.0" encoding="utf-8"?> <dynamo-message-system>
    • 11 Adding Gear Alerts 107 <!--DSS message registry definitions --> <message-registry> <message-family> <message-family-name> paf </message-family-name> <message-type> <jms-type> atg.portal.gear.docexch.DocumentCreatedMessage </jms-type> <message-class> atg.portal.gear.docexch.DocumentCreatedMessage </message-class> <message-context>session</message-context> <display-name>Document Created</display-name> <description> Generated after DocumentFormHandler gear creates a new document </description> </message-type> ... </message-family> </message-registry> </dynamo-message-system> For more information about configuring and using the ATG Message System, see the ATG Message System chapter in the ATG Platform Programming Guide. Adding the Alerts Element to the Gear Manifest File The following is an example of adding the Alerts element to the Gear manifest file mentioned in Step 6 of Adding Custom Alert Messages to Gears (page 102) above. Adding the Alerts element makes it possible to configure user preferences for the alerts from the My Alerts configuration page. For information on the gear manifest syntax, refer to the Gear Packaging and Deployment (page 69) chapter and the Appendix A, Portal Manifest Reference (page 131). The following sample illustrates the syntax used in the gear manifest XML file for the alerts element, which must be placed within the <gear-definition> element set within the gear manifest. ... <gear-definition name="Document Exchange" version="1.0" author="AUTHOR"> ... <alerts> <alert-message name="DocumentCreatedMessage"> <message-type>atg.portal.gear.docexch.DocumentCreatedMessage</message-type> <default-value>yes_locked</default-value> <resource-bundle> atg.portal.gear.docexch.DocumentCreatedResources </resource-bundle> </alert-message> ... </alerts> ...
    • 108 11 Adding Gear Alerts </gear-definition> The parameter default value can be one of the following: Value Description yes_locked The alert is sent to users automatically and they cannot opt out of receiving it. yes_opened The alert will be sent only to users who specifically request it. no The alert will not be sent by default. Note: The resource-bundle parameter is defined by using the full package name of the resource bundle. This is recommended since it guarantees that the name will be unique. Creating a Resource Bundle Properties File The following is an example of the atg.portal.gear.docexch.DocumentCreatedResources properties file mentioned in Step 7 of Adding Custom Alert Messages to Gears (page 102) above. The java.util.ResourceBundle property files contain locale-specific objects for use by Java classes. The ResourceBundle property file must be placed somewhere in the CLASSPATH. Typically this is best accomplished by placing the ResourceBundle properties file in the same directory as the gear message class that it maps to. The ResourceBundle properties file specifies the alert notification string and the properties that will be used to format the string. The java.text.MessageFormat class performs the formatting. The alertPropertyNames key specifies a list of properties of the gear message JavaBean; those properties are converted to strings and inserted into the alert notification text, which is defined by the resource key alertDisplayString. This resource key contains placeholders for the properties of the message that are to be inserted. For instance, the placeholder {0} receives a string obtained by retrieving the first property specified, documentName. The alertEmailTemplate property refers to a JSP page fragment that will be used by the Alert Manager to notify users of the alert via e-mail. This is only required if you wish to support e-mail notifications (rather than just notifications in the Alert gear.) The e-mail template is discussed more in the next step. # # Web displayable string that is used for the alert notification. The # place holders are replaced by properties retrieved from the message bean. # alertDisplayString=The Document {0} has been created by {1} # # Properties that are used to format the unformatted alertDisplayString above. # Delimited by a comma without any spaces. # alertPropertyNames=documentName,authorName # # The email template file that will be used to create email content # for the targeted email. Should be located in a directory in the DOCPATH.
    • 11 Adding Gear Alerts 109 # alertEmailTemplate=/Portal/email/DocCreatedEmail.jsp Creating an E-mail Template File The following is an example of the e-mail template file mentioned in step 8 of Adding Custom Alert Messages to Gears (page 102) above. The e-mail template file, whose name is specified in the resource bundle created in Step 7, is used by the DPS targeted e-mail system to create, format, and send e-mail alerts. This file should be placed in a directory in the DOCPATH. This page fragment will be passed a parameter called alertMsg, which contains the message bean for this event. <!-- Title: Document Updated Alert Notification --> <setvalue param="messageFrom" value="no-one@example.com"> <setvalue param="messageSubject" value="Alert Notification"> <setvalue param="messageReplyTo" value="no-one@example.com"> <setvalue param="mailingName" value="Alert Notification"> <p>The document named <valueof param="alertMsg.documentName">unknown</valueof> has been created by <valueof param="alertMsg.authorName">unknown</valueof> on <valueof param="alertMsg.creationDate">unknown</valueof> Creating an Alert Instance Configuration Form In order to make Alert settings available to community leaders through the PAF Administration utilities, you must create a form for these settings. This form is then incorporated into the instance configuration page for the gear. In doing this, you should use the handleAlertConfig tag and the atg.portal.admin.AlertConfigBean, which captures the form input, as shown in the following code sample. <!--TAG LIBRARY DECLARATIONS GO HERE --> <dsp:page> <paf:InitializeGearEnvironment id="gearEnv"> ... <jsp:useBean id="alertFormInput" scope="request" class="atg.portal.admin.AlertConfigBean"> <jsp:setProperty name="alertFormInput" property="*"/> </jsp:useBean> <!-- Handle the form if it was filled in --> <core:If value="<%= alertFormInput.getHandleForm() %>" > <paf:handleAlertConfig id="alertConfResult" formData="<%= alertFormInput %>" gearEnv="<%= pafEnv %>"> <core:ExclusiveIf> <core:If value="<%= alertConfResult.getSuccess() %>" > <!-- REDIRECT TO SUCCESS PAGE --> </core:If> <%-- if not, display errors --%>
    • 110 11 Adding Gear Alerts <core:DefaultCase> <%=alertConfResult.getErrorMessage()%> </core:DefaultCase> </core:ExclusiveIf> </paf:handleAlertConfig> </core:If> <form ACTION="<%= origURI %>" METHOD="POST"> <input type="hidden" name="handleForm" value="true"> <input type="hidden" name="paf_gear_id" value="<%= gearID %>"> <input type="hidden" name="paf_dm" value="full"> <input type="hidden" name="paf_gm" value="instanceConfig"> <input type="hidden" name="config_page" value="<%= thisConfigPage%>"> <input type="hidden" name="paf_page_id" value="<%= pageID %>"/> <input type="hidden" name="paf_page_url" value="<%= pageURL %>"/> <input type="hidden" name="paf_community_id" value="<%= communityID %>"/> ... <input type="radio" name="gearAlertPref" value="no" checked><font size="2" color="#000000">&nbsp;<%=alertNoOptionDesc%></font> ... <input type="radio" name="gearAlertPref" value="yes_locked"><font size="2" color="#000000">&nbsp;<%=alertLockedOptionDesc%></font> <%! -- ADDITIONAL SETTINGS GO HERE --%> <%! -– CANCEL AND SUBMIT BUTTONS GO HERE --%> ... </form> </paf:InitializeGearEnvironment> </dsp:page> Extending the Scenario User Interface In order to extend the scenario user interface, as described in Step 10 in the Adding Custom Alert Messages to Gears (page 102) section above, you must create and add two files to your gear’s classes.jar file. • expression-grammar.xml (page 110) • GrammarExtension.java (page 111) expression-grammar.xml You need only one expression-grammar.xml file per gear, but it must contain a custom expression for each event. The following code sample shows the contents of an expression-grammar.xml file for a document exchange gear with an expression for a DocumentCreated event. <?xml version="1.0" encoding="utf-8"?> <!-- ==================================================================== --> <!-- Scenario UI grammar extension for the Alert gear. --> <!-- ==================================================================== --> <?xcl-stylesheet resource="atg/ui/expreditor/xcl/grammar.xsl"?> <context serializable="true">
    • 11 Adding Gear Alerts 111 <!-- Include scenario construct definitions --> <include template="atg.portal.scenario.expression.expression-grammar"/> <!-- ==================================================================== --> <!-- Custom expression for the DocumentCreated event. --> <!-- ==================================================================== --> <sequence id="event-message-atg.portal.gear.docexch.DocumentCreatedMessage"> <attribute name="icon"> <icon path="atg/ui/scenario/images/generic-event.gif"/> </attribute> <attribute name="eventType" value="atg.portal.gear.docexch.DocumentCreatedMessage"/> <attribute name="eventContext" value="request"/> <xml-template> <event-name>atg.portal.gear.docexch.DocumentCreatedMessage</event-name> </xml-template> <token><description>Document Created</description></token> <rule name="portal-event-filter"/> </sequence> <sequence id="condition-message-atg.portal.gear.docexch.DocumentCreatedMessage"> <expression-class> atg.ui.scenario.expression.EventConditionExpression </expression-class> <attribute name="icon"> <icon path="atg/ui/scenario/images/generic-condition.gif"/></attribute> <attribute name="checkedEventName" value="atg.portal.gear.docexch.DocumentCreatedMessage"/> <token><description>Document event</description></token> <rule name="portal-condition-filter"/> </sequence> </context> GrammarExtension.java You need only one GrammarExtension.java file per gear; this file contains nothing that is message-specific. The following code sample shows the contents of a GrammarExtension.java file for a document exchange gear. package atg.portal.gear.docexch; import atg.ui.scenario.*; import atg.ui.scenario.expression.*; import atg.xcl.*; /** Scenario UI grammar extension for a custom action / grammar extension example. */ public class DocexchGrammarExtension extends DefaultGrammarExtension { //---------------------------------------- // Constructors
    • 112 11 Adding Gear Alerts //---------------------------------------- public DocexchGrammarExtension() { // Load the XML file that specifies the grammar extension. super("atg.portal.gear.docexch.docexch-expression-grammar"); } } Configuring a Scenario In order to make an action happen when an alert is sent, you must configure a scenario. The following image shows what the scenario editor would look like if you were configuring it to notify the Apps community (according to each user’s specified preferences) whenever a new document is created using the document exchange gear. The “send alert” action in a scenario gives you several options for where to send the alert: to the community which was the source of the event, to all users in a specific community, organization, or role, or to specific users. Performing this action in the Scenarios module will send a message that is received by a global nucleus component, AlertManager, which is responsible for creating Web and e-mail alert notifications based on the channels configured for the target members. For more information on the scenarios, refer to the ATG Personalization Programming Guide and the ATG Personalization Guide for Business Users. Adding Alert Channels An alert channel is a well-defined medium for distributing alert notifications. ATG Portal provides the ability to send alert notifications over two different alert channels, the Web alert channel and the E-mail alert channel. ATG Portal provides an API that you can use to add other alert channels beyond these two channels. A new alert channel is created by configuring a component whose class is defined as the atg.portal.alert.AlertChannel class. The new alert channel must also specify an atg.portal.alert.AlertHandlerInterface in the same property file. The implementation of the AlertHandlerInterface performs the work of delivering alerts. Each alert channel, therefore, has a corresponding implementation of the AlertHandlerInterface. Finally, the new alert channel must register itself with the atg.portal.alert.AlertMgr global Nucleus component. The AlertMgr handles all incoming alerts, determines the list of users to receive the alerts, and which channels each user should receive the alerts on. The AlertMgr loops over the receiving channels and calls their alert handler methods.
    • 11 Adding Gear Alerts 113 The following sections provide the details of how to create a custom alert channel, register it with the AlertMgr, and handle the distribution of the alert notifications. • Configuring an AlertChannel Component (page 113) • AlertHandlerInterface (page 114) • Registering the New Alert Channel (page 115) • Configuring Alert Channel Preferences (page 115) Configuring an AlertChannel Component The AlertChannel is a class that defines a medium that an alert notification can be sent on. For example, ATG Portal provides the EmailAlertChannel, which provides alert notification via the DPS Targeted Email system. Each new alert channel is configured with its own unique properties in a property file whose class definition is atg.portal.alert.AlertChannel. The new file must be placed somewhere in the CONFIGPATH. Property Name Description Example Value channelDisplayName A name to display in the interface. EmailAlertChannel channelDescription A description to display in the interface. Channel to send alerts via the DPS Targeted Email transactionManager The Nucleus address of the Transaction Manager component. /atg/dynamo/transaction/ TransactionManager alertRepositoryManager All alerts must use the AlertRepositoryManager that controls access to the AlertRepository. The AlertChannel must be persisted to the AlertRepository so it receives an ID that will uniquely identify it. The unique channel ID is used for alert configuration purposes. /atg/portal/alert/ AlertRepositoryManager alertHandler The appropriate implementation of the AlertHandlerInterface /atg/portal/alert/ EmailAlertHandler If the new alert channel needs to extend these properties, then you will need to extend the AlertChannel class. Once the AlertChannel class has been extended, add the new properties to the alert channel component’s properties file. The sample property file below shows how the EmailAlertChannel component is configured. $class=atg.portal.alert.AlertChannel $scope=global channelDisplayName=EmailAlertChannel
    • 114 11 Adding Gear Alerts channelDescription=Channel to send alerts via the DPS Targeted Email transactionManager=/atg/dynamo/transaction/TransactionManager alertRepositoryManager=/atg/portal/alert/AlertRepositoryManager alertHandler=/atg/portal/alert/EmailAlertHandler AlertHandlerInterface The AlertHandlerInterface defines an interface that the new alert channel calls to carry out the delivery of alert notifications. This interface contains a single method, shown below, that must be implemented. Once written and compiled, the class file must be placed somewhere in the CLASSPATH public void alertHandlerAction(AlertTargetMessage pMsg, List pUsers,AlertMgr.MessageMapProps pMsgProps); The first parameter is the atg.portal.alert.AlertTargetMessage object that contains properties pertaining to the message and its targeted audience. Typically the only property of this class that is used in the handler is the message bean. The other properties, the message type, the target type, and the list of targets, are available for special situations that might require advanced filtering and also for logging and debug messages. You can access the message bean associated with the alert being processed like this: ... Object msgBean = pMsg.getMessageBean(); ... The following code sample shows how to use the AlertTargetMessage properties to produce coherent debugging messages. Since the example implementation of the AlertHandlerInterface below is assumed to be an atg.nucleus.GenericService, the logging capability of GenericService is used. ... // If there aren't any users, then log empty user list if (pUsers.size() <= 0) { if (isLoggingDebug()) logDebug("Empty User list for target = " + pMsg.getTargetType()); return; } ... For a full description of the methods available in the atg.portal.alert.AlertTargetMessage class, see the Javadoc for that class in the ATG Platform API Reference. The second parameter in the alertHandlerAction method is a List that contains user objects represented as atg.repository.RepositoryItem objects. You can retrieve any property placed on each user that may have consequences for the delivery of the alert. For example, the code below shows how the EmailAlertHandler loops through the List of users retrieving their e-mail addresses: ... // Loop thru each user retrieving their email address List recipients = new ArrayList(); for (int i = 0; i < pUsers.size(); i++) {
    • 11 Adding Gear Alerts 115 RepositoryItem user = (RepositoryItem)pUsers.get(i); recipients.add((String)user.getPropertyValue(getEmailAddressPropertyName())); } ... The third argument in the alertHandlerAction method is the MessageMapProps object. This is a public nested class defined in atg.portal.alert.AlertMgr. The MessageMapProps class reads in all the resources for a specific message type from its resource bundle, provides access methods to these properties, and provides a utility method to format the message’s alert text. The AlertMgr maintains a Map of message types to their resource bundles that is initialized by each gear’s definition file. The following code sample shows how to use the MessageMapProps argument to obtain a locale-sensitive alert message formatted with the message bean argument. Note that the locale obtained from the user’s properties may or may not be desirable depending upon the circumstances. For example, if you want to send an alert to a user by e-mail, then you probably want to obtain the locale from the user’s locale property. However, if you want to send an alert to a portal page using the Alerts gear, you should instead use the Web page’s request locale to create the Web alert display text. ... Object msgBean = pMsg.getMessageBean() for (int i = 0; i < pUsers.size(); i++) { RepositoryItem user = (RepositoryItem)pUsers.get(i); String locName = (String)user.getPropertyValue(getLocalePropertyName())); Locale locale = RequestLocale.getCachedLocale(locName); String alertText = pMsgProps.getWebDisplayString(msgBean, locale); } ... The class atg.servlet.RequestLocale is an ATG utility class that houses information about the current request’s locale. For a full description of the methods available in the atg.portal.alert.AlertMgr.MessageMapProps class, see the Javadoc for that class in the ATG Platform API Reference. Registering the New Alert Channel The new alert channel needs to be registered with the AlertMgr. The AlertMgr registers alert channels in its alertChannels property array. Each new alert channel needs to have its component path name appended to this array. For example: alertChannels+=/atg/portal/alert/EmailAlertChannel Once the alert channel is registered, the AlertMgr takes into account the new channel when determining the channels that should handle alerts. Configuring Alert Channel Preferences Once a channel has been defined as described above, users can choose to redirect alert notifications to the newly added channel using the My Alerts tab on the user’s portal home page. The My Alerts form handler automatically reflects any additional channels that have been configured. The My Alerts form displays each of the alert notifications available to the current user and allows the user to select one or more of the available
    • 116 11 Adding Gear Alerts channels. Typically, the Web channel, which directs alerts to the user’s Web browser using the Alerts Gear, is configurable by the community administrator and not by the user. When the My Alerts form is submitted, the user’s profile is updated to reflect the channel preferences selected. Source Handlers and Target Handlers Two ATG Portal interfaces can be useful if you need to extend the Portal alert system. These are atg.portal.alert.SourceHandler and atg.portal.alert.TargetHandler. Source Handlers The SourceHandler interface provides a method for conveniently accessing the attributes of a message: String getAlertSetting(String pSouceId, String pSourceType, String pMessageType) ATG Portal includes three classes that implement the SourceHandler interface, one for each of the three types of Portal alerts: GearSourceHandler, AdministrativeSourceHandler, and FrameworkSourceHandler. If you need to extend the Portal alert system to include other types of alerts, you can create a new class that implements SourceHandler for that alert type. Target Handlers In the standard ATG Portal configuration, you can target alerts to individual users, to groups of users with the same security role (such as Community Leaders or Portal Administrators), to organizations, and to communities. The TargetHandler interface provides methods for generating a list of users from a set of constraints, so that alerts can be sent to the appropriate individual or group. public Collection selectTargets(User pUser, Collection pBag) public Collection getConstraints(User pUser) public RepositoryItem[] getUserList(String pTarget) ATG Portal includes four classes that implement the TargetHandler interface, one for each of the four basic ways of classifying users in a portal: CommunityTargetHandler, OrganizationTargetHandler, UserTargetHandler, RoleTargetHandler. For example, the CommunityTargetHandler includes these methods: Method Description selectTargets Returns a Collection of Community IDs getConstraints Returns a Collection of constraints getUserList Returns an array of users for this community
    • 11 Adding Gear Alerts 117 In addition, the CommunityTargetHandler has a usersPerCommunity property. This property represents the number of users that will be requested when getting the list of users belonging to a particular community. If the number of members in a community exceeds this count, the AlertMgr will loop until all members have been retrieved in increments of this value. Administrative Alerts and Framework Alerts In addition to gear alerts, ATG Portal includes two other categories of alerts, administrative alerts and framework alerts. Administrative alerts are messages that are generated from the Portal Administration Pages, while framework alerts are generated by the PAF. See Configuring Alerts in the Portal Administration chapter of the ATG Portal Administration Guide for information about how you can use the Alerts tab in the Portal Administration to manage and create administrative and framework alerts. Administrative and framework alerts are created in much the same way as gear alerts, except that they extend AdministrationMessage or FrameworkMessage, rather than GearMessage. You should not need to create new administrative or framework alerts unless you have extended the Portal Administration or the PAF. The following administrative alerts are pre-defined: Message Name Message Type Resource Bundle CommunityGear AddedMessage atg.portal.messaging. CommunityGearAddedMessage atg.portal.messaging. CommunityGearAddedResources CommunityGear RemovedMessage atg.portal.messaging. CommunityGearRemovedMessage atg.portal.messaging. CommunityGearRemovedResources PageGearAdded Message atg.portal.messaging. PageGearAddedMessage atg.portal.messaging. PageGearAddedMessageResources PageGearRemoved Message atg.portal.messaging. PageGearRemovedMessage atg.portal.messaging. PageGearRemovedMessageResources In addition, the following framework alert classes are included in ATG Portal, but are not pre-defined as alerts. See Configuring Alerts in the Portal Administration chapter of the ATG Portal Administration Guide for information about creating new alerts. Message Name Message Type Resource Bundle MemSubscribeMessage atg.portal.messaging. MemSubscribeMessage atg.portal.messaging. MemSubscribeResources MemUnsubscribe Message atg.portal.messaging. MemUnsubscribeMessage atg.portal.messaging. MemUnsubscribeResources
    • 118 11 Adding Gear Alerts Message Name Message Type Resource Bundle MembershipAccepted Message atg.portal.messaging. MembershipAcceptedMessage atg.portal.messaging. MembershipAcceptedResources MembershipDeclined Message atg.portal.messaging. MembershipDeclinedMessage atg.portal.messaging. MembershipDeclinedResources
    • 12 Creating a Custom Portal 119 12 Creating a Custom Portal You can create an ATG Portal application that is customized for your organization’s needs. Use the basic portal contained in <ATG10dir>/Portal/paf/starter-portal/paf-dar/portal.war and modify it as described in the Creating a New Portal (page 119) section of this chapter. The Customizing Portal Appearance (page 123) section of this chapter also explains and illustrates the options and procedures available for customizing your portal. Among other things, you can add style elements, such as color palettes, stylesheets, and templates The Customizing Portal Authentication (page 129) section of this chapter describes how you can customize the log in, registration, access denied, and error pages. Creating a New Portal To create a new portal: 1. Start with a copy of the existing components in the <ATG10dir>/Portal/paf directory, as described in the Copying the Portal Template (page 119) section. 2. Edit the portal framework configuration files, as described in the Editing Portal Framework Files (page 120) section. 3. Set up the portal database, as described in the Setting Up the Portal Database (page 122) section. 4. Assemble, deploy, and start up your portal application. Use the Portal Administration to set up and administer communities, as described in the Starting Up Your Custom Portal Module (page 122) section and in the ATG Portal Administration Guide. Copying the Portal Template 1. Create a new directory named <ATG10dir>/MyPortal. 2. Change to the <ATG10dir>/Portal/paf directory and run the following command jar -cvf $DYNAMO_ROOT/MyPortal/myportal.jar META-INF/MANIFEST.MF paf-dar/portal/* paf-dar/META-INF/* config/atg/portal/framework/Portal.properties 3. Change to your <ATG10dir>/MyPortal directory and unjar the myportal.jar. Use this command: jar -xvf myportal.jar
    • 120 12 Creating a Custom Portal 4. Rename the expanded <ATG10dir>/MyPortal/paf-dar directory to myportal. Use this command: mv paf-dar myportal The new myportal directory will serve as a template for your new MyPortal application. You will need to edit a number of files before we get started with it but it’ll give you a good base to start with. See the detailed description of the edits below. Editing Portal Framework Files To create a new ATG Portal application, you need to modify the following portal application template files in your <ATG10dir>/MyPortal directory: META-INF/MANIFEST.MF (page 120) config/atg/portal/framework/Portal.properties (page 120) myportal/META-INF/application.xml (page 120) myportal/portal/WEB-INF/web.xml (page 121) myportal/portal/WEB-INF/weblogic.xml (WebLogic only) (page 121) META-INF/MANIFEST.MF Edit this file to contain only the following. List any gears you intend to use for your portal in the ATG-Required entry, or use Portal.gears to include every gear. Manifest-Version: 1.0 ATG-Config-Path: config/ ATG-Required: Portal.paf <place the module names of any required gears here> config/atg/portal/framework/Portal.properties This file should only contain the following. It overrides the default context path of your portal, setting the context path to /myportal. This will be the context path all requests for your portal will contain. So to access a community named theatre in your portal, a user would request: http://hostname:port/myportal/theatre where hostname is the name of the machine that runs your application server, port is the port number that application server uses to listen for HTTP requests, and myportal is your portal name. For default port information, see the ATG Installation and Configuration Guide. # The context path of this portal contextPath=/myportal myportal/META-INF/application.xml Use the following for this file. Once again you need to redefine the context root to /myportal: <?xml version="1.0" encoding="UTF-8"?>
    • 12 Creating a Custom Portal 121 <!DOCTYPE application PUBLIC "-//Sun Microsystems, Inc.//DTD J2EE Application 1. 3//EN" "http://java.sun.com/dtd/application_1_3.dtd"> <application> <display-name>My Portal Application Framework</display-name> <description>Description of MyPortal goes here</description> <module> <web> <web-uri>portal</web-uri> <context-root>/myportal</context-root> </web> </module> </application> myportal/portal/WEB-INF/weblogic.xml (WebLogic only) Use the following for this file. Once again you need to redefine the context root to /myportal. <!DOCTYPE weblogic-web-app PUBLIC "-//BEA Systems, Inc.//DTD Web Application 7.0 //EN" "http://www.bea.com/servers/wls700/dtd/weblogic700-web-jar.dtd"> <weblogic-web-app> <context-root>/myportal</context-root> </weblogic-web-app> myportal/portal/WEB-INF/web.xml In this file, you need to replace all references to the context path /portal with /myportal. Change /portal to /myportal in the following locations: <context-param> <param-name>context-root</param-name> <param-value>/myportal</param-value> </context-param> <init-param> <param-name>defaultLoginTemplateContextURI</param-name> <param-value>/myportal</param-value> </init-param> <init-param> <param-name>defaultAccessDeniedTemplateContextURI</param-name> <param-value>/myportal</param-value> </init-param> <init-param> <param-name>defaultOfflineTemplateContextURI</param-name> <param-value>/myportal</param-value> </init-param> You should also update the display name and description. For example: <display-name>My Default Portal Application</display-name> <description> My Default Portal Application may be used as a template for
    • 122 12 Creating a Custom Portal creating new portal applications. </description> Setting Up the Portal Database Next you will need to setup your database correctly: 1. Copy the <ATG10dir>/Portal/install/minimal-data.xml file to your MyPortal module. Use this command: cp $DYNAMO_ROOT/Portal/install/minimal-data.xml $DYNAMO_ROOT/MyPortal 2. Edit <ATG10dir>/MyPortal/minimal-data.xml. Replace all references to /portal with /myportal. There are ten <add-item> elements in this file that set the value of a servletContext property. The value of each of these should be changed from /portal to /myportal. 3. Create the ATG Portal database tables. This procedure is described in the Configuring Databases and Database Access chapter of the ATG Installation and Configuration Guide. Follow the directions for creating the correct portal tables. To import the minimal data you just created, use a command like this: $DYNAMO_HOME/bin/startSQLRepository.bat -m Portal.paf -database oracle -repository /atg/portal/framework/PortalRepository -import $DYNAMO_ROOT/MyPortal/minimal-data.xml Starting Up Your Custom Portal Module Now that you have a functioning portal application, you need to re-assemble an EAR file that includes it. During application assembly, specify the module for your portal application as described in the ATG Platform Programming Guide. Once you have an EAR file, deploy it to the appropriate location and start it up according to the instructions provided in your application server manuals. Use the Portal Administration interface to create new communities: http://hostname:port/portal/admin To access newly-created communities point your browser to the following: http://hostname:port/myportal/mycommunity For the default port information, refer to the ATG Installation and Configuration Guide. See the ATG Portal Administration Guide for information about setting up communities and creating community pages. Further Customization See the Customizing Portal Appearance (page 123) section of this chapter for information about customizing the visual style of your portal. Among other things, you can add style elements, such as color palettes, stylesheets, and templates The Customizing Portal Authentication (page 129) section of this chapter describes how you can customize the log in, registration, access denied, and error pages.
    • 12 Creating a Custom Portal 123 Customizing Portal Appearance You will probably want to customize the visual style of your portal application. Portal administrators can control the portal’s look and feel by adding the following style elements: • Color palettes • Stylesheets • Page Templates • Layout Templates • Gear Title Templates As with gear definitions, these style elements are registered with the PAF by creating and importing an XML manifest file containing data describing the palette, stylesheet, or template. Uploading the manifest file places the data in the portal repository and makes the PAF aware of it. This chapter explains the format of the XML manifest files. For instructions on registering your gear, refer to the Portal Administration chapter of the ATG Portal Administration Guide. For descriptions of the Page Templates, Layout Templates, and Gear Title Templates provided with the Portal module, see the Portal Configuration chapter of the ATG Portal Administration Guide. Sample manifest files are located in the <ATG10dir>/Portal/paf/starter-portal/paf-dar/portal/ WEB-INF/templates directory: /color/color-manifest.xml /layout/layout-manifest.xml /page/page-manifest.xml /style/style-manifest.xml /titlebar/titlebar-manifest.xml If you followed the custom portal creation process described in the Creating a New Portal (page 119) section of this chapter, there will be copies of these manifest files in the <ATG10dir>/MyPortal/portal/WEB-INF/ templates directory. We recommend that you save your manifest files after you have imported them into the PAF as they simplify the process of upgrading customization features or moving them to another portal. Once you register color palettes, stylesheets, or templates you can use the Community Administration utilities to associate them with particular communities or with the entire portal. For information about using style elements in the Community Administration, see the Style Administration section in the Portal Administration chapter of the ATG Portal Administration Guide. There is a Document Type Definition (DTD) that prescribes the format and content for your manifest files. For reference material on the DTD’s elements and a copy of the DTD, see Appendix A, Portal Manifest Reference (page 131). Manifest File Formats for Customizing Portal Appearance Portals use XML manifest files to add color palettes, stylesheets, and templates to the PAF. You can combine several style elements into a single manifest file, or you can use one file per style element. The following sections describe how to create and use these manifest files: • Manifest File Headers (page 124) • Color Palette Manifests (page 124)
    • 124 12 Creating a Custom Portal • Stylesheet Manifests (page 125) • Page Template Manifests (page 126) • Layout Template Manifests (page 127) • Gear Title Template Manifests (page 128) Manifest File Headers The file header for a color palette, stylesheet, or template manifest file looks like this: <?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE portal-manifest PUBLIC "-//Art Technology Group, Inc.//DTD Portal Manifest//EN" "http://www.atg.com/dtds/portal/framework/portal_manifest_1.0.dtd"> <portal-manifest name="NAME" version="1.0" author="AUTHOR"> <!-- BODY OF MANIFEST GOES HERE --!> </portal-manifest> For simplicity, the file header has been omitted from the examples in the following sections, but it should be included in each real manifest file. Color Palette Manifests A Color Palette manifest file enables you to define color palettes for your portal. A color palette can include: • Background color • Text color • Action link color • Visited link color • A URL for color-related images (such as a background image) • A URL for an icon that represents the palette as an option on the color selection pages of the Community Administration. The following sample shows an abbreviated manifest for a single color palette: <!-- FILE HEADER GOES HERE --!> <color-palettes> <color-palette name="Classic" version="1.0" author="ATG Portal Team"> <description>Classic</description> <servlet-context>/portal</servlet-context> <images> <!-- Icon for color selection pages --!> <image type="small"> <url>/templates/color/images/classic.gif</url> </image> </images>
    • 12 Creating a Custom Portal 125 <entity type="page-body"> <colors> <color type="background">cccccc</color> <color type="text">000000</color> <color type="link">336699</color> <color type="action-link">336699</color> <color type="visited-link">006666</color> </colors> </entity> <entity type="gear-body"> <colors> <color type="background">ffffff</color> <color type="text">666666</color> </colors> </entity> <entity type="gear-title"> <colors> <color type="background">006666</color> <color type="text">ffffff</color> </colors> </entity> </color-palette> <!-- ADDITIONAL COLOR PALETTES GO HERE --!> </color-palettes> For details about the tags and attributes you can use in a Color Palette manifest file, see Color Palette Manifest Elements (page 143) in Appendix A, Portal Manifest Reference (page 131). Stylesheet Manifests A Stylesheet manifest file enables you to specify a location for cascading stylesheets by providing a servlet context and a URL to a cascading stylesheet. You can use stylesheets to render branding headers on pages that may be shared between communities. For example, an access denied page could invoke a stylesheet in its head element with the following tag: <link rel="stylesheet" type="text/css" href="<%= cssURL %>" src="<%= cssURL %>"/> ATG Portal defines the following stylesheet elements: error info user_admin_header_bg_img user_admin_header_community_name user_admin_header_links For example: .error { font-size:9pt; color : cc0000} .info { font-size:9pt; color : 00cc00} .user_admin_header_bg_img { height:61px;
    • 126 12 Creating a Custom Portal background-image:url(/portal/layoutTemplates/images/bg_table_trans_03.gif); background-repeat:no-repeat; } .user_admin_header_community_name { font-size:16px; font-weight:700; } .user_admin_header_links { font-size:10px; font-weight:300; } The following sample shows an abbreviated manifest for a Cascading Stylesheet: <!--FILE HEADER GOES HERE --!> <styles> <style name="NAME" version="VERSION" author="AUTHOR"> <description>Default CSS</description> <servlet-context>/portal</servlet-context> <cascading-style-sheet>/templates/style/css/default.css </cascading-style-sheet> </style> </styles> For details about the tags and attributes you can use in a Stylesheet manifest file, see Stylesheet Manifest Elements (page 145) in Appendix A, Portal Manifest Reference (page 131). Page Template Manifests Page Template manifest files enable you to define page templates for your portal. The Page Template provides the outer wrapper of your pages and encloses a Layout Template. In addition, Page Templates do the following: • Start and end the HTML tags • Start the rendering process • Provide Community Page Navigation • Provide persistent navigation links • Provide the footer The following example shows an abbreviated Page Template manifest. <!--FILE HEADER GOES HERE --!> <page-templates> <page-template name="Default Page Template" version="1.0" author="AUTHOR"> <description>Default Page Template</description> <servlet-context>/portal</servlet-context> <display-modes> <display-mode name="shared"> <device-output name="html">/templates/page/html/shared.jsp</device-output> <device-output name="wml">/templates/page/wml/shared.jsp</device-output> </display-mode> <display-mode name="full"> <device-output name="html">/templates/page/html/full.jsp</device-output> <device-output name="wml">/templates/page/wml/full.jsp</device-output> </display-mode>
    • 12 Creating a Custom Portal 127 </display-modes> </page-template> </page-templates> For details about the tags and attributes you can use in a Page Template manifest file, see Page Template Manifest Elements (page 137) in Appendix A, Portal Manifest Reference (page 131). Layout Template Manifests A Layout Template manifest file enables you to define layouts for the area of your portal page that contains the gears. A layout definition can include: • Display Modes • Output Devices • Layout Images (for display on Administration pages) • Region names and dimensions (narrow or wide, short or tall) A Layout Template uses a single-row HTML table structure to render gear region fragments, which are containers for gears. Each region is the content of a cell within the table. The following example shows an abbreviated Layout Template manifest: <!--FILE HEADER GOES HERE --!> <layout-templates> <layout-template name="Layout 25-75 Template" version="1.0" author="ATG Portal Team"> <description> A layout that defines two columns, the left column reserves 25% of the screen, and the rest is used by the right column </description> <servlet-context>/portal/layoutTemplates</servlet-context> <display-modes> <display-mode name="shared"> <device-output name="html">/templates/layout/html/25_75.jsp </device-output> </display-mode> <display-mode name="full"> <device-output name="html">/templates/layout/html/full.jsp </device-output> </display-mode> </display-modes> <regions> <region name="25_75_LEFT"> <dimensions> <dimension name="width">narrow</dimensions> <dimension name="height">tall</dimensions> </dimensions> </region> <region name="25_75_RIGHT"> <dimensions>
    • 128 12 Creating a Custom Portal <dimension name="width">wide</dimensions> <dimension name="height">tall</dimensions> </dimensions> </region> </regions> </layout-template> </layout-templates> For details about the tags and attributes you can use in a Layout Template manifest file, see Layout Template Manifest Elements (page 139) in Appendix A, Portal Manifest Reference (page 131). Gear Title Template Manifests A Gear Title Template manifest file enables you to specify the location of title bar templates and templates for the HTML to be rendered before and after gear output (gear pre- and post-treatment) for shared and full gear display modes. The following example shows a complete Gear Title Template manifest (minus the header) that specifies a gear title template, gear pre-treatment template, and gear post-treatment template for both shared and full modes. <!--FILE HEADER GOES HERE --!> <gear-title-templates> <gear-title-template name="Default Gear Title Template" version="1.0" author="AUTHOR"> <description>Default Gear Title Template</description> <servlet-context>/portal</servlet-context> <gear-title-template-modes> <gear-title-template-mode name="template"> <display-modes> <display-mode name="full"> <device-output name="html"> /templates/titlebar/html/titlebar.jsp </device-output> </display-mode> <display-mode name="shared"> <device-output name="html"> /templates/titlebar/html/titlebar.jsp </device-output> </display-mode> </display-modes> </gear-title-template-mode> </gear-title-template-modes> </gear-title-template> </gear-title-templates> </portal-manifest> For details about the tags and attributes you can use in a Gear Title Template manifest file, see Gear Title Template Manifest Elements (page 141) in Appendix A, Portal Manifest Reference (page 131).
    • 12 Creating a Custom Portal 129 Customizing Portal Authentication ATG Portal features default user authentication pages, which you can customize (or replace with different ones). The default set of authentication pages includes login and logout forms, and an access denied page. The authentication configuration allows pages to be assigned on a device-specific and community-specific basis. This means that each community could have its own customized login page. An example of this configuration is shown in the Specifying Authentication Page Locations (page 129) section, below. Authentication Pages The default authentication page files reside in the following location: <ATG10dir>/Portal/paf/starter-portal/paf-dar/portal The HTML and WML versions of the following default files are provided in the userprofiling and access directories: login.jsp a basic login page logout.jsp a basic logout page accessDenied.jsp displayed when a logged-in user attempts to access a page without access privileges offline.jsp displayed when a user attempts to access a community that is not active Specifying Authentication Page Locations You can specify the location of the authentication pages in the Access Filter specification in the Portal Filter Chain. By default, the Access Filter is configured with the following init parameters: defaultLoginTemplateContextURI /portal defaultLoginTemplatePathURI /userprofiling/login.jsp defaultAccessDeniedTemplateContextURI /portal defaultAccessDeniedTemplatePathURI /access/accessDenied.jsp
    • 130 12 Creating a Custom Portal
    • Appendix A. Portal Manifest Reference 131 Appendix A. Portal Manifest Reference This appendix explains the elements of the XML manifests used to register gears and customize a portal. It also contains a copy of the DTD containing all of the XML manifest formats. It includes the following sections: Portal Manifest Elements (page 131) Gear Manifest Elements (page 132) Page Template Manifest Elements (page 137) Layout Template Manifest Elements (page 139) Gear Title Template Manifest Elements (page 141) Color Palette Manifest Elements (page 143) Stylesheet Manifest Elements (page 145) The Portal Manifest DTD (page 147) Portal Manifest Elements <portal-manifest> Element A container for the entire portal manifest. It contains one or more of the following elements: <gear-definitions> Element (page 132) <color-palettes> Element (page 143) <styles> Element (page 145) <page-templates> Element (page 137) <layout-templates> Element (page 139) <gear-title-templates> Element (page 141) <portal-manifest> ElementAttributes name required
    • 132 Appendix A. Portal Manifest Reference version optional author optional Gear Manifest Elements <gear-definitions> Element A container for one or more <gear-definition> elements. <gear-definition> Element Attributes name required version optional author optional Sub-elements description An optional text description of the gear. servlet-context See <servlet-context> Element (page 133). images See <images> Element (page 143). dimensions See <dimensions> Element (page 134). gear-modes See <gear-modes> Element (page 133). error-handling See <error-handling> Element (page 135). instance-parameters See <instance-parameters> Element (page 136). user-parameters See <user-parameters> Element (page 136) alerts See <alerts> Element (page 136).
    • Appendix A. Portal Manifest Reference 133 <servlet-context> Element The gear’s URI (considered independently of the portal). The servlet context must match the value of <context-root> in the gear’s Enterprise Application Deployment Descriptor file (application.xml). Example <servlet-context> /gear/mygear </servlet-context> <gear-modes> Element A container for one or more <gear-mode> elements. <gear-mode> Element Specifies a gear mode and encloses that mode’s display modes and device outputs. Attributes Possible Values name (required) content userConfig installConfig instanceConfig initialConfig help about preview Sub-elements display-modes See <display-modes> Element (page 134). Gear Modes Example <gear-modes> <gear-mode name="content"> <display-modes> <display-mode name="shared"> <device-output name="html"> /html/userContent.jsp </device-output>
    • 134 Appendix A. Portal Manifest Reference </display-mode> ... </display-modes> </gear-mode> ... </gear-modes> <display-modes> Element A container for one or more <display-mode> elements. <display-mode> Element Specifies a display mode and encloses that mode’s device outputs. Attributes name Required. Possible values are shared or full. Sub-elements device-output Possible names are html, wml, or chtml. The default is html. Display Modes Example <display-modes> <display-mode name="shared"> <device-output name="html"> /html/userContent.jsp </device-output> </display-mode> ... </display-modes> <dimensions> Element Container for one or more <dimension> elements. <dimension> Element Specifies the default size preference for the gear and region. A <dimension> element has no attributes.
    • Appendix A. Portal Manifest Reference 135 Sub-elements name Required? Possible Values height Required Gear: short, tall, or nopreference Region: short or tall width Required Gear: wide, narrow, or nopreference Region: wide or narrow Dimensions Example <dimensions> <dimension name="height"> tall </dimension> <dimension name="width"> narrow </dimension> </dimensions> <error-handling> Element Enables or disables intercept-errors and cover-errors-with-cache functionality. When enabled, intercept-errors buffers gear output so that exceptions can be handled before any gear content is displayed. If cover-errors-with-cache is enabled and an error or timeout occurs while a gear is rendering, cached content will be displayed instead of the error. Sub-elements Element Value Attribute intercept-errors true or false cover-errors-with-cache true or false Error Handling Example <error-handling> <intercept-errors value="true"/> <cover-errors-with-cache value="true"/> </error-handling>
    • 136 Appendix A. Portal Manifest Reference <instance-parameters> Element Defines and specifies instance parameters for the gear. Sub-elements The <instance-parameters> element must include at least one <parameter> sub-element. The <parameter> sub-element must define name and required attributes. The <default-value> sub-element is an optional sub-element of <parameter>. Instance Parameters Example <instance-parameters> <parameter name="fullDisplayCount" > <default-value> 10 </default-value> <description> How many entries to how </description> </parameter> ... </instance-parameters> <user-parameters> Element Defines and specifies user parameters for the gear. Sub-elements The <user-parameters> element must include at least one <parameter> sub-element. The <parameter> sub-element must define name and required attributes. One or more <default-value> sub-elements is an optional sub-element of <parameter>. User Parameters Example <user-parameters> <parameter name="shortListSize" > <default-value> 3 </default-value> </parameter> ... </user-parameters> <alerts> Element A container for one or more <alert-message> elements. <alert-message> Element Each <alert-message> element describes a type of alert that can be sent by the gear.
    • Appendix A. Portal Manifest Reference 137 Attribute name Required. The short name of the message type. Subelements message-type The fully-qualified name of the alert message type. default-value Can be one of the following: yes_locked--the alert is sent to users automatically and they cannot opt out of receiving it. yes_opened—the alert will be sent only to users who specifically request it. no—the alert will not be sent by default. resource-bundle The resource bundle used by the alert message. Alerts Element Example <alerts> <alert-message name="EventViewedMessage"> <message-type>atg.portal.gear.calendar.EventViewedMessage</message-type> <default-value>yes_locked</default-value> <resource-bundle> atg.portal.gear.calendar.EventViewedResources </resource-bundle> </alert-message> </alerts> Page Template Manifest Elements These elements define page templates in the portal. <page-templates> Element A container for one or more <page-template> elements. <page-template> Element Each <page-template> element specifies a page template that can be used in the portal.
    • 138 Appendix A. Portal Manifest Reference Attributes name required version optional author optional Subelements Element Description/Example <description> An optional description of the page template. <description> Default Page Template </description> <servlet-context> Specifies the servlet-context for the page template. <servlet-context> /portal/layoutTemplates </servlet-context> <images> A container for one or more <image> elements. See <image> Element (page 143). <display-modes> A container for one or more <display-mode> elements. See <display-mode> Element (page 134). Page Template Manifest Example <page-templates> <page-template name="Default Page Template" version="1.0"author="AUTHOR"> <description>Default Page Template</description> <servlet-context>/portal/layoutTemplates</servlet-context> <images> <image type="small"> <url>/images/page_template.gif</url> </image> </images> <display-modes> <display-mode name="shared"> <device-output name="html"> /html/shared_page_template.jsp </device-output> <device-output name="wml">
    • Appendix A. Portal Manifest Reference 139 /wml/shared_deck_template.jsp </device-output> </display-mode> ... </display-modes> </page-template> </page-templates> Layout Template Manifest Elements These elements define a page layout template. <layout-templates> Element A container for one or more <layout-template> elements. <layout-template> Element Each <layout-template> element specifies a layout template that can be used in the portal. Attributes name required version optional author optional Subelements Element Description/Example description An optional description of the layout template.
    • 140 Appendix A. Portal Manifest Reference Element Description/Example <region> Defines a region. Required attribute is name. Required sub-element is dimensions. See <dimensions> Element (page 134). <regions> <region name="25_75_LEFT"> <dimensions> <dimension name="width"> narrow </dimension> <dimension name="height"> tall </dimension> ... </dimensions> </region> ... </regions> <servlet-context> The servlet context of the layout template. <display-modes> The display modes of the layout. See <display-modes> Element (page 134). <images> Images used in the layout. See <images> Element (page 143). Layout Template Manifest Example <layout-templates> <layout-template name="Layout 25-75 Template" version="1.0" author="ATG Portal Team"> <description> A layout that defines two columns, the left column reserves 25% of the screen, and the rest is used by the right hand column </description> <servlet-context> /portal/layoutTemplates </servlet-context> <images> <image type="small"> <url> /images/layout_25_75.gif </url> </image> </images> <display-modes> <display-mode name="shared"> <device-output name="html"> /html/layout_25_75.jsp </device-output> </display-mode> </display-modes>
    • Appendix A. Portal Manifest Reference 141 <regions> <region name="25_75_LEFT"> <dimensions> <dimension name="width"> narrow </dimension> <dimension name="height"> tall </dimension> ... </dimensions> </region> ... </regions> </layout-template> ... </layout-templates> Gear Title Template Manifest Elements These tags specify a gear title template. <gear-title-templates> Element A container for one or more <gear-title-template> elements. <gear-title-template> Element Specifies a gear title template. Attributes name required version optional author optional Subelements Element Description/Example <description> An optional description of the layout template.
    • 142 Appendix A. Portal Manifest Reference Element Description/Example <servlet-context> The servlet context of the layout template. <display-modes> The display modes of the layout. See <display-modes> Element (page 134). <images> Images used in the layout. See <images> Element (page 143). Gear Title Template Example <gear-title-templates> <gear-title-template name="Default Gear Title Template" version="1.0" author="ATG Portal Team"> <description> Default Gear Title Template </description> <servlet-context> /portal/layoutTemplates </servlet-context> <images> <image type="small"> <url> /images/page_template.gif </url> </image> </images> <gear-title-template-modes> <gear-title-template-mode name="template"> <display-modes> <display-mode name="full"> <device-output name="html"> /html/titlebar_template.jsp </device-output> </display-mode> <display-mode name="shared"> <device-output name="html"> /html/titlebar_template.jsp </device-output> </display-mode> </display-modes> </gear-title-template-mode> <gear-title-template-mode name="preTemplate"> ... </gear-title-template-mode> <gear-title-template-mode name="postTemplate"> ... </gear-title-template-mode> </gear-title-template-modes> </gear-title-template> </gear-title-templates>
    • Appendix A. Portal Manifest Reference 143 Color Palette Manifest Elements These tags define a color palette for a portal. <color-palettes> Element The container for one or more <color-palette> elements. The <color-palettes> element has no attributes. <color-palette> Element Defines a color palette. Attributes name required version optional author optional Subelements servlet-context description A string describing the color palette. Optional. images Contains an image subelement. entity <images> Element A container for one or more <image> elements. <image> Element Defines an image for the color palette.
    • 144 Appendix A. Portal Manifest Reference Attributes type Required. May be one of small, large, or background. The small image type is used as an icon to represent the palette in color selection pages. The background image type is used in the background image URL attribute of an HTML <body> tag. Subelements url The URL of the image, relative to the servlet context. alt-text Optional <entity> Element Defines the type of page element that the specified colors or images apply to. Attributes type Required. One of page-body, gear-body, gear-title or highlight Subelements colors Container for one or more color elements images Optional <color> Element Defines colors for particular page elements. It has no subelements and a single required attribute, type. The type attribute can be one of background, text, link, action-link, or visited-link. The tag body contains the hexadecimal definition of the color used by the page element. For example: <color type="background">99ccff</color> Color Palette Example <color-palettes>
    • Appendix A. Portal Manifest Reference 145 <color-palette name="Blue Metrix" version="1.0" author="ATG Portal Team"> <description>Blue Metrix</description> <servlet-context>/portal/layoutTemplates</servlet-context> <images> <image type="small"> <url>/images/color_theme_blue_metrix.gif</url> </image> </images> <entity type="page-body"> <colors> <color type="background">99ccff</color> <color type="text">000000</color> <color type="link">0033ff</color> <color type="action-link">990000</color> <color type="visited-link">336699</color> </colors> </entity> <entity type="page-body"> <images> <image type="background"> <url>/images/bg_colorscheme_bluemetrix.gif</url> </image> </images> </entity> <entity type="gear-body"> <colors> <color type="background">ffffff</color> <color type="text">000000</color> </colors> </entity> <entity type="gear-title"> <colors> <color type="background">4a8cd6</color> <color type="text">ffffff</color> </colors> </entity> </color-palette> Stylesheet Manifest Elements These elements define cascading style sheets. <styles> Element A container for one or more <style> elements. <style> Element Each style element specifies a cascading style sheet that can be used in the portal.
    • 146 Appendix A. Portal Manifest Reference Attributes name required version optional author optional Subelements Element Description/Example <description> An optional description of the style. <description> Stock quote gear </description> <cascading-style-sheet> Specifies the location of a cascading stylesheet used by the style. <cascading-style-sheet> /css/default.css </cascading-style-sheet> <servlet-context> Specifies the servlet-context for the style. <servlet-context> /portal/layoutTemplates </servlet-context> Style Example <styles> <style name="Default" version="1.0" author=""> <description> Default Stylesheet </description> <servlet-context> /portal/layoutTemplates </servlet-context> <cascading-style-sheet> /css/default.css </cascading-style-sheet> </style> </styles>
    • Appendix A. Portal Manifest Reference 147 The Portal Manifest DTD As with any XML file, the portal manifest uses a corresponding Document Type Definition (DTD) to specify the permissible elements in the portal manifest XML file. The following is the DTD for the portal manifest XML file: <!-- ==================================================================== portal_manifest_1.0.dtd - document type for Portal Manifests Version: $Id$ ==================================================================== --> <!ELEMENT portal-manifest (gear-definitions? | color-palettes? | styles? | page-templates? | layout-templates? | gear-title-templates?) > <!ATTLIST portal-manifest name CDATA #IMPLIED version CDATA #IMPLIED author CDATA #IMPLIED > <!ELEMENT gear-definitions (gear-definition+)> <!ELEMENT color-palettes (color-palette+)> <!ELEMENT styles (style+)> <!ELEMENT page-templates (page-template+)> <!ELEMENT layout-templates (layout-template+)> <!ELEMENT gear-title-templates (gear-title-template+)> <!ELEMENT gear-definition (description?, localized-names?, localized-descriptions?, servlet-context, images?, dimensions, gear-modes, rendering?, caching?, error-handling?, instance-parameters?, user-parameters?, alerts?, gear-roles?) > <!ATTLIST gear-definition name CDATA #REQUIRED version CDATA #REQUIRED author CDATA #REQUIRED > <!ELEMENT description (#PCDATA)> <!ELEMENT localized-names (localized-name+)> <!ELEMENT localized-name (#PCDATA)> <!ATTLIST localized-name locale CDATA #REQUIRED> <!ELEMENT localized-descriptions (localized-description+)> <!ELEMENT localized-description (#PCDATA)> <!ATTLIST localized-description locale CDATA #REQUIRED> <!ELEMENT servlet-context (#PCDATA)> <!ELEMENT images (image+)> <!ELEMENT image (url | alt-text?)>
    • 148 Appendix A. Portal Manifest Reference <!ATTLIST image type (small | large | background) #REQUIRED > <!ELEMENT url (#PCDATA)> <!ATTLIST url type (template | pretemplate | posttemplate) #IMPLIED > <!ELEMENT alt-text (#PCDATA)> <!ELEMENT dimensions (dimension+)> <!-- Expected values for a dimension in Portal Application Framework 1.0: Gear Height: short | tall | nopreference Region Height: short | tall Gear Width: wide | narrow | nopreference Region Width: wide | narrow --> <!ELEMENT dimension (#PCDATA)> <!ATTLIST dimension name (height | width) #REQUIRED > <!ELEMENT rendering (render-asynchronously, timeout?)> <!ELEMENT render-asynchronously EMPTY> <!ATTLIST render-asynchronously value (true | false) 'true' > <!ELEMENT timeout EMPTY> <!ATTLIST timeout value CDATA #REQUIRED > <!ELEMENT caching (cache-output | (timeout, cache-key?))> <!ELEMENT cache-key (property+)> <!ELEMENT property EMPTY> <!ATTLIST property name CDATA #REQUIRED > <!ELEMENT cache-output EMPTY> <!ATTLIST cache-output value (true | false) 'true' > <!ELEMENT error-handling (intercept-errors | cover-errors-with-cache)> <!ELEMENT intercept-errors EMPTY> <!ATTLIST intercept-errors value (true | false) 'true' > <!ELEMENT cover-errors-with-cache EMPTY> <!ATTLIST cover-errors-with-cache value (true | false) 'true'
    • Appendix A. Portal Manifest Reference 149 > <!ELEMENT gear-modes (gear-mode+)> <!ELEMENT gear-mode (display-modes)> <!ATTLIST gear-mode name (content | userConfig | instanceConfig | initialConfig | installConfig | help | about | preview) #REQUIRED > <!ELEMENT gear-roles (gear-role+)> <!ELEMENT gear-role (#PCDATA)> <!ELEMENT display-modes (display-mode+)> <!ELEMENT display-mode (device-output+)> <!ATTLIST display-mode name (shared | full | popup) #REQUIRED > <!ELEMENT device-output (#PCDATA)> <!ATTLIST device-output name (html | wml | chtml) 'html' > <!ELEMENT instance-parameters (parameter+)> <!ELEMENT user-parameters (parameter+)> <!ELEMENT parameter (default-value?, description?)> <!ATTLIST parameter name CDATA #REQUIRED > <!ELEMENT alerts (alert-message+)> <!ELEMENT alert-message (message-type?, default-value?, resource-bundle?)> <!ATTLIST alert-message name CDATA #REQUIRED > <!ELEMENT message-type (#PCDATA)> <!ELEMENT resource-bundle (#PCDATA)> <!ELEMENT default-value (#PCDATA)> <!ELEMENT color-palette (description, servlet-context, images?, entity+)> <!ATTLIST color-palette name CDATA #REQUIRED version CDATA #IMPLIED author CDATA #IMPLIED > <!ELEMENT entity (colors? | images?)> <!ATTLIST entity type (page-body | gear-body | gear-title | highlight) #REQUIRED > <!ELEMENT colors (color+)>
    • 150 Appendix A. Portal Manifest Reference <!ELEMENT color (#PCDATA)> <!ATTLIST color type (background | text | link | action-link | visited-link) #REQUIRED > <!ELEMENT style (description?, servlet-context, cascading-style-sheet)> <!ATTLIST style name CDATA #REQUIRED version CDATA #IMPLIED author CDATA #IMPLIED > <!ELEMENT cascading-style-sheet (#PCDATA)> <!ELEMENT page-template (description?, servlet-context, images?, display-modes)> <!ATTLIST page-template name CDATA #REQUIRED version CDATA #IMPLIED author CDATA #IMPLIED > <!ELEMENT layout-template (description?, servlet-context, images?, display-modes, regions)> <!ATTLIST layout-template name CDATA #REQUIRED version CDATA #IMPLIED author CDATA #IMPLIED > <!ELEMENT regions (region+)> <!ELEMENT region (dimensions+)> <!ATTLIST region name CDATA #REQUIRED > <!ELEMENT gear-title-template (description?, servlet-context, images?, gear-title-template-modes?)> <!ATTLIST gear-title-template name CDATA #REQUIRED version CDATA #IMPLIED author CDATA #IMPLIED > <!ELEMENT gear-title-template-modes (gear-title-template-mode+)> <!ELEMENT gear-title-template-mode (display-modes)> <!ATTLIST gear-title-template-mode name (preTemplate | template | postTemplate) #REQUIRED >
    • Appendix B. PAF Tag Library Reference 151 Appendix B. PAF Tag Library Reference The PAF tag library contains a core set of tags for portal application JSPs. These tags begin with the prefix “paf,” for example, paf:renderTab. You can find the tag library definition file in <ATG10dir>/Portal/taglib/ pafTaglib/1.3/tld. For information on the accessor methods and properties made available by the PAF Tag Library, refer to the interfaces in the atg.portal.framework package in the ATG Platform API Reference. Earlier versions of the PAF tag library will still function in ATG Portal. However, we recommend that any new portal pages you develop should use the latest version of the tag library. The PAF Tag Library includes the following tags: Tag Name Description paf:layout (page 152) Determines the layout to render based on the Display Mode and the current Device. paf:titlebar (page 152) Includes a GearTitleTemplate. paf:hasRole (page 152) Tests for global roles before allowing access to tag contents. paf:hasCommunityRole (page 153) Tests for community roles before allowing access to tag contents. paf:hasGearRole (page 153) Tests for gear roles before allowing access to tag contents. paf:renderTab (page 154) Renders a tab for a portal template header set of tabs. paf:defaultTab (page 154) Renders this tab if the page object passed to the parent renderTab tag is not the currently rendering page. paf:currentTab (page 154) Renders this tab if the page object passed to the parent renderTab tag is the currently rendering page. paf:encodeURL (page 155) Encodes a portal or gear URL with session ID and portal or gear specific parameters. paf:context (page 155) Obtains a portal or gear context.
    • 152 Appendix B. PAF Tag Library Reference Tag Name Description paf:include (page 156) Dispatches a request to included content For each tag described below, there is a reference to a page that uses the tag. The references to each of the example pages are paths relative to <ATG10dir>/Portal/paf/starter-portal/paf-dar/portal/ templates. paf:layout Includes a page layout. Which layout to render is determined based on the Display Mode, the current Device, and the URL found in page.layout.displayMode.deviceOutputs. Body: empty Example: page/html/shared.jsp paf:titlebar Includes a GearTitleTemplate Body: empty Attributes Attribute Description Required? gear String true type String. May be pre or post, for pre-treatment or post-treatment of the gear. false Example: layout/html/full.jsp paf:hasRole Renders the body of the tag if the user has one of the global roles indicated by the comma-separated list of role paths specified by the roles attribute. A role test can be negated by prepending the role name with an exclamation point (!). If a barrier attribute is specified, and its value is true, this will redirect the user to a login or access denied page rather than filtering the tag body content.
    • Appendix B. PAF Tag Library Reference 153 Body: JSP content Attributes Attribute Description Required? roles String. A comma-separated list of roles to test for. true barrier boolean. If true, redirects user to login or access denied page. false paf:hasCommunityRole Renders the body of the tag if the user has one of the community-relative roles indicated by the comma- separated list specified by the roles attribute. A role test can be negated by prepending the role name with an exclamation point (!). Body: JSP content Attributes Attribute Description Required? roles String. A comma-separated list of roles to test for. true barrier boolean. If true, redirects user to login or access denied page. false Example: page/html/shared.jsp paf:hasGearRole Renders the body of the tag if the user has one of the gear-relative roles indicated by the comma-separated list specified by the roles attribute. A role test can be negated by prepending the role name with an exclamation point (!). Body: JSP content Attributes Attribute Description Required? roles String A comma-separated list of roles to test for. true
    • 154 Appendix B. PAF Tag Library Reference Attribute Description Required? barrier boolean. If true, redirects user to login or access denied page. false paf:renderTab A parent tag with two children tags to render a tab for a portal template header set of tabs. One of the two children tags, defaultTab or currentTab is rendered, depending on whether the current page object passed to the renderTab tag is the same as the current page that is being rendered. Body: JSP content Attributes Attribute Description Required? page true Example: page/html/shared.jsp paf:defaultTab Child tag of renderTab tag. If the page object passed to the parent renderTab tag is not equal to the currently rendering page, then the body of this tag is rendered. Body: JSP content Example: page/html/shared.jsp paf:currentTab Body: JSP content Child tag of renderTab tag. If the page object passed to the parent renderTab tag is equal to the currently rendering page, then the body of this tag is rendered. Example: page/html/shared.jsp
    • Appendix B. PAF Tag Library Reference 155 paf:encodeURL Encodes a portal or gear URL with session ID and portal or gear specific parameters. The id attributes specifies the name of the URL. The optional context attributes are used to encode used a specified context. Body: JSP content Attributes Attribute Description Required? page String true id String false var String false scope String false url String false portalContext String false gearContext String false context String false Example: page/html/shared.jsp paf:context The context tag is used to obtain a portal or gear context. The context is identified by the name specified by the id attribute. The optional type attribute can be used to determine the type of context. The currently supported types include PortalContext.class and GearContext.class. Body: JSP content Attributes Attribute Description Required? id false var false scope false
    • 156 Appendix B. PAF Tag Library Reference Attribute Description Required? type String. One of PortalContext.class or GearContext.class false Example: page/html/shared.jsp paf:include The include tag is used to dispatch a request to included content. Content is specified by the context attribute. Body: JSP content Attributes Attribute Description Required? context true Example: layout/html/region.jspf
    • Index 157 Index A AccessFilter, 18 accessibility recommendations, 56 administrative alerts, 117 alerts, 48 adding, 102 administrative, 117 configuring a scenario, 112 creating an instance configuration form, 109 creating e-mail template files, 109 dynamoMessagingSystem.xml, 106 extending the scenario user interface, 110 framework, 117 gear manifest file, 107 GearMessage class, 103 GearMessagePublisher class, 105 overview, 99 resource bundles, 108 sending code, 106 SourceHandler, 116 TargetHandler, 116 atg.portal.admin.I18nMessageProcessor, 64 atg.portal.alert.GearMessage, 102 atg.portal.alert.SourceHandler, 116 atg.portal.alert.TargetHandler, 116 atg.portal.framework.Environment, 41 atg.portal.framework.GearConfigFormHandler, 35 atg.portal.servlet.GearContext, 8 atg.portal.servlet.GearServletRequest, 9 atg.portal.servlet.GearServletResponse, 11 atg.portlet.DispatchPortlet, 75 atg.portlet.GenericPortletService, 74 authentication pages, 129 specifying location, 129 C cascading stylesheets (see stylesheet manifests) color palette manifests, 124, 143 Community objects, 9 CommunityFilter, 17 configuration pages, 58 example, 63 form handling (see form handling) initial configuration, 61 install configuration, 59 instance configuration, 61 user configuration, 61 copying a gear, 50 customizing portal appearance, 123 portal authentication, 129 D deployment descriptor, 75 deployment portlets deployment descriptor, 75 Device objects, 9 device outputs, 46 DeviceFilter, 15 DeviceOutputFilter, 16 display modes, 46, 51, 134 DisplayFilter, 15 DisplayMode objects, 9 DSP page initializations, 57 DTD (see portal manifest DTD) dynamoMessagingSystem.xml (see alerts) DynamoServerPageFilter, 76 E e-mail template files (see alerts) error messages, 64 F FailureMessageProcessor component, 64 filter mapping, 13 filters (see servlet filters) form handling, 33 accessing configuration parameters, 34 gear configuration pages, 33 gear pages, 33 GearConfigFormHandler, 35 JSP, 35 framework alerts, 117 G gear definition, 2 gear design example, 51 gear instance, 2 gear manifests, 69, 133 alerts element, 107 example, 70 file format, 70
    • 158 Index wireless, 72 gear modes, 45, 133 gear names localizing, 50 gear page fragments configuration pages, 58 wireless pages, 66 gear title template manifests, 128, 141 GearConfigFormHandler (see form handling) GearContext (see atg.portal.servlet.GearContext) GearEnvironment initialization, 57 GearMessage class (see alerts) GearMessagePublisher class (see alerts) gears Administration, 48 alerts, 48 (see alerts) and the PAF, 31 definition, 1 designing, 45 device outputs, 46 dimensions, 47 display modes, 46, 51 extending existing, 50 gear modes, 45 implementation overview, 3 manifests, 69, 72 packaging and deployment, 69 page fragments, 47, 55 persistent data repositories, 35 rendering, 21, 31 roles, 48, 51 synchronizing, 36 wireless, 72 GearServletFilter, 14 GearServletRequest (see atg.portal.servlet.GearServletRequest) GearServletResponse (see atg.portal.servlet.GearServletResponse) H Helloworld portlet, 74 HTML considerations, 55 I I18nMessageProcessor (see atg.portal.admin.I18nMessageProcessor) Include Filter, 42 L layout considerations, 56 layout template manifests, 127, 139 link URLs, 32 usage, 33 links, 32 usage, 33 localization gear names, 50 localization considerations, 49 M manifests color palette, 124, 143 gear, 69, 133 gear title template, 128, 141 layout template, 127, 139 manifest file headers, 124 page template, 126, 137 stylesheet, 125, 145 message handling, 64 N naming conventions database tables, 66 Java class instances, 66 NucleusServlet, 77 O OASIS, 81 OfflineFilter, 19 P packaging J2EE applications, 69 PAF (see Portal Application Framework) PAF tag library gear development, 32, 40 security, 40 page fragments, 47 (see gears) message handling, 64 Page objects, 9 page template manifests, 126, 137 PageFilter, 18 PageTemplateDispatcherServlet, 20 performance resources, 37 persistent data repositories, 35 Portal Application Framework administration pages, 2 definition, 2 services, 2 Portal Filter Chain, 11 portal manifest DTD, 147 portal objects, 9 lookup method, 11
    • Index 159 PortalContext component, 7 PortalFilter, 16 PortalObjectResolver component, 10 portals appearance customization, 123 authentication customization, 129 definition, 1 page structure, 21 roles, 48 PortalServerFilter, 13 portlet class, 74 Portlet Deployment Tool, 78 command line arguments, 79 portlets, 73 and gears, 73 deploying, 78 JSPs, 77 R request accessing, 8 attributes, 8 request properties, accessing, 7 resource bundles, 108 response, 11 response URIs, 11 role test methods (see security methods) S security, 39 Include Filter, 42 J2EE, 43 levels, 3 predefined areas, 39 Secure Socket Layer, 44 tags, 40 security methods, 40 hasRole(), 42 isPortalAdministrator(), 41 security tags hasCommunityRole, 41 hasGearRole, 41 hasRole, 40 sending code (see alerts) servlet filters, 11 filter mapping, 13 logging parameters (see servlet filters) SourceHandler interface, 116 stylesheet manifests, 125, 145 SuccessMessageProcessor component, 64 T tag libraries declaration, 56 TargetHandler interface, 116 templates, 22 full deck templates, 30 gear title templates, 29, 29 layout templates, 26, 27 page templates, 22, 22 region fragment, 28 shared deck templates, 30 wireless templates, 30 U URLs, 32 usage, 33 W Web Services for Remote Portlets (see WSRP) wireless device emulators, 67 Wireless Markup Language (WML), 67 wireless pages, 66 WSRP, 81 consumer, 86 consumer administration, 93 consumer portlet modes, 87 consumer UserProfile items, 88 consumer window states, 88 Markup interface, 85 producer, 82 producer administration, 92 Registration interface, 85 remote portlet-proxy portlet relationship, 92 Service Description interface, 83 WSRP-ProxyPortlet, 86
    • 160 Index