Pagelet and Portlet Development

IDK Proxy and Portlet APIs

Always use the IDK. Using IDK methods ensures that your pagelets work correctly in multiple implementations of Ensemble and the ALI portal.

This page provides a comparison of the IDK Proxy and Portlet APIs. For details on installing the IDK, see Setting Up the IDK. For more details on objects and methods, see the IDK API Documentation. Note: The IDK was formerly called the Plumtree Development Kit (EDK); some package names retain old naming conventions.

The bea.alui.proxy and plumtree.remote.portlet packages/namespaces include the following interfaces:

  • IProxyContext

  • IProxyRequest

  • IProxyResponse

  • IProxyUser

  • IPortletContext

  • IPortletRequest

  • IPortletResponse

  • IPortletUser

In general, these interfaces are called in the following order.

  1. The first method is slightly different depending on the interface.
    A pagelet uses ProxyContextFactory.getInstance().createProxyContext to initiate a connection for communicating with Ensemble or the portal.
    A portlet uses PortletContextFactory.createPortletContext to initiate a connection with the portal.

Pagelet:

Java

<%@ page language="java" import="com.bea.alui.pagelet.*,java.util.*"%>
<%
IPageletContext pageletContext = PageletContextFactory.getInstance.createPageletContext(request, response);
%>

.NET

ProxyContextFactory factory;

factory = ProxyContextFactory.getInstance();
proxyContext = factory.CreateProxyContext(request, response);

Portlet:

Java

<%@ page language="java" import="com.plumtree.remote.portlet.*,java.util.*"%>
<%
IPortletContext portletContext = PortletContextFactory.createPortletContext(request, response);
%>

.NET

Dim portletContext As IPortletContext
portletContext = PortletContextFactory.createPortletContext(Request, Response)

  1. The IProxyContext / IPortletContext object returned allows the pagelet to access information about the request and response, the current user, and the session. The pagelet uses this information as needed, in arbitrary order, to generate a proper response. Using IP*Context, the pagelet can access IP*Request, IP*User, IRemoteSession and IP*Response.

  2. The pagelet retrieves parameters from the request using IProxyRequest / IPortletRequest. These interfaces provide access to the following information:

Parameter

IProxyRequest Method

IPortletRequest Method

Description

Resource / Pagelet ID

GetIdentifier / GetInstanceIdentifier

GetPortletID

This value is useful for appending to the names of HTML forms and client-side JavaScript functions to ensure unique form and function names. This value is also used in Adaptive Tags and by the IDK Remote APIs.

Content Mode

IEnvironment. GetAggregationType

GetAggregationMode

The aggregation mode for the pagelet. These methods are not exactly equivalent.
IEnvironment.GetAggregationType:
o None: The pagelet code is alone on an HTML page (i.e., proxied page).
o Page: The pagelet code is displayed as part of a portal page.
o Pagelet: The pagelet code is displayed as part of a page proxied by Ensemble.
IPortletRequest.GetAggregationMode:
o Single: The portlet code is alone on an HTML page (i.e., gatewayed page).
o Multiple: The portlet code is displayed as part of a portal page.

Return URL

GetHostPageURI

GetHostPageURI / GetReturnURI

The URL to the page that hosts the pagelet. Preference pages need this URL to return the user to the correct page after settings are configured. (IPortletRequest.getReturnURI allows you to set the return URL to something other than the page that hosts the portlet.)

Image Service URL

GetImageServerURI

GetImageServerURI

The absolute URL to the root virtual directory of the Image Service in the current implementation. This base URI is used to access images on the Image Server that should not be gatewayed.

Stylesheet URL

GetStylesheetURI

GetStylesheetURI

The absolute URL to the current user's stylesheet. This URI can be used to display associated pages in the style of the current implementation. Using AquaLogic styles ensures that pagelets match their environment. You can also access the stylesheet using Adaptive Tags.

Settings

GetSetting
 

GetSettingValue
GetEncryptedSettingValue
GetSettingCollection

