62 Creating Customizable Applications

Oracle Metadata Services (MDS) framework allows you to create customizable Oracle Fusion applications. This chapter describes how to configure your application at design time so that it can be customized by end users.

This chapter includes the following sections:

Section 62.1, "Introduction to Creating Customizable Applications"
Section 62.2, "Preparing an Application for Customizations"
Section 62.3, "Enabling Runtime Customization of Pages and Components"

62.1 Introduction to Creating Customizable Applications

With the customization features provided by Oracle Metadata Services (MDS), both developers and customers can customize Oracle Fusion applications. Customizing an application involves taking a generalized application and making modifications to suit the needs of a particular group, such as a specific industry or site.

When an application is customizable, an end user can customize a user interface page at runtime in one of four ways:

Implicitly: Implicit customizations occur when a customer changes certain component attributes, such as the size of a panel or whether detail content is displayed.
Using Page Composer: Page Composer enables end users who have the correct permissions, such as administrators, to change a user interface page to suit their company's needs, such as change the page layout, add task flows, documents, and other objects to a page, or wire pages to each other, as described in the "Customizing Existing Pages" chapter in the Oracle Fusion Applications Extensibility Guide.
Using the Personalization menu: The Personalization menu in the global area of Oracle Fusion Applications gives an end user access to Page Composer to customize a page to suit their needs. Only the end user sees the changes. End users can also use the Personalization menu to reset a page to display the default content and layout.
Using the Customization Manager: Customization Manager enables end users who have the correct permissions, such as administrators, to download, upload, reset, and delete application customizations on objects such as pages and task flows, as described in the "Viewing and Diagnosing Runtime Customizations" section in the Oracle Fusion Applications Extensibility Guide.

Some customizations, such as changes to the model or to task flow roles, must be done from Oracle JDeveloper, as described in the "Using JDeveloper for Customizations" chapter in the Oracle Fusion Applications Extensibility Guide. Customizations made from JDeveloper are referred to as design-time customizations. Design-time customizations that are created and shipped with Oracle Fusion Applications are known as seeded customizations.

Note:

End users with the correct permissions can also customize some menus, such as the Navigator menu. For more information, see the "Customizing the Navigator Menu" chapter in the Oracle Fusion Applications Extensibility Guide.

For more information about customization, see the "Customizing and Extending Oracle Fusion Applications" chapter in the Oracle Fusion Applications Extensibility Guide.

A customized application contains a base application and one or more layers of customized metadata content. The customized metadata objects are stored in an MDS repository and, when a customized application is launched, the customized content is retrieved and applied over the base content. For more information, see the "Customizing Applications with MDS" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition) and the "Managing the Metadata Repository" chapter in the Oracle Fusion Applications Administrator's Guide.

Note:

When you run your page in JDeveloper, all customizations created at runtime are, by default, written to a simulated MDS repository directory, which is stored at a temporary location in your system directory. The simulated MDS repository that is configured for the application reflects the metadata information that is contained in the Metadata Archive (MAR).

For more information, see Section 53.2.1, "How to Deploy an Application with Metadata to Integrated WebLogic Server."

To enable runtime customizations of an application, you first prepare the application for customizations, then you enable the runtime customization of pages and components.

62.2 Preparing an Application for Customizations

To enable an application for customization, you must complete the following steps in your JDeveloper application workspace in the order shown.

Set project properties to enable user and seeded customizations.
Configure the persistence change manager parameter to use the composer change manger.
Enable end-user translations of customized strings.
Add Oracle WebCenter Portal — Composer technology scope to your project. This technology scope contains the components that are used for Page Composer customization.
(Optional) Enable user customization of the user interface (UI) shell template.
(Optional) Create an IDE connection to your database (in addition to the application connection) to enable access to layer values that are populated from a database call.

After you complete these steps, you can enable runtime customization for the application's web pages and task flows as described in Section 62.3, "Enabling Runtime Customization of Pages and Components."

62.2.1 How to Set Project Properties to Enable User and Seeded Customizations

To enable user customizations, you must configure the view project to persist the customized metadata objects to a MDS repository so that the objects are available across sessions. You must also enable seeded customizations so that the page fragments and JSPX pages that you create will be configured to allow customizations.

Note:

ADF components (such as controller, model, and business components objects) must have a unique identifier so that they can be customized. ADF components that are generated by JDeveloper are created with identifiers by default, with the exception of fragments and pages in your user interface projects. To cause JDeveloper to generate identifiers for components on pages that you create in your user interface projects, you must explicitly specify this at the project level by enabling seeded customizations.

To set project properties for your view project:

In the Application Navigator in JDeveloper, right-click your view project and choose Project Properties.
In the Project Properties dialog, select ADF View to display the ADF View settings.
Select Enable User Customizations and select Across Sessions Using MDS, as shown in Figure 62-1.
Select Enable Seeded Customizations.

Figure 62-1 Project Properties — ADF View
Click OK.

62.2.2 How to Configure the Persistence Change Manager

You must configure the persistence change manager in order for the following runtime behavior to occur:

The Persist and Don't Persist attributes that you set for components at design time will govern which implicit changes that the end users make at runtime will be persisted during the session as well as across sessions.
The changes that end users make in the design view of Page Composer will be stored in the MDS repository.

When you enabled user customizations across sessions by completing the procedure in Section 62.2.1, "How to Set Project Properties to Enable User and Seeded Customizations," the IDE added the CHANGE_PERSISTENCE context parameter to the view project's web.xml file, and set the parameter to use the filtered persistence change manager. You must modify this parameter to use the composer change manager, and you must add the composer filter and its mapping.

Before you begin:

Modify your view project's properties to enable user customizations across sessions as described in Section 62.2.1, "How to Set Project Properties to Enable User and Seeded Customizations."

To configure the persistence change manager:

In the Application Navigator, expand the WEB-INF node for your view project and double-click web.xml.

In the source editor, change the org.apache.myfaces.trinidad.CHANGE_PERSISTENCE context parameter value to oracle.adf.view.page.editor.change.ComposerChangeManager, as shown in the following code.

<context-param>
  <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
  <param-value>
    oracle.adf.view.page.editor.change.ComposerChangeManager
  </param-value>
</context-param>

Add the filter and filter-mapping elements for the WebCenterComposerFilter class as shown in bold in Example 62-1.

Note:

Filters must be configured in the following order.

JpsFilter
ApplSessionFilter
WebCenterComposerFilter
ADFBindingFilter

Example 62-1 composerFilter and Mappings in web.xml

....
  <!-- composerFilter goes here -->
  <filter>
    <filter-name>composerFilter</filter-name>
    <filter-class>
      oracle.adf.view.page.editor.webapp.WebCenterComposerFilter
    </filter-class>
  </filter>
  <filter>
    <filter-name>adfBindings</filter-name>
    <filter-class>oracle.adf.model.servlet.ADFBindingFilter</filter-class>
  </filter>
.....

  <!-- composerFilter mapping goes here -->
  <filter-mapping>
    <filter-name>composerFilter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>
  <filter-mapping>
    <filter-name>adfBindings</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>
....

Enable sessions for the JSPX pages and task flows that you create in your view project as described in Section 48.2.1, "How to Configure Your Project to Use Application User Sessions."

This step, among other modifications, adds the Applications Core and Web Service Data Control libraries to your project, which you need to complete the tasks to prepare your application for customization.

62.2.3 How to Enable Translations of Customized Strings

You must configure your application to enable end users to provide translated values for customized strings at runtime, as described in the "Translating Custom Text" chapter in the Oracle Fusion Applications Extensibility Guide.

The resource string editor enables the runtime editing of strings. The changes made using the resource string editor are saved into an application override bundle, which can be translated and imported back into the application.

For more information about configuring the runtime resource string editor, see the "Configuring Runtime Resource String Editing" section in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

Note:

This procedure only enables resource string editing if the changes are customizations and not user personalizations, as user personalizations do not need to be translated.

To set up runtime resource string editing for customizations:

In the Application Navigator in JDeveloper, right-click the application and select Application Properties.
In the Application Properties dialog, select Resource Bundles.
Click Add.
Type the following string in the File Name field in the Select Resource Bundle dialog.
```
oracle.adf.view.page.editor.resource.ComposerOverrideBundle.xlf
```
Click Open.
Select the Overridden check box.
Click OK to save your changes.
Open the adf-config.xml file, which is located in the Application Resources > Descriptors > ADF META_INF folder.

Add the resource-string-editor element shown in Example 62-2 to the page-editor-config section to enable resource string editing.

Example 62-2 Configuration to Turn On Resource Editor

<pe:page-editor-config>
  ...
  <resource-string-editor>
    <enabled>
      #{GlobalAreaBackingBean.tipLayerNonUser}
    </enabled>
  </resource-string-editor>
</pe:page-editor-config>

62.2.4 How to Add Composer Technology Scope to Your Project

You must add the Oracle WebCenter Portal — Composer technology scope in order to access the technologies for consuming Page Composer components and enabling runtime customization.

To add Composer technology scope:

Right-click your view project and select Project Properties.
Select Technology Scope.
Add the Oracle WebCenter Portal — Composer technology scope to your project and click OK.

