oracle atg portal dev guide

Version 10.0.2

Portal Development Guide

Oracle ATG One Main Street Cambridge, MA 02142 USA

ATG Portal Development Guide

Document Version Doc10.0.2 PORTALDEVv1 04/15/2011

Copyright Copyright © 1997, 2011, Oracle and/or its affiliates. All rights reserved.

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 software or related documentation 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 RIGHTS Programs, software, databases, and related documentation and technical data delivered to U.S. Government customers are “commercial computer software” or “commercial technical data” pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, duplication, disclosure, modification, and adaptation shall be subject to the restrictions and license terms set forth in the applicable Government contract, and, to the extent applicable by the terms of the Government contract, the additional rights set forth in FAR 52.227-19, Commercial Computer Software License (December 2007). Oracle America, Inc., 500 Oracle Parkway, Redwood City, CA 94065.

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 licensed through X/Open Company, Ltd.

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/us/corporate/accessibility/index.html.

Oracle customers have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/support/contact.html or visit http://www.oracle.com/accessibility/support.html if you are hearing impaired.

A T G P o r t a l D e v e l o p m e n t G u i d e

i i i

C o n t e n t s

μ

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 4 Other Resources 5

Portal Administration Guide 5 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 10 Mapping Hostnames and URLs to Portals 10 Object Lookup 11

The Portal Response 11 Response URIs 11 GearServletResponse 12

The Portal Filter Chain 12 Portal Filter Chain Elements 13

Portal Server Filter 14 Gear Filter 15 Display Filter 15 Device Filter 16 DeviceOutput Filter 17 Portal Filter 17 Community Filter 18


i v

C o n t e n t s

μPage Filter 18 Access Filter 19 Offline Filter 20 Dynamo 5 Style Attributes 20

Page Template Dispatch Servlet 20

3 The Portal Page Structure 23 How Gear Rendering Works 23 Portal Templates 24

Page Template 24 Layout Template 29 Gear Title Template 32

Wireless Templates 33 The Shared Deck Template 34 The Full Deck Template 34

4 Gears and the Portal Application Framework 35 How Portal Pages Are Rendered 35

How the PAF Processes Page Requests 35 Tag Libraries and Gear Development 36 Link URLs 36

URL Usage 37 Form Handling 37

Gear Form Handling 37 Gear Configuration Form Handling 37 JSP Form Handling 39

Configuring Gears to Work with Persistent Data Repositories 40 Keeping Gears Synchronized with Each Other 40 Performance Recommendations 40

Avoid Inefficient Java Methods 40 Additional Performance Resources 41

5 Portal Security 43 Security Roles 43 Predefined Security Areas 43 Security Tags 44

Role Test Tags 44 Role Test Methods 46 includeOnly Tag 46

Include Filter 46 J2EE Security 47 Secure Socket Layer Security 48

6 Designing a Gear 49 Gear Modes 49 Display Modes 50


v

C o n t e n t s

μDevice Outputs 50 Matrix of Gear Modes, Display Modes, and Device Outputs 51 User Interface Look and Feel Recommendations 51

Minimum Gear Sizing Rules 51 Gear Dimensions 51

Portal and Gear Roles 52 Gear Alerts 52 Gear Administration Considerations 52 Localization Considerations 53

Creating Configurable, Localizable Content in Gears 53 Localized Gear Names and Descriptions 54

Extending an Existing Gear 54 Example: A Discussion Forum Gear 55

Roles 55 Choosing Display Modes 56

7 Creating Gear Page Fragments 59 HTML Considerations 59 Layout Considerations 60 Accessibility Recommendations 60 Page Elements 60

Tag Library Declaration 60 DSP Page Initialization 61 Gear Environment Initialization 61

Gear Configuration Page Fragments 62 Developing Install Configuration Pages 63 Developing Initial, Instance, or User Configuration Pages 65 Example: A Document Exchange User Configuration Page 67

Message Handling in Page Fragments 69 I18nMessageProcessor 69 Adding Messages 69 Message Handling Example 70

Avoiding Gear Instance Conflicts 71 Naming Conventions 72

Wireless Gear Page Fragments 72 Wireless Markup Language 72 Wireless Device Emulator 73

8 Gear Packaging and Deployment 75 Gear Manifests 75

The Gear Manifest File Format 76 Wireless Gear Deployment Considerations 78

Gear Assembly 78 Gear Manifest 78


v i

C o n t e n t s

μ9 Developing and Deploying Portlets 81

Portlets and Gears 81 Comparison of Portlets and Gears 81

Developing a Portlet 82 Helloworld Portlet 82 Portlet Class 82 Portlet Deployment Descriptor File 83 Web Application Deployment Descriptor 85 Portlet JSPs 86 Helloworld Servlet Beans 87

Portlet Deployment Tool 87 Running the Portlet Deployment Tool 87 Portlet Deployment Tool Arguments 88

10 Web Services for Remote Portlets 89 WSRP Overview 89

Producer Overview 90 Consumer Overview 94

Producer Administration 100 Starting Up the Producer 100 Producer Database Configuration 101 Using the Producer Administration UI 101 Importing Portlet Descriptions 101

Consumer Administration 102 Starting Up the Consumer Module 102 Consumer Database Configuration 102 Using the Consumer Administration UI 102 Adding a New Producer to a Consumer 103 Modifying Producer Information 106 Deleting a Producer 106 Configuring a ProxyPortlet Instance 107

11 Adding Gear Alerts 109 Alerts Overview 109 Alert Services Provided by the PAF and Baseline Gears 110

Baseline Gear Events 111 Baseline Gear Scenario Templates 111 PAF Events 112

Adding Custom Alert Messages to Gears 112 Sample GearMessage Extension 114 Adding GearMessagePublisher to the Gear 116 Sample Sending Code 116 Sample dynamoMessagingSystem.xml File 117 Adding the Alerts Element to the Gear Manifest File 118 Creating a Resource Bundle Properties File 119 Creating an E-mail Template File 120