These methods are not exactly equivalent.
IProxyRequest.getSetting returns the value for the referenced setting. Searches all stored settings, including session preferences and attributes.
IPortletRequest.GetSettingValue returns the value for the referenced setting. Searches only the referenced setting type in the ALI database.
GetEncryptedSettingValue returns the value for the referenced encrypted setting. Searches only the referenced setting type in the ALI database.
GetSettingCollection returns an array/dictionary object of all settings of the referenced setting type (Admin, Community, CommunityPortlet, Portlet, User, and UserInfo) from the ALI database..

User

GetUser

IPortletContext.GetUser

The user making the request (IProxyUser or IPortletUser). For details on this interface, see the next section.

Payload

GetPayload

n/a

Ensemble only. The (optional) payload content available with the request (IPayload).

Environment

GetEnvironment

n/a

Ensemble only. The environment in which the pagelet is running (IEnvironment). IEnvironment.GetType returns the environment of execution for the request:
o None: The pagelet is running in a non-proxied page.
o Plumtree / Portlet: The pagelet is running in the ALI portal. (The values Plumtree and Portlet are equivalent.)
o Proxy: The pagelet is running in a proxied page.
Note: The IEnvironment interface also provides the following methods: GetAggregationType (see above), and
GetProtocolVersion (returns the CSP version).

Community ID

n/a

GetCommunityID

ALI portal only. The Community ID for the Community in which the portlet appears. (If CommunityID=0, the portlet appears on a My Page.) To check if the portlet is in a community, use IsInCommunity. (If false, the portlet is on a My Page.) For a list of all Communities that contain the portlet, use the PRC method IPortlet.QueryContainingCommunities.

Page ID

n/a

GetPageID

ALI portal only. The Page ID for the current portal page. This value allows a single Portlet object to display different content on different portal pages. The PageID is also useful for appending to the names of HTML forms and client-side JavaScript functions in a portlet. You must configure the portal to send the PageID to the portlet on the Advanced Settings page of the Web Service editor.

Experience Definition ID

n/a

GetSubportalID

ALI portal only. The ID for the Experience Definition the current user belongs to.

Alignment

n/a

GetAlignment

ALI portal only. The alignment of the portlet:
o Narrow
o Wide
o Header
o Footer
o Content Canvas

Gateway Status

n/a

IsGatewayed

ALI portal only. Checks to see if the request is gatewayed. All requests to portlets should be gatewayed; all other methods will throw NotGatewayedException if the request is not gatewayed.

Browser Type

n/a

GetUserInterface

ALI portal only. The type of device being used to access the portal:
o Accessible
o HDML
o PDA
o Standard
o WML

Time Zone

n/a

GetTimeZone

ALI portal only. A TimeZone object representing the time zone of the current user in the format used by the portal. This value should be used to localize any time-specific data in the portlet. For additional user information, use the IPortletUser interface. You must configure the portal to send the time zone to the portlet on the Advanced Settings page of the Web Service editor.

Portlet Mode

n/a

GetPortletMode

ALI portal only. The mode in which the portlet is running:
o Portlet: Normal view; the portlet is displayed on a portal page, viewed through a standard Web browser.
o Preview: The portlet is being previewed by a user (available when users select portlets for portal pages).
o Summary: The portlet is being displayed on a non-standard browser or other alternative browsing device.
o Syndicated (Portlet, Preview and Summary): Portlets can also be viewed asynchronously when executed by a job.

  1. The pagelet retrieves user information and preferences from IProxyUser / IPortletUser. This interface provides access to the following information:

Parameter

IProxyUserMethod

IPortletUserMethod

Description

User ID

GetUserID

GetUserID

