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 Oracles 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.
Contents
Introduction
Portals and Gears

What Is a Portal?
What Is a Gear?
Gear Definitions and Gear Instances
PAF Services
PAF Administration Pages
Security Levels
Gear Implementation Overview
Other Resources
Portal Administration Guide
Helloworld Example Gear and Portlet
ATG Documentation Set
API Documentation
1
1
1
2
2
2
3
4
5
5
5
5
5
Portal Requests and the Filter Chain
Portal Context
GearContext
The Portal Request
HTTP Parameters and Request Headers
Request Path Elements
Gear Servlet Request
Portal Objects
Mapping Hostnames and URLs to Portals
Object Lookup
The Portal Response
Response URIs
GearServletResponse
The Portal Filter Chain
Portal Filter Chain Elements
Portal Server Filter
Gear Filter
Display Filter
Device Filter
DeviceOutput Filter
Portal Filter
Community Filter
7
8
8
8
8
9
10
10
11
11
11
12
12
13
14
15
15
16
17
17
18
iii
Contents
Page Filter
Access Filter
Offline Filter
Dynamo 5 Style Attributes
Page Template Dispatch Servlet
The Portal Page Structure

How Gear Rendering Works
Portal Templates
Page Template
Layout Template
Gear Title Template
Wireless Templates
The Shared Deck Template
The Full Deck Template
Gears and the Portal Application Framework

How Portal Pages Are Rendered
How the PAF Processes Page Requests
Tag Libraries and Gear Development
Link URLs
URL Usage
Form Handling
Gear Form Handling
Gear Configuration Form Handling
JSP Form Handling
Configuring Gears to Work with Persistent Data Repositories
Keeping Gears Synchronized with Each Other
Performance Recommendations
Avoid Inefficient Java Methods
Additional Performance Resources
Portal Security
Security Roles
Predefined Security Areas
Security Tags
Role Test Tags
Role Test Methods
includeOnly Tag
Include Filter
J2EE Security
Secure Socket Layer Security
Designing a Gear
Gear Modes
Display Modes
18
19
20
20
20
23
23
24
24
29
32
33
34
34
35
35
35
36
36
37
37
37
37
39
40
40
40
40
41
43
43
43
44
44
46
46
46
47
48
49
49
50
iv
Contents
Device Outputs
Matrix of Gear Modes, Display Modes, and Device Outputs
User Interface Look and Feel Recommendations
Minimum Gear Sizing Rules
Gear Dimensions
Portal and Gear Roles
Gear Alerts
Gear Administration Considerations
Localization Considerations
Creating Configurable, Localizable Content in Gears
Localized Gear Names and Descriptions
Extending an Existing Gear
Example: A Discussion Forum Gear
Roles
Choosing Display Modes
Creating Gear Page Fragments

HTML Considerations
Layout Considerations
Accessibility Recommendations
Page Elements
Tag Library Declaration
DSP Page Initialization
Gear Environment Initialization
Gear Configuration Page Fragments
Developing Install Configuration Pages
Developing Initial, Instance, or User Configuration Pages
Example: A Document Exchange User Configuration Page
Message Handling in Page Fragments
I18nMessageProcessor
Adding Messages
Message Handling Example
Avoiding Gear Instance Conflicts
Naming Conventions
Wireless Gear Page Fragments
Wireless Markup Language
Wireless Device Emulator
Gear Packaging and Deployment

Gear Manifests
The Gear Manifest File Format
Wireless Gear Deployment Considerations
Gear Assembly
Gear Manifest
50
51
51
51
51
52
52
52
53
53
54
54
55
55
56
59
59
60
60
60
60
61
61
62
63
65
67
69
69
69
70
71
72
72
72
73
75
75
76
78
78
78
v
Contents
Developing and Deploying Portlets

Portlets and Gears
Comparison of Portlets and Gears
Developing a Portlet
Helloworld Portlet
Portlet Class
Portlet Deployment Descriptor File
Web Application Deployment Descriptor
Portlet JSPs
Helloworld Servlet Beans
Portlet Deployment Tool
Running the Portlet Deployment Tool
Portlet Deployment Tool Arguments
10 Web Services for Remote Portlets

