15 Accessing Portal Objects

Many web services, applications and UI customizations require access to portal objects and pages. This chapter describes the options available through the portal API—adaptive tags, Common Object Opener, ASURL, and Redirect.

Adaptive tags allow you to reference portal objects in portlets and UI components. The openerlink tag allows you to open any portal object from any gatewayed HTML, such as a portlet. For details on adaptive tags, see Oracle WebCenter Interaction Web Service Development Guide.
The Common Object Opener allows you to open any portal object from anywhere within the portal. The CommonOpener_OpenObject function is included in every page generated by the portal application, and can be called from any piece of UI or from within a portlet. For details on using the Common Object Opener in UI code, see Using the Common Object Opener. Portlets can also call the function remotely through the Oracle WebCenter Interaction Development Kit (IDK). For details, see the Oracle WebCenter Interaction Web Service Development Guide.
The ASURL object allows you to create portal-specific URLs to Activity Spaces as Strings or HTMLAnchor objects. For details on using the ASURL object, see Using ASURL and Redirect.
The Redirect object can return any URL, and handles the page change to the new URL. The portal uses the Redirect object to redirect control flow from one Activity Space or Control to another. For details on using the Redirect object, see Using ASURL and Redirect.

Using the Common Object Opener

The Common Object Opener allows you to open any portal object from anywhere within the portal UI. (To retrieve an URL as a String or HTMLAnchor object, use ASURL) Portlets can also call functions remotely through the Oracle WebCenter Interaction Development Kit (IDK). For details, see the Oracle WebCenter Interaction Web Service Development Guide.

The PTCommonOpener class is included in every page generated by the portal application, and can be called from any piece of UI or from within a portlet. The most commonly used function in this class is getOpenerURLOpenObjID.

function getOpenerURLOpenObjID (_nClassID, _nObjectID, _strOptQSArgs, _nOpenerMode)

This javascript creates a URL that calls the Opener Activity Space and its corresponding OpenObject Control (the only MVC module in the Opener ActivitySpace). The URL includes all necessary parameters for the Control. As noted above, the Common Opener function is available from any portal page. The getOpenerURLOpenObjID function has four required parameters:

nClassID refers to the numeric ID for the type of object being opened (e.g., User = 1, Portlet = 43, Content Source = 35). A full list of object types can be found in the PTCLASSDESCRIPTION table in the com.plumtree.portaluiinfrastructure.classtypedescriptors package.
nObjectID is the identifier for the specific object being opened. Every object has a unique identifier (ObjectID) stored within the database (for example, for the Users object type: Administrator = 1, Guest = 2, Default Profile = 3). The ObjectID can be retrieved through the com.plumtree.server package and usually through a QueryResult.
strOptQSArgs allows you to add arguments to the query string that are not included by default. This argument may be empty.
nOpenerMode defines the mode in which the object will be opened, which controls the actions that can be performed on the object (Create = 0, Edit = 1, View = 2, View Meta Data = 3).

As noted above, the getOpenerURLOpenObjID function returns a URL. To open the URL you must pass it to another function. PTCommonOpener includes two handy functions for opening URLs: openInSameWindow and openInNewWindow.

Call either of these functions in a standard OnClick event. The example below opens the User Editor ActivitySpace as the Administrator user in View mode.

<INPUT value="Opener Click" type="Button" name="btnSubmit" onClick="PTCommonOpener.openInSameWindow(PTCommonOpener.getOpenerURLOpenObjID(1,1,'null',2));"/>

You can execute custom functionality whenever the Common Opener is used to open an object or direct to an Activity Space through the IOpenerActions PEI. For more details on PTCommonOpener and its functions, see the Common Opener API documentation.

Custom Activity Spaces and Non-Portal Pages

As noted earlier, PTCommonOpener functions can be called from within any portal page. You can also use these functions in a custom editor or browsing page by making a call to the Opener ActivitySpace. The Common Opener functionality can be implemented in a variety of ways; the method explained here is the easiest and most commonly used.

Note: To use the following method, first import the package that contains the Opener ActivitySpace (com.plumtree.portaluiinfrastructure.classtypedescriptors.classframework).

Within the DisplayJavaScript method in the View class of your custom Activity Space, make a call to GetOpenerJavascript as shown in the code snippet below. This function requires one parameter: the Activity Space that contains the javascript function (inherited from the top level AActivitySpace object (m_asOwner)). The HTMLScript element returned contains Common Opener javascript functions.

public HTMLScript DisplayJavascript()
{
HTMLScript myScript;
myScript = new HTMLScript("text/javaScript");
myScript = PTOpenerLinks.GetOpenerJavascript(m_asOwner);
return myScript;
}

This code creates a new HTMLScript element, initializes it, and makes a call to GetOpenerJavascript.

Other methods for generating javascript code on the server are described in the API documentation for PTOpenerLinks in the portaluiinfrastructure package.

Using ASURL and Redirect

The ASURL and Redirect objects are used throughout the portal application to access different Activity Spaces and their Controls. Although they provide similar functionality, each serves a specific purpose.

The ASURL class supports automated creation of portal-specific URLs as Strings or HTMLAnchor objects. The Redirect object can return any URL, and handles the page change to the new URL.

ASURL

The URLs created using the ASURL class are always based on the BaseURL obtained from the config.xml file. ASURL methods allow you to append the necessary arguments to the base URL and create a complete ASURL object.

