|Oracle® Fusion Middleware User Interface Customization Guide for Oracle WebCenter Interaction
10g Release 4 (10.3.3.0.0)
Part Number E14110-03
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.
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.
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
function getOpenerURLOpenObjID (_nClassID, _nObjectID, _strOptQSArgs, _nOpenerMode)
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:
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.
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).
This code creates a new HTMLScript element, initializes it, and makes a call to
PTOpenerLinks in the portaluiinfrastructure package.
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.
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.
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.
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.
If the Activity Space is not cached, you can add it using the
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".
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 .
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.
If the control requires query string parameters, add them through calls to the
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 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.
To redirect to a page outside the portal, call the S
etLinkToExternalURL 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).