Professional Documents
Culture Documents
2
Portal Development Guide
Oracle ATG
One Main Street
Cambridge, MA 02142
USA
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
1
1
1
2
2
2
3
4
5
5
5
5
5
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
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
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
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
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
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.
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.
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:
Error-handling Presenting helpful error messages in a format that reflects the look
and feel of the portal.
Navigation Structuring gear page parameters in a way that makes pages readily
accessible.
Add gears
2
1 - Introduction
Add stylesheets
Administer communities
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
Community Member
Community Guest
Registered User
Anonymous 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
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.
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.
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.
7.
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.
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
ATG Portal is implemented as a J2EE v.1.3 Web application, using Java Servlet Technology, v2.3 (Servlets).
When a portal user enters the portal, an HTTP request is made to a Web server. The request is received by
the Web server and handed off to the Portal container. The Portal container creates and initializes a portal
context for the request. The Portal container may optionally authenticate the client and fire events or
alerts.
The request is handled by a series of servlet filters known as the Portal Filter Chain. Each filter in the chain
handles a specific task for the request and passes the request to the next filter. At the end of the Portal
Filter Chain, the Portal request is dispatched to its target, typically a JSP or Servlet. The target servlet
generates content to send back to the portal user via the response object, using Portal gears and other
portal assets. (The process of rendering the page is covered in the Gears and the Portal Application
Framework chapter.) Once the Portal container is finished with the response, control of the response is
handed back to the Web server.
This chapter describes the Portal context, response and request and the Portal Filter Chain. It includes the
following sections:
Portal Context
The Portal Request
The Portal Response
The Portal Filter Chain
Portal Filter Chain Elements
Portal Context
The PortalContext is an object that represents a portal in a particular state, using these properties:
portal
page
community
displayMode
ATG Portal includes a request-scoped component that makes Portal objects accessible as properties of a
Nucleus component. This component, /atg/portal/PortalContext, provides access to Portal objects
through these properties. You can use the PortalContext properties to access the state of the portal
associated with the request. Access to these properties in the PortalContext enables you to, for
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
Refer to Java Servlet Technology, v.2.3 (Servlets) for information on access to HTTP protocol parameters
and request headers.
8
2 - Portal Requests and the Filter Chain
getPathInfo
getPortalContextPath
getPortalServletPath
getPortalPathInfo
/portal
/*.jsp
/templates
/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
9
2 - Portal Requests and the Filter Chain
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
PORTAL
getPortal
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
DISPLAYMODE
getDisplayMode
Device
An object encapsulating
information about the portal
client device. Contains
information about preferred
MIME types and user agent.
DEVICE
getDevice
10
2 - Portal Requests and the Filter Chain
Property
Description
hostToPortalMap
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:/
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 specified portal context. This lets you change the
PortalContext associated with the request.
11
2 - Portal Requests and the Filter Chain
GearServletResponse
<filter>
<filter-name>PortalServerFilter</filter-name>
<display-name>PortalServerFilter</display-name>
<description>Responsible for wrapping the HttpServletRequest and
HttpServletResponse objects.</description>
<filter-class>atg.portal.servlet.PortalServerFilter</filter-class>
<init-param>
<param-name>loggingDebug</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>loggingWarning</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>loggingError</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>loggingInfo</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
12
2 - Portal Requests and the Filter Chain
<param-name>portalServletRequestFactory</param-name>
<param-value>ctx:dynamo:/atg/portal/servlet/PortalServletFactory
</param-value>
</init-param>
<init-param>
<param-name>portalServletResponseFactory</param-name>
<param-value>ctx:dynamo:/atg/portal/servlet/PortalServletFactory
</param-value>
</init-param>
<init-param>
<param-name>wrapping</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>initD5StyleAttributes</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>portalServletRequestName</param-name>
<param-value>PortalServletRequest</param-value>
</init-param>
</filter>
Each Portal filter has logging parameters that correspond to the logging levels of Nucleus components:
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.
13
2 - Portal Requests and the Filter Chain
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.
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.
Description
PORTALSERVLETREQUEST
PORTALSERVLETRESPONSE
PORTALCONTEXTPATH
PORTALSERVLETPATH
PORTALPATHINFO
Parameter
Description
portalServletRequestFactory
14
2 - Portal Requests and the Filter Chain
portalServletResponseFactory
wrapping
them down the filter chain. Defaults to false, which means that
the HttpServletRequest and HttpServletResponse are
passed on.
initD5StyleAttributes
portalServletRequestName
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
15
2 - Portal Requests and the Filter Chain
Parameter
Description
defaultDisplayModeName
The name of the default display mode for the portal. Defaults to
shared.
displayModeParameterName
initD5StyleAttributes
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
DEVICE
16
2 - Portal Requests and the Filter Chain
Parameter
Description
Default
mimeTypePreferences
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
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
17
2 - Portal Requests and the Filter Chain
Parameter
Description
portalManager
portalIdParameterName
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.
The following attribute is set when the filter is invoked.
COMMUNITY
Parameter
Description
portalManager
communityIdParameterName
initD5StyleAttributes
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.
The following attribute is set when the filter is invoked.
18
2 - Portal Requests and the Filter Chain
PAGE
Parameter
Description
portalManager
pageIdParameterName
initD5StyleAttributes
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.
Parameter
methodName
Description
The method used to dispatch requests. Defaults to
forward.
defaultLoginTemplateContextURI
defaultLoginTemplatePathURI
defaultAccessDeniedTemplateContextURI
defaultAccessDeniedTemplatePathURI
profileName
d5StyleAccess
19
2 - Portal Requests and the Filter Chain
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
Parameter
Description
methodName
defaultOfflineTemplateContextURI
defaultOfflineTemplatePathURI
offline
d5StyleOffline
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.
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.
20
2 - Portal Requests and the Filter Chain
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.
Parameter
Description
methodName
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
2 - Portal Requests and the Filter Chain
22
2 - Portal Requests and the Filter Chain
Understanding the portal page template and auxiliary files that are used provides important information
for customizing a portal or for understanding the context in which gears are rendered. If you use the page
templates provided with ATG Portal, then you do not need to develop new portal page templates, but
you will still need to understand the portal page template context. In addition, to change the look and
feel of your portal pages, you will need to edit the default templates (after making backup copies).
For a listing and description of the provided template files, see the Portal Configuration chapter of the ATG
Portal Administration Guide. For more detailed information on customizing a portal, see the Creating a
Custom Portal chapter of this manual. For information on the PAF tags that appear in the code samples in
this chapter, see Appendix B: PAF Tag Library Reference and the Gears and the Portal Application Framework
chapter.
This chapter includes the following sections:
How Gear Rendering Works
Portal Templates
Wireless Templates
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
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:
Rendering the pages layout, which is typically done with a layout template
uri="http://java.sun.com/jstl/core" %>
%>
24
3 - The Portal Page Structure
Internationalization Initialization
This element makes available the resource bundle used for localizing user messages on the page.
<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
3 - The Portal Page Structure
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.
url="/portal/settings/community_settings.jsp"/>
url="${contextPath}/userprofiling/login.jsp"/>
<paf:encodeURL var="logoutURL"
url="${contextPath}/userprofiling/logout.jsp"/>
<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
3 - The Portal Page Structure
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.
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
3 - The Portal Page Structure
bgcolor='<c:out value="${pageBackgroundColor}"/>'>
<font color='<c:out value="${pageTextColor}"/>'>
<c:choose>
<c:when test="${profile.transient == false}">
<fmt:message key="page-message-logged-in"
bundle="${templatesbundle}"/>
<b><dsp:valueof bean="Profile.login"/></b><br/>
<a href='<c:out value="${logoutURL}"/>'>
<fmt:message key="page-label-logout"
bundle="${templatesbundle}"/></a>
</c:when>
<c:otherwise>
<a href='<c:out value="${loginURL}"/>'>
<fmt:message key="page-label-login"
bundle="${templatesbundle}"/></a><br/>
</c:otherwise>
</c:choose>
</font>
</td>
<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
3 - The Portal Page Structure
<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>
<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:
29
3 - The Portal Page Structure
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.
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.
uri="http://java.sun.com/jstl/core" %>
Next, we set the portal request and response and other variables.
value="${portalServletRequest.page}"/>
<c:set var="regionMap"
value="${page.regions}"/>
The next section begins the table that defines the page layout.
<center>
<table border="0" width="96%" cellpadding="0" cellspacing="0">
<tr>
The first cell is defined. It is allocated 25% of the pages width, and includes the region rendering
fragment.
30
3 - The Portal Page Structure
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}">
2.
3.
<%
pageContext.setAttribute("gearContextType",GearContext.class);
31
3 - The Portal Page Structure
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.
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.
titlebar.jsp
titlebar-pre.jsp
titlebar-post.jsp
The next section optionally displays an Edit link for the gear, if the gear has been configured to be
customizable by the user:
32
3 - The Portal Page Structure
The next section optionally displays an About link for the gear:
The next section optionally displays a Help link for the gear:
<%
gearContext.setGearMode(GearMode.HELP);
%>
<c:if test="${showHelp == true}">
<a href="<%= gearServletResponse.encodeGearURL
(gearServletRequest.getPortalRequestURI(),gearContext) %>">
<font color="<c:out value="${gearTitleTextColor}"/>">
<fmt:message key="titlebar-control-help" bundle="${templatesbundle}"/></font></a>
</c:if>
Wireless Templates
A wireless portal template consists of a deck of sequential screens. The content of these screens resides in
JSP files that you create. These files differ from ordinary JSP files, however, in that their contents are
written in WML. A set of WML portal template files is included in ATG Portal. These template files can be
found in <ATG10dir>/Portal/paf/start-portal/paf-dar/portal/templates/page/wml. You can
make a backup copy of the files in this archive and then supplement or edit them to supply your own
pages.
33
3 - The Portal Page Structure
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.
34
3 - The Portal Page Structure
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.
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.
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.
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.
Link URLs
Links in a portal page typically need to pass information. There are several techniques you can use in
constructing a link, including:
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
url
The URL to encode. Defaults to the requested URI if not specified. Optional.
portalContext
gearContext
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
4 - Gears and the Portal Application Framework
The example below shows how one might create a link to a gear rendering in help mode, using the
GearServletResponse.encodeGearUrl method.
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.
37
4 - Gears and the Portal Application Framework
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:
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
4 - Gears and the Portal Application Framework
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.
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:
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
4 - Gears and the Portal Application Framework
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 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.
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
4 - Gears and the Portal Application Framework
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:
41
4 - Gears and the Portal Application Framework
42
4 - Gears and the Portal Application Framework
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
Portal Administrator
Every portal user belongs to at least one of these categories. These groups also generally correspond to
varying levels of access, features, and functionality. Users with higher security roles implicitly hold lower
roles as well. For example, a community leader is also a community member and community guest (but
not a portal administrator).
For administrative information on portal security (restricting access to communities, pages, and gears),
refer to the Portal Access Control chapter of the ATG Portal Administration Guide.
43
5 - Portal Security
Area
Base URL
Description
Portal Administration
/portal/admin
Community
Administration
/portal/settings
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.
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
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:
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:
45
5 - Portal Security
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:
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>
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.
Gear Administration Considerations
You may need to design how a gear is configured for different portal contexts.
Localization Considerations
If your gears will need to be localized for use in different languages or regions, you will
need to plan accordingly.
Extending an Existing Gear
The easiest way to create a new gear is to copy and extend an existing gear.
The final section of this chapter is an example of gear design: Example: A Discussion Forum Gear.
Gear Modes
Gear modes reflect the functional mode a gear is in. A gear can have one or more of the following seven
gear modes:
49
6 - Designing a Gear
Gear Mode
Description
About
Information about the gear (for example, author, copyright, and version).
Content
Help
Preview
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
User Configuration
Display Modes
Display modes reflect the size and appearance of a gear. Most gears will have both of the available display
modes:
Shared
Full Page
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
6 - Designing a Gear
Gear Mode
Display Mode
Device Output
Page Fragment
Content
Full
HTML
newsFull.jsp
Content
Shared
HTML
newsShared.jsp
Content
Full
WML
newsFull.wml
Instance Configuration
Full
HTML
newsInstanceConfig.jsp
User Configuration
Full
HTML
newsUserConfig.jsp
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
6 - Designing a Gear
One of the most basic decisions you will make is that of what roles to use or define for the gear and what
privileges to give to each of the roles. The pre-defined portal roles are:
Portal Administrator
Community Leader
Community Member
Community Guest
Registered User
Anonymous User
The PAF Tag Library provides tags that gear and portal developers can use to check for these roles and to
grant or deny access to pages and content accordingly. You can also create additional roles for your gear
if you need them, by adding them to profile repository and then using them in your gear code as
necessary.
For information on the security tags in the PAF Tag Library, refer to the Portal Security chapter of this
manual. For information on creating roles, refer to the ATG Personalization Guide for Business Users.
Gear Alerts
You can create alerts that will be sent by your gears and handled by ATG scenarios. You can create
scenarios to generate actions based on the alerts. For example, an action might cause an e-mail message
to be sent to specified users and a notice to appear in the Alerts gear. As you plan your gear, you need to
consider what events you would like to create alerts for and what actions you would like to be carried out.
ATG Portal alerts use Java Messaging System (JMS) as their underlying technology. The following Web
location contains comprehensive information on JMS:
java.sun.com/products/jms
For complete information on setting up your gears so that they can send alerts, refer to the Adding Gear
Alerts chapter of this manual. For information on scenarios, refer to the ATG Personalization Guide for
Business Users.
52
6 - Designing a Gear
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.
Localization Considerations
If your gears will need to be localized for use in different languages or regions, you will need to plan
accordingly. In particular, you will want to ensure that your gear will be acceptable in any locale (without
recompiling), provided that localization data is provided and that dates and currencies, for example,
conform to the conventions for a given locale. Fortunately, these goals are attainable with a minimum of
additional effort provided that you use particular well-known methods and tools in developing your
gears.
See the Internationalizing a Dynamo Web Site chapter of the ATG Programming Guide for more information.
In addition, you might want to consider using 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/
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
6 - Designing a Gear
%>
<fmt:bundle basename=my.portal.Resources/>
<fmt:message id="finishButton" key="finishButton"/>
<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>
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.
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
6 - Designing a Gear
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
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
6 - Designing a Gear
Role
Privileges
Leader
Poster
Reader
Read posts
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
Shared
Full-Page
Message Content
Full-Page
56
6 - Designing a Gear
57
6 - Designing a Gear
58
6 - Designing a Gear
As part of the process of designing a gear, you should decide how the matrix of gear modes, display
modes, and device outputs will map to page fragments, so you will know what page fragments you need
to create. For an example of this exercise, refer to the table in the Matrix of Gear Modes, Display Modes,
and Device Outputs section of the Designing a Gear chapter in this manual. The next step is creating the
page fragments that make up the presentation of the gear. This chapter describes some important
considerations in developing gear page fragments. It includes the following sections:
HTML Considerations
Layout Considerations
Accessibility Recommendations
Page Elements
Gear Configuration Page Fragments
Message Handling in Page Fragments
Avoiding Gear Instance Conflicts
Wireless Gear Page Fragments
HTML Considerations
Because gears appear as parts of a portal page (and more specifically, within an HTML table cell), you
should not treat the HTML tags for the gear as you would for a freestanding HTML page. Because they
would be redundant, you should not use the following HTML tags within your gear page documents:
<html></html>
<header></header>
<body></body>
<title></title>
<meta></meta>
<frameset></frameset>
59
7 - Creating Gear Page Fragments
Layout Considerations
A portal page will usually consist of a header area, footer area, and a content area. The gears will reside
within regions in the content area. The number and width of the regions will be selectable from a portal
administration page. When a gear is rendered in full display mode, it occupies the entire space between
the header and the footer. When a gear is rendered in shared display mode, it will share the space
between the header and footer with other gears. You need to design your gear with appropriate
dimensions to function in shared or full display mode.
Accessibility Recommendations
We recommend that you create gear HTML so that it complies with the Web Content Accessibility
Guidelines of the World Wide Web Consortium (W3C). The primary features of the accessibility guidelines
are summarized at the following Web location:
http://www.w3.org/TR/WAI-WEBCONTENT
Page Elements
Page fragments have several important elements you need to include to enable tag functionality:
uri="http://java.sun.com/jstl/core" %>
uri="http://java.sun.com/jstl/fmt"
%>
%>
In most cases you will at least need the declarations for the pafTaglib shown above.
60
7 - Creating Gear Page Fragments
<dsp:page>
<%!-- GEAR SPECIFIC JSP GOES HERE --%>
</dsp:page>
<%
//Obtain request/response
GearServletResponse gearServletResponse =
(GearServletResponse)request.getAttribute(Attribute.GEARSERVLETRESPONSE);
GearServletRequest gearServletRequest =
(GearServletRequest)request.getAttribute(Attribute.GEARSERVLETREQUEST);
%>
Current community
Current URL
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
7 - Creating Gear Page Fragments
For additional information on the PAF Tag Library, refer to Appendix B: PAF Tag Library Reference in this
manual.
Install Configuration
installConfig
Initial Configuration
initialConfig
Instance Configuration
instanceConfig
User Configuration
userConfig
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
7 - Creating Gear Page Fragments
</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.
Surround the page content with the hasRole tag to prevent users other than a portal
administrator from accessing this page. For example:
<%@ taglib uri="/paf-taglib" prefix="paf" %>
<paf:hasRole roles="portal-admin">
<%!--INSTALL CONFIGURATION FORM PAGE CONTENT GOES HERE --%>
</paf:hasRole>
2.
Import your form handler. For example, if you create a subclass of the
GearConfigFormHandler that you have named MyConfigFormHandler, you would
import it as follows:
<%@ taglib uri="/dsp" prefix="dsp" %>
<dsp:importbean bean="/atg/portal/gear/MyConfigFormHandler"/>
If you need additional functionality in the form handler, you can extend the class.
3.
Set the gear definition request attribute to the value passed to you by the PAF.
<%request.setAttribute(atg.portal.framework.RequestAttributes.
GEAR_DEFINITION,(String) request.getParameter("paf_gear_def_id") );%>
4.
Set up the default values needed by your form using <dsp:setvalue> tags to set
values in your form handler:
<dsp:setvalue bean="MyConfigFormHandler.paramType" value="instance"/>
<dsp:setvalue bean="MyConfigFormHandler.settingDefaultValues"
value="true"/>
63
7 - Creating Gear Page Fragments
<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
7 - Creating Gear Page Fragments
1.
1.
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"/>
2.
Import your form handler. For example, if you plan to use the
GearConfigFormHandler that is provided with the Portal module, you would import
it as follows:
<%@ taglib uri="/dsp" prefix="dsp" %>
<dsp:importbean bean="/atg/portal/gear/GearConfigFormHandler"/>
65
7 - Creating Gear Page Fragments
If you need additional functionality in the form handler, you can extend the
GearConfigFormHandler class.
3.
Set up the default values needed by your form using <dsp:setvalue> tags to set
values in your form handler:
<dsp:setvalue bean="GearConfigFormHandler.paramType" value="instance"/>
<dsp:setvalue bean="GearConfigFormHandler.settingDefaultValues"
value="false"/>
<dsp:setvalue bean="GearConfigFormHandler.paramNames"
value="property1 property2 property3"/>
4.
Create your configuration form. The form tag action method differs depending on the
type of configuration. For Initial and Instance Configuration, you should use
request.getRequestURI(). For User Configuration, use
gearEnv.getOriginalRequestURI() to get the URI you want to go to.
For Initial and Instance Configuration, your form tag should look like this:
<dsp:form method="post" action="<%=request.getRequestURI() %>">
<%!-- CONFIGURATION FORM PAGE CONTENT GOES HERE --%>
</dsp:form>
For User Configuration, your form tag should look like this:
<dsp:form method="post" action="<%=gearEnv.getOriginalRequestURI()%>">
<%!-- CONFIGURATION FORM PAGE CONTENT GOES HERE --%>
</dsp:form>
5.
Create the hidden fields necessary for navigation and form processing.
The form 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
7 - Creating Gear Page Fragments
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.
7.
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.
67
7 - Creating Gear Page Fragments
<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
7 - Creating Gear Page Fragments
</dsp:form>
</paf:InitializeGearEnvironment>
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
7 - Creating Gear Page Fragments
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().
<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">\
<%
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.
We get the failure messages and output them in the same way.
70
7 - Creating Gear Page Fragments
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 --%>
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
7 - Creating Gear Page Fragments
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.
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.
WML Specification
WMLScript Specification
72
7 - Creating Gear Page Fragments
73
7 - Creating Gear Page Fragments
74
7 - Creating Gear Page Fragments
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
Display Modes
Instance Parameters
User Parameters
76
8 - Gear Packaging and Deployment
<dimension name="width">wide</dimension>
</dimensions>
<gear-modes>
<gear-mode name="content">
<display-modes>
<display-mode name="shared">
<device-output name="html">/DocExchShared.jsp</device-output>
</display-mode>
<display-mode name="full">
<device-output name="html">/DocExchFull.jsp</device-output>
</display-mode>
</display-modes>
</gear-mode>
<gear-mode name="userConfig">
<display-modes>
<display-mode name="full">
<device-output name="html">/UserConfig.jsp</device-output>
</display-mode>
</display-modes>
</gear-mode>
<!-- ADDITIONAL GEAR MODES GO HERE --!>
</gear-modes>
<instance-parameters>
<parameter name="repositoryPath" required="false">
<default-value>
/atg/portal/gear/docexch/DocumentRepository
</default-value>
</parameter>
<parameter name="itemDescriptorName" required="false">
<default-value>
document
</default-value>
</parameter>
</instance-parameters>
<!-- ADDITIONAL INSTANCE PARAMETERS GO HERE --!>
<user-parameters>
<parameter name="shortListSize" required="false">
<default-value>
3
</default-value>
</parameter>
<parameter name="fullListPageSize" required="false">
<default-value>
12
77
8 - Gear Packaging and Deployment
</default-value>
</parameter>
</user-parameters>
<!-- ADDITIONAL USER PARAMETERS GO HERE --!>
</gear-definition>
</gear-definitions>
Gear Manifest
A gear intended for wireless output needs to have the wml device output specified in the gear manifest
for each gear mode the gear uses, as illustrated in the following code sample:
<gear-modes>
<gear-mode name="content">
<display-modes>
<display-mode name="shared">
<device-output name="html">/html/DocExchShared.jsp</device-output>
<device-output name="wml">/wml/DocExchShared.jsp</device-output>
</display-mode>
<display-mode name="full">
<device-output name="html">/html/DocExchFull.jsp</device-output>
<device-output name="wml">/wml/DocExchFull.jsp</device-output>
</display-mode>
</display-modes>
</gear-mode>
<gear-mode name="userConfig">
<display-modes>
<display-mode name="full">
<device-output name="html">/html/UserConfig.jsp</device-output>
<device-output name="wml">/wml/UserConfig.jsp</device-output>
</display-mode>
</display-modes>
</gear-mode>
78
8 - Gear Packaging and Deployment
79
8 - Gear Packaging and Deployment
80
8 - Gear Packaging and Deployment
This chapter provides an introduction to portlet development on ATG Portal. For more detailed and
advanced information about portlet development, read the portlet specification,
http://jcp.org/aboutJava/communityprocess/review/jsr168/.
Gears
Portlets
If you are designing a new portal component, you need to decide whether to develop it as a portlet or a
gear. If you develop it as a gear, you may be able to take advantage of ServletFilters and other
features that are not available to portlets. However, if you develop it as a portlet, your new component
will be portable and able to run (after processing) on other portal platforms, as well on the ATG Portal.
81
9 - Developing and Deploying Portlets
Developing a Portlet
The principal elements of a portlet are:
Portlet Class
Portlet JSPs
This section discusses each of these elements, using the Helloworld sample portlet as an example. ATG
Portal includes three sample portlets that you can use as a guide for developing your own portlets:
Helloworld portlet- A bare-bones portlet that displays a text message and a form field
that lets you change the text message.
Slot portlet A portlet that displays an ATG slot, which can render variable content
based on targeting rules.
Helloworld Portlet
The Helloworld Portlet is used to demonstrate how to construct a portlet that integrates with the ATG
platform. The Helloworld Portlet demonstrates the use of ATG servlet beans, including form handlers. It
displays a property value of one bean and provides a form input to alter the property value.
The Helloworld Portlet can be found in the ATG platform distribution at
<ATG10dir>/Portlet/helloworld. The helloworld module directory includes the following:
helloworld/
HelloWorldPortlet-manifest.xml
helloworld.war
helloworld.ear
config/
lib/
META-INF/
src/
helloworld/
Portlet Class
The portlet deployment descriptor needs to specify a portlet Java class. ATG provides two base classes
you can either use as your portlet class or extend in your own subclass:
atg.portlet.GenericPortletService
atg.portlet.DispatchPortlet
82
9 - Developing and Deploying Portlets
The GenericPortletService class provides standard methods for an ATG Nucleus component,
including support for self-configuration, name resolution, performance profiling and logging.
A class derived from GenericPortletService should override the following methods:
startService
handleRender
handleProcessAction
stopService
The DispatchPortlet class extends GenericPortletService. You can use DispatchPortlet as your
portlet class if, as in most cases, you want your portlet to dispatch to a JSP or other resource. The
DispatchPortlet.path property defines the resource the portlet dispatches to.
<portlet>
<portlet-name>MyPortletService</portlet-name>
<portlet-class>com.acme.portlet.MyPortletService</portlet-class>
<init-param>
<param-name>loggingDebug</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>loggingWarning</param-name>
<param-value>false</param-value>
</init-param>
<init-param>
<param-name>loggingError</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>loggingInfo</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>MyString</param-name>
<param-value>foobar</param-value>
</init-param>
<param-name>Object</param-name>
83
9 - Developing and Deploying Portlets
<param-value>ctx:dynamo:/com/Acme/MyFooObject</param-value>
</init-param>
</portlet>
Portlets derived from GenericPortletService can use the lookup method to look up objects by JNDI
context. The objects JNDI context is accessible through the context property. A
GenericPortletService can log information using the standard Nucleus logging facilities provided.
Support for info, warning, error and debug levels are provided by the service. If a performance monitor is
enabled, the portlet collects performance metrics about the handleService method.
Element
Description
Value
portlet-class
atg.portlet.DispatchPortlet
path
/index.jsp
84
9 - Developing and Deploying Portlets
supports
text/html
VIEW
DynamoServerPageFilter
This element of the deployment descriptor file invokes the DAF servlet pipeline. The DAF servlet pipeline
(described in the Request Handling with Servlet Pipelines chapter of the ATG Programming Guide) is a series
of request-handling servlets. If the current request has not already started the DAF servlet pipeline, the
DynamoServerPageFilter routes the request to the servlet pipeline.
<filter>
<filter-name>DynamoServerPageFilter</filter-name>
<display-name>DynamoServerPageFilter</display-name>
<description>This filter invokes the dynamo application framework servlet
pipeline.</description>
<filter-class>atg.filter.dspjsp.PageFilter</filter-class>
</filter>
NucleusServlet
This element starts Nucleus, if Nucleus has not already been started. The NucleusServlet creates an
instance of Nucleus and sets it as an attribute of the Web application, making Nucleus services available.
<servlet>
<servlet-name>NucleusServlet</servlet-name>
<display-name>NucleusServlet</display-name>
<description>Initializes nucleus in the current web application.</description>
<servlet-class>atg.nucleus.servlet.NucleusServlet</servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
Taglibs
In addition, you may want to add elements like these, which make available the ATG dspjsp and
dspjspEL taglibs, as well as the Java portlet taglib. These are standard tag libraries that may be
valuable in portlet JSPs:
85
9 - Developing and Deploying Portlets
<taglib>
<taglib-uri>dsp</taglib-uri>
<taglib-location>/WEB-INF/tld/dspjspTaglib1_0.tld</taglib-location>
</taglib>
<taglib>
<taglib-uri>atg-dspjspEL</taglib-uri>
<taglib-location>/WEB-INF/tld/dspjspELTaglib1_0.tld</taglib-location>
</taglib>
<taglib>
<taglib-uri>http://java.sun.com/portlet</taglib-uri>
<taglib-location>/WEB-INF/tld/portlet.tld</taglib-location>
</taglib>
Portlet JSPs
In many cases, a portlet is designed to dispatch to one or more JSPs. This lets you format the presentation
of the portlet output in a page. The Helloworld portlet uses a simple page located at
<ATG10dir>/Portlet/helloworld/helloworld/helloworld/html/index.jsp. There is nothing
that makes this page different from a non-portlet JSP that uses a form handler.
The Helloworld index.jsp page uses the HelloWorldFormHandler. This line in the index.jsp page
sets the actionURL variable, which is used in the action attribute of a form tag:
<c:set var="actionURL"><portlet:actionURL/></c:set>
The core of the index.jsp page accesses the HelloWorldFormHandler with the form and input
submit tags from the dpsel tag library.
86
9 - Developing and Deploying Portlets
87
9 - Developing and Deploying Portlets
Argument
Description
-i
Input: the absolute pathname of the portlets WAR file or exploded WAR directory. The
Portlet Deployment Tool expects to find a portlet.xml file in the WARs WEB-INF
directory.
-o
Output: the absolute path of the directory where the portlet should be installed.
-w
The path of the working directory the tool should use. If you do not explicitly set the
working directory, the tool uses the default working directory. The default working
directory is ${atg.dynamo.root}/home/data, if atg.dynamo.root is set as an
environment variable. Otherwise, the default working directory is the current
directory.
-c
The context root that should be used for the deployed WAR.
-f
Overwrite: If there is already a portlet with the same name in the location specified by
the -o argument, overwrite it. If you do not use this argument, the Portlet Deployment
Tool exits and reports an error if it finds that there is already a portlet with the same
name in the location specified by the -o argument.
-ear
-debug
-info
-warning
-error
-silent
-usage
88
9 - Developing and Deploying Portlets
Web Services for Remote Portlets (WSRP) is a means to create presentation-oriented web services that can
be easily plugged into a portal. Portals can aggregate presentations from many WSRP services, and those
services can be made aware of the portal context, including user profiles for personalization, locale
awareness, and interactivity.
This chapter contains the following sections:
WSRP Overview
Producer Administration
Consumer Administration
WSRP Overview
WSRP involves two major entities, a producer and a consumer. The producer offers one or more portlets,
information on them, and interfaces for interacting with them. The consumer negotiates with the
producer and ultimately presents the portlet contents to an end-user. An example of a producer is a
weather information service that hosts interactive applications, and a consumer is a portal site that wants
to make these applications available to its users.
The WSRP specification is defined by OASIS, a non-profit global consortium. It defines a set of interfaces
for accessing and managing portlets. Portals can use these interfaces to display remotely-running portlets
inside their pages, without any additional programming by the portal developers. To the end-user, it
appears that the portlet is running locally within their portal, but in reality the portlet resides in a
remotely-running portlet container.
The ATG WSRP environment includes a producer, which provides WSRP services, and a consumer, a client
portal that aggregates the remote markup fragments provided by the producer(s) into a portal page.
Communication between the consumer and producer is based on the standard WSRP interfaces, which
allows producers and consumers to interoperate regardless of location and implementation.
For more information on WSRP visit the OASIS site at http://www.oasis-open.org.
The figure that follows shows a high-level WSRP environment:
89
10 - Web Services for Remote Portlets
The ATG consumer and producer can be used in either a homogeneous WSRP environment (ATG
consumer and ATG producer) or a heterogeneous environment (mix of ATG and third-party consumer
and producer).
Producer Overview
The producer can be viewed as a container environment in which remote portlets reside and execute. The
Web service interfaces exposed by the producer allow a WSRP-compliant consumer to discover the
capabilities and offerings of the producer and establish a contract with the producer.
Note: The remote components must conform to the JSR 168 standard.
The WSRP specification defines four interfaces:
Markup (required)
Registration (optional)
Note: The ATG WSRP implementation does not implement the Portlet Management interface; third-party
consumers that expect it (specifically Cloning operations) may not function properly.
A simple example of how these interfaces are used is:
1.
2.
The producer response indicates that registration is required, and what information is
requested.
3.
4.
Now that the consumer has registered, the Service Description includes a list of
offered portlets.
5.
The consumer uses the methods of the Markup interface to request content from the
producer and provide end-user interactivity.
90
10 - Web Services for Remote Portlets
The WSRP specification also defines the data model. The subset of this model that does not change
frequently per request or per session is persisted in the GSA repository. The persistent WSRP information
in ATG producer includes:
A single producer repository exists for persisting producer-specific information, structured so that it has
almost a one-to-one mapping with the structure of the WSRP data-types. Other items are handled by
WSRP services located at /atg/wsrp in Nucleus.
Service Description
The service description provides information about the producer to a consumer that requests it. The
information can include:
Portlets offered
Each portlet offered by the producer is associated with a detailed PortletDescription containing the
portlets meta-data and capability information.
The ATG producer is shipped with a service description that includes information for the out-of-the-box
capabilities and meta-data supported in the ATG producer environment; however it does not include any
portlet descriptions. Customers add portlets by importing them using the WSRP administration UI (see
Importing Portlet Descriptions later in this chapter).
Note: The provided service description can be customized through the repository either directly or using
the ACC; however this is not recommended. Customized information may be inconsistent with the
underlying ATG functionality and features. In particular, do not modify the following parts of the service
description:
RegistrationPropertyDescription
CustomModeDescription
CustomWindowStateDescription
The following table shows the Contact properties required for registration, which are included in the
defaults shipped with the service description:
Property Name
Type
Label
Label
XmlLang
91
10 - Web Services for Remote Portlets
contact.prefix
xsd:string
Name Prefix
en_US
contact.givenName
xsd:string
Given Name
en_US
contact.familyName
xsd:string
Family Name
en_US
contact.middleName
xsd:string
Middle Name
en_US
contact.suffix
xsd:string
Name Suffix
en_US
contact.company
xsd:string
Company Name
en_US
contact.title
xsd:string
Title
en_US
contact.postal.name
xsd:string
Address
en_US
contact.postal.street
xsd:string
Street
en_US
contact.postal.city
xsd:string
City
en_US
contact.postal.stateprov
xsd:string
State/Province
en_US
contact.postal.postalcode
xsd:string
Postal Code
en_US
contact.postal.country
xsd:string
Country
en_US
contact.postal.organization
xsd:string
Organization Name
(Postal)
en_US
contact.online.email
xsd:string
en_US
contact.online.uri
xsd:string
URL
en_US
contact.telecom.telephone.intcode
xsd:string
Telephone
(International Code)
en_US
contact.telecom.telephone.loccode
xsd:string
Telephone (Local
Code)
en_US
contact.telecom.telephone.number
xsd:string
Telephone (Number)
en_US
contact.telecom.telephone.ext
xsd:string
Telephone
(Extension)
en_US
contact.telecom.telephone.comment
xsd:string
Telephone
(Comments)
en_US
contact.telecom.fax.intcode
xsd:string
Fax (International
Code)
en_US
contact.telecom.fax.loccode
xsd:string
en_US
contact.telecom.fax.number
xsd:string
Fax (Number)
en_US
contact.telecom.fax.ext
xsd:string
Fax (Extension)
en_US
contact.telecom.fax.comment
xsd:string
Fax (Comments)
en_US
92
10 - Web Services for Remote Portlets
contact.telecom.mobile.intcode
xsd:string
Mobile (International
Code)
en_US
contact.telecom.mobile.loccode
xsd:string
en_US
contact.telecom.mobile.number
xsd:string
Mobile (Number)
en_US
contact.telecom.mobile.ext
xsd:string
Mobile (Extension)
en_US
contact.telecom.mobile.comment
xsd:string
Mobile (Comments)
en_US
contact.telecom.pager.intcode
xsd:string
Pager (International
Code)
en_US
contact.telecom.pager.loccode
xsd:string
en_US
contact.telecom.pager.number
xsd:string
Pager (Number)
en_US
contact.telecom.pager.ext
xsd:string
Pager (Extension)
en_US
contact.telecom.pager.comment
xsd:string
Pager (Comments)
en_US
The service description also includes the OfferedPortlets property, a set of portlet descriptions
describing the metadata and capabilities for each Portlet offered by the producer.
Do not modify the PortletDescription directly in the repository; use the WSRP administration tool for
modifications.
Registration
The optional Registration interface is a way for consumers to provide information to the producer, which
uses it to establish a unique identity for and relationship with the consumer. Users can:
Specify the lifespan of a consumer registration (apart from the deregister operation);
invalidates the consumer registration after a specified time-lapse, either from the
point when registration was done or last modified, or from the last consumer activity.
Consumers must provide contact details as registration properties (see the Service Description section).
Registration requests that fail to provide this information are rejected. Using the information, a
Consumer-Contact instance is created in the ATG environment. The contact information is associated
with a registered consumer and has dynamic properties analogous to the User-Profile properties of
the ATG personalization module. The producer is packaged with a default set of Contact
RegistrationProperties customers can modify, similar to customizing the ATG User-Profile.
93
10 - Web Services for Remote Portlets
Markup
The required Markup interface includes two methods for obtaining markup fragments and performing
actions on remote portlets: getMarkup and performBlockingInteraction. See the WSRP specification
for details on these methods.
One producer task is to smoothly interact with the JSR168 container and perform render and action
requests on the target JSR168 portlet. However, there are fundamental differences between the way a
JSR168 container is invoked from a conventional portal application and the way it is invoked from the
producer environment:
Once added to the ATG-Portal, a conventional portlet behaves in conjunction with the
portal, community, or page to which it was added, particularly for URL generation. In
contrast, a WSRP request does not provide or require the Portal Context information
for the producer.
To handle these potential issues, the ATG producer uses a simulated J2EE FilterChain, which is based
on the Nucleus service. The FilterChain and Filter components can be found in the Producer Module
at /atg/wsrp/producer/filter.
The Producer executes the following scenario:
1.
2.
3.
4.
5.
Synthesize the Web service method response using the state present in the
request/response wrapper.
The producer is shipped with preconfigured filters in the WSRP servlet filter chain. Customers can add
new Filters for specific functionality such as UserContext handling. Do not remove any filters. The
FilterChain must always include the first (head) and last (tail) filters. The head filter initializes the
request/response with WSRP specific information, and the tail filter delegates the request to JSR168
Container as a Render request. An ActionFilter must also be present, to identify Action requests and
appropriately invoke the JSR168 Container.
Consumer Overview
A WSRP consumer is an intermediary system that communicates with producers and the portlets they
offer on behalf of its client (typically a portal). It gathers markup delivered by the remote portlets to be
used by the portal and manages the remote portlet providers. The portal then mediates the markup and
interaction between end-users and the producer. The consumer provides comprehensive client-side
support for the four WSRP interfaces (Service Description, Registration, Markup, and Manage Portlets).
94
10 - Web Services for Remote Portlets
Once a standard JSR168 portlet is deployed in ATG, it behaves like any other ATG portal gear. A gear
manifest is generated which can be used for adding the portlet to the ATG Portal framework.
The ATG consumer is shipped as separate module responsible for communicating with a producer based
on the standard WSRP interfaces. It also is responsible for managing the producer and its offered portlets
using ATG repositories. All WSRP functionality is encapsulated within the WSRP-ProxyPortlet.
WSRP-ProxyPortlet
WSRP-ProxyPortlet acts as a proxy for the remotely running portlet. In the ATG portal framework, it
behaves like any other ATG gear. It is provided in deployed form in the WSRP.consumer module, and can
be added to the Portal Framework. Like any other portlet, the WSRP-ProxyPortlet can have multiple
instances, and each instance can be configured to interact with a specific remote producer offered
portlet.
WSRP-related configuration and management functionality is provided through the following two
custom portlet modes of WSRP-ProxyPortlet:
Modes that are primarily handled by the proxy portlet itself. These modes are required
for proxy portlet administration, and their handling is confined to the scope of the ATG
proxy portlet. The modes are:
Edit_defaults
CONFIG
Modes whose handling is delegated to a remote WSRP portlet by the proxy portlet,
and which are handled by the ATG consumer. These modes may not be present in the
supported modes definition of the proxy portlet; instead their support is determined
by the proxy portlet itself. The following remote portlet modes are supported by ATG
proxy portlet:
95
10 - Web Services for Remote Portlets
VIEW
EDIT
HELP
When a JSR168 portlet is deployed to the ATG portal framework, the existing portlet modes for that
portlet are mapped to the corresponding gear mode implementation in ATG, and further mapped to
WSRP Portlet modes. The following table shows the mapping:
VIEW
CONTENT
wsrp: view
EDIT
USERCONFIG
wsrp: edit
Edit_defaults
INSTANCECONFIG
Not Applicable
CONFIG
INSTALLCONFIG
Not Applicable
HELP
HELP
wsrp: help
ABOUT
ABOUT
Not Supported
PREVIEW
PREVIEW
wsrp: preview
The portlet modes supported by the consumer can be passed in the RegistrationData; the portal
administrator can select the view, edit, help, or preview portlet modes during registration.
The Normal and Minimized window states correspond to Shared display mode.
The Maximized and Solo window states correspond to Full display mode.
96
10 - Web Services for Remote Portlets
UserCategories. An optional array of strings, each of which specifies a producerdefined user category in which the consumer places the end-user relative to the
current operation, to be used for personalization. The ATG consumer does not support
UserCategories, and they are ignored if offered by a producer.
UserProfile: An optional WSRP structure used to carry information about the enduser. Note that this structure does not carry any user credentials, such as ID or
password. The portlet uses the userProfileItems in its metadata to describe the
fields it uses to generate markup from this set and any others the consumer indicated
were available when it registered. The ATG consumer provides a mapping between
the WSRP UserProfile and ATG personalizations UserProfile attributes. To
modify the default mapping, change the userProfileMap property in the
/atg/wsrp/consumer/Configuration Nucleus component. The default mapping is
described in the table below.
Profile Name
Field Name
name/prefix
prefix
ContactInformation.prefix
name/given
given
User.firstName
name/family
family
User.lastName
name/middle
middle
User.middleName
name/suffix
suffix
ContactInformation.suffix
name/nickname
nickname
"Empty"
bdate
bdate
User.dateOfBirth
Gender
gender
User.gender
employerInfo/employer
employer
"Empty"
departmen
"Empty"
employerInfo/department
t
employerInfo/jobtitle
jobtitle
homeInfo/postal/name
name
ContactInformation.title
ContactInformation.address
1
homeInfo/postal/street
street
ContactInformation.address
2
homeInfo/postal/city
City
ContactInformation.city
homeInfo/postal/stateprov
stateprov
ContactInformation.state
homeInfo/postal/postalcode
homeInfo/postal/country
postalcod
ContactInformation.postalC
ode
country
ContactInformation.country
97
10 - Web Services for Remote Portlets
homeInfo/postal/organization
organizat
ion
ContactInformation.company
Name
homeInfo/telecom/telephone/intcod
e
intcode
ContactInformation.phoneNu
mber
homeInfo/telecom/telephone/loccod
loccode
e
homeInfo/telecom/telephone/number
number
homeInfo/telecom/telephone/ext
Ext
"Empty"
homeInfo/telecom/telephone/commen
t
comment
"Empty"
homeInfo/telecom/fax/intcode
intcode
ContactInformation.faxNumb
homeInfo/telecom/fax/loccode
loccode
homeInfo/telecom/fax/number
number
homeInfo/telecom/fax/ext
Ext
"Empty"
homeInfo/telecom/fax/comment
comment
"Empty"
homeInfo/telecom/mobile/intcode
intcode
"Empty"
homeInfo/telecom/mobile/loccode
loccode
"Empty"
homeInfo/telecom/mobile/number
number
"Empty"
homeInfo/telecom/mobile/ext
Ext
"Empty"
homeInfo/telecom/mobile/comment
comment
"Empty"
homeInfo/telecom/pager/intcode
intcode
"Empty"
homeInfo/telecom/pager/loccode
loccode
"Empty"
homeInfo/telecom/pager/number
number
"Empty"
homeInfo/telecom/pager/ext
Ext
"Empty"
homeInfo/telecom/pager/comment
comment
"Empty"
homeInfo/online/email
User.email
homeInfo/online/uri
Uri
"Empty"
businessInfo/postal/name
name
"Empty"
businessInfo/postal/street
street
"Empty"
businessInfo/postal/city
City
"Empty"
businessInfo/postal/stateprov
stateprov
"Empty"
er
98
10 - Web Services for Remote Portlets
businessInfo/postal/postalcode
postalcod
e
"Empty"
businessInfo/postal/country
country
"Empty"
organizat
"Empty"
businessInfo/postal/organization
ion
businessInfo/telecom/telephone/in
tcode
intcode
"Empty"
businessInfo/telecom/telephone/lo
loccode
"Empty"
businessInfo/telecom/telephone/nu
mber
number
"Empty"
businessInfo/telecom/telephone/ex
Ext
"Empty"
businessInfo/telecom/telephone/co
mment
comment
"Empty"
businessInfo/telecom/fax/intcode
intcode
"Empty"
businessInfo/telecom/fax/loccode
loccode
"Empty"
businessInfo/telecom/fax/number
number
"Empty"
businessInfo/telecom/fax/ext
Ext
"Empty"
businessInfo/telecom/fax/comment
comment
"Empty"
businessInfo/telecom/mobile/intco
de
intcode
"Empty"
businessInfo/telecom/mobile/locco
loccode
"Empty"
businessInfo/telecom/mobile/numbe
r
number
"Empty"
businessInfo/telecom/mobile/ext
Ext
"Empty"
businessInfo/telecom/mobile/comme
nt
comment
"Empty"
businessInfo/telecom/pager/intcod
intcode
"Empty"
businessInfo/telecom/pager/loccod
e
loccode
"Empty"
businessInfo/telecom/pager/number
number
"Empty"
businessInfo/telecom/pager/ext
Ext
"Empty"
ccode
de
99
10 - Web Services for Remote Portlets
businessInfo/telecom/pager/commen
t
comment
"Empty"
businessInfo/online/email
"Empty"
businessInfo/online/uri
Uri
"Empty"
Producer Administration
This section describes how to manage the WSRP.admin producer module. It includes the following
sections:
Starting Up the Producer
Producer Database Configuration
Using the Producer Administration UI
Importing Portlet Descriptions
100
10 - Web Services for Remote Portlets
Refer to the ATG Installation and Configuration Guide for default port information.
The user must log in with a username and password that has portal administrator role privileges
(admin/admin can be used).
Features provided by the Producer Administration module include:
2.
3.
Note: Only gear Instances corresponding to JSR168 portlets present in an ATG Community are available
for importing (the Portlet.helloworld and Portlet.slot sample portlets shipped with ATG are
strictly JSR168 compliant). Do not import the WSRP-ProxyPortlet required by the Consumer module.
101
10 - Web Services for Remote Portlets
Consumer Administration
This section provides information on administering the consumer module. It includes the following
sections:
Starting Up the Consumer Module
Consumer Database Configuration
Using the Consumer Administration UI
Adding a New Producer to a Consumer
Modifying Producer Information
Deleting a Producer
Configuring a ProxyPortlet Instance
Go to Portal Admin > Gears > New Gear and upload the
<ATGdir>/WSRP/consumer/proxyPortlet/WSRP4ATGProxyPortletmanifest.xml gear manifest file.
2.
Go to Portal Admin > Gear and click the Configure link corresponding to
WSRP4ATGProxyPortlet to configure the ProxyPortlet using the installConfig
mode.
3.
102
10 - Web Services for Remote Portlets
Modifying any of the existing producers with which the consumer is registered
(changing the end point URL of any of the WSRP interface, changing Name,
Description etc.).
To add a new producer and portlets offered by it to the Consumer environment follow the wizard
included in installConfig.
1.
103
10 - Web Services for Remote Portlets
2.
Specify the remote Producer properties such as Producer-URL. If necessary provide the
URLs for each type of WSRP interface (Service Description, Registration, Markup and
Portlet Management).
3.
If the producer requires registration, the user is provided with the option of modifying
the ATG consumers default Registration details, such as:
Consumer-Name
104
10 - Web Services for Remote Portlets
Consumer-Agent
is-method-GET-supported
Consumer modes
Window-states
User-Scopes
Additional properties.
4.
Select the portlets to be added to the consumer environment from the list of portlets
offered by this producer.
105
10 - Web Services for Remote Portlets
Description
Interface-URLs
Registration Properties
Offered-Portlets
To modify the producer, use the wizard-based installConfig interface as described in Adding a New
Producer to a Consumer. In the first step, select the Modify option for an existing producer from the list
provided, then proceed through the wizard.
Deleting a Producer
To delete a producer and all of its offered portlets from the consumer, use the wizard-based
installConfig interface as described in Adding a New Producer to a Consumer. In the list of existing
producers, select the Delete option corresponding to the producer name.
106
10 - Web Services for Remote Portlets
107
10 - Web Services for Remote Portlets
108
10 - Web Services for Remote Portlets
The PAF provides a service to send alert notifications based on gear events. For example, you might want
to have an e-mail sent automatically to all members of a community when a new event is scheduled in
the communitys Calendar Gear. The alert notifications can be displayed by the baseline Alerts gear or
sent by e-mail. You can also create your own channels to transmit alerts. In all cases, the scenarios
configured for each alert type determine who receives the alert notification.
The baseline gears have already been developed to provide some default alert behavior. If you want a
gear you develop to send alerts, you need to design your gear so that it publishes Java Message Service
(JMS) messages and then create a scenario that performs an action when it receives those messages. The
following sections of this chapter explain how to enable this functionality:
Alerts Overview
Alert Services Provided by the PAF and Baseline Gears
Adding Custom Alert Messages to Gears
Adding Alert Channels
Source Handlers and Target Handlers
Administrative Alerts and Framework Alerts
Alerts Overview
Gear alerts are notifications that originate from a gear event, are filtered and targeted by ATG Scenario
Personalization, and are presented to their target audience.
The gear developer must determine the events within the gear that are significant enough to capture and
translate into alerts. When those events take place, the events types and properties are translated into a
Java message bean. The message bean is then published via the Java Message Service (JMS) and is
consumable by any JMS client configured as a listener to that event.
The gear developer must configure the Scenario module to listen to and process the messages that the
gear publishes. The Scenario module is responsible for receiving the gear messages, performing any
filtering that is desired, and determining who should receive the alert notification. The logic for all of this
is based on the criteria defined in the scenario segment. Since the scenario segments can perform
complex filtering and targeting based on the properties of the gears message bean, this process is
dynamic.
109
11 - Adding Gear Alerts
Once the Scenario module has finished its part, it sends the gear message bean and targeting information
along to the AlertMgr. The AlertMgr is a global Nucleus component that is responsible for persisting
the alert, formatting the alert in a locale-sensitive manner, and sending the alert to the appropriate
targets.
The AlertMgr persists alerts to the AlertRepository. The AlertRepository is a persistent store and is
accessed by the Alerts gear to retrieve alerts that will be displayed by a Web browser.
Each gear event that needs to be translated into an alert must register the event type and a
ResourceBundle with the AlertMgr. The ResourceBundle contains the events unformatted alert text
and defines the properties of the gear message bean that will be used to format the alert text into a
displayable String. Each ResourceBundle must be translated to the locales that need to be supported.
The Alerts Gear is responsible for displaying the appropriate alerts on a page within a Web browser. When
a request to display alerts is received by the Alerts Gear, the appropriate alerts are retrieved from the
AlertRepository and then formatted by the AlertMgr. The AlertMgr provides an API for formatting
the alert based on the requests locale and the gear message bean properties that have been persisted
with the alert.
The AlertMgr may also send e-mail alert notifications if desired. The AlertMgr leverages the DPS
Targeted Email system to provide this functionality. Each gear event must specify in its ResourceBundle
the name of the e-mail template that is to be used to create the targeted e-mail.
In addition to gear alerts, ATG Portal generates administrative alerts and framework alerts, which work in
basically the same way as gear alerts, but which are generated by the Portal Administration or the PAF.
See Administrative Alerts and Framework Alerts.
A pre-configured gear topic destination to which all gears messages are published.
The destination is JMS-compliant and can be looked up by gears via the Java Naming
& Directory Interface (JNDI).
110
11 - Adding Gear Alerts
Calendar Gear
Event Created
Event Deleted
Event Edited
Event Viewed
Communities Gear
Discussion Gear
Document Created
Document Deleted
Document Updated
Document Viewed
Poll Gear
Poll Response
URL Changed
Discussion Alerts
111
11 - Adding Gear Alerts
PAF Events
The following pre-defined alerts are provided for PAF events:
Profile Updated
Member Subscribe
Member Unsubscribe
Membership Approved
Membership Declined
Determine which alerts you want your gear to send. You need to decide which events
trigger an alert and what the alert message should contain.
For example, if you are creating a document exchange gear, you might want to send
alerts when documents are created, updated, or deleted, and each alert might contain
the community, the document ID, the profile of the user, and the page.
112
11 - Adding Gear Alerts
2.
3.
In the case of a document exchange gear, for example, you might extend
GearMessage by creating the DocExchMessage class to contain all the properties
needed by all document exchange messages, such as the authors name and the
document name. You would then create classes that extend DocExchMessage with
properties and values that are specific to each message type (for example,
DocumentCreatedMessage, DocumentUpdatedMessage,
DocumentDeletedMessage). Each message class must have a unique message type
string defined. Add code to make the GearMessagePublisher global service
component available. (See Adding GearMessagePublisher to the Gear below.)
GearMessagePublisher is a Nucleus service that makes it easier to publish
messages, by handling the initialization of JMS messages, the message destination
lookup, and the message publishing.
GearMessagePublisher exposes a method called writeMessage(), which can take
5.
Model the contents of the file after the code shown in Sample
dynamoMessagingSystem.xml File below. For more information about configuring
and using the Dynamo Message System, see the Dynamo Message System chapter in
the ATG Programming Guide.
6.
Create an alerts element in the gear manifest file inside the gear-definition tag.
(See Adding the Alerts Element to the Gear Manifest File below.)
Once you re-upload the gears manifest file, this makes the gears alerts available for
configuration through the Portal Administration.
7.
For each message format and language locale, create a resource bundle properties file
with the name referenced in the AlertMgr component. (See Creating a Resource
Bundle Properties File below.)
8.
If you want your alerts to send e-mail, create the e-mail template file used in sending
e-mail alerts about this event. (See Creating an E-mail Template File below.)
9.
Provide a form as part of the gears Instance Configuration mode that allows a
Community Leader to enable or disable alerts for the gear. (See Creating an Alert
Instance Configuration Form below.)
113
11 - Adding Gear Alerts
10. Extend the Scenario user interface to handle your new message types as it does other
alert messages. (See Extending the Scenario User Interface below.)
11. Using the Scenario module, configure a scenario that will perform the desired
response upon receiving a gear alert. (See Configuring a Scenario below.)
package atg.portal.gear.docexch;
import atg.portal.framework.*;
import atg.portal.alert.*;
public class DocExchMessage extends GearMessage
{
//------------------------------------------// Member variables specific to DocExch Messages
//------------------------------------------/** Document Id **/
private String mDocumentId;
/** Document Name **/
private String mDocumentName;
//------------------------------------// Constructors
//------------------------------------public DocExchMessage()
{
}
public DocExchMessage(GearEnvironment pGearEnv, String pMessageType)
{
super(pGearEnv, pMessageType);
}
114
11 - Adding Gear Alerts
package atg.portal.gear.docexch;
import atg.portal.framework.*;
public class DocumentCreatedMessage extends DocExchMessage
{
//------------------------------------// Member variables
//-------------------------------------
115
11 - Adding Gear Alerts
"atg.portal.gear.docexch.DocumentCreatedMessage";
//------------------------------------// Constructors
//------------------------------------public DocumentCreatedMessage(GearEnvironment pGearEnv)
{
super(pGearEnv, MESSAGE_TYPE);
}
}
In the above example, the getPublisherName method (a method you must provide) returns the
property equal to "dynamo:/atg/portal/alert/GearMessagePublisher" (the "dynamo:" protocol
signifies that the component is a Nucleus component.)
Note that if you are using a Nucleus component as a form handler, you can also make the gear publisher
available as a property, and use the components .properties file to set that property to link to
/atg/portal/alert/GearMessagePublisher.
Also note that repeatedly making a JNDI lookup using InitialContext() can impede performance.
Consequently, you may want to create the InitialContext once and then always reference that
instance. It would also make sense to cache the result of the lookup. PAF provides a utility class,
atg.portal.nucleus.NucleusComponents, which does this. The following is an example of how the
NucleusComponents class can be used:
mPublisher = (GearMessagePublisher)
NucleusComponents.lookup(getPublisherName());
116
11 - Adding Gear Alerts
The following is an example of the sending code, mentioned in Step 4 of Adding Custom Alert Messages
to Gears above.
117
11 - Adding Gear Alerts
</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.
...
<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>
118
11 - Adding Gear Alerts
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
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.
#
# 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
11 - Adding Gear Alerts
120
11 - Adding Gear Alerts
<core:ExclusiveIf>
<core:If value="<%= alertConfResult.getSuccess() %>" >
<!-- REDIRECT TO SUCCESS PAGE -->
</core:If>
<%-- if not, display errors --%>
<core:DefaultCase>
<%=alertConfResult.getErrorMessage()%>
</core:DefaultCase>
</core:ExclusiveIf>
</paf:handleAlertConfig>
</core:If>
expression-grammar.xml
GrammarExtension.java
121
11 - Adding Gear Alerts
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.
-->
-->
122
11 - Adding Gear Alerts
<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.
package atg.portal.gear.docexch;
import atg.ui.scenario.*;
import atg.ui.scenario.expression.*;
import atg.xcl.*;
/** Scenario UI grammar extension for a custom action / grammar extension example.
*/
public class DocexchGrammarExtension extends DefaultGrammarExtension {
//---------------------------------------// Constructors
//---------------------------------------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
11 - Adding Gear Alerts
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.
AlertHandlerInterface
124
11 - Adding Gear Alerts
Property Name
Description
Example Value
channelDisplayName
EmailAlertChannel
channelDescription
/atg/dynamo/transaction/
/atg/portal/alert/
AlertRepositoryManager that
AlertRepositoryManager
transactionManager
alertRepositoryManager
TransactionManager
/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
11 - Adding Gear Alerts
AlertHandlerInterface
The AlertHandlerInterface defines an interface that the new alert channel calls to carry out the
delivery of alert notifications. This interface contains a single method, shown below, that must be
implemented. Once written and compiled, the class file must be placed somewhere in the CLASSPATH
public void alertHandlerAction(AlertTargetMessage pMsg,
List pUsers,AlertMgr.MessageMapProps pMsgProps);
The 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;
}
...
...
// 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
11 - Adding Gear Alerts
}
...
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.
Once the alert channel is registered, the AlertMgr takes into account the new channel when determining
the channels that should handle alerts.
127
11 - Adding Gear Alerts
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.
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
getConstraints
getUserList
128
11 - Adding Gear Alerts
Message Name
Message Type
Resource Bundle
CommunityGearAddedMessage
atg.portal.messaging.
CommunityGearAddedMessage
atg.portal.messaging.
CommunityGearAddedResources
CommunityGearRemovedMessage
atg.portal.messaging.
CommunityGearRemovedMessage
atg.portal.messaging.
CommunityGearRemovedResources
PageGearAddedMessage
atg.portal.messaging.
PageGearAddedMessage
atg.portal.messaging.
PageGearAddedMessageResources
PageGearRemovedMessage
atg.portal.messaging.
PageGearRemovedMessage
atg.portal.messaging.
PageGearRemovedMessageResources
In addition, the following framework alert classes are included in ATG Portal 6, but are not pre-defined as
alerts. See Configuring Alerts in the Portal Administration chapter of the ATG Portal Administration Guide for
information about creating new alerts.
Message Name
Message Type
Resource Bundle
MemSubscribeMessage
atg.portal.messaging.
MemSubscribeMessage
atg.portal.messaging.
MemSubscribeResources
129
11 - Adding Gear Alerts
MemUnsubscribeMessage
atg.portal.messaging.
MemUnsubscribeMessage
atg.portal.messaging.
MemUnsubscribeResources
MembershipAcceptedMessage
atg.portal.messaging.
MembershipAcceptedMessage
atg.portal.messaging.
MembershipAcceptedResources
MembershipDeclinedMessage
atg.portal.messaging.
MembershipDeclinedMessage
atg.portal.messaging.
MembershipDeclinedResources
130
11 - Adding Gear Alerts
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.
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.
2.
3.
131
12 - Creating a Custom Portal
4.
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.
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>
config/atg/portal/framework/Portal.properties
This file should only contain the following. It overrides the default context path of your portal, setting the
context path to /myportal. This will be the context path all requests for your portal will contain. So to
access a community named theatre in your portal, a user would request:
http://hostname:port/myportal/theatre
where hostname is the name of the machine that runs your application server, port is the port number
that application server uses to listen for HTTP requests, and myportal is your portal name. For default
port information, see the ATG Installation and Configuration Guide.
132
12 - Creating a Custom Portal
myportal/META-INF/application.xml
Use the following for this file. Once again you need to redefine the context root to /myportal:
myportal/portal/WEB-INF/web.xml
In this file, you need to replace all references to the context path /portal with /myportal. Change
/portal to /myportal in the following locations:
<context-param>
<param-name>context-root</param-name>
<param-value>/myportal</param-value>
</context-param>
<init-param>
<param-name>defaultLoginTemplateContextURI</param-name>
<param-value>/myportal</param-value>
</init-param>
133
12 - Creating a Custom Portal
<init-param>
<param-name>defaultAccessDeniedTemplateContextURI</param-name>
<param-value>/myportal</param-value>
</init-param>
<init-param>
<param-name>defaultOfflineTemplateContextURI</param-name>
<param-value>/myportal</param-value>
</init-param>
You should also update the display name and description. For example:
2.
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
134
12 - Creating a Custom Portal
http://hostname:port/portal/admin
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.
Color palettes
Stylesheets
Page Templates
Layout 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
12 - Creating a Custom Portal
/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.
Stylesheet Manifests
For simplicity, the file header has been omitted from the examples in the following sections, but it should
be included in each real manifest file.
136
12 - Creating a Custom Portal
Background color
Text color
A URL for an icon that represents the palette as an option on the color selection pages
of the Community Administration.
The following sample shows an abbreviated manifest for a single color palette:
137
12 - Creating a Custom Portal
</colors>
</entity>
</color-palette>
<!-- ADDITIONAL COLOR PALETTES GO HERE --!>
</color-palettes>
For details about the tags and attributes you can use in a Color Palette manifest file, see Color Palette
Manifest Elements in Appendix A: Portal Manifest Reference.
Stylesheet Manifests
A Stylesheet manifest file enables you to specify a location for cascading stylesheets by providing a servlet
context and a URL to a cascading stylesheet.
You can use stylesheets to render branding headers on pages that may be shared between communities.
For example, an access denied page could invoke a stylesheet in its head element with the following tag:
<link rel="stylesheet" type="text/css" href="<%= cssURL %>"
src="<%= cssURL %>"/>
138
12 - Creating a Custom Portal
For details about the tags and attributes you can use in a Stylesheet manifest file, see Stylesheet Manifest
Elements in Appendix A: Portal Manifest Reference.
139
12 - Creating a Custom Portal
For details about the tags and attributes you can use in a Page Template manifest file, see Page Template
Manifest Elements in Appendix A: Portal Manifest Reference.
Display Modes
Output Devices
A Layout Template uses a single-row HTML table structure to render gear region fragments, which are
containers for gears. Each region is the content of a cell within the table.
The following example shows an abbreviated Layout Template manifest:
140
12 - Creating a Custom Portal
<region name="25_75_RIGHT">
<dimensions>
<dimension name="width">wide</dimensions>
<dimension name="height">tall</dimensions>
</dimensions>
</region>
</regions>
</layout-template>
</layout-templates>
For details about the tags and attributes you can use in a Layout Template manifest file, see Layout
Template Manifest Elements in Appendix A: Portal Manifest Reference.
141
12 - Creating a Custom Portal
</gear-title-template-modes>
</gear-title-template>
</gear-title-templates>
</portal-manifest>
For details about the tags and attributes you can use in a Gear Title Template manifest file, see Gear Title
Template Manifest Elements in Appendix A: Portal Manifest Reference.
Authentication Pages
The default authentication page files reside in the following location:
<ATG10dir>/Portal/paf/starter-portal/paf-dar/portal
The HTML and WML versions of the following default files are provided in the userprofiling and
access directories:
login.jsp
logout.jsp
accessDenied.jsp
offline.jsp
142
12 - Creating a Custom Portal
defaultLoginTemplateContextURI
/portal
defaultLoginTemplatePathURI
/userprofiling/login.jsp
defaultAccessDeniedTemplateContextURI
/portal
defaultAccessDeniedTemplatePathURI
/access/accessDenied.jsp
143
12 - Creating a Custom Portal
144
12 - Creating a Custom Portal
This appendix explains the elements of the XML manifests used to register gears and customize a portal. It
also contains a copy of the DTD containing all of the XML manifest formats. It includes the following
sections:
Portal Manifest Elements
Gear Manifest Elements
Page Template Manifest Elements
Layout Template Manifest Elements
Gear Title Template Manifest Elements
Color Palette Manifest Elements
Stylesheet Manifest Elements
The Portal Manifest DTD
<portal-manifest> ElementAttributes
name
required
version
optional
author
optional
145
Appendix A: Portal Manifest Reference
<gear-definition> Element
Attributes
name
required
version
optional
author
optional
Sub-elements
description
servlet-context
images
dimensions
gear-modes
error-handling
instance-parameters
user-parameters
alerts
<servlet-context> Element
The gears URI (considered independently of the portal). The servlet context must match the value of
<context-root> in the gears Enterprise Application Deployment Descriptor file (application.xml).
146
Appendix A: Portal Manifest Reference
Example
<servlet-context>
/gear/mygear
</servlet-context>
<gear-modes> Element
A container for one or more <gear-mode> elements.
<gear-mode> Element
Specifies a gear mode and encloses that modes display modes and device outputs.
Attributes
Possible Values
name (required)
content
userConfig
installConfig
instanceConfig
initialConfig
help
about
preview
Sub-elements
display-modes
147
Appendix A: Portal Manifest Reference
<display-modes> Element
A container for one or more <display-mode> elements.
<display-mode> Element
Specifies a display mode and encloses that modes device outputs.
Attributes
name
Sub-elements
device-output
<dimensions> Element
Container for one or more <dimension> elements.
<dimension> Element
Specifies the default size preference for the gear and region. A <dimension> element has no attributes.
Sub-elements
name
Required?
Possible Values
height
Required
148
Appendix A: Portal Manifest Reference
width
Required
Dimensions Example
<dimensions>
<dimension name="height">
tall
</dimension>
<dimension name="width">
narrow
</dimension>
</dimensions>
<error-handling> Element
Enables or disables intercept-errors and cover-errors-with-cache functionality. When enabled,
intercept-errors buffers gear output so that exceptions can be handled before any gear content is
displayed. If cover-errors-with-cache is enabled and an error or timeout occurs while a gear is
rendering, cached content will be displayed instead of the error.
Sub-elements
Element
Value Attribute
intercept-errors
true or false
cover-errors-with-cache
true or false
<instance-parameters> Element
Defines and specifies instance parameters for the gear.
149
Appendix A: Portal Manifest Reference
Sub-elements
The <instance-parameters> element must include at least one <parameter> sub-element. The
<parameter> sub-element must define name and required attributes. The <default-value> subelement is an optional sub-element of <parameter>.
<user-parameters> Element
Defines and specifies user parameters for the gear.
Sub-elements
The <user-parameters> element must include at least one <parameter> sub-element. The
<parameter> sub-element must define name and required attributes. One or more <default-value>
sub-elements is an optional sub-element of <parameter>.
<alerts> Element
A container for one or more <alert-message> elements.
150
Appendix A: Portal Manifest Reference
<alert-message> Element
Each <alert-message> element describes a type of alert that can be sent by the gear.
Attribute
name
Subelements
message-type
default-value
resource-bundle
151
Appendix A: Portal Manifest Reference
<page-templates> Element
<page-template> Element
Each <page-template> element specifies a page template that can be used in the portal.
Attributes
name
required
version
optional
author
optional
Subelements
Element
Description/Example
<description>
<servlet-context>
<images>
<display-modes>
152
Appendix A: Portal Manifest Reference
<url>/images/page_template.gif</url>
</image>
</images>
<display-modes>
<display-mode name="shared">
<device-output name="html">
/html/shared_page_template.jsp
</device-output>
<device-output name="wml">
/wml/shared_deck_template.jsp
</device-output>
</display-mode>
...
</display-modes>
</page-template>
</page-templates>
<layout-templates> Element
A container for one or more <layout-template> elements.
<layout-template> Element
Each <layout-template> element specifies a layout template that can be used in the portal.
Attributes
name
required
version
optional
author
optional
Subelements
Element
Description/Example
description
153
Appendix A: Portal Manifest Reference
<region>
<regions>
<region name="25_75_LEFT">
<dimensions>
<dimension name="width">
narrow
</dimension>
<dimension name="height">
tall
</dimension>
...
</dimensions>
</region>
...
</regions>
<servlet-context>
<display-modes>
<images>
154
Appendix A: Portal Manifest Reference
</device-output>
</display-mode>
</display-modes>
<regions>
<region name="25_75_LEFT">
<dimensions>
<dimension name="width">
narrow
</dimension>
<dimension name="height">
tall
</dimension>
...
</dimensions>
</region>
...
</regions>
</layout-template>
...
</layout-templates>
<gear-title-templates> Element
A container for one or more <gear-title-template> elements.
<gear-title-template> Element
Specifies a gear title template.
Attributes
name
required
version
optional
author
optional
Subelements
155
Appendix A: Portal Manifest Reference
Element
Description/Example
<description>
<servlet-context>
<display-modes>
<images>
156
Appendix A: Portal Manifest Reference
</gear-title-template-mode>
</gear-title-template-modes>
</gear-title-template>
</gear-title-templates>
<color-palettes> Element
The container for one or more <color-palette> elements. The <color-palettes> element has no
attributes.
<color-palette> Element
Defines a color palette.
Attributes
name
required
version
optional
author
optional
Subelements
servlet-context
description
images
entity
<images> Element
A container for one or more <image> elements.
157
Appendix A: Portal Manifest Reference
<image> Element
Defines an image for the color palette.
Attributes
type
Subelements
url
alt-text
Optional
<entity> Element
Defines the type of page element that the specified colors or images apply to.
Attributes
type
Subelements
colors
images
Optional
158
Appendix A: Portal Manifest Reference
<color> Element
Defines colors for particular page elements. It has no subelements and a single required attribute, type.
The type attribute can be one of background, text, link, action-link, or visited-link. The tag
body contains the hexadecimal definition of the color used by the page element. For example:
<color type="background">99ccff</color>
159
Appendix A: Portal Manifest Reference
</entity>
</color-palette>
<styles> Element
A container for one or more <style> elements.
<style> Element
Each style element specifies a cascading style sheet that can be used in the portal.
Attributes
name
required
version
optional
author
optional
Subelements
Element
Description/Example
<description>
<cascading-style-sheet>
<servlet-context>
160
Appendix A: Portal Manifest Reference
Style Example
<styles>
<style name="Default" version="1.0" author="">
<description>
Default Stylesheet
</description>
<servlet-context>
/portal/layoutTemplates
</servlet-context>
<cascading-style-sheet>
/css/default.css
</cascading-style-sheet>
</style>
</styles>
<!-====================================================================
portal_manifest_1.0.dtd - document type for Portal Manifests
Version: $Id$
====================================================================
-->
<!ELEMENT portal-manifest (gear-definitions? | color-palettes? | styles? |
page-templates? | layout-templates? |
gear-title-templates?)
>
<!ATTLIST portal-manifest
name
CDATA
#IMPLIED
version
CDATA
#IMPLIED
author
CDATA
#IMPLIED
>
<!ELEMENT gear-definitions (gear-definition+)>
<!ELEMENT color-palettes (color-palette+)>
<!ELEMENT styles (style+)>
<!ELEMENT page-templates (page-template+)>
<!ELEMENT layout-templates (layout-template+)>
161
Appendix A: Portal Manifest Reference
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
#REQUIRED
>
<!ELEMENT url (#PCDATA)>
<!ATTLIST url
type
#IMPLIED
>
<!ELEMENT alt-text (#PCDATA)>
<!ELEMENT dimensions (dimension+)>
<!-- Expected values for a dimension in Portal Application Framework 1.0:
Gear
Region
-->
162
Appendix A: Portal Manifest Reference
(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
#REQUIRED
163
Appendix A: Portal Manifest Reference
>
<!ELEMENT gear-roles (gear-role+)>
<!ELEMENT gear-role (#PCDATA)>
<!ELEMENT display-modes (display-mode+)>
<!ELEMENT display-mode (device-output+)>
<!ATTLIST display-mode
name
#REQUIRED
>
<!ELEMENT device-output (#PCDATA)>
<!ATTLIST device-output
name
'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
#REQUIRED
>
164
Appendix A: Portal Manifest Reference
#REQUIRED
>
<!ELEMENT style
<!ATTLIST style
name
CDATA
#REQUIRED
version
CDATA
#IMPLIED
author
CDATA
#IMPLIED
>
<!ELEMENT cascading-style-sheet (#PCDATA)>
<!ELEMENT page-template
<!ATTLIST page-template
name
CDATA
#REQUIRED
version
CDATA
#IMPLIED
author
CDATA
#IMPLIED
>
<!ELEMENT layout-template
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
Appendix A: Portal Manifest Reference
<!ATTLIST gear-title-template-mode
name
#REQUIRED
>
166
Appendix A: Portal Manifest Reference
The PAF tag library contains a core set of tags for portal application JSPs. These tags begin with the prefix
paf, for example, paf:renderTab. You can find the tag library definition file in
<ATG10dir>/Portal/taglib/pafTaglib/1.3/tld. For information on the accessor methods and
properties made available by the PAF Tag Library, refer to the interfaces in the atg.portal.framework
package in the ATG API Reference.
Earlier versions of the PAF tag library will still function in ATG Portal. However, we recommend that any
new portal pages you develop should use the latest version of the tag library.
The PAF Tag Library includes the following tags:
Tag Name
Description
paf:layout
Determines the layout to render based on the Display Mode and the current
Device.
paf:titlebar
Includes a GearTitleTemplate.
paf:hasRole
paf:hasCommunityRole
paf:hasGearRole
paf:renderTab
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
paf:include
167
Appendix B: PAF Tag Library Reference
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
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
Appendix B: PAF Tag Library Reference
Attributes
Attribute
Description
Required?
roles
true
barrier
false
denied page.
paf:hasCommunityRole
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
true
barrier
false
denied page.
Example: page/html/shared.jsp
paf:hasGearRole
Renders the body of the tag if the user has one of the gear-relative roles indicated by the 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
Appendix B: PAF Tag Library Reference
Attribute
Description
Required?
roles
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
Example: page/html/shared.jsp
paf:defaultTab
Child tag of renderTab tag. If the page object passed to the parent renderTab tag is not equal to the
currently rendering page, then the body of this tag is rendered.
Body: JSP content
Example: page/html/shared.jsp
paf:currentTab
Body: JSP content
Child tag of renderTab tag. If the page object passed to the parent renderTab tag is equal to the
currently rendering page, then the body of this tag is rendered.
170
Appendix B: PAF Tag Library Reference
Example: page/html/shared.jsp
paf:encodeURL
Encodes a portal or gear URL with session ID and portal or gear specific parameters. The id attributes
specifies the name of the URL. The optional context attributes are used to encode used a specified
context.
Body: JSP content
Attributes
Attribute
Description
Required?
page
String
true
id
String
false
var
String
false
scope
String
false
url
String
false
portalContext
String
false
gearContext
String
false
context
String
false
Example: page/html/shared.jsp
paf:context
The context tag is used to obtain a portal or gear context. The context is identified by the name specified
by the id attribute. The optional type attribute can be used to determine the type of context. The
currently supported types include PortalContext.class and GearContext.class.
Body: JSP content
Attributes
171
Appendix B: PAF Tag Library Reference
Attribute
Description
Required?
id
false
var
false
scope
false
type
false
Example: page/html/shared.jsp
paf:include
The include tag is used to dispatch a request to included content. Content is specified by the context
attribute.
Body: JSP content
Attributes
Attribute
context
Description
Required?
true
Example: layout/html/region.jspf
172
Appendix B: PAF Tag Library Reference
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
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