| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.1.5) Part Number E15524-01 |
|
|
View PDF |
| Oracle® Fusion Applications Developer's Guide 11g Release 1 (11.1.1.5) Part Number E15524-01 |
|
|
View PDF |
Oracle Metadata Services (MDS) framework allows you to create customizable applications. This chapter describes how to configure your application at design time so that it can be customized.
This chapter also provides information about how to perform runtime customizations.
This chapter includes the following sections:
Section 61.1, "Introduction to Creating Customizable Applications"
Section 61.2, "Setting Project Properties to Enable User and Seeded Customizations"
Section 61.5, "Authorizing Runtime Customization of Pages and Task Flows"
Section 61.6, "Restricting Customization for a Specific Component on a Page"
Section 61.7, "Configuring Runtime Resource String Editing for Customizations"
Section 61.9, "Enabling User Customization of the UI Shell Template"
Section 61.10, "Creating a Database Connection at the IDE Level"
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.
A customized application contains a base application and one or more layers of customized metadata content. MDS stores the customized metadata objects in a metadata repository and retrieves them at run time to reveal the customized application. When a customized application is launched, the customized content is applied over the base content.
For more information about MDS repositories (database and file-based) and metadata archives (MAR), see the "Managing the Metadata Repository" chapter in the Oracle Fusion Applications Administrator's Guide. For more information about customization, see the "Customizing Applications with MDS" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework. For information about the ways in which developers and end users can customize the application, see the "Customizing and Extending Oracle Fusion Applications" chapter in the Oracle Fusion Applications Extensibility Guide.
You must perform the following tasks in the order shown in your JDeveloper application workspace to ensure that your pages can be customized by customers. You must complete all the non-optional tasks.
Set project properties to enable user and seeded customizations.
Configure the persistence change manager parameter to use the composer change manger.
Define the customization layers and their order of precedence.
Authorize runtime customization of pages and task flows.
(Optional) Restrict customizations for specific components on a page.
Set up resource bundles for translation.
Enable application pages for runtime customization.
(Optional) Enable user customization of the user interface (UI) shell template.
Create an IDE connection to your database (in addition to the application connection) to enable access to layer values.
Once the application is configured to enable customizations, customizations can be created in two different ways:
At design time using JDeveloper, also known as design-time customization.
Design-time customizations that are created and shipped with Oracle Fusion Applications are known as seeded customizations.
At runtime using Oracle Composer or Oracle Application Development Framework (ADF) implicit customizations, also known as runtime customizations.
End users are also able to customize the navigator menu that displays in the UI Shell global area.
To allow JDeveloper-based and Oracle Composer-based customizations for your application, you must enable user and seeded customizations.
To enable user customization, you must configure the view project to allow user customizations, and 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 61-1.
Select Enable Seeded Customizations.
Click OK.
Before you can define customization layers, you must configure the persistence change manager parameter to use the composer change manger
When you enabled user customizations across sessions using MDS by completing the procedure in Section 61.2, "Setting 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 using MDS as described in Section 61.2, "Setting Project Properties to Enable User and Seeded Customizations."
To configure the persistence change manager:
Expand the WEB-INF node for your view project, right-click the web.xml node and choose Open.
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 61-1.
Note:
Filters must be configured in the following order.JpsFilter
ApplSessionFilter
WebCenterComposerFilter
ADFBindingFilter
Example 61-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.
A customizable application can have multiple customization layers, such as Global, Site, and User. You need to define the application's customization layers and their order of precedence.
For information about customization layers, see the "Understanding Customization Layers" section in the Oracle Fusion Applications Extensibility Guide.
When a user opens an application page in a browser, the page opens in view mode. Additionally, Oracle Composer provides access to another mode that enables users with appropriate privileges to customize and personalize application pages and to save the changes as customizations that are available for all users accessing the page. Users can also be granted the privilege to edit a task flow at runtime.
For information about using Oracle Composer to customize pages, see the "Customizing Existing Pages" chapter of the Oracle Fusion Applications Extensibility Guide.
You modify the resource grants in the jazn-data.xml file to authorize runtime customization of pages and task flows.
To authorize pages and task flows for runtime customizations:
Open the jazn-data.xml file, which is located in Application Resources > Descriptors > META-INF.
Tip:
If thejazn-data.xml file does not exist, you can create it by right-clicking the META-INF folder, selecting New Oracle Deployment Descriptor, selecting jazn-data.xml, and clicking Finish.In the overview editor, click the Resource Grants navigation tab, as shown in Figure 61-2.
Select Web Page from the Resource Type dropdown list.
Set the Source Project to ViewController.
For each Oracle Composer enabled web page, select the Customize and Personalize action for each role for which you want to enable page customization.
Select Task Flow from the Resource Type dropdown list.
For each task flow that Oracle Composer can customize in your application, select the Customize and Personalize actions for each role for which you want to enable task flow customization.
For more information, see the "Implementing Task Flow Security" section in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
Customization is enabled for all components on a page by default. However, there might be situations where you want to prevent customization for some of the components on a page.
You can specify at the component level whether customizations for the component are permitted at runtime and who is permitted to customize that component.
How to restrict customization for a page component:
In the Application Navigator, select the page or fragment for which you want to edit customization properties.
In the Structure window, select the component for which you wish to restrict customization.
If the Property Inspector is not open, choose Property Inspector from the View menu.
In the Property Inspector, expand the Customization node.
Set the appropriate customization attribute.
To disable customization of a component at runtime, 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.
The resource string editor enables 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.
You must configure your application to enable runtime resource string editing of translated values for customizations.
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.
In the File Name field in the Select Resource Bundle dialog, type oracle.adf.view.page.editor.resource.ComposerOverrideBundle.xlf, and 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 61-2 to the page-editor-config section to enable resource string editing.
This setting only enables resource string editing if the changes are customizations and not user personalizations, as user personalizations do not need to be translated.
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.
Pages can be customized at runtime using Oracle Composer.
You must perform the following steps to enable runtime customization of a web page using Oracle Composer:
Add the Oracle Composer technology scope to your project.
Prepare your page for end-user personalizations.
Ensure that the customizable pages have page definition files.
Make pages runtime editable by adding Oracle 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.
(Optional) Persist elements and properties across sessions outside of Oracle Composer.
You must add the Oracle Composer technology scope in order to access the technologies for consuming Oracle Composer components and enabling runtime customization.
To add Oracle Composer technology scope:
Right-click your view project and select Project Properties.
Select Technology Scope.
Add the Oracle Composer technology scope to your project and click OK.
You 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 pane, select the af:pageTemplate node.
In the Property Inspector, select true from the isPersonalizableInComposer dropdown list.
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.
To make a JSPX document editable at runtime, you add Oracle 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 Composer technology scope, which you added when you completed the steps in Section 61.8.1.1, "Adding Oracle Composer Technology Scope to Your Project," and which are available from the Oracle Composer page in the Component Palette.
For more information about the Panel Customizable and Layout Customizable components, see the "Oracle Composer Components" section in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
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.
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 default catalog definition file default-catalog.xml to the newly created <application-root>/ViewController/src/oracle/adf/rc/metadata directory.
Caution:
The Oracle WebCenter default catalog should only be used for testing purposes. You must create your own catalog for production purposes.Certain ADF Faces components have attributes that can be saved during a user session. For example, whether the user left a panel box component expanded or collapsed. This type of change is referred to as implicit customization.
In Section 61.2, "Setting Project Properties to Enable User and Seeded Customizations," you configured the application to persist user customizations across sessions. This enables you to configure attributes to be saved across sessions. For information about how to configure the persistence of component attribute values, see the "Allowing User Customizations at Runtime" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
You can configure the UI Shell template so that it can be customizable out-of-the-box. This functionality enables customers to use Oracle 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 that launches the UI Shell template that allows the UI Shell template to be customized from Oracle Composer.
To add a link to a page fragment:
From JDeveloper, open the 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 61-3.
Example 61-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 61-3.
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 61-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.
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 61-4 to the <bindings> element. If you are enabling the customization of a UI Shell page other than TemplateCustomizationUIShell, change the viewID value to the view ID for that page.
Example 61-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>
If you are enabling the customization of a UI Shell page in another application, provide the values for the viewId, webApp, and pageParametersList, as shown in Example 61-5. For more information about these values, see Table 14-15.
Example 61-5 Example of viewId, webApp, and pageParametersList Values
<NamedData NDName="viewId" NDValue="specialUIShellPage"
NDType="java.lang.String"/>
<NamedData NDName="webApp" NDValue="commonApp"
NDType="java.lang.String"/>
<NamedData NDName="pageParametersList" NDValue="taskflow1"
NDType="java.lang.String"/>
In addition to the application level connection to your application database, you might also need to create an IDE level connection.
The IDE level 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.
You create the IDE level connection from the Database Navigator.
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.
While Oracle Composer enables user interface customizations, other customizations, such as changes to the model or task flow roles, must be done from JDeveloper. For information about implementing design-time customizations from JDeveloper, see the "Using JDeveloper for Customizations" chapter in the Oracle Fusion Applications Extensibility Guide.
You can implement the following types of runtime customizations:
Implicit runtime customizations: These are runtime customizations that are based on the user's behavior, such as saving an entered value or remembering whether the user last expanded or collapsed a panel.
For information about implementing implicit runtime customizations, see the "Allowing User Customizations at Runtime" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
For information about saving user customizations across sessions, see Section 61.8.1.7, "Configuring the Persistence of Implicit Runtime Customizations."
Explicit runtime customizations: These are customizations that the user explicitly implements by running a customization tool. For information about implementing explicit runtime customizations, see the Oracle Fusion Applications Extensibility Guide.
For information about building editable pages, see the "Allowing User Customizations at Runtime" chapter in the Oracle Fusion Middleware Developer's Guide for Oracle WebCenter.
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).The navigator menu is the global menu that displays in the UI Shell global area, and is displayed when you click Navigator buttons or links in the UI Shell, as shown in Figure 61-4.
A user with the required privileges can perform the following tasks to customize the menu at the Site level:
Add, delete, or edit a group
Add, delete, or edit an item
Specify navigation
Navigate to a taskflow in the application
Navigate to a URL
Hide a group or an item or show a hidden group or item
Note:
You cannot customize the Home menu or the Preferences menu.For more information, see the "Customizing the Navigator Menu" chapter in the Oracle Fusion Applications Extensibility Guide.
|
 Copyright © 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
