| Oracle® Fusion Middleware User Interface Customization Guide for Oracle WebCenter Interaction 10g Release 4 (10.3.3.0.0) Part Number E14110-03 |
|
|
View PDF |
| Oracle® Fusion Middleware User Interface Customization Guide for Oracle WebCenter Interaction 10g Release 4 (10.3.3.0.0) Part Number E14110-03 |
|
|
View PDF |
If you are implementing advanced UI customizations, this chapter provides detailed portal architecture information for portal UI layers, MVC architecture, activity spaces, session management, and request control flow.
The figure below shows the major portal UI projects and how they depend on each other. (For an introduction to the portal page design, see Chapter 2, "Portal Page Layout".) 
Description of the illustration uiprojects.gif
Portal UI Infrastructure is another level of infrastructure and frameworks that mirrors UI Infrastructure and contains the implementation that depends on the portal server API. For example, the implementation of the tree in the UI Infrastructure project is a generic tree of items, whereas the version of the tree in Portal UI Infrastructure is a tree of PTObjects (i.e., Users, Groups, Content Crawlers, etc.).
Portal Pages contains the source code for most of the portal's end-user pages. This project is divided into three main categories: admin pages (pages under Administration), browsing pages (end-user pages that do not appear under Administration) and common pages (pages common to both Administration and end-user browsing). Within these three categories, packages are separated into feature groups, e.g., browsing.login, admin.editors.group , common.search.
There are many reasons the portal UI is built using a layered approach:
Unified Code Base: The entire portal UI is written in Java and automatically converted to C# using a proprietary tool built specifically for the portal. Both versions of the UI undergo equal testing. Their level of quality is equivalent and they offer the exact same set of features.
MVC Architecture: All UI source code is implemented following the Model-View-Control (MVC) design pattern. Separating presentation from logic makes front-end customization simpler, and facilitates upgrades when a new version of the portal becomes available. For more details on the MVC design pattern, see the next section.
Object-Oriented Code: All UI source code is written in object-oriented and compiled code (Java or C#). As a consequence, there is no JSP or ASP. Object-oriented code has a number of advantages; the most important for the portal are upgrading, refactoring and maintenance.
Strong Infrastructure and Frameworks: Several UI projects are specifically dedicated to infrastructure, frameworks and reusable components. Examples include the Activity Space framework (Chapter 14, "Creating Custom Activity Spaces"), Programmable Event Interfaces (Chapter 12, "Using PEIs"), and Dynamic Discovery (cChapter 18, "Deploying Custom Code Using Dynamic Discovery").These projects are extensively tested and should be leveraged as much as possible when customizing the UI.
The architecture of the portal UI is based on the Model-View-Control (MVC) design pattern. The MVC paradigm allows you to separate the code that handles business logic from the code that controls presentation and event handling. Each page in the portal is made up of a combination of at least one Model and View, and one or more Controls.
Model classes store the data for a page or page section. A single page might use one or more Model classes, depending on how much of the page data can be shared by other types of pages. A Model defines how data is accessed and set for a given page, including any functions necessary for security or data validation and modification. Models encapsulate calls to the portal server API and also store UI-specific data. Data that is globally accessed by the UI is available from the Activity Space object (discussed in the next section). All other data should be stored in a Model.
View classes contain HTMLElements and HTMLConstructs that describe how the data from the Model should be displayed to the user. In the portal UI design, DisplayPage objects are used to aggregate View objects to encapsulate all the information needed to render a particular page. Some Views are common throughout the portal and some are specific to certain pages. For example, the banner that makes up the majority of the portal is a common View that defines the color scheme and where the search section will be displayed. In contrast, the View used to create and modify data within a User Profile is specific to the User Profile function and is seen only on that page.
Control are actions or sets of actions that are executed when a specific event is triggered. Multiple Controls can be defined within a page, each with its own functional specification. For example, one Control might produce a popup window that allows the user to browse for a specific object and places the selection within the View, and another could save the new data to the Model.
The diagram below shows a simplified version of how the classes used for the Login page interact with each other using the Model-View-Control (MVC) pattern. 
Description of the illustration mvcloginflow.gif
The Control either redirects to another page or returns to the same page with new data since the Model has been updated. In this case, the Control redirects to the MyPage.
The Interpreter gets the HTML for the page requested by the Control from the appropriate View, in this case the MyPage View.
The View returns the HTML for the page.
The Interpreter sends the HTML for the page back to the browser.
Note that the redirect from the Login page to the MyPage occurred without returning to the client. These Server Redirects are handled by the Interpreter. The portal favors server redirects over regular redirects (i.e., Response.redirect) because they avoid unnecessary roundtrips to the client. Regular redirects are used in a few cases; for example, some Security Modes require a redirect to switch between HTTP and HTTPS pages.
An Activity Space groups multiple task-specific actions into a logical set and provides the programmer with base functionality. An Activity Space takes several related pages and turns them into one group of Model-View-Control objects. Most of the classes in the UI projects are part of an Activity Space, for example:
Login page (plumtree.portalpages.browsing.login.LoginAS)
My Pages (plumtree.portalpages.browsing.myportal.mypages.MyPageAS)
Select Portlet page (plumtree.portalpages.browsing.objectselection.portlets.PortletSelectionEditorAS)
Knowledge Directory (plumtree.portalpages.browsing.directory.DirAS)
Search (plumtree.portalpages.browsing.search.basic.BasicSearchAS or plumtree.portalpages.browsing.search.advanced.AdvancedSearchAS)
Group editor (plumtree.portalpages.admin.editors.group.GroupEditorAS)
Tree Control (plumtree.portaluiinfrastructure.tree.TreeAS)
The Activity Space is the base unit; the Interpreter dispatches incoming requests to the correct Activity Space. Redirects can be done from one Activity Space to another. For example, when the client requests the Login page, the Interpreter redirects the request to LoginAS. As shown in the example in the previous section, LoginAS redirects to MyPageAS.
Each Activity Space contains at least one Model, View and Control. Most Activity Spaces contain at least one Display Page. Display Pages correspond to actual portal pages; there is a one-to-one mapping between portal pages and DP classes. Each portal page is broken into areas and one View is implemented for each area. The Display Page puts the Views together to render the page.
To browse to a specific Activity Space, you must add the name of the Activity Space to the URL. The name of the Activity Space corresponds to the value of the STR_MVC_CLASS_NAME constant in the AS class. For details, see the example that follows.
The diagram below shows a simplified version of the members of the Login Activity Space. This Activity Space contains one Control, one Model, and one Display Page that contains three Views.
All classes in the UI projects follow the naming conventions shown in the diagram.
| Object Type | Name Suffix |
|---|---|
|
Activity Space |
AS |
|
Display Page |
DP |
|
View |
View |
|
Control |
Control |
|
Model |
Model |
The classes for the Login Activity Space (LoginAS) are located in the UI projects (com.plumtree.portalpages.browsing.login).
Note: NavigationView and TopBarView are located under \common because they are used in all portal pages.
As noted above, you can browse to an Activity Space by adding the name of the Activity Space to the URL. The name of the Activity Space corresponds to the value of the STR_MVC_CLASS_NAME constant in the AS class. For example, the value of STR_MVC_CLASS_NAME in LoginAS is "Login" so the URL to access the login page would be: http://localhost/portal/server.pt?space=Login.
For more information and detailed instructions on Activity Space customization, see Chapter 14, "Creating Custom Activity Spaces".
Access to the HTTP session in Java and the HTTP session state object in .NET is controlled through the HTTPMemoryManagement module. This wraps the underlying session object into a Session Manager, which allows you to manage the session hierarchically.
The session contains several infrastructure-level data structures, such as the Activity Space cache. It also provides a Sandbox Session Manager, where UI developers can store data on the session. In an MVC architecture, most data storage should be done on the Model, but there are situations where it is necessary to store data directly in the Sandbox Session Manager to share data between ActivitySpaces. Using the Model for data storage is preferable because the Model is cleaned up when the ActivitySpace is removed from the cache; the Sandbox is only cleaned up when the user logs out. The Sandbox contains booleans that describe the user's browser (i.e., IE, Netscape, Macintosh, etc.).
The diagram below shows what is stored on the session and how it is organized. 
Description of the illustration sessionorg.gif
As explained in the previous sections, the portal UI is accessed through the MVC-based Activity Space Framework. Instead of navigating to UI pages via file links, each user request is handled by an Interpreter that determines the page (i.e., Activity Space) to be displayed.
This section summarizes what happens when a request is made by filling in the gaps between the user request and page display. These pages take a look inside the Interpreter to see some of the common checks that are processed for each request, explore the relationship between the Interpreter and Activity Spaces, and gain a better understanding of how control flows from one to another.
When a request is made to the portal, the Interpreter controls the UI page to be displayed to the user. The Interpreter is simply a class in the UIInfrastructure library that serves as an entry point for HTTP requests; it "interprets" the query string to determine the contents of the request and decide where to send the user. Since the Interpreter is involved with every request, you should have an understanding of some of the logic it performs.
When an HTTP request is made to the portal entry point (e.g., server.pt), the HandleRequest method in the Interpreter is called. This method receives the necessary information required for processing: request, response, application, and session. Several checks and functions are performed, summarized below in the order they occur:
Check for successful startup: If the portal fails to start up, the Interpreter cannot perform a redirect, because it has no Activity Space. Instead, it writes the following error message directly on the response: "The server has experienced an error on startup. This problem must be fixed before using the system." When starting your portal, open Logging Spy and check for a successful startup message for the UI Infrastructure component. If there is a problem, you should see a startup failure message in Logging Spy.
In most cases, you will also see an error page in your browser, though some portal errors are drastic enough such that you will not reach the portal's error page. For example, if the path you supplied for the portal in your config file is incorrect, your libraries (including UIInfrastructure) will not load; the code will not reach the Interpreter and you will likely see an error message from your web server.
Check for gatewayed request: Gatewayed requests are handled by the HandleGatewayRequest method in the GatewayHandlers class. Any minor differences in processing are noted in the explanations that follow.
Check security mode: The Interpreter confirms that the request matches the current security mode of the portal:
In mode 0, the portal is either secure or insecure, depending on how the user accesses the portal.
In mode 1, only Activity Spaces specified in the config file SecureActivitySpaces are secure.
In mode 2, the entire portal is secure and all requests must be made via HTTPS.
To perform this check, HandleRequest calls the helper method CheckHTTPSecurityAndRedirect. This method checks whether the incoming request matches the security mode, and redirects as necessary. If the portal is expecting an SSL request (modes 1 or 2) but a non-SSL request comes in, the Interpreter creates a 302 redirect to the same page using a secure URL. This redirect is constructed using the secure URL mapping entered in the x_config.xml file:
<!-- URLMapping - Entry 0 --> <URLFromRequest0 value="*"></URLFromRequest0> <ApplicationURL0 value="http://myserver/portal/server.pt"></ApplicationURL0> <SecureApplicationURL0 value="https://myserver/portal/server.pt"></SecureApplicationURL0>
Load query string settings: At this point, the Interpreter accepts the request and attempts to interpret (parse) its content by calling the helper method LoadQSSettings. This method begins by extracting any expected query string arguments such as "space", "in_hi_space", "control", "in_hi_control", etc. These arguments are stored so they can be passed back for processing. Before returning to HandleRequest, the method performs two more functions. First, the arguments are checked for unsafe characters. If the arguments have suspicious characters (indicative of cross-site hack attempts), an error will be thrown and shown in Logging Spy.
Finally, the method checks the Accepts and User-Agent headers to determine if the request is coming from a known device, such as a PDA (the list of known devices is specified in the config file devices.xml). If a match is found, the appropriate markup format will be used; otherwise, standard HTML will be used.
Increment performance counters: The portal keeps track of several performance benchmarks, including total number of hits. The Interpreter is used to track this statistic because it is involved with every request. For each request made, this counter is incremented. (Gatewayed requests are recorded in a separate counter.)
Session locking and request management: After all the information is retrieved from the request, the Interpreter gets to work. To ensure that it works on one request at a time per session, a queue is used to store requests. If the queue has reached its limit, new requests are denied and the portal reports an error message.
Determine browser settings: After establishing a good request, the Interpreter retrieves and stores the user's browser settings, including the type of browser (IE or Netscape), and the version if available. These settings can then be used to make minor modifications so the UI displays correctly for the user.
Log in: Once the request is prepared, the Interpreter processes it through the portal. The first step is to make sure the user has the correct access. The Interpreter checks if the "Remember my Password" cookie has been set and is valid. If the cookie does not exist or is invalid, and the current session is empty or has timed out, the Interpreter redirects the user to the login page. Until a valid user logs in, the portal defaults the current user to Guest, and access is limited. The login process also involves experience rules evaluation; for details, see Experience Definition Control Flow. If the login check succeeds, the Interpreter continues, passing the control flow to the desired Activity Space, covered in the next section.
After completing the basic checks listed in the previous section, the Interpreter turns the control flow over to the requested Activity Space. The major steps in this process are summarized below. The entire Activity Space control flow is illustrated in the diagram at the bottom of this section. Page requests also involve experience rules evaluation; for details, see Experience Definition Control Flow.
Locate Activity Space: Before an Activity Space can be run, it must first be loaded and initialized. Since multiple users are constantly accessing different portal pages, the Interpreter first looks in the cache to see if the Activity Space already exists. This action is shown in Logging Spy.
Invoke OnPageStart PEI: Before the Activity Space is processed, the OnPageStart PEI is invoked. This PEI allows you to customize the behavior of the portal before any page is loaded. To learn more about PEIs and supported events, see Chapter 12, "Using PEIs".
Determine Control: The first step in processing the Activity Space is to determine which Control should be used. If no Control is specified, then the Activity Space's default Control is used. If there is no default, the Control is left empty. The arguments for the Control are then retrieved. (For security purposes and SSO, the login page Control requires further processing.)
Pass Control to Activity Space: If the Control is valid, the CheckActionSecurityAndExecute method is called. This method is implemented for each Control, usually by the developer of the Activity Space, or by a development framework (e.g., the Editor framework for Activity Spaces). When the method is called, control flow essentially passes to the Activity Space. Any code implemented for the Activity Space is run according to the logic in the Control. When the method finishes, it returns a Redirect object, and control is passed back to the Interpreter. An example of this method, from PortalPages, is shown below. In this implementation, the Control calls the Model to perform some action, and then returns a NULL for the Redirect object.
publicclass OpenSubFolderControl implements IControl
public RedirectCheckActionSecurityAndExecute(XPHashtablearguments)
{
String[] sValues = (String[])arguments.GetElement(m_SubFolderID);
if (sValues ==null)
{
log.Error("could not find folder ID in query string.");
return null;
}
m_asModel.OpenSubFolder(XPConvert.ToInteger(sValues[0]));
returnnull;
}
Redirect Control: When control returns to the Interpreter, it checks the Redirect object returned by the Activity Space:
If the Redirect object is NULL, the Interpreter processes the Display Page set by the Activity Space (or by the Control itself).
If the Redirect is not NULL, the Interpreter processes the Redirect in a loop until all internal Redirects are handled, at which point the final Display Page is processed. Note: The Gateway does not support internal Redirects. Gatewayed requests are executed through a true HTTP 302 redirect. The only time a redirect occurs from a gatewayed request is if the user does not have sufficient privileges, at which point the user is returned to the login page.
If the Redirect is an HTTP Redirect, the final Display Page response is set and the Interpreter starts from the beginning.
With this mechanism, an Activity Space can use multiple controls, perform multiple actions, and repost as needed. The excerpt from PortalPages shown below demonstrates this logic. After the page is deleted, a redirect is created that sets a Control to direct the browser to the user's home page.
publicclass DeletePageControlimplements IControl
public RedirectCheckActionSecurityAndExecute(XPHashtablearguments)
{\
String[] sValues = (String[])arguments.GetElement(STR_PAGE_ID);
if(sValues == null)
{
log.Error("could not find page ID in query string.");
return null;
}
int nDeletePageID = XPConvert.ToInteger(sValues[0]);
m_asModel.DeletePage(nDeletePageID);
IPTSession objSession = (IPTSession)m_asOwner.GetUserSession();
int nUserID = objSession.GetSessionInfo().GetCurrentUserID();
int nHomePageID = -1 * nUserID;
Redirect redirect = new Redirect();
redirect.SetLinkCreateNewSpace(m_asOwner.GetName(), m_asOwner);
redirect.SetControl(SetPageControl.STR_MVC_CLASS_NAME);
redirect.AddControlArgument(SetPageControl.STR_PAGE_ID, nHomePageID);
return redirect;
}
In the Logging Spy trace, the user begins on the MyPage Activity Space. When the user tries to delete a MyPage, control is delegated to DeletePageControl. The RedirectCheckActionSecurityAndExecute method is invoked, and as shown in the code above, a call is made to the Model to delete the page. This action is shown in Logging Spy ("... removed 1 pages ...").
DeletePageControl then creates a new Redirect by sending control to SetPageControl with the argument to go to the user's home page. Logging Spy shows that the Interpreter handles this redirect. Since SetPageControl does not return any further redirects, processing is complete, and the Display Page is shown.
Render Display Page: The control flow ends with the rendering of the Display Page. At this point the UI has completed loading, and the Interpreter waits for the user to make another request, restarting the cycle.
The diagram below illustrates the Activity Space control flow: 
Description of the illustration ascontrolflow.gif
As noted in the previous section, gatewayed requests are treated differently by the Interpreter.
If the page contains portlets with tags, the request will also be handled by the Transformer; for details see Adaptive Tag Control Flow.
Experience definitions let you tailor portal experiences for different groups of users. In a single portal implementation, you can create a distinct user experience for each audience. Experience definitions let you specify which navigation and branding schemes, mandatory links, and default home pages to display to each set of users.
In every request cycle, experience rules are evaluated a maximum of two times. These two phases may or may not resolve to the same experience definition.
The first experience rules evaluation phase takes place when a user accesses the portal and has not yet been authenticated. This evaluation determines which Guest User object to log in. Since the current user has not been authenticated, the session needs a Guest User object to browse the portal.
The login experience rules evaluation returns the experience definition for the first rule that evaluates to true, and uses the associated Guest User object. (Each experience definition has an associated Guest User object and default login page, either the standard login page or the Guest User's My Page. For details on the Experience Definition Login Settings page, see the portal online help.)
Note: At this time, only experience rules relevant to unauthenticated users can be evaluated. Since no user is logged into the portal, and the destination page has not been determined, rules with conditions based on user properties or destination page are meaningless. Only rules with globally determined conditions like the time of day, browser type, request URL, etc., can be evaluated. If the evaluation of all relevant rules return false, the user is logged in as the Default Guest User object.
After a user is logged in, experience rules are evaluated to determine which experience definition object to use in displaying the requested page. This evaluation occurs after all the Control actions have executed, and all redirects have been followed. For more information on redirects, see MVC Architecture.
At this point in the request cycle, the destination page has been determined and the user is logged into the portal. The experience definition is determined as follows:
All experience rules are evaluated and the first rule that has all conditions met returns an experience definition.
If none of the experience rules evaluate to true, the experience definition is determined by folder association. (Each experience definition can be associated with a folder that contains User objects.)
If no experience definition is associated with the user's folder, the default experience definition is used.
The requested page is displayed using the stylesheet, header navigation, etc., for the returned experience definition.
Note: Users are no longer tied to a single experience definition; therefore a user could view a page with one experience definition, click on a link and view the next page with a different experience definition.
Adaptive Tags allow web designers to utilize portal data directly in their HTML. The portal ships with a set of Adaptive Tag libraries, and you can create custom tags if additional functionality is needed.
The figure below shows the control flow of a typical portal request that makes use of Adaptive Tags. 
Description of the illustration tagcontrolflow.gif
First, the portal page requests portlet data from the Transformer.
The Transformer retrieves the requested portlets from the remote portlet servers. Native UI tags, such as JSP Tags or .NET web controls, are processed on the remote server before the HTML is returned to the Transformer.
The Transformer converts the HTML into markup data including both HTML and Adaptive Tags. This markup data is passed to the Tag Transformation Engine, which processes the tags and converts them into standard HTML.
Finally, the HTML is returned to the portal page where it is displayed to the end user.
It is important to note that native UI tags are processed first on the remote portlet server, and Adaptive Tags are processed later in the Tag Transformation Engine, described below.
The Tag Transformation Engine converts markup data from the Transformer into a tree of HTML and Adaptive Tags. The Engine moves through the tree and outputs HTML and processes the tags. When a tag is processed, it can cause all of its child nodes to be processed, or it can skip that entire section of the tree.
This figure below shows an example of a tree. 
Description of the illustration tagtransformationengine.gif
In this example, when the Choose tag is executed, it determines whether or not the current user matches the conditions in the choose clause. If it does, the When tag will display the HTML inside the tag. If not, the Otherwise tag will display its HTML. For details on these tags, see the Oracle WebCenter Interaction Web Service Development Guide.
|
 Copyright © 2011, 2012, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|