62.2.5 How to Enable the User Customization of the UI Shell Template

You can configure the UI Shell template so that it can be customizable out-of-the-box. This functionality enables customers to use Page Composer to customize UI Shell pages, as described in the "Customizing Existing Pages" chapter in the Oracle Fusion Applications Extensibility Guide.

To enable users to customize the UI shell template, you add a link or button to the page fragment from which you want end users to launch the UI Shell template for editing. You then configure the link (or button) to enable end users to modify the template.

To enable the user customization of the UI Shell Template:

From JDeveloper, open the JSF page fragment (.jsff) from where the UI Shell can be edited.
In the Application Navigator, expand the Data Controls hierarchy to locate and expand the FndUIShellController.
Drag and drop the customizeUIShellTemplate operation onto the page, and choose Create > Method > ADF Button or choose Create > Method > ADF Link.
In the Edit Action Binding dialog, provide a comma delimited list of fully packaged qualified customization classes for the custClass parameter, as shown in Example 62-3.
Example 62-3 Sample custClass List
```
oracle.apps.fnd.applcore.customization.GlobalCC,oracle.apps.fnd.applcore.customization.SiteCC
```
Each of the customization classes supplied in the list must be valid and configured in the adf-config.xml file, as shown in Figure 62-2.

Figure 62-2 adf-config.xml — Customization Classes

If any of the classes cannot be instantiated, or if they are not pre-configured in the adf-config.xml file, an exception is thrown at runtime.

The last customization class specified is the tip customization layer and the modifications to the UI Shell is written to this layer. In Example 62-3, the customization of the UI Shell takes place in SiteCC. The purpose of the earlier customization in the list is to view the UI Shell with any other customizations applied.

For information about customization layers, see the "Understanding Customization Layers" section in the Oracle Fusion Applications Extensibility Guide.
Click OK.
Open the page definition file for the page fragment.
In the editor window, click the Source tab.

Add the <methodAction> element shown in Example 62-4 to the <bindings> element. The id attribute must be set to custNavigate, which is the key to the customizeUIShellTemplate operation that you dropped on the page in Step 3.

Example 62-4 custNavigate methodAction Binding

<bindings>
    <methodAction id="custNavigate" RequiresUpdateModel="true"
                  Action="invokeMethod" MethodName="navigate"
                  IsViewObjectMethod="false" DataControl="FndUIShellController"
                  InstanceName="FndUIShellController.dataProvider"
                  ReturnName=
"FndUIShellController.methodResults.navigate_FndUIShellController_dataProvider_navigate_result">
      <NamedData NDName="viewId" NDValue="TemplateCustomizationUIShell"
                 NDType="java.lang.String"/>
      <NamedData NDName="webApp" NDType="java.lang.String"/>
      <NamedData NDName="pageParametersList" NDType="java.lang.String"/>
      <NamedData NDName="navTaskFlowId" NDType="java.lang.String"/>
      <NamedData NDName="navTaskKeyList" NDType="java.lang.String"/>
      <NamedData NDName="navTaskParametersList" NDType="java.lang.String"/>
      <NamedData NDName="navTaskLabel" NDType="java.lang.String"/>
      <NamedData NDName="methodParameters"
  NDType="oracle.apps.fnd.applcore.patterns.uishell.ui.bean.FndMethodParameters"/>
    </methodAction>
  </bindings>

Add the view permission for oracle_apps_fnd_applcore_template_customization_TemplateCustomizationUIShellPageDef (the customization page) for each role for which you want to enable the view action as described in Section 62.3.4, "How to Authorize the Runtime Customization of Pages and Task Flows." To access oracle_apps_fnd_applcore_template_customization_TemplateCustomizationUIShellPageDef in the Resource Grants navigation tab, select Web Page from the Resource Type dropdown list and select Show web pages imported from ADF libraries.

62.2.6 How to Create a Database Connection at the IDE Level

In addition to the application level connection to your application database, you might also need to create an Integrated Development Environment (IDE) connection.

The IDE connection is required when implementing design-time customizations from JDeveloper, as described in the "Using JDeveloper for Customizations" chapter in the Oracle Fusion Applications Extensibility Guide.

To create a database connection at the IDE level

From the Database Navigator, right-click the ApplicationDB node under your application's node and choose Properties.
Make a note of the settings and click Cancel.
Right-click IDE Connections and choose New Connection.
Enter the settings that you noted in Step 2.
Click Test Connection to ensure the settings are correct.
Click OK.

The database connection appears under the IDE Connections node.

62.3 Enabling Runtime Customization of Pages and Components

