In the Oracle WebCenter Sites: Contributor interface framework, specifically the UI Controller handles all interface requests and processes elements.
About the Contributor Interface Framework
The framework of the Contributor interface sits on top of the Services Layer and handles client requests.
This figure shows the framework, consisting of the Presentation Layer and UI Controller.
Figure 59-1 Contributor Interface Framework
Description of "Figure 59-1 Contributor Interface Framework"
The Presentation Layer consists of elements that render views and elements that generate a response. The UI Controller processes the requests it receives from the Contributor interface, as explained in UI Controller.
The UI Controller is not used to process requests pertaining to asset forms, given that asset forms exist outside the Contributor framework. See Customizing Asset Forms for the Contributor Interface.
The UI Controller processes requests in configuration, action, and presentation phases. In each phase, it determines the corresponding element by a naming convention. There is a process by which the UI Controller checks for custom elements.
How the UI Controller Processes Requests
The UI Controller can be reached by invoking the
fatwire/ui/controller SiteCatalog entry. The UI Controller requires the incoming request to provide at least one parameter,
elementName, which determines the controller element to be executed. For example, the following URL invokes the controller element
A controller element is processed in the following three phases:
where each phase consists of running a distinct element. For each phase, the corresponding element name is determined by a naming convention, described below.
A controller element is any element that can be invoked through the UI Controller.
In each of the phases, the UI Controller first tests for the custom element specific to that phase. The process flow is illustrated in the steps of UI Controller Processing an Element Request: Example.
1. Configuration Phase
This phase consists of evaluating the configuration element. The configuration element is meant to contain configuration settings used by the controller element being invoked. The expected element name is
<controllerElementName> is the value of the
elementName parameter. For instance, in our example, where the controller element name is assumed to be
Foo/Bar, the expected name of the configuration element is
The Configuration phase is based on Apache Commons Configuration and requires configuration data to be formatted as a valid XML document. For example:
<myconfig> <foo>123</foo> <bar>foobar</bar> </myconfig>
The XML configuration data is evaluated into a configuration object, that is, an instance of
org.apache.commons.configuration.beanutils.ConfigurationDynaBean, which is kept in the request scope, where it is identified by the name of the XML root element. In our example, the configuration object can be accessed in the Action phase or Presentation phase as follows:
ConfigurationDynaBean configBean = (ConfigurationDynaBean)request.getAttribute("myconfig");
myconfig matches the name of the top-level XML element in the configuration element. More information about Apache commons configuration can be obtained at the following URL:
About Configuration Elements in the Configuration Phase:
The Configuration phase is conditional. If the element
<controllerElementName>Configdoes not exist, the UI Controller skips this phase and moves on to the next phase without creating a configuration object.
Unlike in the other two phases, the configuration element is not evaluated directly (using, for example,
ics.callElement). Instead, it is invoked through the
fatwire/ui/controller/readConfigurationSiteCatalog entry, using
ics.ReadPage(), allowing to capture its output.
While creating the configuration object, the controller checks if there is a custom configuration available for the requested element under CustomElements. If there is one, the controller, by default, merges the custom configuration with the corresponding system configuration. This is the default behavior. If you do not want to merge the custom configuration with the system configuration, specify
merge=falsefor the field resdetails1 or resdetails2 in the ElementCatalog entry for the custom configuration element.
For example, if the system configuration is:
<myconfig> <foo>123</foo> <bar>foobar</bar> </myconfig>
And if the custom configuration is:
<myconfig> <foo1>456</foo1> <bar1>foo1bar1<bar1> </myconfig>
Then the controller merges the system configuration and custom configuration to have the following:
<myconfig> <foo>123</foo> <bar>foobar</bar> <foo1>456</foo1> <bar1>foo1bar1</bar1> </myconfig>
2. Action Phase
In this phase, the UI Controller evaluates the action element. The expected name of the action element is
<controllerElementName>Action. In our example, the action element name is
The action element is meant to contain arbitrary business logic. It typically builds Java objects in the request scope, to be consumed by the next phase.
The Action phase is conditional. If the element
<controllerElementName>Action does not exist, then the UI Controller skips this phase and moves on to the Presentation phase.
3. Presentation Phase
In this last phase, the UI Controller evaluates the presentation element, whose name depends on the content type of the generated output. The UI Controller can serve either HTML (the default behavior) or JSON. The element name would then be
In our example, the UI Controller attempts to evaluate
Foo/BarHtml, because HTML is the default content type. To generate JSON data instead, you must explicitly specify a response type as follows:
In this case, the UI Controller attempts to evaluate the presentation element called
UI Controller Processing an Element Request: Example
When the UI Controller processes any element request, it tests for the custom element as follows:
In each phase (Configuration, Action, and Presentation), the UI Controller first looks for the custom element specific to that phase. If the custom element is not found, the UI Controller looks for the default element. If the default element is not found, the UI Controller skips the phase and moves on to the next phase.
The steps below explain, by example, how the UI Controller processes an element request. In this example, the request is for an existing element named
UI/Layout/LeftNavigation, and the response type is
Configuration Phase. The UI Controller looks for the
LeftNavigationelement's configuration. That is, the UI Controller looks for the element named
ElementCatalog). If the element exists, the UI Controller reads this element. Otherwise, it reads the default element
UI/Layout/). The UI Controller then generates the configuration object and keeps this object in the request scope.
An alternative is to pass the configuration file name as an argument to the UI Controller call. The passed parameter is named
configNameis passed, the UI Controller looks for the element specified in that parameter.
Action Phase. The UI Controller now looks for the element
LeftNavigationAction.jsp. If it finds the element under
CustomElements, the UI Controller executes this element. Otherwise, it executes the default
Presentation Phase. In the current example, the response type is Html. Therefore, the UI Controller looks for the element
LeftNavigationHtml.jsp. If it finds the element under
CustomElements, the UI Controller executes this element to generate an
Htmlresponse. Otherwise, it executes the default
When you are customizing the Contributor interface, remember to store your custom elements in the recommended location. Make sure that you know how the custom elements are located by the UI Controller.
The framework of the Contributor interface allows developers to keep their custom elements separate from the system default elements, in accordance with best practices.
Oracle recommends not modifying the system's default configurations. Instead, create your own custom elements and store them under
CustomElements of the ElementCatalog to ensure their preservation during upgrades.
The path to a custom element depends on whether the element is global, site-specific, site- and asset type- specific, or just asset type-specific. This figure shows paths to custom elements.
Figure 59-2 Paths to Custom Elements
Description of "Figure 59-2 Paths to Custom Elements"
How the UI Controller Locates Elements
When the UI Controller looks for an element:
The UI Controller first looks for the customized version of the element by traversing all paths under
CustomElementsin the following order:
Site-specific and asset type-specific paths
Asset type-specific paths
(For an example of paths, see Figure 59-2.)
If the custom element is not found, the UI Controller uses the system-defined element.
For the UI Controller to use the asset type-specific element, the
assetTypeParam parameter must be passed with a valid asset type as its value.
Element Naming Conventions
When referring to a system-defined element or sample element packaged with WebCenter Sites, this guide provides the full path to the element. The full path always begins with
UI/Layout/. For example, the system-defined element
DashBoardContentsConfig.jsp is presented as follows in this guide:
When referring to a custom-defined element that you create, this guide provides only the name of the element (JSP), given that its path is unknown. For example:
It is assumed that the custom element is stored under