58 Understanding the Contributor Interface Framework and UI Controller

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 58-1 Contributor Interface Framework

Description of Figure 58-1 follows
Description of "Figure 58-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.

UI Controller

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 Foo/Bar:


A controller element is processed in the following three phases:

  1. Configuration phase

  2. Action phase

  3. Presentation phase

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>Config, where <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 Foo/BarConfig.

The Configuration phase is based on Apache Commons Configuration and requires configuration data to be formatted as a valid XML document. For example:


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");

where 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: http://commons.apache.org/configuration.


About Configuration Elements in the Configuration Phase:

  1. The Configuration phase is conditional. If the element <controllerElementName>Config does not exist, the UI Controller skips this phase and moves on to the next phase without creating a configuration object.

  2. 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/readConfiguration SiteCatalog entry, using ics.ReadPage(), allowing to capture its output.

  3. 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=false for the field resdetails1 or resdetails2 in the ElementCatalog entry for the custom configuration element.

    For example, if the system configuration is:


    And if the custom configuration is:


    Then the controller merges the system configuration and custom configuration to have the following:


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 Foo/BarAction.

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 <controllerElementName>Html or <controllerElementName>Json.

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 Foo/BarJson.

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 Html:

  1. Configuration Phase. The UI Controller looks for the LeftNavigation element's configuration. That is, the UI Controller looks for the element named LeftNavigationConfig.jsp under CustomElements (in the ElementCatalog). If the element exists, the UI Controller reads this element. Otherwise, it reads the default element LeftNavigationConfig.jsp (in 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 configName. If configName is passed, the UI Controller looks for the element specified in that parameter.

  2. 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 LeftNavigationAction.jsp element (in UI/Layout/).

  3. 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 Html response. Otherwise, it executes the default LeftNavigationHtml.jsp element (in UI/Layout/).

Custom Elements

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.


Element Storage

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 58-2 Paths to Custom Elements

Description of Figure 58-2 follows
Description of "Figure 58-2 Paths to Custom Elements"

How the UI Controller Locates Elements

When the UI Controller looks for an element:

  1. The UI Controller first looks for the customized version of the element by traversing all paths under CustomElements in the following order:

    1. Site-specific and asset type-specific paths

    2. Asset type-specific paths

    3. Site-specific paths

    4. Global paths

    (For an example of paths, see Figure 58-2.)

  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 CustomElements.