v i i

C o n t e n t s

μCreating an Alert Instance Configuration Form 120 Extending the Scenario User Interface 121 Configuring a Scenario 123

Adding Alert Channels 124 Configuring an AlertChannel Component 125 AlertHandlerInterface 126 Registering the New Alert Channel 127 Configuring Alert Channel Preferences 127

Source Handlers and Target Handlers 128 Source Handlers 128 Target Handlers 128

Administrative Alerts and Framework Alerts 129

12 Creating a Custom Portal 131 Creating a New Portal 131

Copying the Portal Template 131 Editing Portal Framework Files 132 Setting Up the Portal Database 134 Starting Up Your Custom Portal Module 134 Further Customization 135

Customizing Portal Appearance 135 Manifest File Formats for Customizing Portal Appearance 136 Manifest File Headers 136 Color Palette Manifests 137 Stylesheet Manifests 138 Page Template Manifests 139 Layout Template Manifests 140 Gear Title Template Manifests 141

Customizing Portal Authentication 142 Authentication Pages 142 Specifying Authentication Page Locations 142

Appendix A: Portal Manifest Reference 145 Portal Manifest Elements 145

<portal-manifest> Element 145 Gear Manifest Elements 146

<gear-definitions> Element 146 <gear-definition> Element 146 <servlet-context> Element 146 <gear-modes> Element 147 <gear-mode> Element 147 <display-modes> Element 148 <display-mode> Element 148 <dimensions> Element 148 <dimension> Element 148 <error-handling> Element 149


v i i i

C o n t e n t s

μ<instance-parameters> Element 149 <user-parameters> Element 150 <alerts> Element 150 <alert-message> Element 151

Page Template Manifest Elements 151 <page-templates> Element 152 <page-template> Element 152

Layout Template Manifest Elements 153 <layout-templates> Element 153 <layout-template> Element 153

Gear Title Template Manifest Elements 155 <gear-title-templates> Element 155 <gear-title-template> Element 155

Color Palette Manifest Elements 157 <color-palettes> Element 157 <color-palette> Element 157 <images> Element 157 <image> Element 158 <entity> Element 158 <color> Element 159 Color Palette Example 159

Stylesheet Manifest Elements 160 <styles> Element 160 <style> Element 160

The Portal Manifest DTD 161

Appendix B: PAF Tag Library Reference 167 paf:layout 168 paf:titlebar 168 paf:hasRole 168 paf:hasCommunityRole 169 paf:hasGearRole 169 paf:renderTab 170 paf:defaultTab 170 paf:currentTab 170 paf:encodeURL 171 paf:context 171 paf:include 172

Index 173


1

1 - I n t r o d u c t i o n

μ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.


2


μ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.

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 that ATG provides 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


3


μ Add portal page templates

Add gear layout templates

Add region fragments

Add gear title templates

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 chapter of this manual. For additional information on portal and community administration, refer to the Community Administration chapter of the ATG Portal Administration Guide.


4


μ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.

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 chapter in this manual.

3. Develop the gear page fragments.

For examples of portions of gear page fragments, see the Creating Gear Page Fragments 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 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 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.


5


μ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.

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 ATG 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 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


μ


7

2 - P o r t a l R e q u e s t s a n d t h e F i l t e r C h a i n

μ2 Portal Requests and the Filter Chain

ATG Portal is implemented as a J2EE v.1.3 Web application, using Java Servlet Technology, v2.3 (Servlets). 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 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

The Portal Request

The Portal Response

The Portal Filter Chain

Portal Filter Chain Elements

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


8


μ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.

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


9


μgetPathInfo

getPortalContextPath

getPortalServletPath

getPortalPathInfo

For example, suppose the Portal Context is set as follows:

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


1 0


μ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.

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


1 1


μ/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.

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.


1 2


μ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.

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>


</init-param>

<init-param>

<param-name>loggingInfo</param-name>


</init-param>

<init-param>


1 3


μ <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>


</init-param>

<init-param>

<param-name>initD5StyleAttributes</param-name>


</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:

loggingDebug

loggingWarning

loggingError

loggingInfo

The other parameters of the Portal filters are described in the Portal Filter Chain Elements 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

Gear Filter

Display Filter

Device Filter


1 4


μDeviceOutput Filter

Portal Filter

Community Filter

Page Filter

Access Filter

Offline Filter

In addition, this chapter describes the Page Template Dispatch Servlet, 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.

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.


1 5


μ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. See Dynamo 5 Style Attributes.

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.

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 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:


1 6


μ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 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

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:


1 7


μ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 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:


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.

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:


1 8


μ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.


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:



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.

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.



1 9


μ

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:



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:


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.

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.


2 0


μ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:



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.

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

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


2 1


μ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:



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.


2 2


μ


2 3

3 - T h e P o r t a l P a g e S t r u c t u r e

μ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 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 and the Gears and the Portal Application Framework chapter.

This chapter includes the following sections:

How Gear Rendering Works

Portal Templates

Wireless Templates

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 section of this chapter.


2 4


μ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 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

Layout Template

Gear Title Template

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

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. 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" %>


2 5


μInternationalization Initialization

This element makes available the resource bundle used for localizing user messages on the page.

<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}"/>


2 6


μ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.

<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.


2 7


μ<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/>

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 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"


</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.


2 8


μ<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"


<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/>

</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.

<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.


2 9


μ<paf:renderTab page="${portalContext.page}">

<paf:defaultTab>

<td bgcolor='<c:out value="${gearTitleBackgroundColor}"/>' nowrap><nobr>

<font size="-1">  <a href="<c:out value="${communityPageURL}"/>">

<font color="<c:out value="${gearTitleTextColor}"/>" >

<c:out value="${communityPage.name}"/></font></a>

  </font></nobr>

</td>

</paf:defaultTab>

<paf:currentTab>

<td bgcolor='<c:out value="${gearTitleTextColor}"/>' nowrap><nobr>

