Portal UI Customization: Advanced

Upgrading Existing Customizations (5.x > 6.0)

AquaLogic Interaction (formerly called Plumtree Foundation) 6.0 provides wide-ranging backward compatibility with existing UI customizations written for version 5.0.2 or above.  In most cases, you only need to recompile existing customization code against the new 6.0 jars/assemblies.

This page explains how to upgrade UI customizations from version 5.0.2 or above to version 6.0. The following sections outline backward compatibility of different UI components, introduce new features that can be used to replace older functionality, and list deprecated APIs and components.  For a full list of new features in 6.0, see What's New in G6?

Post-Installation Steps: Upgrading Existing UI Customizations

After AquaLogic Interaction 6.0 installation is complete, the portal will be installed without any UI customization. (For details on installation, see the Installation Guide for AquaLogic Interaction (Plumtree Foundation) 6.0.) You must follow the steps below to upgrade your existing UI customizations from version 5.0.2 and above to version 6.0.

Note: Some jar/assembly files have changed. Make sure to change your classpath to use the jars/assemblies for version 6.0 when recompiling. In particular, the classes in ptdebug.jar/ptdebug.dll are now part of uiinfrastructure.jar/uiinfrastructure.dll. These classes are supplied only for backward compatibility (see Deprecated APIs: Logging API for instructions on replacing this class).

The contents of 5.0.x plumtreeserver.jar/plumtreeserver.dll are split into plumtreeserver.jar/plumtreeserver.dll and ptportalobjects.jar/ptportalobjects.dll in 6.0. ptportalobjects contains the implementation classes and plumtreeserver contains the interfaces. If the classes you need cannot be found after upgrading, make sure to reference ptportalobjects as well as plumtreeserver. For example, PortalObjectsFactory, which was in plumtreeserver in 5.0.x, is now in ptportalobjects.

The build scripts for the 6.0 UICI work differently that the previous version. The build process now puts the jar/dll under the customer_repo directory, not the same location as the source code, and the install process takes the built jar/dll and adds it to the war file or webapp directory. See Setting Up the Development Portal for details.

  1. If you implemented any custom Activity Spaces in your portal, recompile your code against the new 6.0 jars or .NET assemblies correspondingly. See Custom Activity Spaces for details.

  2. If you implemented any custom PEIs, recompile your PEI code against the new 6.0 jars or .NET assemblies correspondingly. See PEIs for details.

  3. If you implemented a custom navigation solution, see Custom Navigation Schemes for details on upgrading your customizations.

  4. After recompiling your custom code against the new 6.0 jars/assemblies, deploy the jars/assemblies containing your custom code as follows:

  5. If you are upgrading from 5.0.2 or above, the installer creates a new directory called /settings_customer under the 6.0 <PT_HOME>. This directory contains the upgraded UI customization setting files for your custom Activity Spaces and PEIs. After completing the steps above, copy all the folders and files under /settings_customer to the /settings directory. (For example, all files under settings_customer/portal/dynamicloads/PEIs/ should be copied to settings/portal/dynamicloads/PEIs/.)

Custom Activity Spaces

In most cases, custom Activity Spaces written for a prior version of the portal will continue to function in 6.0. You must recompile any custom code against the new 6.0 jars or assemblies to ensure that it will work correctly.

Custom Activity Spaces written by extending standard Activity Spaces might not function as expected, since implementation of the super class for the custom implementation may have changed. The list below includes changes to the base Activity Space class (AActivitySpace) after version 5.0.2, including any new methods and modifications to old methods. Note that new methods are newly implemented API methods that provide additional functionality (instead of abstract methods that require subclasses to implement).

AActivitySpace

Method

Added/Modified in Version:

public String GetLanguage()

6.0

public String GetLocale()

6.0

public String GetTimeZone()

6.0

public void ReInit()

6.0

public boolean GetIsInPlaceRefreshEnabled()

6.0

public void SetIsInPlaceRefreshEnabled(boolean IsInPlaceRefreshEnabled)

6.0

public boolean GetIsInPlaceRefreshDisplayOn()

6.0

public void SetIsInPlaceRefreshDisplayOn(boolean IsInPlaceRefreshDisplayOn)

6.0

protected boolean RegisterPage(IDisplayPage page)
changed to
public boolean RegisterPage(IDisplayPage page)

5.0J

protected boolean RegisterPage(IDisplayPage page, String strStorageName)
changed to
public boolean RegisterPage(IDisplayPage page, String strStorageName)

5.0J

public boolean GetIsAccessStyleStandard()

5.0.4

public boolean GetIsAccessStyleNonStandard()

5.0.4

public abstract HTMLElementCollection GetStyleSheetLinks()
changed to
public HTMLElementCollection GetStyleSheetLinks()

5.0.4

public IXPRequest GetCurrentHTTPRequest()

5.0.3

public IXPResponse GetCurrentHTTPResponse()

5.0.3

public void SetCurrentHTTPRequestResponseObjects(IXPRequest xpRequest, IXPResponse xpResponse)

5.0.3