WSRP Overview
Producer Overview
Consumer Overview
Producer Administration
Starting Up the Producer
Producer Database Configuration
Using the Producer Administration UI
Importing Portlet Descriptions
Consumer Administration
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
11 Adding Gear Alerts

Alerts Overview
Alert Services Provided by the PAF and Baseline Gears
Baseline Gear Events
Baseline Gear Scenario Templates
PAF Events
Adding Custom Alert Messages to Gears
Sample GearMessage Extension
Adding GearMessagePublisher to the Gear
Sample Sending Code
Sample dynamoMessagingSystem.xml File
Adding the Alerts Element to the Gear Manifest File
Creating a Resource Bundle Properties File
Creating an E-mail Template File
81
81
81
82
82
82
83
85
86
87
87
87
88
89
89
90
94
100
100
101
101
101
102
102
102
102
103
106
106
107
109
109
110
111
111
112
112
114
116
116
117
118
119
120
vi
Contents
Creating an Alert Instance Configuration Form

Extending the Scenario User Interface
Configuring a Scenario
Adding Alert Channels
Configuring an AlertChannel Component
AlertHandlerInterface
Registering the New Alert Channel
Configuring Alert Channel Preferences
Source Handlers and Target Handlers
Source Handlers
Target Handlers
Administrative Alerts and Framework Alerts
12 Creating a Custom Portal

Creating a New Portal
Copying the Portal Template
Editing Portal Framework Files
Setting Up the Portal Database
Starting Up Your Custom Portal Module
Further Customization
Customizing Portal Appearance
Manifest File Formats for Customizing Portal Appearance
Manifest File Headers
Color Palette Manifests
Stylesheet Manifests
Page Template Manifests
Layout Template Manifests
Gear Title Template Manifests
Customizing Portal Authentication
Authentication Pages
Specifying Authentication Page Locations
Appendix A: Portal Manifest Reference

Portal Manifest Elements
<portal-manifest> Element
Gear Manifest Elements
<gear-definitions> Element
<gear-definition> Element
<servlet-context> Element
<gear-modes> Element
<gear-mode> Element
<display-modes> Element
<display-mode> Element
<dimensions> Element
<dimension> Element
<error-handling> Element
120
121
123
124
125
126
127
127
128
128
128
129
131
131
131
132
134
134
135
135
136
136
137
138
139
140
141
142
142
142
145
145
145
146
146
146
146
147
147
148
148
148
148
149
vii
Contents
<instance-parameters> Element
<user-parameters> Element
<alerts> Element
<alert-message> Element
Page Template Manifest Elements
<page-templates> Element
<page-template> Element
Layout Template Manifest Elements
<layout-templates> Element
<layout-template> Element
Gear Title Template Manifest Elements
<gear-title-templates> Element
<gear-title-template> Element
Color Palette Manifest Elements
<color-palettes> Element
<color-palette> Element
<images> Element
<image> Element
<entity> Element
<color> Element
Color Palette Example
Stylesheet Manifest Elements
<styles> Element
<style> Element
The Portal Manifest DTD
Appendix B: PAF Tag Library Reference

paf:layout
paf:titlebar
paf:hasRole
paf:hasCommunityRole
paf:hasGearRole
paf:renderTab
paf:defaultTab
paf:currentTab
paf:encodeURL
paf:context
paf:include
Index
149
150
150
151
151
152
152
153
153
153
155
155
155
157
157
157
157
158
158
159
159
160
160
160
161
167
168
168
168
169
169
170
170
170
171
171
172
173
viii
Contents
1 Introduction
This document provides guidelines for developing portals and gears that can be easily integrated into
ATGs 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.
1
1 - Introduction
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
2
1 - Introduction
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.
3
1 - Introduction
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/pafdar/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.
4
1 - Introduction
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.
5
1 - Introduction
6
1 - Introduction
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
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
7
2 - Portal Requests and the Filter Chain
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
8
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
9
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
10
/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 requests 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 portals 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.
11
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 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 applications 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 applications
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>
12
<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.

The standard ATG Portal Filter Chain consists of the following filter elements:
Gear Filter
Display Filter
Device Filter
13
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.

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.
14
portalServletResponseFactory
wrapping
A reference to a component that creates