<font size="-1">

<b><a href="<c:out value="${communityPageURL}"/>">

<font color="<c:out value="${gearTitleBackgroundColor}"/>">

<c:out value="${communityPage.name}"/></font></a></b>

  </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 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 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)


3 0


μ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: Layout Template Manifests 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 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" %>


Next, we set the portal request and response and other variables.



<c:set var="portalServletRequest" value="${requestScope[PORTALSERVLETREQUEST]}"/>



<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>


<tr>

The first cell is defined. It is allocated 25% of the page’s width, and includes the region rendering fragment.


3 1


μ <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" value="${requestScope[PORTALSERVLETREQUEST]}"/>



<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);


3 2


μ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}"/>

<paf:include context="${gearContext}"/>

1. 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.


<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:


3 3


μ<c:if test="${showEdit ==true}">

<%

gearContext.setGearMode(GearMode.USERCONFIG);

%>

<a href="<%= gearServletResponse.encodeGearURL

(gearServletRequest.getPortalRequestURI(),gearContext) %>">


<fmt:message key="titlebar-control-edit" bundle="${templatesbundle}"/></font></a>

</c:if>

The next section optionally displays an About link for the gear:

<c:if test="${showAbout == true}">

<%

gearContext.setGearMode(GearMode.ABOUT);

%>




<fmt:message key="titlebar-control-about" bundle="${templatesbundle}"/></font></a>

</c:if>

The next section optionally displays a Help link for the gear:

<%

gearContext.setGearMode(GearMode.HELP);

%>

<c:if test="${showHelp == true}">




<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.


3 4


μ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.


3 5

4 - G e a r s a n d t h e P o r t a l A p p l i c a t i o n F r a m e w o r k

μ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 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.


3 6


μ8. The gears and their content are rendered in the appropriate layout template for the

requested output device.

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 and The Portal Page Structure 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>


3 7


μ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);

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:


3 8


μ UserConfig

InstanceConfig

InstallConfig

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 ATG 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)


3 9


μFor more information, refer to the gear interfaces under the atg.portal.framework package in the ATG API Reference.

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 section in the Creating Gear Page Fragments chapter. For Javadoc on the GearConfigFormHandler class, see the ATG 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.


4 0


μ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 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()


4 1


μ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("/");