No changes were made to IView, IModel, IModelRO, IControl, and IHTTPControl.  Any classes implementing these interfaces should work as expected.

PEIs

Previous implementations of PEIs should continue to work as expected in 6.0.  You must recompile any custom code against the new 6.0 jars or assemblies to ensure that it will work correctly. Two new PEIs were added in 6.0: IOpenerActions and ILoginActions2.

Custom Navigation Schemes

Most existing custom navigation schemes (previously called "pluggable navigation") are supported in version 6.0. However, Isomorphic navigation can not be used due to licensing restrictions. You must rewrite any Isomorphic-related code. For advanced JavaScript navigation schemes, you can use the JSPortalmenu framework; see Advanced JavaScript Navigation Elements. In 6.0, you can use Adaptive Tags to create custom navigation schemes.

Cascading Style Sheets (CSS)

Existing CSS customizations should work as expected in version 6.0. Many new customization options are available in version 6.0. For details, see Using Adaptive Styles (CSS Customization) and Modifying Portal Style Sheets.

Multiple Guest Users / Branded Login Pages (Experience Rules)

A common UI customization is branded login pages. In previous versions, this was accomplished through the use of PEIs. The sample code that implements this feature (samplesubportalguests) is still usable, but experience definitions and experience rules provide a more simple and elegant solution.  

In version 6.0, you can create multiple guest users in addition to the default guest user that has always existed.  This feature allows you to define the portal experience for groups of unauthenticated users. You can accomplish this customization without writing any code.  Using the administrative UI, you can create a new experience definition (previously called "subportals") and create experience rules to define the audience. You can choose the layout for the login page/My Page by creating a new guest user associated with the experience definition and configuring the My Page layout for that user.

For example, you might want users who use different URLs to access the portal to see different login pages with different branding.  You could create two experience definitions with experience rules that direct users based on the URL used to access the portal (e.g., www.URL-A.com and www.URL-B.com). You would also create two guest users (e.g., Guest-A and Guest-B), associate each user with one of the experience definitions (e.g., URL-A with Guest-A, and URL-B with Guest-B), and modify the layout of each user's My Page. When users view the portal, they would see the My Page defined for the user that is associated with the experience definition that was returned based on the URL used to access the portal (e.g., www.URL-A.com would return Guest-A's My Page).  

The portal conditionally selects which experience definition to use for a particular request based on conditions such as URL, IP address, community, and group. You can also create custom conditions. For details, see Customizing Experience Definitions.

Common Opener (Portal URLs)

The Common Opener is a framework for opening portal objects in the UI in a way that shortens URLs and provides various new features such as the Common Opener PEI, Common Opener plugins, and navigaton by UUID and keyword. The Common Opener is completely backward compatible; 5.0.x-style URLs and older will continue to function. Third-party products that track portal usage based on URL information might need to be adjusted after upgrading to 6.0.

The example URLs below both open a data source in mode 2 (edit).

5.0.x:
http://www.myportal.com/portal/server.pt?space=Opener&control=OpenObject&in_hi_userid=243&in_hi_ClassID=35&in_hi_ObjectID=104&in_hi_OpenerMode=2

6.0:
http://www.myportal.com/portal/server.pt?space=Opener&clsID=35&objID=104&mode=2

For details, see Using the Common Opener.

Deprecated APIs

Some APIs have been deprecated in version 6.0.

Logging API

The PTDebug style of logging continues to work, but this class is deprecated.  The recommended style is to use OpenLog as shown below. The key difference between the old logging style and the new is the use of a different set of classes. Essentially, OpenLog contains all the functionality PTDebug has with minor name differences.  For details on using logging, see Debugging Using ALI Logging Utilities.

OLD PTDebug logging style:

Java:

import com.plumtree.debug.*;
if (PTDebug.IsFatalTracingEnabled(Component.Portal_UI_Infrastructure)) {
PTDebug.Trace(Component.Portal_UI_Infrastructure, TraceType.Fatal, "Error Message …“, exception);
}

.NET:

using com.plumtree.debug;
if (PTDebug.IsFatalTracingEnabled(Component.Portal_UI_Infrastructure)) {
PTDebug.Trace(Component.Portal_UI_Infrastructure, TraceType.Fatal, "Error Message …“, exception);
}  

NEW OpenLog logging style:

Java:

import com.plumtree.openlog.*;
private static OpenLogger log = OpenLogService.GetLogger(OpenLogService.GetComponent("UI_Infrastructure"), "location");
log.Fatal(exception, “Error Message …”);

.NET

using com.plumtree.openlog;
private static OpenLogger log = OpenLogService.GetLogger(OpenLogService.GetComponent("UI_Infrastructure"), "location");
log.Fatal(exception, “Error Message …”);

Pages API

In 6.0, Pages are objects, resulting in significant changes to the APIs surrounding Pages. All deprecated APIs work with 6.0, but may not perform as well as the APIs that replace them. Deprecated interfaces will be eliminated in a future version of the portal. Any custom code that uses the deprecated APIs should be updated. (For a list of deprecated APIs and methods, see API Changes below.)

Note: There are no longer any Pages with a negative ID.

In previous versions, IPTMyPortal was used to represent a Page. The IPTMyPortal interface and all associated methods are deprecated in 6.0. Use IPTPage or IPTPageInfo instead.

In 6.0, Pages are created like any other object. To add a new page, call Create() on the Object Manager for Pages (instead of calling AddPage() on IPTCommunity or IPTMyPages).

To create a new Community Page, pass in the Folder ID that contains the Community to which the Page should be added:

IPTPage ptCommunityPage = (IPTPage)ptSession.GetPages().Create(nCommunityFolderID);

To create a new My Page, pass in the negative of the ID of the User to whom the My Page belongs:

int nUserID = ptSession.GetSessionInfo().GetCurrentUserID();
IPTPage ptMyPage = (IPTPage)ptSession.GetPages().Create(-nUserID);

To retrieve an existing IPTPage, use the Pages Object Manager:

IPTObjectManager ptomPages ptSession.GetPages();
IPTPage ptPage = (IPTPage) ptomPages.Open(nPageID,false);

There are several ways to retrieve an IPTPageInfo. Pages are contained by Page Containers, such as a Community or a User’s My Pages. IPTCommunity and IPTMyPages both extend the interface IPTPageContainer, which includes the method GetPage(int nPageID). To retrieve the first page in a Community or set of My Pages, substitute nPageID with "0".

The following code retrieves a Page in a Community:

IPTObjectManager ptomCommunities = ptSession.GetCommunities();
IPTCommunity ptCommunity = (IPTCommunity)ptomCommunities.Open(nCommunityID,false);
IPTPageInfo ptPageInfo = ptCommunity.GetPage(nPageID);

The following code retrieves a User’s My Page:

IPTMyPages ptMyPages = ptSession.GetMyPages();
IPTPageInfo ptPageInfo = ptMyPages.GetPage(nPageID);

You can also retrieve a cached Community Page from a cached Community as shown below:

IPTCommunityManager ptomCommunities = (IPTCommunityManager) ptSession.GetCommunities();
IPTCommunityInfo ptCommunityInfo = ptomCommunities. CachedOpenCommunityInfo(nCommunityID,false);
IPTPageInfo ptPageInfo = ptCommunityInfo.GetPage(nPageID);

You can retrieve a cached My Page from a User’s IPTSessionInfo:

IPTSessionInfo ptSessionInfo = ptSession.GetSessionInfo();
IPTPageInfo ptPageInfo = ptSessionInfo.GetCurrentMyPage(nPageID);

If you do not know which Community contains the Community Page, you can get the Page directly from the Page Manager:

IPTPageManager ptomPages = (IPTPageManager)ptSession.GetPages();
IPTPageInfo ptPageInfo = ptomPages.CachedOpenPageInfo(nPageID,false,false);

For a summary of deprecated methods, see the next section. For a complete list of methods, see the API documentation.

My Pages and Community Pages API Changes

The following is a summary of the changes and additions to APIs for IPTPreferencesContext, IPTPageContainer, IPTCommunity, IPTMyPages, IPTGadgetGateway, IPTCommunityManager, IPTPageTemplate, IPTGadgetInfo, IPTCommunityInfo, and IPTSessionInfo.

The IPTPreferencesContext interface provides methods for setting, removing, and looking up preferences. In previous versions, these methods were on the IPTMyPortal interface. The IPTPreferencesContext interface is extended by IPTPageContainer (which is extended by both IPTCommunity and IPTMyPages). The signature for these methods has also been changed to make them easier to use: pass in a Portlet ID (0 if the preference is not a portlet preference), and a PT_PREF_TYPES (PT_PREFTYPE_CURRENT_USER if the preference is for the current user or PT_PREFTYPE_ALL_USERS if the preference is for all users). For a full list of methods, see the API documentation.

The IPTPageContainer interface extends IPTPreferencesContext and provides the following methods:

The following changes were made to the IPTCommunity interface:

The following changes were made to the IPTMyPages interface:

The following changes were made to the IPTGadgetGateway interface:

The following methods were moved to the IPTCommunityManager interface from IPTMyPages: QueryMemberships, QueryAvailableCommunities, JoinCommunity, QuitCommunity, QueryMandatoryTabs, and FlushMandatoryTabsCache.

The following methods were added to the IPTPageTemplate interface to allow the default page name to be localized:  GetDefaultPageLocalizable, GetLocalizedDefaultPageNames, SetLocalizedDefaultPageNames, GetLocalizedDefaultPageName, GetIsDefaultPageLocalized, SetIsDefaultPageLocalized, GetDefaultPagePrimaryLang, and SetDefaultPagePrimaryLang.

In the IPTGadgetInfo interface, GetCommunityID is deprecated. Use GetPageContainerClassID and GetPageContainerObjectID.

In the IPTCommunityInfo interface, OpenPage is deprecated. Use the new method GetPage.

In the IPTSessionInfo interface, the method GetCurrentMyPage was added.