PortalServletResponse objects.
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 requests 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:
15
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.
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 requests DEVICE attribute. The mimeTypes property is
derived from the HTTP accept header. The preferred MIME type is determined by matching the Device
Filters 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:
16
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 requests 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:
Parameter
Description
deviceOutputFactory
The Nucleus address of the DeviceOutputFactory component. Default:

ctx:dynamo:/atg/portal/framework/DeviceOutputFactory
Portal Filter
Filter Class Name: atg.portal.servlet.PortalFilter
The Portal Filter is used to set the requests 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:
17
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 requests 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 Portals 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:
Parameter
Description
portalManager
communityIdParameterName
The name of the community ID query parameter. Defaults to

paf_commnuityId.

product.
Page Filter
Filter Class Name: atg.portal.servlet.PageFilter
The Page Filter sets the requests 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 Portals PortalObjectResolver to resolve the page.
18
PAGE
A reference to the Page object.
Page Filter Parameters

The following init parameters can be used to control the behavior of the Page Filter:
Parameter
Description
portalManager
pageIdParameterName
The name of the page ID query parameter. Defaults to paf_pageId.

product.
Access Filter
Filter Class Name: atg.portal.servlet.AccessFilter
The Access Filter checks the permissions of the PORTAL, COMMUNITY and PAGE attributes of the request.
If the request has the correct permissions, the request is passed on. If the permissions are incorrect, the
access filter directs the request to the appropriate login or access denied pages.
Access Filter Parameters

The following init parameters can be used to control the behavior of the Access Filter:
Parameter
methodName
Description
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.
19
Offline Filter
The Offline Filter checks whether the community is currently offline. If the community is offline the
request is directed to the offline page. If the community is not offline the request is passed down the filter
chain.
Filter Class Name: atg.portal.servlet.OfflineFilter
Offline Filter Parameters

The following init parameters can be used to control the behavior of the Offline Filter:
Parameter
Description
methodName
The method used to dispatch requests. Defaults to forward.
defaultOfflineTemplateContextURI
The context URI to use for the offline template.
defaultOfflineTemplatePathURI
The path URI to use for the offline template.
offline
If true, turns all communities offline. Defaults to false.
d5StyleOffline
A boolean used to configure the offline filter to use ATG

Dynamo 5 style offline handling.
The Portal request passes down the Portal Filter Chain and is transformed along the way. At the end of the
Portal Filter Chain, the Portal request is dispatched to its target, typically a JSP or Servlet.
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
20
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 communitys 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 applications deployment descriptor file,
just as each element of the Portal Filter Chain is, but using a <servlet> tag rather than a <filter> tag.
By default, the servlet mapping of the Page Template Dispatch Servlet uses a URL pattern of /, which
maps to the default servlet.
Page Template Dispatch Servlet Parameters

The following init parameters can be used to control the behavior of the Page Template Dispatch Servlet:
Parameter
Description
methodName
The method used to dispatch requests. Defaults to forward.
defaultDisplayModeName
The name of the display mode to use if none was set. Defaults to
shared.
defaultDeviceOutputName
The name of the device output to use if none was set. Defaults to
htmlURL.
21
22
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:
Portal Templates
Wireless Templates

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.
23
3 - The Portal Page Structure
Portal Templates
The portal page consists of a combination of template files. A full set of these files, referred to here as
template files, is included with the ATG Portal installation. The default storage directory for the template
files is the templates folder in <ATG10dir>/Portal/paf/start-portal/portal.war. You can make
a backup copy of the files in this archive and then supplement or edit them to supply your own pages,
headers, graphics, background images, regions, etc. By doing this, you can change the appearance of your
portal pages and insert your own portal branding.
Note that there is also a folder named <ATG10dir>/Portal/templates. The templates in that folder are
there for backwards compatibility with ATG 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 pages 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, lets 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.

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 Developers 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"
%>
24
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 pages 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}"/>
25
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.
26
<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 users 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.
27
<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.
28
<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 pages 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 columnsleft, wide; right, narrow)
25_75.jsp (two columnsleft, narrow; right, wide)
25_50_25.jsp (three columnsnarrow, wide, narrow)
29
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 gears 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 pages width, and includes the region rendering
fragment.
30
<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 gears 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);
31
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 posttreatment. 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:
32
<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.
33
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.
34
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 communitys 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 communitys
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.
35
4 - Gears and the Portal Application Framework
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
Developers 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>
36
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 gears
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:
37
UserConfig
InstanceConfig
InstallConfig
InitialConfig
These modes display forms that allow users, community leaders, and portal administrators to set a gears
configuration parameters. A gear developer needs to create a link to a UserConfig form. The remaining
three configuration forms are invoked by the PAFs 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)
38
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.
39
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()
40
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.
41
42
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 Librarys Permissions Methods.
Security Roles
The PAF recognizes six distinct categories of user:
Anonymous User
Registered User
Community Guest
Community Member
Community Leader
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.
43
5 - Portal Security
Area
Base URL
Description
Portal Administration
/portal/admin
Manages portal-wide configuration issues,