Once the ASURL object has been created, it can return the URL in a variety of ways. You can generate an HTMLAnchor element that contains the full URL, which can be used within an Activity Space. You can also provide the URL as a String to be used in an OnClick event, or as a "document.location" URL for use in client-side javascript.

For example, within the LoginView class that makes up the Login screen of the portal, the CreateAccount button automatically redirects to the CreateAccount Activity Space. The code that creates the ASURL is shown here:

myHRef = new ASURL();
myHRef.SetLinkGetSpaceIfCached(CreateAccountAS.STR_MVC_CLASS_NAME,
this.m_asOwner);
myHRef.SetControl(CreateAccountControl.STR_MVC_CLASS_NAME);
myHRef.AddInnerHTMLString(m_asOwner.GetString(637, "ptmsgs_portalbrowsingmsgs"));
myCell.addInnerHTMLElement(myHRef.GetURLAsHTMLElement());

The code above begins by creating a new instance of the ASURL object. The object initializes itself by grabbing the BaseURL and using it to start the URL. Method calls on the ASURL object append the query string parameters required by the application to determine the target Activity Space.

SetLinkGetSpaceIfCached

The most important parameters that must be added to the URL are the Activity Space name and cache ID. Activity Spaces are cached on the HTTP Session and retrieved for re-use through a cache ID. The name and ID parameters in the ASURL can be populated by passing the Activity Space into the SetLinkGetSpaceifCached method. This creates a URL to that particular Activity Space.

If you do not have access to the Activity Space, pass in the Activity Space name. This creates a URL that will search the cache for the named Activity Space, or create a new Activity Space if the referenced one cannot be found. This is very useful for Activity Spaces such as the MyPage Activity Space, which is usually cached on the HTTP Session; you can retrieve a cache ID even if you do not have access to the Activity Space itself.

SetLinkCreateNewSpace

If the Activity Space is not cached, you can add it using the SetLinkCreateNewSpace method.

SetControl

Set the Control name for the URL using the SetControl method call.

AddInnerHTMLString

Once the two primary parameters are set, the URL can be generated, and you can add HTMLElements or Strings to the anchor as needed. In this example, the message corresponding to ID 637 in the portalbrowsingmsgs language file ("Create an account") is added using the AddInnerHTMLString method. For details on language files, see Chapter 6, "Using String Replacement".

AddInnerHTMLElement

Once the entire URL is complete, place it into an HTMLAnchor element using the AddInnerHTMLElement method, as shown in the code snippet. In this example, the returned HTMLAnchor is used in the View class of the Create Account Editor .

GetURLAsString

You can also choose to return the URL as a String using the GetURLAsString method.

For a full list of ASURL methods, see the Common Opener API documentation.

Redirect

The Redirect object is very similar to ASURL, but can return any URL, and handles the page change to the new URL. (ASURL can only be used for portal URLs and only returns the URL as a String or HTMLAnchor.)

The portal uses the Redirect object to redirect control flow from one Activity Space or Control to another. In many cases, the redirect happens internally, and no HTTP redirect (status code 302) is sent to the browser. One redirect can chain to another. In conditions when you need the browser to change pages, you can force an HTTP redirect using the SetIsHTTPRedirect method (covered below).

As with ASURL, a variety of different methods allow you to set query string parameters for portal-specific URLs, as shown in the sample code below:

Redirect repostURL = new Redirect();
repostURL.SetLinkCreateNewSpace(FolderEditorAS.STR_MVC_CLASS_NAME, m_asOwner); 
repostURL.SetControl(EditorStartControl.STR_MVC_CLASS_NAME); 
repostURL.AddControlArgument(EditorStartControl.QS_EDITOR_TYPE,
String.valueOf(EditorStartControl.EDITOR_START_FLAG_EDIT));
repostURL.AddControlArgument(ObjEditorModel.EDITOR_QS_INT_CLASS_ID,
String.valueOf(PT_CLASSIDS.PT_CATALOGFOLDER_ID));
repostURL.AddControlArgument(ObjEditorModel.EDITOR_QS_INT_QS_OBJECT_ID,
String.valueOf(((IDirModelRO) m_dirModel).GetCurrentFolderID()));
SetRedirect(repostURL);

The code above begins by creating a new instance of the Redirect object. The method calls made to the object append the query string parameters required by the application to determine the target.

SetLinkCreateNewSpace

Set the ActivitySpace name through the SetLinkCreateNewSpace method.

SetControl

Set the Control name for the URL through the SetControl method.

AddControlArgument

If the control requires query string parameters, add them through calls to the AddControlArgument method.

SetRedirect

Once the entire URL has been built, the redirect call is returned through the SetRedirect method, inherited from the RepostControl class.

If you need to show an external page in the browser or set a cookie (which requires a full HTTP 302 redirect), you can still use the Redirect object by using SetIsHTTPRedirect and SetLinkToExternalURL.

SetIsHTTPRedirect

Call SetIsHTTPRedirect to set the redirect type:

True will force a full HTTP 302 redirect.
False will cause a server-side redirect.

After forcing a 302 redirect, you must handle the redirect back to the portal.

SetLinkToExternalURL

To redirect to a page outside the portal, call the SetLinkToExternalURL method and pass in the target URL as a String.

Note: To redirect outside the portal, SetIsHTTPRedirect must be set to True and the URL must be encoded (you can use one of the standard encoding methods in the HTMLElements package).