/* 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.


4 2


μ


4 3

5 - P o r t a l S e c u r i t y

μ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.


4 4


μ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 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

hasCommunityRole

hasGearRole

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:


4 5


μ[tag library declaration]

...

<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>


4 6


μ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 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. 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 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


4 7


μ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.

</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.


4 8


μ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>

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.


4 9

6 - D e s i g n i n g a G e a r

μ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 section of the Introduction chapter.

There are three important concepts that comprise the high-level design of a gear:

Gear Modes

Display Modes

Device Outputs

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 You will need to determine whether your gear will need to send alerts when certain actions occur.

Gear Administration Considerations You may need to design how a gear is configured for different portal contexts.

Localization Considerations 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 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.

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:


5 0


μ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:


5 1


μ 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.


5 2


μ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 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 ATG 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 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.


5 3


μ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 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 section of the Gears and the Portal Application Framework chapter of this manual and the Gear Configuration Page Fragments section of the Creating Gear Page Fragments 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 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 a Dynamo Web Site chapter of the ATG 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:


5 4


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

<fmt:bundle basename=my.portal.Resources/>

<fmt:message id="finishButton" key="finishButton"/>

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:


5 5


μ 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

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:


5 6


μ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.

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


5 7


μ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.


5 8


μ


5 9

7 - C r e a t i n g G e a r P a g e F r a g m e n t s

μ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 section of the Designing a Gear 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

Layout Considerations

Accessibility Recommendations

Page Elements

Gear Configuration Page Fragments

Message Handling in Page Fragments

Avoiding Gear Instance Conflicts

Wireless Gear Page Fragments

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>


6 0


μ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:


DSP Page Initialization

Gear Environment Initialization


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="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" %>

In most cases you will at least need the declarations for the pafTaglib shown above.


6 1


μ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.


6 2


μFor additional information on the PAF Tag Library, refer to Appendix B: PAF Tag Library Reference in this manual.

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 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


6 3


μ </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 API Reference for 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.

1. Surround the page content with the hasRole tag to prevent users other than a portal administrator from accessing this page. For example:


<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"/>


6 4


μ<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:

<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


6 5


μ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() %>"/>

1. 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" />

1. 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"/>

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.

1. As with any gear page fragment, use the InitializeGearEnvironment tag to initialize your gear environment. For example:



<%!--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"/>


6 6


μ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() %>">


</dsp:form>

For User Configuration, your form tag should look like this:

<dsp:form method="post" action="<%=gearEnv.getOriginalRequestURI()%>">


</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).

<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.


6 7


μ<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 section.

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.


6 8


μ<%@ taglib uri="/dsp" prefix="dsp" %>



<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"/>

<input type="submit" value="Cancel"/>

...


6 9


μ</dsp:form>

</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);


7 0


μ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().

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")%>'>

<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"


7 1


μ bean="FailureMessageProcessor.messages">

<core:ForEach id="failureIterator"

values="<%=failureMessages%>"

castClass="String"

elementId="failureMessage">

<img src='<%=dmpage.getRelativeUrl("/html/images/error.gif")%>' >

<font class="error"><%=failureMessage%></font><br>

</core:ForEach>

</dsp:getvalueof><%-- failureMessages --%>

Finally, we clear all the messages from the two I18nMessageProcessor components.

<%

failureMessageProcessor.clear();

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.


7 2


μ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).

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 section of the Portal Page Structure chapter. For general information on wireless programming in ATG products, see the Creating Wireless Applications chapter in the ATG Programming Guide.

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


7 3


μ 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


7 4


μ


7 5

8 - G e a r P a c k a g i n g a n d D e p l o y m e n t

μ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.

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

7 6


μ 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>

7 7


μ <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>

<display-mode name="full">

<device-output name="html">/DocExchFull.jsp</device-output>

</display-mode>

</display-modes>

</gear-mode>

<gear-mode name="userConfig">

<display-modes>


<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

7 8


μ </default-value>

</parameter>

</user-parameters>

<!-- ADDITIONAL USER PARAMETERS GO HERE --!>

</gear-definition>

</gear-definitions>

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>


<display-modes>


<device-output name="html">/html/DocExchShared.jsp</device-output>

<device-output name="wml">/wml/DocExchShared.jsp</device-output>

</display-mode>


<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>


<device-output name="html">/html/UserConfig.jsp</device-output>

<device-output name="wml">/wml/UserConfig.jsp</device-output>

</display-mode>

</display-modes>

</gear-mode>

7 9


μ<!-- ADDITIONAL GEAR MODES GO HERE --!>

</gear-modes>


8 0


μ


8 1

9 - D e v e l o p i n g a n d D e p l o y i n g P o r t l e t s

μ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 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.


8 2


μDeveloping a Portlet

The principal elements of a portlet are:

Portlet Class

Portlet Deployment Descriptor File

Portlet JSPs

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.xml Portlet Deployment Descriptor File

helloworld.war helloworld 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. ATG provides two base classes you can either use as your portlet class or extend in your own subclass:

atg.portlet.GenericPortletService

atg.portlet.DispatchPortlet


8 3


μThe GenericPortletService class provides standard methods for an ATG Nucleus component, including support for self-configuration, name resolution, performance profiling and logging.

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>


</init-param>

<init-param>

<param-name>loggingWarning</param-name>


</init-param>

<init-param>

<param-name>loggingError</param-name>


</init-param>

<init-param>

<param-name>loggingInfo</param-name>


</init-param>

<init-param>

<param-name>MyString</param-name>

<param-value>foobar</param-value>

</init-param>

<param-name>Object</param-name>


8 4


μ <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.

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


8 5


μ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 Programming Guide) is a 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:


8 6


μ<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:

<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> </td>

<td><dspel:input iclass="portlet-form-button" type="submit"

bean="HelloWorldFormHandler.update"/></td>

</tr>

</table>

</dspel:form>


8 7


μ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 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


8 8


μ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.

-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.


8 9

1 0 - W e b S e r v i c e s f o r R e m o t e P o r t l e t s

μ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

Producer Administration

Consumer Administration

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:


9 0


μ

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.


9 1


μ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

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 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


9 2


μ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

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


9 3


μ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

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 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.


9 4


μ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.

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).


9 5


μ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

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:


9 6


μ 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.

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.


9 7


μ 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

employerInfo/employer employer "Empty"

employerInfo/department departmen

t

"Empty"

employerInfo/jobtitle jobtitle ContactInformation.title

homeInfo/postal/name name ContactInformation.address

1

homeInfo/postal/street street ContactInformation.address

2

homeInfo/postal/city City ContactInformation.city

homeInfo/postal/stateprov stateprov ContactInformation.state

homeInfo/postal/postalcode postalcod

e

ContactInformation.postalC

ode

homeInfo/postal/country country ContactInformation.country


9 8


μhomeInfo/postal/organization organizat

ion

ContactInformation.company

Name

homeInfo/telecom/telephone/intcod

e

intcode

homeInfo/telecom/telephone/loccod

e

loccode

homeInfo/telecom/telephone/number number

ContactInformation.phoneNu

mber

homeInfo/telecom/telephone/ext Ext "Empty"

homeInfo/telecom/telephone/commen

t

comment "Empty"

homeInfo/telecom/fax/intcode intcode

homeInfo/telecom/fax/loccode loccode

homeInfo/telecom/fax/number number

ContactInformation.faxNumb

er

homeInfo/telecom/fax/ext Ext "Empty"

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"


9 9


μbusinessInfo/postal/postalcode postalcod

e

"Empty"

businessInfo/postal/country country "Empty"

businessInfo/postal/organization organizat

ion

"Empty"

businessInfo/telecom/telephone/in

tcode

intcode "Empty"

businessInfo/telecom/telephone/lo

ccode

loccode "Empty"

businessInfo/telecom/telephone/nu

mber

number "Empty"

businessInfo/telecom/telephone/ex

t

Ext "Empty"

businessInfo/telecom/telephone/co

mment

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/intco

de

intcode "Empty"

businessInfo/telecom/mobile/locco

de

loccode "Empty"

businessInfo/telecom/mobile/numbe

r

number "Empty"

businessInfo/telecom/mobile/ext Ext "Empty"

businessInfo/telecom/mobile/comme

nt

comment "Empty"

businessInfo/telecom/pager/intcod

e

intcode "Empty"

businessInfo/telecom/pager/loccod

e

loccode "Empty"

businessInfo/telecom/pager/number number "Empty"

businessInfo/telecom/pager/ext Ext "Empty"


1 0 0


μbusinessInfo/telecom/pager/commen

t

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 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

Producer Database Configuration

Using the Producer Administration UI

Importing Portlet Descriptions

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 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.


1 0 1


μProducer Database Configuration

The ATG producer uses the GSA repository for persistent information and comes preconfigured with the necessary schema and default data for the SOLID database bundled with ATG. Customers using a different database, such as Oracle or MS-SQL, must create the Producer schema in their database using the DDL scripts provided at <ATG10dir>/WSRP/producer/sql.

Customers must 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 Programming Guide. Deploy your application to the appropriate location and start it according to the instructions provided in your application server manuals.

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.


1 0 2


μConsumer Administration

This section provides information on administering the consumer module. It includes the following sections:

Starting Up the Consumer Module

Consumer Database Configuration

Using the Consumer Administration UI

Adding a New Producer to a Consumer

Modifying Producer Information

Deleting a Producer

Configuring a ProxyPortlet Instance

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 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 information and is preconfigured with the necessary schema structure for the SOLID database. Customers using a different database, such as Oracle or MS-SQLServer, 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.


1 0 3


μ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).

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.


1 0 4


μ

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


1 0 5


μ 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.


1 0 6


μ

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.


1 0 7


μ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.

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.


1 0 8


μ


1 0 9

1 1 - A d d i n g G e a r A l e r t s

μ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

Alert Services Provided by the PAF and Baseline Gears

Adding Custom Alert Messages to Gears

Adding Alert Channels

Source Handlers and Target Handlers

Administrative Alerts and Framework Alerts

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.


1 1 0


μ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.

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.


1 1 1


μBaseline Gear Events

The following pre-defined alerts are provided with the baseline gears:

Calendar Gear

Event Created

Event Deleted

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


1 1 2


μ Favorite Communities Recorder

Poll Vote Recorder

PAF Events

The following pre-defined alerts are provided for PAF events:

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.


1 1 3


μ2. Create a JavaBean that extends atg.portal.alert.GearMessage for each message

format you require. (See Sample GearMessage Extension 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.

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 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 below.)

5. Define the message in the Dynamo 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/dynamoMessag

ingSystem.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 below. For more information about configuring and using the Dynamo Message System, see the Dynamo Message System chapter in the ATG 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 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 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 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 below.)


1 1 4


μ10. Extend the Scenario user interface to handle your new message types as it does other

alert messages. (See Extending the Scenario User Interface below.)

11. Using the Scenario module, configure a scenario that will perform the desired response upon receiving a gear alert. (See Configuring a Scenario 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).

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 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);

}


1 1 5


μ

//-------------------------------------

// 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

}

}

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 Dynamo 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.)


import atg.portal.framework.*;

public class DocumentCreatedMessage extends DocExchMessage

{

//-------------------------------------

// Member variables

//-------------------------------------


1 1 6


μ 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 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.)

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.

1 1 7


μThe following is an example of the sending code, mentioned in Step 4 of Adding Custom Alert Messages to Gears 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 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>



<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


1 1 8


μ </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 Dynamo Message System, see the Dynamo Message System chapter in the ATG 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 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 chapter and the Appendix A: Portal Manifest Reference.

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>

...

</gear-definition>

The parameter default value can be one of the following:


1 1 9


μ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 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

1 2 0


μ# for the targeted email. Should be located in a directory in the DOCPATH.

#

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 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.



<setvalue param="messageFrom" value="[email protected]">

<setvalue param="messageSubject" value="Alert Notification">

<setvalue param="messageReplyTo" value="[email protected]">

<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.



<dsp:page>


...

<jsp:useBean id="alertFormInput" scope="request"

class="atg.portal.admin.AlertConfigBean">

<jsp:setProperty name="alertFormInput" property="*"/>

</jsp:useBean>



<core:If value="<%= alertFormInput.getHandleForm() %>" >

<paf:handleAlertConfig id="alertConfResult" formData="<%= alertFormInput %>"

1 2 1


μ gearEnv="<%= pafEnv %>">

<core:ExclusiveIf>

<core:If value="<%= alertConfResult.getSuccess() %>" >



</core:If>

<%-- if not, display errors --%>

<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"> <%=alertNoOptionDesc%></font>

...

<input type="radio" name="gearAlertPref" value="yes_locked"><font size="2"

color="#000000"> <%=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 section above, you must create and add two files to your gear’s classes.jar file.

expression-grammar.xml

GrammarExtension.java

1 2 2


μ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"?>







<?xcl-stylesheet resource="atg/ui/expreditor/xcl/grammar.xsl"?>

<context serializable="true">



<include template="atg.portal.scenario.expression.expression-grammar"/>







<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"/>


1 2 3


μ <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.


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

//----------------------------------------

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 an ATG 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.


1 2 4


μ

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.

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

AlertHandlerInterface

Registering the New Alert Channel

Configuring Alert Channel Preferences


1 2 5


μ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

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


1 2 6


μ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 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++)

{

RepositoryItem user = (RepositoryItem)pUsers.get(i);

recipients.add((String)user.getPropertyValue(getEmailAddressPropertyName()));


1 2 7


μ}

...

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 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


1 2 8


μ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 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


1 2 9


μ

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

CommunityGearAddedMessage atg.portal.messaging. CommunityGearAddedMessage

atg.portal.messaging. CommunityGearAddedResources

CommunityGearRemovedMessage atg.portal.messaging. CommunityGearRemovedMessage

atg.portal.messaging. CommunityGearRemovedResources

PageGearAddedMessage atg.portal.messaging. PageGearAddedMessage

atg.portal.messaging. PageGearAddedMessageResources

PageGearRemovedMessage atg.portal.messaging. PageGearRemovedMessage

atg.portal.messaging. PageGearRemovedMessageResources

In addition, the following framework alert classes are included in ATG Portal 6, 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


1 3 0


μMemUnsubscribeMessage atg.portal.messaging.

MemUnsubscribeMessage atg.portal.messaging. MemUnsubscribeResources

MembershipAcceptedMessage atg.portal.messaging. MembershipAcceptedMessage

atg.portal.messaging. MembershipAcceptedResources

MembershipDeclinedMessage atg.portal.messaging. MembershipDeclinedMessage

atg.portal.messaging. MembershipDeclinedResources


1 3 1

1 2 - C r e a t i n g a C u s t o m P o r t a l

μ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 section of this chapter.

The Customizing Portal Appearance 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 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 section.

2. Edit the portal framework configuration files, as described in the Editing Portal Framework Files section.

3. Set up the portal database, as described in the Setting Up the Portal Database 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 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


1 3 2


μ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


myportal/META-INF/application.xml

myportal/portal/WEB-INF/web.xml

myportal/portal/WEB-INF/weblogic.xml (WebLogic only)

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>


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


1 3 3


μ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"?>

<!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>


</init-param>


1 3 4


μ<init-param>

<param-name>defaultAccessDeniedTemplateContextURI</param-name>


</init-param>

<init-param>

<param-name>defaultOfflineTemplateContextURI</param-name>


</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

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 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:


1 3 5


μ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 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 section of this chapter describes how you can customize the log in, registration, access denied, and error pages.

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

1 3 6


μ/style/style-manifest.xml

/titlebar/titlebar-manifest.xml

If you followed the custom portal creation process described in the Creating a New Portal 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.

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

Color Palette Manifests

Stylesheet Manifests

Page Template Manifests

Layout Template Manifests

Gear Title Template Manifests

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.

1 3 7


μ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>

<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>


</colors>

</entity>

<entity type="gear-title">

<colors>

<color type="background">006666</color>

<color type="text">ffffff</color>

1 3 8


μ </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 in Appendix A: Portal Manifest Reference.

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;

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:


<styles>


1 3 9


μ <style name="NAME" version="VERSION" author="AUTHOR">

<description>Default CSS</description>


<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 in Appendix A: Portal Manifest Reference.

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.


<page-templates>

<page-template name="Default Page Template" version="1.0" author="AUTHOR">

<description>Default Page Template</description>


<display-modes>


<device-output name="html">/templates/page/html/shared.jsp</device-output>

<device-output name="wml">/templates/page/wml/shared.jsp</device-output>

</display-mode>


<device-output name="html">/templates/page/html/full.jsp</device-output>

<device-output name="wml">/templates/page/wml/full.jsp</device-output>

</display-mode>

</display-modes>

</page-template>

</page-templates>


1 4 0


μFor details about the tags and attributes you can use in a Page Template manifest file, see Page Template Manifest Elements in Appendix A: Portal Manifest Reference.

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:


<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>


<device-output name="html">/templates/layout/html/25_75.jsp

</device-output>

</display-mode>


<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>


1 4 1


μ <region name="25_75_RIGHT">

<dimensions>

<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 in Appendix A: Portal Manifest Reference.

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.


<gear-title-templates>

<gear-title-template name="Default Gear Title Template" version="1.0"

author="AUTHOR">

<description>Default Gear Title Template</description>


<gear-title-template-modes>

<gear-title-template-mode name="template">

<display-modes>


<device-output name="html">

/templates/titlebar/html/titlebar.jsp

</device-output>

</display-mode>



/templates/titlebar/html/titlebar.jsp

</device-output>

</display-mode>

</display-modes>

</gear-title-template-mode>


1 4 2


μ </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 in Appendix A: Portal Manifest Reference.

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 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:


1 4 3


μ

defaultLoginTemplateContextURI /portal

defaultLoginTemplatePathURI /userprofiling/login.jsp

defaultAccessDeniedTemplateContextURI /portal

defaultAccessDeniedTemplatePathURI /access/accessDenied.jsp


1 4 4


μ


1 4 5

A p p e n d i x A : P o r t a l M a n i f e s t R e f e r e n c e

μ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

Gear Manifest Elements

Page Template Manifest Elements

Layout Template Manifest Elements

Gear Title Template Manifest Elements

Color Palette Manifest Elements

Stylesheet Manifest Elements

The Portal Manifest DTD

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 <color-palettes> element <styles> element <page-templates> element <layout-templates> element <gear-title-templates> element

<portal-manifest> ElementAttributes

name required

version optional

author optional


1 4 6


μ

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.

images See <images> Element.

dimensions See <dimensions> Element.

gear-modes See <gear-modes> Element.

error-handling See <error-handling> Element.

instance-parameters See <instance-parameters> Element.

user-parameters See <user-parameters> Element.

alerts See <alerts> Element.

<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).


1 4 7


μ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.

Gear Modes Example

<gear-modes>


<display-modes>



/html/userContent.jsp

</device-output>

</display-mode>

...

</display-modes>

</gear-mode>

...

</gear-modes>


1 4 8


μ<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>



/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.

Sub-elements

name Required? Possible Values

height Required Gear: short, tall, or nopreference Region: short or tall


1 4 9


μ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>

<instance-parameters> Element

Defines and specifies instance parameters for the gear.


1 5 0


μ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.


1 5 1


μ<alert-message> Element

Each <alert-message> element describes a type of alert that can be sent by the gear.

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.


1 5 2


μ<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.

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.

<display-modes> A container for one or more <display-mode> elements. See <display-mode> Element.

Page Template Manifest Example

<page-templates>

<page-template name="Default Page Template"

version="1.0"author="AUTHOR">

<description>Default Page Template</description>


<images>



1 5 3


μ <url>/images/page_template.gif</url>

</image>

</images>

<display-modes>



/html/shared_page_template.jsp

</device-output>

<device-output name="wml">

/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


description An optional description of the layout template.


1 5 4


μ<region> Defines a region. Required attribute is name. Required sub-element is

dimensions. See <dimensions> Element.

<regions>


<dimensions>


narrow

</dimension>


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.

<images> Images used in the layout. See <images> Element.

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>


</servlet-context>

<images>


<url>

/images/layout_25_75.gif

</url>

</image>

</images>

<display-modes>



/html/layout_25_75.jsp


1 5 5


μ </device-output>

</display-mode>

</display-modes>

<regions>


<dimensions>


narrow

</dimension>


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


1 5 6


μElement Description/Example

<description> An optional description of the layout template.

<servlet-context> The servlet context of the layout template.

<display-modes> The display modes of the layout. See <display-modes> Element.

<images> Images used in the layout. See <images> Element.

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>


</servlet-context>

<images>


<url>

/images/page_template.gif

</url>

</image>

</images>

<gear-title-template-modes>

<gear-title-template-mode name="template">

<display-modes>



/html/titlebar_template.jsp

</device-output>

</display-mode>



/html/titlebar_template.jsp

</device-output>

</display-mode>

</display-modes>


<gear-title-template-mode name="preTemplate">

...


<gear-title-template-mode name="postTemplate">

...


1 5 7


μ </gear-title-template-mode>

</gear-title-template-modes>

</gear-title-template>

</gear-title-templates>

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.


1 5 8


μ<image> Element

Defines an image for the color palette.

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


1 5 9


μ<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>

<color-palette name="Blue Metrix" version="1.0" author="ATG Portal Team">

<description>Blue Metrix</description>


<images>


<url>/images/color_theme_blue_metrix.gif</url>

</image>

</images>


<colors>

<color type="background">99ccff</color>


<color type="link">0033ff</color>

<color type="action-link">990000</color>

<color type="visited-link">336699</color>

</colors>

</entity>


<images>

<image type="background">

<url>/images/bg_colorscheme_bluemetrix.gif</url>

</image>

</images>

</entity>

<entity type="gear-body">

<colors>

<color type="background">ffffff</color>


</colors>

</entity>

<entity type="gear-title">

<colors>

<color type="background">4a8cd6</color>

<color type="text">ffffff</color>

</colors>


1 6 0


μ </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.

Attributes

name required

version optional

author optional

Subelements


<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


<servlet-context> Specifies the servlet-context for the style.

<servlet-context>


</servlet-context>

1 6 1


μ

Style Example

<styles>

<style name="Default" version="1.0" author="">

<description>

Default Stylesheet

</description>

<servlet-context>


</servlet-context>

<cascading-style-sheet>

/css/default.css


</style>

</styles>

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:



<!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+)>

1 6 2


μ<!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?)>

<!ATTLIST image

type (small | large | background) #REQUIRED

>

<!ELEMENT url (#PCDATA)>

<!ATTLIST url

type (template | pretemplate | posttemplate) #IMPLIED

>

<!ELEMENT alt-text (#PCDATA)>

<!ELEMENT dimensions (dimension+)>


1 6 3


μ<!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


>

<!ELEMENT cache-output EMPTY>

<!ATTLIST cache-output


>

<!ELEMENT error-handling (intercept-errors | cover-errors-with-cache)>

<!ELEMENT intercept-errors EMPTY>

<!ATTLIST intercept-errors


>

<!ELEMENT cover-errors-with-cache EMPTY>

<!ATTLIST cover-errors-with-cache


>

<!ELEMENT gear-modes (gear-mode+)>

<!ELEMENT gear-mode (display-modes)>

<!ATTLIST gear-mode

name (content | userConfig | instanceConfig | initialConfig |

installConfig |

help | about | preview) #REQUIRED


1 6 4


μ>

<!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


>

<!ELEMENT alerts (alert-message+)>

<!ELEMENT alert-message (message-type?, default-value?, resource-bundle?)>

<!ATTLIST alert-message


>

<!ELEMENT message-type (#PCDATA)>

<!ELEMENT resource-bundle (#PCDATA)>

<!ELEMENT default-value (#PCDATA)>

<!ELEMENT color-palette (description, servlet-context, images?, entity+)>

<!ATTLIST color-palette




>

<!ELEMENT entity (colors? | images?)>

<!ATTLIST entity

type (page-body | gear-body | gear-title | highlight) #REQUIRED

>


1 6 5


μ<!ELEMENT colors (color+)>

<!ELEMENT color (#PCDATA)>

<!ATTLIST color

type (background | text | link | action-link | visited-link) #REQUIRED

>

<!ELEMENT style (description?, servlet-context, cascading-style-sheet)>

<!ATTLIST style




>

<!ELEMENT cascading-style-sheet (#PCDATA)>

<!ELEMENT page-template (description?, servlet-context, images?, display-modes)>

<!ATTLIST page-template




>

<!ELEMENT layout-template (description?, servlet-context, images?,

display-modes, regions)>

<!ATTLIST layout-template




>

<!ELEMENT regions (region+)>

<!ELEMENT region (dimensions+)>

<!ATTLIST region


>

<!ELEMENT gear-title-template (description?, servlet-context, images?,

gear-title-template-modes?)>

<!ATTLIST gear-title-template




>

<!ELEMENT gear-title-template-modes (gear-title-template-mode+)>

<!ELEMENT gear-title-template-mode (display-modes)>


1 6 6


μ<!ATTLIST gear-title-template-mode

name (preTemplate | template | postTemplate) #REQUIRED

>


1 6 7

A p p e n d i x B : P A F T a g L i b r a r y R e f e r e n c e

μ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 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 Determines the layout to render based on the Display Mode and the current Device.

paf:titlebar Includes a GearTitleTemplate.

paf:hasRole Tests for global roles before allowing access to tag contents.

paf:hasCommunityRole Tests for community roles before allowing access to tag contents.

paf:hasGearRole Tests for gear roles before allowing access to tag contents.

paf:renderTab Renders a tab for a portal template header set of tabs.

paf:defaultTab Renders this tab if the page object passed to the parent renderTab tag is not the currently rendering page.

paf:currentTab Renders this tab if the page object passed to the parent renderTab tag is the currently rendering page.

paf:encodeURL Encodes a portal or gear URL with session ID and portal or gear specific parameters.

paf:context Obtains a portal or gear context.

paf:include Dispatches a request to included content


1 6 8


μ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.

Body: JSP content


1 6 9


μAttributes


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


roles String. A comma-separated list of roles to test for. true


false


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


1 7 0


μAttribute Description Required?

roles String A comma-separated list of roles to test for. true


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


page true


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


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.


1 7 1


μExample: page/html/shared.jsp

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


page String true

id String false

var String false

scope String false

url String false

portalContext String false

gearContext String false

context String false


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


1 7 2


μAttribute Description Required?

id false

var false

scope false

type String. One of PortalContext.class or GearContext.class false


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


context true

Example: layout/html/region.jspf

1 7 3

I n d e x

Index

A AccessFilter, 19 accessibility recommendations, 60 administrative alerts, 129 alerts, 52

adding, 112 administrative, 129 configuring a scenario, 123 creating an instance configuration form, 120 creating e-mail template files, 120 dynamoMessagingSystem.xml, 117 extending the scenario user interface, 121 framework, 129 gear manifest file, 118 GearMessage class, 114 GearMessagePublisher class, 116 overview, 109 resource bundles, 119 sending code, 116 SourceHandler, 128 TargetHandler, 128

atg.portal.admin.I18nMessageProcessor, 69 atg.portal.alert.GearMessage, 112 atg.portal.alert.SourceHandler, 128 atg.portal.alert.TargetHandler, 128 atg.portal.framework.Environment, 46 atg.portal.framework.GearConfigFormHandler, 39 atg.portal.servlet.GearContext, 8 atg.portal.servlet.GearServletRequest, 9 atg.portal.servlet.GearServletResponse, 12 atg.portlet.DispatchPortlet, 83 atg.portlet.GenericPortletService, 82 authentication pages, 142

specifying location, 142

C cascading stylesheets. See stylesheet manifests color palette manifests, 137, 157 Community objects, 10 CommunityFilter, 18 configuration pages, 62

example, 67 form handling. See form handling initial configuration, 65 install configuration, 63 instance configuration, 65

user configuration, 65 copying a gear, 54 customizing

portal appearance, 135 portal authentication, 142

D deployment descriptor, 83 deployment portlets

deployment descriptor, 83 Device objects, 10 device outputs, 50 DeviceFilter, 16 DeviceOutputFilter, 17 display modes, 50, 56, 148 DisplayFilter, 15 DisplayMode objects, 10 DSP page initializations, 61 DTD. See portal manifest DTD dynamoMessagingSystem.xml. See alerts DynamoServerPageFilter, 85

E e-mail template files. See alerts error messages, 69

F FailureMessageProcessor component, 69 filter mapping, 13 filters. See servlet filters form handling, 37

accessing configuration parameters, 38 gear configuration pages, 37 gear pages, 37 GearConfigFormHandler, 39 JSP, 39

framework alerts, 129

G gear definition, 2 gear design example, 55 gear instance, 2 gear manifests, 75, 146

alerts element, 118 example, 76

1 7 4

I n d e x

file format, 76 wireless, 78

gear modes, 49, 147 gear names

localizing, 54 gear page fragments

configuration pages, 62 wireless pages, 72

gear title template manifests, 141, 155 GearConfigFormHandler. See form handling GearContext. See atg.portal.servlet.GearContext GearEnvironment

initialization, 61 GearMessage class. See alerts GearMessagePublisher class. See alerts gears

Administration, 52 alerts, 52, See alerts and the PAF, 35 definition, 1 designing, 49 device outputs, 50 dimensions, 51 display modes, 50, 56 extending existing, 54 gear modes, 49 implementation overview, 4 manifests, 75, 78 packaging and deployment, 75 page fragments, 51, 59 persistent data repositories, 40 rendering, 23, 35 roles, 52, 55 synchronizing, 40 wireless, 78

GearServletFilter, 15 GearServletRequest. See

atg.portal.servlet.GearServletRequest GearServletResponse. See

atg.portal.servlet.GearServletResponse

H Helloworld portlet, 82 HTML considerations, 59

I I18nMessageProcessor. See

atg.portal.admin.I18nMessageProcessor Include Filter, 46

L layout considerations, 60 layout template manifests, 140, 153 link URLs, 36

usage, 37 links, 36

usage, 37

localization gear names, 54

localization considerations, 53

M manifests

color palette, 137, 157 gear, 75, 146 gear title template, 141, 155 layout template, 140, 153 manifest file headers, 136 page template, 139, 151 stylesheet, 138, 160

message handling, 69

N naming conventions

database tables, 72 Java class instances, 72

NucleusServlet, 85

O OASIS, 89 OfflineFilter, 20

P packaging

J2EE applications, 75 PAF. See Portal Application Framework PAF tag library

gear development, 36, 44 security, 44

page fragments, 51, See gears message handling, 69

Page objects, 10 page template manifests, 139, 151 PageFilter, 18 PageTemplateDispatcherServlet, 20 performance

resources, 41 persistent data repositories, 40 Portal Application Framework

administration pages, 2 definition, 2 services, 2

Portal Filter Chain, 12 portal manifest DTD, 161 portal objects, 10

lookup method, 11 PortalContext component, 7 PortalFilter, 17 PortalObjectResolver component, 10 portals

appearance customization, 135 authentication customization, 142 definition, 1

1 7 5

I n d e x

page structure, 23 roles, 52

PortalServerFilter, 14 portlet class, 82 Portlet Deployment Tool, 87

command line arguments, 88 portlets, 81

and gears, 81 deploying, 87 JSPs, 86

R request

accessing, 8 attributes, 8

request properties, accessing, 7 resource bundles, 119 response, 11 response URIs, 11 role test methods. See security methods

S security, 43

Include Filter, 46 J2EE, 47 levels, 3 predefined areas, 43 Secure Socket Layer, 48 tags, 44

security methods, 44 hasRole(), 46 isPortalAdministrator(), 46

security tags hasCommunityRole, 45 hasGearRole, 45 hasRole, 44

sending code. See alerts servlet filters, 12

filter mapping, 13 logging parameters. See servlet filters

SourceHandler interface, 128 stylesheet manifests, 138, 160 SuccessMessageProcessor component, 69

T tag libraries

declaration, 60 TargetHandler interface, 128 templates, 24

full deck templates, 34 gear title templates, 32 layout templates, 29, 30 page templates, 24 region fragment, 31 shared deck templates, 34 wireless templates, 33

U URLs, 36

usage, 37

W Web Services for Remote Portlets. See WSRP wireless device emulators, 73 Wireless Markup Language (WML), 72 wireless pages, 72 WSRP, 89

consumer, 94 consumer administration, 102 consumer portlet modes, 95 consumer UserProfile items, 96 consumer window states, 96 Markup interface, 94 producer, 90 producer administration, 100 Registration interface, 93 remote portlet-proxy portlet relationship, 100 Service Description interface, 91 WSRP-ProxyPortlet, 95

oracle atg portal dev guide

Documents