including gear installation and configuration.
Only users with the portal-admin role can
access.
Community
Administration
/portal/settings
Manages community-specific configuration

settings. Only portal administrators and
community leaders can access.
Security Tags
ATG Portal includes several access control tags in the PAF tag library and Java methods that are of interest
to both gear developers and to portal page developers. For additional information on the tags and their
underlying Java classes, refer to the ATG 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 commaseparated 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 shouldnt 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:
44
5 - Portal Security
[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:

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

...
<dsp:page>
<paf:hasGearRole roles="gear-reader,gear-writer" barrier="true">
...
[page contents]
...
</paf:hasGearRole>
</dsp:page>
45
5 - Portal Security
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 wasnt 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 PAFs Access Filter and security role tags can prevent users from navigating to content they shouldnt
see. In addition, you can prevent users from reaching gear content by directly entering URLs using the
46
5 - Portal Security
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 gears 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, youd 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 PAFs 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 gears 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.
47
5 - Portal Security
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.
48
5 - Portal Security
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 users 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.
You may need to design how a gear is configured for different portal contexts.
If your gears will need to be localized for use in different languages or regions, you will
need to plan accordingly.
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:
49
6 - Designing a Gear
Gear Mode
Description
About
Information about the gear (for example, author, copyright, and version).
Content
The main or primary presentation of the gear.
Help
Help information for the gear.
Preview
A mode for administrators or community leaders to view the

presentations of the gear.
Initial Configuration
Options that are set when the gear is first created in a community.
Typically, these are set by the community leader.
Instance Configuration
Administrative customization options, which configure a gear for a

particular community. Often these are gear appearance or community
membership settings. Typically, these are set by a community leader.
User Configuration
Gear personalization options (for example, entering stock quotes in a

stock ticker or ZIP Codes in a weather gear). These are always set by portal
end users.
Display Modes
Display modes reflect the size and appearance of a gear. Most gears will have both of the available display
modes:
Shared
Appears when the gear is on a portal page with other gears.
Full Page
Appears when a user follows a link that presents the gear on

a page by itself. (For example, when a user clicks on the
headline of a news story.)
You can specify only one page fragment per display mode. However, you can include any number of page
fragments within that page fragment and use the internal logic of the gear to decide which one to render.
For example, a discussion forum gear might require two full-page views in content modeone 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 gears Device Outputs reflect the type of devices on which a gear will be rendered. At present, there are
two Device Output options:
50
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
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 pages layout template. Both the layout
template and the placement of gears within the layout template are customizable by the Community
Leader.
51
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:
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.

Each gear will be administered by a portal administratorusually 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.
52
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 Developers Guide and the Working with
Forms and Form Handlers chapter of the ATG Programming Guide.
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 Jakartas 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:
53
<%@ 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 localizeddescriptions elements in the gear manifest. Use a separate localized-name and localizeddescription 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>

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
gears 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 gears 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:
54
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 tags
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 gears 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:
55
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
56
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.
57
58
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
Page Elements
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>
59
7 - Creating Gear Page Fragments
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.
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:

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

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>

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 users 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.
61
For additional information on the PAF Tag Library, refer to Appendix B: PAF Tag Library Reference in this
manual.

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
Initial Configuration
initialConfig
instanceConfig
User Configuration
userConfig
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.
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.
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.
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
62
</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"/>
63
<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 forms 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 handlers 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
64
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 forms 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 forms 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:
<dsp:importbean bean="/atg/portal/gear/GearConfigFormHandler"/>
65
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 handlers 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.
66
<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 forms 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 forms 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 gears shared view. It uses a subclass of GearConfigFormHandler named
DocExchConfigFormHandler.
67

<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"/>
...
68
</dsp:form>
</paf:InitializeGearEnvironment>

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 pages 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 doesnt 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);
69
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 dont 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"
70
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 --%>

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 users 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, dont 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 recreate the GearEnvironment object in your form handler using these parameters.
71
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.

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
72
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. Youll 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
73
74
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 Portals 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 gears 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 DTDs 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
75
8 - Gear Packaging and Deployment
Servlet Context
Images
Dimensions (narrow or wide, short or tall)
Display Modes
Instance Parameters
User Parameters
The Gear Manifest File Format