Once you have completed the non-optional procedures described in Section 62.2, "Preparing an Application for Customizations," you can enable pages, task flows, and components for runtime customization.

To enable an application's pages, task flows, and components for runtime customization:

Enable runtime customization of web pages.
Enable end-user personalization for the desired pages.
(Optional) Restrict customizations of specific page fragments and components. (By default customization is allowed for pages, page fragments, and components on a page.)
Authorize runtime customization of pages and task flows.
(Optional) Enable and disable persistence of attributes for implicit runtime customizations.

As shown in Figure 62-3, the settings that you make by following the procedures in this section affect whether an end user can customize an object under the following scenarios:

User performs an implicit customizations: If the component can be persisted and customization is allowed, the implicit customization is persisted for the session as well as across sessions.
User accesses Customization Manager: If the end user has an administrative role or privilege, the user can access the Customization Manager. If the task flow has edit permissions for a user's role or privilege, the user can import, export, or delete customizations of objects for which customization is allowed.
User accesses Page Composer to customize a page: If the end user has an administrative role or privilege and customization is allowed for the page (JSPX root), the user can access Page Composer. If the task flow has edit permissions for the user's role or privilege, the user can customize any object for which customization is allowed.
User accesses Page Composer to personalize a page: If the page enabled for end-user personalizations and customization is allowed for the page (JSPX root), the user can access the page in Page Composer. If the task flow has edit permissions for the user's role or privilege, the user can customize any object for which customization is allowed.
User accesses Page Composer to reset content and layout: If customization is allowed for the page and the task flow has edit permissions for the user's role or privilege, the user can reset the content and layout for which customization is allowed.

To determine whether customization is allowed, the application looks at the component's Customization Allowed property to see if it has an explicit value. If there is no explicit value, the application looks at the parent object and continues up the tree, ending at the JSF page fragment (.jsff root), until it finds an explicit value. For example, if Customization Allowed is not set for a component, but is set to true for the page fragment, then customization is allowed for the component. However, if Customization Allowed is false for the component, the application disallows customization of that object, even if the page fragment's Customization Allowed property is set to true. Conversely, if the page fragment's Customization Allowed property is set to false, but a component's property is set to true, the end user can customize the component.

By default the Customization Allowed property for the page (.jspx) root is true. Therefore, you must explicitly set Customization Allowed to false at some level, such as for a component, region, fragment (.jsff), or page (.jspx), to disallow customization for that object and its children objects.

Note:

You can optionally use the Customization Allowed By property to permit customizations only for certain roles.

Figure 62-3 Runtime Effects of Customization Settings

62.3.1 How to Enable Pages for Runtime Customization

Perform the following steps to enable runtime customization of a web page using Page Composer:

Ensure that the customizable pages have page definition files.
Make pages runtime editable by adding Page Composer components to the pages.
If you are enabling the runtime addition of content, set up a resource catalog.
(Optional) Set up a default catalog definition file to facilitate testing.

62.3.1.1 Ensuring Customizable Pages Have Page Definitions

Page definition files define the binding objects that populate data the data in UI components at runtime. A page definition is required for runtime customizations that add additional components such as task flows and portlets. Page definition files can be found under Projects > View Controller > Application Sources > oracle.apps.view. If a required page definition file does not exist, complete the following steps to create one.

To create a page definition file for a JSPX page:

In the Application Navigator, right-click the JSPX page and choose Go to Page Definition.
If the page does not have a page definition, a Confirm Create New Page Definition dialog appears. Click Yes to create the page.

62.3.1.2 Making a JSPX Document Editable at Runtime

To make a JSPX document editable at runtime, you add Composer components to the page at design time. You use the Panel Customizable component to define an area of the page onto which users can add components at runtime. You use the Layout Customizable component to enable users to lay out its child components in several predefined ways, such as two-column or three-column.

The Layout Customizable and Panel Customizable components are from the Oracle WebCenter Portal — Composer technology scope, which you added when you completed the steps in Section 62.2.4, "How to Add Composer Technology Scope to Your Project," and which are available from the Composer page in the Component Palette.

For more information about the Panel Customizable and Layout Customizable components, see the "Composer Components" section in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

62.3.1.3 Setting Up a Resource Catalog

If you have a Panel Customizable component on your page to enable the runtime addition of content, you must set up a resource catalog to list the available content.

To learn how to create a custom resource catalog, see the "Creating and Managing Resource Catalogs" chapter in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

62.3.1.4 Using the Default Catalog Definition File for Testing

A considerable amount of work is involved in setting up a resource catalog. If you want to test runtime customizations before you finish setting up your catalog, you can use the default catalog definition file.

To use the default catalog for testing:

Create the application_root/ViewController/src/oracle/adf/rc/metadata directory structure.
Copy the Oracle WebCenter Portal default catalog definition file default-catalog.xml to the newly created application_root/ViewController/src/oracle/adf/rc/metadata directory.

Caution:

The Oracle WebCenter Portal default catalog should only be used for testing purposes. You must create your own catalog for production purposes.

62.3.2 How to Enable End-User Personalizations for a Page

Control whether an end user can personalize a page by setting the page's isPersonalizableInComposer property.

Note:

You must enable personalizations for all your dashboards. However, workareas should have personalizations enabled only if absolutely required.

To enable end-user personalizations:

In the Application Navigator, select the .jspx page.
In the Structure window, select the af:pageTemplate component.
In the Property Inspector, select true from the isPersonalizableInComposer dropdown list.

62.3.3 How to Restrict Customization of a Page, Page Fragment, or Component

Customization is enabled for pages, page fragments, and components by default. However, there might be situations where you want to prevent customization for some objects.

You can specify at the page, page fragment, or component level whether customizations for a component are permitted at runtime and who is permitted to customize that component.

Before you begin:

Review the introduction to Section 62.3, "Enabling Runtime Customization of Pages and Components" to understand how the application uses the value of the Customization Allowed property to determine whether an object can be customized.

To restrict customization of a page, page fragment, or component:

In the Application Navigator, select the page or fragment for which you want to edit customization properties.
If you are restricting the customization of a component, select the component in the Structure window.
If the Property Inspector is not open, choose Property Inspector from the View menu.
In the Property Inspector, expand Customization.
Set the appropriate customization attribute.
- To disable runtime customization, set Customization Allowed to false.
- To restrict customization to specific sets of users and layers, set Customization Allowed By to a space-separated list of the security roles for which you wish to permit customization.

For more information about these attributes, see the "Extended Metadata Properties" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).

For information about customization layers, see the "Understanding Customization Layers" section in the Oracle Fusion Applications Extensibility Guide.

62.3.4 How to Authorize the Runtime Customization of Pages and Task Flows

As illustrated in Figure 62-3 a user can edit customizable components in a user interface page at runtime only if they have permission to edit the page and permission to edit the task flow that contains the component. For example, an end user can only customize components in a task flow using Page Composer if that user has permission to customize the task flow. You use the jazn-data.xml file to define which roles can edit the page or task flow.

Before you begin:

Enable the desired pages for editing in Page Composer as described in Section 62.3, "Enabling Runtime Customization of Pages and Components."

To authorize pages and task flows for runtime customizations:

In the Application Resources panel, expand Descriptors, expand META-INF nodes, and then double-click jazn-data.xml.

Tip:

If the jazn-data.xml file does not exist, you can create it by right-clicking the META-INF node, selecting New Oracle Deployment Descriptor, selecting jazn-data.xml, and then clicking Finish.
In the overview editor, click the Resource Grants navigation tab, as shown in Figure 62-4.

Figure 62-4 Resource Grants Tab in jazn-data.xml Overview
Select Web Page from the Resource Type dropdown list.

You use the Web Page resource type for both web pages and page fragments.
Set the Source Project to ViewController.
For each Page Composer enabled web page, select the Customize action for each role for which you want to enable page customization.

You must also authorize customization for the task flows, as described in the following two steps.
Select Task Flow from the Resource Type dropdown list.
For each task flow, select the Customize action for each role for which you want to enable customization of the components in the task flow.
If you want the task lists that are exposed in your pages to be customizable for your application, select the entry for TaskList in the Resources list, and, for each role for which you want to enable task list customization, select the customize and grant actions.

For more information, see the "Implementing Task Flow Security" section in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter Portal.

62.3.5 How to Persist Implicit Runtime Customizations

Certain ADF Faces components have attributes that can be saved during a user session. For example, if a user expands a panel box component, the box will be expanded when the user returns to the page. This type of change is referred to as implicit runtime customization. For information about which component properties can be persisted, see the "Allowing User Customizations at Runtime" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).

In Section 62.2.1, "How to Set Project Properties to Enable User and Seeded Customizations," you configured the application to persist implicit runtime customizations across sessions as well as within sessions.

The attributes that can be persisted are set in the tag library, but you can override these settings. For example, you might not want the end users to change column widths, but you want all other default attribute changes for columns to be persisted. You set and unset these values in the Overview Editor for the adf-config.xml file, as described in the "Configuring User Customizations" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition). You can also override these settings for specific components, as described in the "Controlling User Customizations in Individual JSF Pages" section in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework (Oracle Fusion Applications Edition).