The User ID of the currently logged in user. This value can be used to determine if the session has expired. (In ALI portal, if UserID=2, the default Guest user is logged in; any other user's session has ended.)

User Name

GetUserName

GetUserName

The name of the logged in user. The user's name can be used to personalize display or pre-fill form fields.

Login Status

IsAnonymous

IsGuestUser

Flag indicating if current user is the Anonymous (Ensemble) or Guest (ALI portal). These user types are not exactly equivalent. For details, see the ALI portal or Ensemble online help.

Permissions: Role

GetRoles
IsUserInRole

n/a

Ensemble only. The role(s) for the user in the current context.
GetRoles returns an enumeration of all of the roles the current user has in the current context. IsUserInRole returns a boolean indicating whether or not the current user is in a specific role.

Permissions: Activity Rights

n/a

HasActivityRight
GetActivityRights
 

ALI portal only. HasActivityRight returns a flag indicating whether or not the current user has the specified portal Activity Right.
GetActivityRights returns an enumeration of all the portal Activity Rights associated with the current user. (You must configure the portal to send the Activity Rights to the portlet on the Advanced Settings page of the Web Service editor.)

Permissions: Settings

n/a

HasSettingsRight
GetSettingsRights

ALI portal only. HasSettingsRight returns a flag indicating whether or not the current user has the right to change a particular type of SettingType (Admin, Community, CommunityPortlet, Portlet, User, and UserInfo).
GetSettingsRights returns an enumeration of all of the types of settings that the current user can set in the current context. All users always have access to Portlet and User settings, but might or might not have access to Administrative settings. If the portlet is displayed in a Community, the user might or might not have access to Community and CommunityGadget settings.

Permissions: Community

n/a

GetCurrentCommunityAccessLevel

ALI portal only. The Community Access Level (in the Community ACL) the current user has for the current Community:
o Read
o Select
o Edit
o Admin
o None

You must configure the portal to send the Community ACL to the portlet on the Advanced  Settings page of the Web Service editor.

Locale

n/a

GetCharacterSet

ALI portal only. The current user's character set. This value is essential when determining the correct content to return in an internationalized implementation of the portal. Tokens are defined by the IANA Character Set registry (http://ietf.org/rfc/rfc1700.txt pp. 100-116).

  1. The pagelet can access functionality in AquaLogic applications using IRemoteSession. For details, see Remote APIs.

  2. The pagelet constructs a response using IProxyResponse / IPortletResponse. The response includes content to be displayed and any settings to be stored or removed. These interfaces provide access to the following functionality:

Parameter

IProxyResponse Method

IPortletResponse Method

Description

Settings

SetSetting
RemoveSetting

SetSettingValue
SetEncryptedSettingValue
RemoveSettingValue

Methods are not exactly equivalent.
SetSetting sets a new session preference (in both Ensemble and ALI portal).
SetSettingValue sets a new value for any portal setting in the ALI database. New names and values are appended to the existing set in the database. Note: If any settings already have corresponding values stored in the ALI database, the existing values will be overwritten.
SetEncryptedSettingValue uses the cryptographer supplied by the client to encrypt and set a new value for a setting in the ALI database.
RemoveSetting removes the referenced session preference  (in both Ensemble and ALI portal).
RemoveSettingValue removes the referenced setting from the portal. You must pass in the setting type and the setting name of an existing setting. There is no need to pass in a value; only a name is required. If the setting does not exist, no errors occur.

Portlet Title

n/a

SetTitle

ALI portal only. Sets the portlet's title in the title bar on the portlet page. The string passed in will override the title set in the portlet editor. If the title bar is suppressed, the title will not be displayed.

Hosted Display Mode

n/a

SetHostedDisplayMode

ALI portal only. Tells the portal how pages associated with the portlet should be displayed (with or without the portal banner). Calling this function makes the Portal Server display the page in the style of the current portal implementation, including the portal banner. Generally, a portlet's preference pages and any click-through pages should be in Hosted Display Mode. Note: Popup windows should not be displayed in Hosted Display Mode. You can also set Hosted Display Mode using Adaptive Tags.

Return to Portal

n/a

ReturnToPortal

ALI portal only. Redirects users to the portal page they started on.

 

For a simple example of how to use IProxy* methods in a pagelet, see IDK Quickstart: Hello World Pagelet (Java | .NET).

For a simple example of how to use IPortlet* methods in a portlet, see IDK Quickstart: Hello World Portlet (Java | .NET).

For a complete listing of interfaces, classes, and methods, see the IDK API Documentation.