File Header
The file header for a gear manifest file looks like this:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE portal-manifest PUBLIC
"-//Art Technology Group, Inc.//DTD Portal Manifest//EN"
"http://www.atg.com/dtds/portal/framework/portal_manifest_1.0.dtd">
<portal-manifest name="NAME" version="1.0" author="AUTHOR">

<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
117
</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:
118
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
119
# 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="no-one@atg.com">
<setvalue param="messageSubject" value="Alert Notification">
<setvalue param="messageReplyTo" value="no-one@atg.com">
<setvalue param="mailingName" value="Alert Notification">
<p>The document named <valueof param="alertMsg.documentName">unknown</valueof> has
been created by <valueof param="alertMsg.authorName">unknown</valueof> on <valueof
param="alertMsg.creationDate">unknown</valueof>
Creating an Alert Instance Configuration Form

In order to make Alert settings available to community leaders through the PAF Administration utilities,
you must create a form for these settings. This form is then incorporated into the instance configuration
page for the gear. In doing this, you should use the handleAlertConfig tag and the
atg.portal.admin.AlertConfigBean, which captures the form input, as shown in the following code
sample.


<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 %>"
120
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 gears classes.jar file.
expression-grammar.xml
GrammarExtension.java
121
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"/>
122
<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 messagespecific. 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 users 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.
123
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.

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

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
The Nucleus address of the

Transaction Manager component.
/atg/dynamo/transaction/
All alerts must use the
/atg/portal/alert/
AlertRepositoryManager that
AlertRepositoryManager
transactionManager
alertRepositoryManager
via the DPS Targeted

Email
TransactionManager
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.
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 components 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
125
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()));
126
}
...
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 messages alert text. The AlertMgr maintains a
Map of message types to their resource bundles that is initialized by each gears definition file.
The following code sample shows how to use the MessageMapProps argument to obtain a localesensitive alert message formatted with the message bean argument. Note that the locale obtained from
the users 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 users
locale property. However, if you want to send an alert to a portal page using the Alerts gear, you should
instead use the Web pages 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
requests 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.

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.

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 users portal home page. The My Alerts form
127
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 users 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 users profile is updated to reflect the channel preferences selected.

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

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
CommunityGearAddedResources
CommunityGearRemovedMessage
CommunityGearRemovedMessage
CommunityGearRemovedResources
PageGearAddedMessage
PageGearAddedMessage
PageGearAddedMessageResources
PageGearRemovedMessage
PageGearRemovedMessage
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
MemSubscribeMessage
MemSubscribeResources
129
MemUnsubscribeMessage
MemUnsubscribeMessage
MemUnsubscribeResources
MembershipAcceptedMessage
MembershipAcceptedMessage
MembershipAcceptedResources
MembershipDeclinedMessage
MembershipDeclinedMessage
MembershipDeclinedResources
130
12 Creating a Custom Portal
You can create an ATG Portal application that is customized for your organizations 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
131
12 - Creating a Custom Portal
4.
Rename the expanded <ATG10dir>/MyPortal/paf-dar directory to myportal. Use

this command:
mv paf-dar myportal
The new myportal directory will serve as a template for your new MyPortal application. You will need to
edit a number of files before we get started with it but itll 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 ATGRequired 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
132
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>
133
<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:
134
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 portals 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/pafdar/portal/WEB-INF/templates directory:
/color/color-manifest.xml
/layout/layout-manifest.xml
/page/page-manifest.xml
135
/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/WEBINF/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 DTDs 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:

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

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

162
<!ELEMENT dimension (#PCDATA)>

<!ATTLIST dimension
name
(height | width)
#REQUIRED
>
<!ELEMENT rendering (render-asynchronously, timeout?)>
<!ELEMENT render-asynchronously EMPTY>
<!ATTLIST render-asynchronously
value
(true | false)
'true'
>
<!ELEMENT timeout EMPTY>
<!ATTLIST timeout
value
CDATA
#REQUIRED
>
<!ELEMENT caching (cache-output | (timeout, cache-key?))>
<!ELEMENT cache-key (property+)>
<!ELEMENT property EMPTY>
<!ATTLIST property
name
CDATA
#REQUIRED
>
<!ELEMENT cache-output EMPTY>
<!ATTLIST cache-output
value
(true | false)
'true'
>
<!ELEMENT error-handling (intercept-errors | cover-errors-with-cache)>
<!ELEMENT intercept-errors EMPTY>
<!ATTLIST intercept-errors
value
(true | false)
'true'
>
<!ELEMENT cover-errors-with-cache EMPTY>
<!ATTLIST cover-errors-with-cache
value
(true | false)
'true'
>
<!ELEMENT gear-modes (gear-mode+)>
<!ELEMENT gear-mode (display-modes)>
<!ATTLIST gear-mode
name
(content | userConfig | instanceConfig | initialConfig |

installConfig |
help | about | preview)
#REQUIRED
163
>
<!ELEMENT gear-roles (gear-role+)>
<!ELEMENT gear-role (#PCDATA)>
<!ELEMENT display-modes (display-mode+)>
<!ELEMENT display-mode (device-output+)>
<!ATTLIST display-mode
name
(shared | full | popup)
#REQUIRED
>
<!ELEMENT device-output (#PCDATA)>
<!ATTLIST device-output
name
(html | wml | chtml)
'html'
>
<!ELEMENT instance-parameters (parameter+)>
<!ELEMENT user-parameters (parameter+)>
<!ELEMENT parameter (default-value?, description?)>
<!ATTLIST parameter
name
CDATA
#REQUIRED
>
<!ELEMENT alerts (alert-message+)>
<!ELEMENT alert-message (message-type?, default-value?, resource-bundle?)>
<!ATTLIST alert-message
name
CDATA
#REQUIRED
>
<!ELEMENT message-type (#PCDATA)>
<!ELEMENT resource-bundle (#PCDATA)>
<!ELEMENT default-value (#PCDATA)>
<!ELEMENT color-palette (description, servlet-context, images?, entity+)>
<!ATTLIST color-palette
name
CDATA
#REQUIRED
version
CDATA
#IMPLIED
author
CDATA
#IMPLIED
>
<!ELEMENT entity (colors? | images?)>
<!ATTLIST entity
type
(page-body | gear-body | gear-title | highlight)
#REQUIRED
>
164
<!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
name
CDATA
#REQUIRED
version
CDATA
#IMPLIED
author
CDATA
#IMPLIED
>
<!ELEMENT cascading-style-sheet (#PCDATA)>
<!ELEMENT page-template
(description?, servlet-context, images?, display-modes)>
<!ATTLIST page-template
name
CDATA
#REQUIRED
version
CDATA
#IMPLIED
author
CDATA
#IMPLIED
>
<!ELEMENT layout-template
(description?, servlet-context, images?,
display-modes, regions)>
<!ATTLIST layout-template
name
CDATA
#REQUIRED
version
CDATA
#IMPLIED
author
CDATA
#IMPLIED
>
<!ELEMENT regions (region+)>
<!ELEMENT region (dimensions+)>
<!ATTLIST region
name
CDATA
#REQUIRED
>
<!ELEMENT gear-title-template (description?, servlet-context, images?,
gear-title-template-modes?)>
<!ATTLIST gear-title-template
name
CDATA
#REQUIRED
version
CDATA
#IMPLIED
author
CDATA
#IMPLIED
>
<!ELEMENT gear-title-template-modes (gear-title-template-mode+)>
<!ELEMENT gear-title-template-mode (display-modes)>
165
<!ATTLIST gear-title-template-mode
name
(preTemplate | template | postTemplate)
#REQUIRED
>
166
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.
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
167
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/pafdar/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
String. May be pre or post, for pre-treatment or post-treatment of the
false
type
gear.
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
168
Attributes
Attribute
Description
Required?
roles
String. A comma-separated list of roles to test for.
true
barrier
boolean. If true, redirects user to login or access
false
denied page.
Renders the body of the tag if the user has one of the community-relative roles indicated by the commaseparated list specified by the roles attribute. A role test can be negated by prepending the role name
with an exclamation point (!).
Body: JSP content
Attributes
Attribute
Description
Required?
roles
String. A comma-separated list of roles to test for.
true
barrier
false
denied page.
paf:hasGearRole
Renders the body of the tag if the user has one of the gear-relative roles indicated by the commaseparated 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
169
Attribute
Description
Required?
roles
String A comma-separated list of roles to test for.
true
barrier
false
denied page.
paf:renderTab
A parent tag with two children tags to render a tab for a portal template header set of tabs. One of the
two children tags, defaultTab or currentTab is rendered, depending on whether the current page
object passed to the renderTab tag is the same as the current page that is being rendered.
Body: JSP content
Attributes
Attribute
Description
page
Required?
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.
170
paf:encodeURL
Encodes a portal or gear URL with session ID and portal or gear specific parameters. The id attributes
specifies the name of the URL. The optional context attributes are used to encode used a specified
context.
Body: JSP content
Attributes
Attribute
Description
Required?
page
String
true
id
String
false
var
String
false
scope
String
false
url
String
false
portalContext
String
false
gearContext
String
false
context
String
false
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
171
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
Attribute
context
Description
Required?
true
Example: layout/html/region.jspf
172
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
173
Index
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
174
Index
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
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
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
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
175
Index

Oracle Atg Portal Dev Guide

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Oracle Atg Portal Dev Guide

Hochgeladen von

Copyright:

Verfügbare Formate

Version 10.0.

ATG Portal Development Guide

ATG Portal Development Guide

Portals and Gears

Portal Requests and the Filter Chain

ATG Portal Development Guide

The Portal Page Structure

Gears and the Portal Application Framework

ATG Portal Development Guide

Creating Gear Page Fragments

Gear Packaging and Deployment

ATG Portal Development Guide

Developing and Deploying Portlets

10 Web Services for Remote Portlets

11 Adding Gear Alerts

ATG Portal Development Guide

Creating an Alert Instance Configuration Form

12 Creating a Custom Portal

Appendix A: Portal Manifest Reference

ATG Portal Development Guide

Appendix B: PAF Tag Library Reference

ATG Portal Development Guide

Portals and Gears

ATG Portal Development Guide

Gears and Portlets

Gear Definitions and Gear Instances

Caching Gear content is stored in order to improve performance.

Logging Recording and analysis of user activity.

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

Add color palettes

ATG Portal Development Guide

Add portal page templates

Add gear layout templates

Add region fragments

Add gear title templates

Set user privileges

Specify default content

Specify default layouts

Specify default colors

Adds members to a community; adds and removes gears and pages;

Typically has read/write permissions within community. Community

Typically has read-only permissions within community. Community

A registered, logged-in portal user.

A non-registered or non-logged-in portal user.

ATG Portal Development Guide

Gear Implementation Overview

Plan your gear by deciding what it should have in terms of:

Develop the gear page fragments.

Package, deploy, and register your gear.

Test your gear and revise as needed.

ATG Portal Development Guide

Helloworld Example Gear and Portlet

ATG Documentation Set

ATG Portal Development Guide

ATG Portal Development Guide

2 Portal Requests and the Filter Chain

ATG Portal Development Guide

The Portal Request

HTTP Parameters and Request Headers

Request Path Elements