| Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter 11g Release 1 (11.1.1) E10148-02 |
|
 Previous |
 Next |
| Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter 11g Release 1 (11.1.1) E10148-02 |
|
Previous |
Next |
Oracle Composer provides an easy-to-use, declarative, and programmable extensibility mechanism for customizing runtime editing to fit your application requirements. This chapter describes how to extend Oracle Composer runtime editing capabilities to suit your business needs and enhance the end-user customization experience. It contains the following sections:
Section 5.4, "Configuring Event Handlers for Oracle Composer UI Events"
Section 5.8, "Overriding Default Security Behavior of Oracle Composer Components"
Oracle Composer provides a framework on which to build customizable application pages. In addition to its default capabilities, you can extend the Oracle Composer framework to augment the runtime capabilities available to end users.
This section describes the options available for extending Oracle Composer runtime capabilities declaratively. It contains the following subsections:
Typically, add-ons are custom task flows that are rendered as buttons on the Oracle Composer toolbar. The Page Properties and Reset Page buttons are examples of add-ons on the Oracle Composer toolbar. Click these buttons to display panels for editing page properties and resetting page customizations. You can create add-ons that appear along with or in place of the Page Properties and Reset Page add-ons. For example, you can create a Revision History add-on, which displays a Revisions button on the toolbar. Clicking this button displays the page revision history.
The process of creating Oracle Composer add-ons includes creating them as task flows, packaging them into JAR files, and defining them in the Oracle Composer extension file. For more information, see Section 5.2, "Creating Oracle Composer Add-Ons."
You can create and register custom property panels with Oracle Composer and include them as additional tabs in the Component Properties dialog box. The default Component Properties dialog in Oracle Composer is analogous to the Oracle JDeveloper Property Inspector. The Component Properties dialog displays categories of attributes on different tabs. You can create and register custom property panels for a component, populate them with categories of component properties, and render them as tabs along with the default tabs in the Component Properties dialog.
The process of creating custom property panels includes creating them as task flows, packaging them into JAR files, and defining them in the Oracle Composer extension file. For more information, see Section 5.3, "Creating Custom Property Panels."
Oracle Composer provides an intuitive user interface for editing pages at runtime. This includes such UI components as the Save, Close, and Delete buttons. Sometimes it is necessary to provide additional user interactions that augment Oracle Composer's innate capabilities. For example, when a user clicks Save, in addition to the save operation that Oracle Composer provides by default, you might want to configure the application to perform additional workflows. You can accomplish this with event handlers. An event handler is the code that is called back by Oracle Composer when a particular composer event is invoked. For more information, see Section 5.4, "Configuring Event Handlers for Oracle Composer UI Events."
The Component Properties dialog displays properties with editable values. Depending on what properties you want to expose, you can define filters declaratively to hide certain properties, show hidden properties, or filter properties dynamically using Expression Language (EL). For more information, see Section 5.5, "Defining Property Filters."
You can define criteria for applying customizations to your application's metadata objects. For example, you can define customizations that come into play depending on a user's assigned permissions, an application's deployment location (also known as localization), or a specific industry domain. Each criterion denotes a customization layer and is depicted using a CustomizationClass. A CustomizationClass is the interface MDS uses to identify the customization layer to be overlaid on the base definition. For an example, see Section 5.6.1.3, "How to Create a Custom UserCC Tip Layer."
When you implement a CustomizationClass, you must register it with the MDS. The MDS provides a means of associating a list of CustomizationClass types with a single MetadataObject. This is called the fine-grained association. The MDS also provides the means of associating a list of CustomizationClass types with a set of MetadataObjects. This is called the coarse-grained association. For information about the MDS-specific configurations, Section 5.6, "Performing MDS-Specific Configurations."
Typically, in a custom WebCenter application that uses a file system to store metadata, runtime customizations are saved immediately in the application-root/mds directory. Changes made in both View and Edit modes are saved in this way. However, in certain circumstances, you might first want to apply the customizations in your view and evaluate whether to keep or cancel the changes before actually saving them to the back end.
Customizations can be stored in a file system repository or database repository. If you are using a database repository to store customizations, then you can configure Oracle Composer to create a sandbox. A sandbox is a temporary storage area for saving runtime page customizations before they are either saved to the back end or canceled.
Customizations made in View mode are saved to the back end immediately. Because such changes are available only to the user performing the customizations, there is no particular value in reviewing such changes before saving.
Because Edit mode customizations are available to all users who access the page, you might want to enable a sandbox so that you can experiment with page customizations and assess them before committing them. If you enable a sandbox for the application, a Save button is displayed on the Oracle Composer toolbar in both Design view and Source view of the page.
For information about enabling and using the sandbox, see Section 5.7, "Using Oracle Composer Sandbox."
Before you start with the extensibility configurations described in this chapter, there are two important configuration files that you must know about. Most of the extensions discussed in this chapter are defined in these files:
Oracle Composer extension file (pe_xet.xml)
The pe_ext.xml file is not available in your application by default. You must create it the first time you perform such tasks as including add-ons, property panels, or event handlers. Create this file in the META-INF directory under the project's Web context root. In addition to your application having a pe_ext.xml file, each JAR that your application includes on its classpath can also have a pe_ext.xml file. All of these JARs are searched on application startup. Every JAR with a pe_ext.xml in its META-INF folder is processed, and the Composer extensions are loaded and combined. For information about the different elements you can define in pe_ext.xml to extend Oracle Composer capabilities, see Section B.2.1, "pe_ext.xml."
Application's adf-config.xml file
When you create your application, the adf-config.xml file is created automatically. The adf-config.xml file is located in the ADF META-INF folder under Descriptors in the Application Resources panel. When you perform such tasks as registering new add-ons and custom property panels, or creating customization layers, you must include the required entries in the adf-config.xml file.
For information about the Oracle Composer-specific configurations you can make in adf-config.xml, see Section B.2.2, "adf-config.xml."
Oracle Composer provides the following default capabilities for runtime editing:
Page properties editor
This dialog opens when users click the Page Properties button on the Oracle Composer toolbar. The Page Properties dialog displays the current page's properties and enables users to modify property values.
Reset page option
The Reset Page dialog box opens when users click the Reset Page button on the Oracle Composer toolbar. The Reset Page dialog enables users to remove all edits, regardless of when they were made, and reset the page to its original, out-of-the-box state.
In addition to these, you can register new add-ons in Oracle Composer. For example, you can create a custom task flow with information about the application and register it as an add-on with the title About. Your add-on displays as an About button in the Oracle Composer toolbar. Clicking the About button opens a panel that contains the information you specified.
You can create and register custom task flows that can be invoked from buttons on the Oracle Composer toolbar. All registered add-ons have an associated button that displays on the toolbar.
This section steps through the procedure of creating an add-on and registering it with Oracle Composer. It includes an example that demonstrates how to create an add-on that displays information about the Fusion Order Demo (FOD) application. The example add-on renders an About button on the Oracle Composer toolbar (Figure 5-1) that users can click to invoke a task flow that contains information about FOD.
Figure 5-1 About FOD Button in Oracle Composer Toolbar
This section contains the following subsections:
Oracle Composer add-ons are task flows you create using JSPX pages or page fragments. To complete the process, you package the task flows into JAR files and register them with Oracle Composer and the adf-config.xml file.
To create an add-on:
In your WebCenter application project, create a JSFF file called custompanelview.jsff:
From the File menu, select New.
In the New Gallery dialog box, expand Web Tier, select JSF, then JSF Page or JSF Fragment.
Click OK.
Design the fragment by adding the code shown in Example 5-1.
Example 5-1 Sample code in the JSFF Fragment
<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
<af:panelGroupLayout id="pnlgrp1" layout="vertical" halign="center">
<af:spacer id="sp1" width="10" height="20" />
<af:image id="customimage" source="/images/FusionOrderDemoLogo.jpg"/>
<af:spacer id="sp2" width="10" height="20"/>
<af:outputText id="actoutput1" value="Fusion Order Demo (FOD) is a sample shopping cart application based on Oracle ADF Framework.
It also uses the Webcenter Framework to enable Collaboration,Customization and Personalization features."
inlineStyle="font-size:small;"/>
<af:spacer id="sp3" width="10" height="20"/>
<af:outputText id="actoutput2" value="Build : 11.1.1.1"
inlineStyle="font-size:medium; font-weight:bolder;
text-decoration:none; font-style:normal;
background-color:White; color:Blue; font-family:garamond;"/>
</af:panelGroupLayout>
</jsp:root>
Create a task flow definition called custom-panel-task-flow:
From the File menu, choose New.
In the New Gallery dialog box, expand Web Tier, select JSF, then ADF Task Flow.
Click OK.
Drop the custompanelview.jsff fragment that you created onto the task flow definition.
|
See Also: "Getting Started with ADF Task Flows" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework for information about creating task flows. |
Save the task flow definition file.
To package the task flow in an ADF library:
Create a deployment profile for the task flow:
Right-click ViewController and choose New.
In the New Gallery, expand General, select Deployment Profile, and then ADF Library JAR File, and click OK.
In the Create Deployment Profile -- ADF Library JAR File dialog, enter a name for your deployment profile and click OK.
In the ADF Library JAR Deployment Profile Properties dialog, click OK.
In the Project Properties dialog, click OK.
In the Application Navigator, right-click the project folder, choose Deploy, deployment profile name, to, and then choose to ADF Library JAR file. This creates a deploy folder including the JAR file, in the project folder located at <Application_Root>\ViewController\deploy\.
After you create the task flows, you must register them with Oracle Composer so that they are displayed on the Oracle Composer toolbar along with the default options.
To register an add-on with Oracle Composer:
If it does not already exist, create the Oracle Composer extension file, pe_ext.xml in the META-INF directory under the project's Web context root:
From the File menu, select New.
In the New Gallery dialog box, expand General, select XML, then XML Document.
Click OK.
Name the file pe_ext.xml.
Add one <panel> element for each task flow that you want to register as an add-on.
Any number of panels can be declared under the <panels> element in the extension file.
Example 5-2 shows the code of the extension file with a <panel> entry.
Example 5-2 Oracle Composer Extension File
<?xml version="1.0" encoding="US-ASCII" ?>
<pe-extension xmlns="http://xmlns.oracle.com/adf/pageeditor/extension">
<addon-config>
<panels>
<panel name="oracle.fod.custom.panel" title="About FOD"
icon="http://myforums.oracle.com/jive3/images/question-pts-available-16x16.gif"
taskflow-id="/WEB-INF/custom-panel-task-flow.xml#custom-panel-task-flow" />
</panels>
</addon-config>
</pe-extension>
For more information about the addon-config and other nested elements, see Section B.2.1.1, "addon-config."
To register an add-on, you must add a reference to it in the application's adf-config.xml file. Add the addon-panels entry to define new add-ons.
To register add-ons in adf-config.xml:
Open the application's adf-config.xml file, located in the ADF META-INF folder under Descriptors in the Application Resources panel.
Add the following namespace within the adf-config element in the file:
xmlns:pe="http://xmlns.oracle.com/adf/pageeditor/config"
Add a <page-editor-config> entry with an <addon-panels> entry.
Within page-editor-config, add <addon-panel> entries for the default options and the new panels, as shown in Example 5-3.
You must include entries for the default add-ons along with those for new panels. Without these entries, the default add-ons are not displayed in Oracle Composer.
The name attribute must contain the name you used to register the panel in the Oracle Composer extension file.
Example 5-3 New Add-Ons Referenced in adf-config.xml
<pe:page-editor-config>
<addon-panels>
<!-- Page Properties add-on -->
<addon-panel name="oracle.adf.pageeditor.addonpanels.page-settings" />
<!-- Page Reset add-on -->
<addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" />
<addon-panel name="oracle.fod.custom.panel" />
</addon-panels>
</pe:page-editor-config>
|
Note: If you do not specify any<addon-panel> entries under <addon-panels>, then only the default options are displayed in Oracle Composer. |
For information about the Oracle Composer-specific configurations you can make in adf-config.xml, see Section B.2.2, "adf-config.xml."
Custom add-ons that you register with Oracle Composer are rendered on the Oracle Composer toolbar along with the default add-ons.
In the example, an About FOD button is rendered on the Oracle Composer toolbar (Figure 5-2).
Figure 5-2 About FOD Button in Oracle Composer Toolbar
Clicking this button displays the About FOD task flow (Figure 5-3).
You can look at these catalog definitions in the StoreFrontModule in the Fusion Order Demo application. For information about this application, see Chapter 2, "Introduction to the WebCenter Sample Application."
You can choose to show or hide the Page Properties and Reset Page buttons in Oracle Composer. Not all Oracle Composer components have the same flexibility. For example, you cannot select to hide the Catalog or the Component Properties dialogs. To display only the Page Properties or Reset Page button, you can selectively include the button's associated add-on in the adf-config.xml file. Example 5-4 shows the entries you can add for the two built-in add-ons.
Example 5-4 Default Built-In Options
<!-- Page Properties add-on --> <addon-panel name="oracle.adf.pageeditor.addonpanels.page-settings" /> <!-- Page Reset add-on --> <addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" />
In Example 5-5, the Page Properties add-on entry is removed and a new add-on is included.
Example 5-5 The adf-config.xml File with Only One Built-In Option
<addon-panels> <!-- Page Reset add-on --> <addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" /> <addon-panel name="oracle.fod.custom.panel" /> </addon-panels>
The excluded default add-on (Page Properties) is not rendered on the Oracle Composer toolbar. The included add-ons are rendered on the toolbar in the order in which they are defined in the adf-config.xml file.
Depending on your business requirement, you may need to selectively hide the add-ons available to different users in Oracle Composer. To hide an add-on, you must set the rendered attribute for the panel to false using a constant value or an EL expression, as shown in Example 5-6.
Example 5-6 rendered Attribute Setting in the adf-config.xml File
<addon-panels>
<addon-panel name="oracle.fod.custom.panel"
rendered="#{bean.showNotification}" />
. . .
</addon-panels>
In this example, at runtime, a backing bean's isShowNotification() method is called. It returns either true or false, depending on whether the panel is to be rendered.
If the returned value is false, Oracle Composer does not display the add-on. If the returned value is true, Oracle Composer displays a button for the panel.
|
Note: The default value forrendered is true. That is, if you do not specify a rendered attribute for a panel, the panel is always rendered. |
When a user clicks the Edit icon on a component, its properties are shown in the Component Properties dialog. The Component Properties dialog provides a series of tabs that group related attributes together. The attributes have associated, typically editable values that control a component's visual and style properties. Parameters and Events tabs provide a means of creating or consuming component parameters and events.
Similarly, when a user clicks the Page Properties button, a Page Properties dialog opens with its own series of tabs. These contain display-related properties, page parameters, and security settings.
You can create and register custom property panels to render in place of or in addition to the panels displayed in the Component Properties or Page Properties dialog. For example, you can develop a custom property panel for an Image component to expose a picker for an image's Source property.
This section describes how to create custom property panels and how to exclude, override, and selectively render default property panels. It contains the following subsections:
Creating a custom property panel is similar to creating an add-on. That is, you create custom property panels as task flows and register them in the Oracle Composer extension file. You can configure a custom property panel to render in the dialog at all times or only when a particular component or task flow is selected for editing.
This section describes how to create and register a custom property panel. It contains the following subsections:
Section 5.3.1.2, "Registering a Custom Property Panel for a Component"
Section 5.3.1.3, "Registering a Custom Property Panel for a Task Flow"
Property panels provide a means of editing page or component properties. For example, the end user may click the Edit icon on a selected portlet and then modify its parameter values and change its visual attributes in the resulting properties dialog.
Oracle Composer enables you to associate property panels with components and task flows. When a user clicks the Edit icon on the component or task flow, Oracle Composer opens the Component Properties dialog and displays the custom property panels you associated with the object along with the default property panels. If you do not associate a property panel with a particular component or task flow, then that panel is rendered for all pages, components and task flows in the Component Properties and Page Properties dialogs.
The steps for creating a custom property panel and declaring it in the Oracle Composer extension file are similar to those for creating and declaring Oracle Composer add-ons. For information about these tasks, see Section 5.2.1.1, "Creating an Add-On" and Section 5.2.1.2, "Registering Add-Ons with Oracle Composer."
After declaring a custom property panel in the extension file, you must also register it in the extension file and associate it with a component, if required. Registering a custom property panel ensures that the panel displays automatically in the Oracle Composer Component Properties and Page Properties dialog.
Use the property-panels element to register the custom property panel in the pe_ext.xml file and to associate the custom panel with a component.
To register a property panel for a component:
Add a <property-panels> element in the pe_ext.xml file.
For information about creating the extension file, see Section 5.2.1.2, "Registering Add-Ons with Oracle Composer."
Add a property-panel declaration within the <property-panels> element.
You can have multiple property-panel entries.
Within the property-panel element, add a component element to specify the runtime class name of the component (optional) and a panel element to specify the name you used to declare the panel in the addon-config section of the file.
Example 5-7 shows a custom property panel that is associated with a Command Button component by specifying the component's fully qualified class name. For information about Oracle ADF components and their runtime classes, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
Example 5-7 Code to Register a Property Panel for a Component
<property-panels>
<property-panel name="cmdbtn">
<component>oracle.rich.CommandButton</component>
<panel name="prop.panel.cmdbtn" />
<panel name="prop.panel.generic" />
</property-panel>
</property-panels>
|
Note: When registering a property panel, if you do not associate it with a component or task flow, then the registered panel is rendered for all pages, task flows, and components in the Component Properties and Page Properties dialogs.You can register multiple |
You can define custom property panels for a task flow by registering it with the Oracle Composer extension file. Example 5-8 shows the sample code used to register a custom property panel for a task flow.
A custom property panel registered for a specific task flow appears only when its associated task flow is selected. Otherwise, default property panels appear.
|
Note: Use task flow-specific custom property panels only to customize task flow parameters or any other aspect of the task flow's working. Note that a custom property panel does not function if its associated task flow is rendered using the Oracle JSF Portlet Bridge. |
To register a property panel for a task flow:
Add a <property-panels> element in the pe_ext.xml file.
For information about creating the extension file, see Section 5.2.1.2, "Registering Add-Ons with Oracle Composer."
Add a property-panel declaration within this.
You can have multiple property-panel entries.
Addtaskflow-id and panel elements within the property-panel element.
Add the taskflow-id element to specify the task flow name. Add the panel element to specify the name you used to declare the property panel in the addon-config section of the file.
Example 5-8 shows a custom property panel associated with a dashboard task flow.
Example 5-8 Code to Register a Property Panel for a Task Flow Instance
<property-panels>
<property-panel name="dashboard">
<taskflow-id>/WEB-INF/dashboard-taskflow#prop-panel</taskflow-id>
<panel name="dashboard.prop-panel" />
</property-panel>
</property-panels>
|
Note: When registering a property panel, if you do not associate it with a component or task flow, then the registered panel is rendered for all pages, task flows, and components in the Component Properties and Page Properties dialogs.You can register multiple |
If you associated the custom property panel with a specific component or task flow, at runtime the panel renders as a tab in the Component Properties dialog invoked from the specified component or task flow. If you did not associate the custom property panel with a specific component or task flow, at runtime the custom property panel renders as a tab in both the Page Properties and Component Properties dialogs for all pages, components, and task flows.
You can use the rendered attribute to show or hide a default property panel in the Page Properties and Component Properties dialogs. Set the attribute value to true to show the default property panel; set it to false to hide a default property panel.
Example 5-9 shows the rendered attribute set to false for the Content Style property tab of a Command Button component. For information about default property panels, see Section B.3, "Oracle Composer Default Add-Ons and Property Panels."
Example 5-9 rendered Attribute for a Property Panel
<property-panels>
<property-panel name="cmdbtn">
<component>oracle.rich.CommandButton</component>
<panel name="prop.panel.cmdbtn" />
<panel name="oracle.adf.pageeditor.pane.content-style-editor" rendered="false" />
</property-panel>
</property-panels>
You can override a default property panel with a custom panel you provide by registering your custom panel using the same name as the default panel. When you register a custom panel, provide the name of the default panel as the value for the name attribute within the panel element. Your custom property panel is then rendered on the default tab in lieu of the tab's default properties in the Component Properties or Page Properties dialog.
For a list of default property panels that you can override, see Section B.3, "Oracle Composer Default Add-Ons and Property Panels."
Custom property panels registered in the application are rendered in the Component Properties dialog when users click the Edit icon on a specified component. To display property panels selectively, you can use an EL value in the property-panel's rendered attribute as follows:
<property-panel name="global-but-just" rendered="#{bean.showProperty}">
When a user performs an action, such as clicking a Save button, Oracle Composer calls back into the application code to give the application a chance to respond to the action—or event. This is useful in performing application-specific tasks on such events. Moreover, this is the recommended approach to, for example, saving the changes on a custom property panel.
Oracle Composer provides a means of registering event handlers for different events. This section describes how. It contains the following subsections:
Section 5.4.1, "How to Create and Register Handlers for Composer UI Events"
Section 5.4.2, "What Happens When You Create and Register Event Handlers"
When you register an event handler with Oracle Composer, it is called when the corresponding event is fired in the Composer UI. This section describes how to create an event handler and register it with Oracle Composer. It contains the following subsections:
Section 5.4.1.1, "UI Events that Support Event Handler Registration"
Section 5.4.1.3, "Registering an Event Handler with Oracle Composer"
Table 5-1 lists the UI events for which Oracle Composer currently supports registering of handlers.
Table 5-1 Events for Which Registering Handlers is Supported
| Event | Cause | Event Type | Listener Interface to Be Implemented | Method to Be Implemented | Event Parameters |
|---|---|---|---|---|---|
|
Save |
Invoked when a user clicks the Save button on the Oracle Composer toolbar, or the Apply or OK button in the Component Properties dialog or Page Properties dialog. |
|
|
|
|
|
Close |
Invoked when a user clicks the Close button on the Oracle Composer toolbar. |
|
|
|
|
|
Deletion |
Invoked when a user deletes the component. |
|
|
|
Get the deleted component using |
|
Addition |
Invoked when a user adds a component to the page from the catalog, by clicking the Add button against an item in the Catalog dialog. |
|
|
|
|
|
Selection |
Invoked when a user selects:
|
|
|
|
|
To register an event with Oracle Composer, you must first create a Java class and implement the appropriate listener for the event handler. This section describes the steps to create a Save event handler. You can perform similar steps to create event handlers for all the supported events listed in Table 5-1.
A Save event handler is called when a user clicks the Save button on the Oracle Composer toolbar or the Apply or OK button in the Component Properties or Page Properties dialog. A Save event handler must implement oracle.adf.view.page.editor.event.SaveListener.
To create a Save event handler:
In JDeveloper, select the ViewController project, and from the File menu, choose New.
In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
In the Create Java Class dialog, specify a name for the class, for example, SaveHandler.
Under the Optional Attributes section, add the oracle.adf.view.page.editor.event.SaveListener interface.
Click OK.
The Java class source looks like the following:
package view;
import javax.faces.event.AbortProcessingException;
import oracle.adf.view.page.editor.event.SaveEvent;
import oracle.adf.view.page.editor.event.SaveListener;
public class Class1 implements SaveListener {
public Class1() {
super();
}
public void processSave(SaveEvent saveEvent) throws AbortProcessingException {
// Your implementation goes here
}
}
You must declare the processSave method as throws AbortProcessingException because the method may throw this exception if the event must be canceled. You can include the reason for cancelling this event in the Exception object when you create it.
On throwing this exception, further processing of this event is canceled and the listeners that are in the queue are skipped.
You can create event handlers for all supported events by performing steps similar to these.
After creating and implementing an event handler, you must register it with Oracle Composer. Registration is necessary for ensuring that the handler is called back by Composer when the corresponding event occurs in the UI.
Register event handlers in the Oracle Composer extension file, /META-INF/pe_ext.xml. For more information about creating this file, see Section 5.2.1.2, "Registering Add-Ons with Oracle Composer."
To register an event handler:
In the pe_ext.xml file, add the following entries:
<event-handlers> <event-handler event="save">view.SaveHandler</event-handler> </event-handlers>
The values you provide for the event attribute and between the event-handler tags are unique to the type of event being entered and the name you specified for the event class.
Save the file.
At runtime, registered event handlers are called according to the sequence in the extension file and according to the order in which they were found on the class path. Oracle Composer's native event handler is called last.
On invocation of an event handler's processEventName method, if an event handler throws AbortProcessingException, then the event is canceled and no further event handlers are called, including Composer's native event handlers.If, however, an error occurs while instantiating an event handler, then Oracle Composer continues with the next event handler. A warning message is logged.
Some component properties are not displayed in Oracle Composer's Component Properties dialog box because they are filtered out by default. The default filters are defined in the <filter-config> section of the Composer's extension file (/META-INF/pe_ext.xml).
Global filters filter attributes for all components. They are defined using the <global-attribute-filter> tag. Tag-level filters filter attributes for a specified component only. They are defined using the <taglib-filter> tag.
|
Note: In an extension file, you can have any number of<taglib-filter> tags under <filter-config>, but you can have only one <global-attribute-filter> tag to define all global attribute filters. |
You can define additional filters to hide more properties in the Component Properties dialog. This section describes how. It contains the following subsections:
Oracle Composer defines a built-in filter configuration. You can use the extension file, pe_ext.xml, to define additional property filters and to delete filters. You can define any number of filters, even for a single tag, in different extension files. Oracle Composer merges the filtering information from all the extension files.
To define property filters in an extension file:
In the pe_ext.xml file, add the filter-config element as shown in the following example:
|
Note: For information about creating thepe_ext.xml file, see Section 5.2.1.2, "Registering Add-Ons with Oracle Composer." |
<filter-config> <global-attribute-filter> <attribute name="accessKey" /> <attribute name="attributeChangeListener" /> <attribute name="autoSubmit" /> <attribute name="binding" /> </global-attribute-filter> <taglib-filter namespace="http://xmlns.oracle.com/adf/faces/rich"> <tag name="commandButton"> <attribute name="text" /> <attribute name="icon" /> </tag> </taglib-filter> </filter-config>
Save the file.
At runtime, when you edit a component's properties, the properties that were filtered out are not rendered in the Component Properties dialog.
You can remove global and tag-level filters so that previously filtered properties are now rendered in the Component Properties dialog. This is useful for displaying properties that are filtered out by Oracle Composer's built-in filters or by another extension file defined elsewhere the application.
|
Note: After you remove a property filter, it is rendered in the Component Properties dialog even if a filter is defined for that property in another extension file. |
To remove a property filter:
Edit the Oracle Composer extension file, pe_ext.xml, available in the META-INF directory.
You can remove property filters by editing entries in this file.
Search for the attribute from which to remove the filter, and set filtered to false in the <attribute> tag as shown in the following example:
<pe-extension xmlns="http://xmlns.oracle.com/adf/pageeditor/extension">
. . .
<filter-config>
<global-attribute-filter>
<attribute name="accessKey" filtered="false" />
<attribute name="attributeChangeListener" />
. . .
</global-attribute-filter>
<taglib-filter namespace="http://xmlns.oracle.com/adf/faces/rich">
<tag name="activeCommandToolbarButton">
. . .
<attribute name="windowWidth" filtered="false"/>
</tag>
</taglib-filter>
</filter-config>
</pe-extension>
Save the file.
Most industries customize their enterprise applications to serve different audiences and domains. Problems can arise when an application is modified at the site level. For example, upgrading an application with site-level customizations may lead to data loss or data-merge errors. Consequently, a new version of the application cannot be deployed until all merge conflicts are reconciled.
In the metadata domain, MDS provides the customization feature to address such problems. The customization feature allows for the creation of nonintrusive customization layers that are applied on top of the base application definitions. Customization layers, or layered changes, are described in their own documents and are stored separately from the base application definition. At runtime, applicable customizations are loaded from the metadata store and layered over the base metadata definition to produce the desired effect. Product upgrades and patches affect only the base metadata definition, so customizations continue to function properly.
You can apply component-level restrictions to the JSF pages that use Oracle Composer components, add customization layers to WebCenter applications that provide different user- and site-level privileges, and set the location of a customization store for all MDS customizations.
The MDS enables clients to specify multiple customization types. For example, you can add customizations to runtime modes, application or user roles, application states, or any client specified criteria. Each such customization type is called a customization layer. Customization layers are applied in order of precedence, that is, if the same change is made in two different layers that apply to the given user and session, the change defined in the higher precedence layer is applied first.
This section provides an example of adding of a customization layer. Additionally, it provides a usage example of the customizationAllowed attribute. It contains the following subsections:
Section 5.6.1, "Adding Customization Layers to View and Edit Modes: Example"
Section 5.6.2, "Applying Tag-Level Security Using the customizationAllowed Attribute"
You can apply customizations to a metadata object based on client-defined criteria. For example, you can customize an application and the metadata objects that it uses based on an end-user's permissions, an application's deployment location (also called localization), or a specific industry domain. Each such category—permissions, localization, and domain—denotes a customization layer, and each is depicted using a CustomizationClass. A CustomizationClass is the interface MDS uses to identify the customization layer to be overlaid on the base definition. See Section 5.6.1.3, "How to Create a Custom UserCC Tip Layer" for an example.
When you implement a CustomizationClass, you must also register it with the MDS. The MDS provides the ability to associate a list of CustomizationClass types with a single MetadataObject. This is called the fine-grained association. The MDS also provides the ability to associate a list of CustomizationClass types with a set of MetadataObjects. This is called the coarse-grained association.
This section explains through example how adding customization tip layers to View and Edit runtime modes provides personalization capabilities to all users and customization capabilities to selective users. To enable customizations in the Edit mode, the site tip layer is added. To enable personalization in the View mode, the user tip layer is added. By default, the user tip layer is applied on top of the site tip layer. The user tip layer stores all customizations made in the View mode in a specific location created for the user who made them. Such changes are visible only to that user. The site tip layer stores all customizations made in the Edit mode and are visible to all users.
To enable tip layers at runtime, Oracle Composer provides the WebCenterComposerFilter filter and supplies a means of defining an abstract factory for creating the MDS SessionOptions object. This object provides applicable customization layers at runtime and enables users to perform personalizations (View mode) or customizations (Edit mode) based on their role. When creating a new MDS session, the MDSSession.createSession method of this object is used to specify the session options.
This section provides an example exercise for creating, implementing, and registering customization layers, configuring WebCenterComposerFilter, and switching between MDS customization layers. It contains the following subsections:
Section 5.6.1.4, "How to Implement the ComposerSessionOptionsFactory Class"
Section 5.6.1.5, "How to Register the Implementation with Oracle Composer"
Section 5.6.1.7, "How to Redirect the Servlet to Enable Switch Between MDS Customization Layers"
This section describes how to add the Page Customizable component to a JSF page. The purpose of this exercise is to provide Oracle Composer in the Edit mode at runtime so that the admin user can perform customizations at the site level. This section includes the addition of a Change Mode Link to enable switching from View mode to Edit mode at runtime.
To add Oracle Composer to a JSF Page:
Open the JSPX page and select Oracle Composer from the Component Palette.
Select Change Mode Link and drop it onto the page.
Select Page Customizable and drop it onto the page.
The Source view should like this:
<af:form id="f1">
<pe:changeModeLink id="cml1"/>
<pe:pageCustomizable id="pageCustomizable1">
<cust:panelCustomizable id="panelCustomizable1" layout="scroll"/>
<f:facet name="editor">
<pe:pageEditor id="pep1"/>
</f:facet>
</pe:pageCustomizable>
</af:form>
When you drop these components onto the page, the default UserCC tip layer is extended by the ADF. Consequently, the adf-config.xml file is updated with this customization class:
<cust-config>
<match>
<customization-class name="oracle.adf.share.config.UserCC" />
</match>
</cust-config>
This section describes how to create a SiteCC tip layer, site, in which all site-level customizations performed in Edit mode are stored. In this sample application, site-level customizations are stored in the /mds/mdssys/cust/site/webcenter/pagename.jspx.xmldirectory.
To create the site tip layer:
From the File menu, choose New.
In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
The Create Java Class dialog box opens.
In the Name field, enter SiteCC.
In the Extends field, enter CustomizationClass.
This imports oracle.mds.cust.CustomizationClass.
Click OK.
The SiteCC.java file is rendered in the Source view.
To implement the getCacheHint, getName, and getValue methods, double-click the bulb on the left corner and select Implement Methods.
In the Implement Methods dialog, click OK.
In the Source view, press Enter after public class SiteCC extends CustomizationClass, and add the following string:
{
private static final String DEFAULT_LAYER_NAME = "site";
private String mLayerName = DEFAULT_LAYER_NAME;
private String mLayerValue = "webcenter";
The following libraries are imported:
import oracle.mds.core.MetadataObject; import oracle.mds.core.RestrictedSession; import oracle.mds.cust.CacheHint;
Update the code as shown in bold here:
public class SiteCC extends CustomizationClass
{
private static final String DEFAULT_LAYER_NAME = "site";
private String mLayerName = DEFAULT_LAYER_NAME;
private String mLayerValue = "webcenter";
Note: You can provide any site name.
public CacheHint getCacheHint()
{
return CacheHint.ALL_USERS;
}
public String getName()
{
return mLayerName;
}
public String[] getValue(RestrictedSession mdsSession, MetadataObject mo)
{
return new String[] { mLayerValue };
}
}
Save the SiteCC.java file.
The ADF extends a default UserCC (user) tip layer when you drop Oracle Composer components onto a JSF page. Subsequently, the adf-config.xml file is updated to include the UserCC customization class.
This section describes how to create a custom user tip layer for a user, scott. This layer is applied on top of the site layer. The personalizations that a user performs in View mode are saved in this user tip layer in a folder created specifically for the logged-in user. In this example, the personalizations performed in View mode are saved in the /mds/mdssys/cust/user/scott/pagename.jspx.xmldirectory.
To create the user tip layer:
From the File menu, choose New.
In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
The Create Java Class dialog box opens.
In the Name field, enter UserCC.
In the Extends field, enter CustomizationClass.
This imports the oracle.mds.cust.CustomizationClass.
Click OK.
The UserCC.java file displays in the Source view.
To implement the getCacheHint, getName, and getValue methods, double-click the bulb on the left corner and select Implement Methods.
In the Implement Methods dialog box, click OK.
In the Source view, press Enter after public class SiteCC extends CustomizationClass, and add the following string:
{
private static final String DEFAULT_LAYER_NAME = "user";
private String mLayerName = DEFAULT_LAYER_NAME;
private String mLayerValue = "scott"; //The name of the logged-in user
in this example. The logged-in user name can be acquired dynamically.
The following libraries are imported:
import oracle.mds.core.MetadataObject; import oracle.mds.core.RestrictedSession; import oracle.mds.cust.CacheHint;
Update the code as shown in bold here:
public class UserCC extends CustomizationClass
{
private static final String DEFAULT_LAYER_NAME = "user";
private String mLayerName = DEFAULT_LAYER_NAME;
private String mLayerValue = "scott";
public CacheHint getCacheHint()
{
return CacheHint.USER;
}
public String getName()
{
return mLayerName;
}
public String[] getValue(RestrictedSession mdsSession, MetadataObject mo)
{
return new String[]{mLayerValue};
}
}
Save the UserCC.java file.
In this section, the ComposerSessionOptionsFactory class provided by the ADF is implemented in order to supply MDS SessionOptions for each HTTP request.
To implement the ComposerSessionOptionsFactory class:
From the File menu, choose New.
In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
The Create Java Class dialog box opens.
In the Name field, enter AppsSessionOptionsFactoryImpl.
Click OK.
The AppsSessionOptionsFactoryImpl.java file is rendered in the Source view.
Import the following libraries:
import oracle.adf.view.page.editor.mds.ComposerSessionOptionsFactory; import oracle.adf.view.page.editor.mode.ModeContext; import oracle.mds.config.CustClassListMapping; import oracle.mds.config.CustConfig; import oracle.mds.core.SessionOptions; import oracle.mds.cust.CustClassList; import oracle.mds.cust.CustomizationClass;
Add the following code to implement the ComposerSessionOptionsFactory class and provide SessionOptions:
public class AppsSessionOptionsFactoryImpl
implements ComposerSessionOptionsFactory
{
public SessionOptions createSessionOptions(SessionOptions defaultSessionOptions, String mode)
{
CustomizationClass[] custLayer;
CustConfig custConfig = null;
if (ModeContext.EDIT_MODE.equals(mode))
{
//Mode is Edit, change to SiteCC
custLayer = EDIT_LAYER;
}
else
{
//Mode is View, change to UserCC + SiteCC
custLayer = VIEW_LAYER;
}
try
{
CustClassList custClassList = new CustClassList(custLayer);
CustClassListMapping custClassListMapping =
new CustClassListMapping("/", null, null, custClassList);
custConfig = new CustConfig(new CustClassListMapping[]
{ custClassListMapping });
}
catch (Exception e)
{
e.printStackTrace();
}
if(defaultOptions.getServletContextAsObject() != null){
return new SessionOptions(defaultSessionOptions.getIsolationLevel(),
defaultSessionOptions.getLocale(), custConfig,
defaultSessionOptions.getVersionContext(),
defaultSessionOptions.getVersionCreatorName(),
defaultSessionOptions.getCustomizationPolicy());
sessionOptions.getServletContextAsObject());
}
else
{
return new SessionOptions(sessionOptions.getIsolationLevel(),
sessionOptions.getLocale(), custConfig,
sessionOptions.getVersionContext(),
sessionOptions.getVersionCreatorName(),
sessionOptions.getCustomizationPolicy());
}
}
//Edit mode SiteCC
private static final CustomizationClass[] EDIT_LAYER =
new CustomizationClass[]
{ new SiteCC() };
//View mode SiteCC + USerCC
private static final CustomizationClass[] VIEW_LAYER =
new CustomizationClass[]
{ new SiteCC(), new UserCC() };
}
For the site and user customization layers to function, you must register the ComposerSessionOptionsFactory class with Oracle Composer. For example, if the concrete class is view.AppsSessionOptionsFactoryImpl, the following snippet must be added to the adf-config.xml file located in the \.adf\META-INF folder in your application directory:
<page-editor-config xmlns="http://xmlns.oracle.com/adf/pageeditor/config"> <session-options-factory>view.AppsSessionOptionsFactoryImpl</session-options-factory> </page-editor-config>
You must configure the WebCenterComposerFilter filter in the web.xml file located in the ViewController\public_html\WEB-INF folder in your application directory. This filter registers Oracle Composer's concrete SessionOptionsFactory with the ADF for every HTTP request. When the filter receives a call from the ADF, it forwards the request to the WebCenter application and gets the SessionOptions with the new customized layer. If you have not set the Sandbox or VersionContext in the SessionOptions, then Oracle Composer sets its own Sandbox and returns it to the ADF. For more information on Sandbox, see Section 5.7.1, "How to Enable Oracle Composer Sandbox Creation." The composerFilter and its filter mapping must be configured after ServletADFFilter and before ADFBindingFilter. For example, see the following web.xml file:
....
<filter>
<filter-name>ServletADFFilter</filter-name>
<filter-class>oracle.adf.share.http.ServletADFFilter</filter-class>
</filter>
<!-- WebCenterComposerFilter 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>
.....
<filter-mapping>
<filter-name>ServletADFFilter</filter-name>
<servlet-name>Faces Servlet</servlet-name>
<dispatcher>FORWARD</dispatcher>
<dispatcher>REQUEST</dispatcher>
</filter-mapping>
<!-- WebCenterComposerFilter 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>
....
For information about the Oracle Composer-specific configurations you can make in web.xml, see Section B.2.3, "web.xml."
To redirect the servlet, that is, to refresh the full page at runtime, you must create:
The AppNavigationUtils class, which calls the AppNavigationUtils.redirectToSamePage() method
The AppCloseHandler CloseListener, which uses the AppNavigationUtils class
The AppModeBean, which displays Edit mode
This section describes how to create these objects. It contains the following subsections:
To create the AppNavigationUtils class:
From the File menu, choose New.
In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
The Create Java Class dialog box opens.
In the Name field, enter AppNavigationUtils and click OK.
The AppNavigationUtils.java file is rendered in the Source view.
Import the following libraries:
import javax.faces.context.FacesContext; import javax.servlet.http.HttpServletRequest;
Add the following code:
public class AppNavigationUtils
{
public static void redirectToSamePage()
{
HttpServletRequest request =
(HttpServletRequest)FacesContext.getCurrentInstance().getExternalContext().getRequest();
String url = request.getRequestURL().toString();
String _adfCtrlState = request.getParameter("_adf.ctrl-state");
url = url + "?_adf.ctrl-state="+ _adfCtrlState;
System.out.println(url);
try
{
FacesContext.getCurrentInstance().getExternalContext().redirect(url);
FacesContext.getCurrentInstance().responseComplete();
}
catch(Exception e)
{
e.printStackTrace();
}
}
}
To create AppCloseHandler:
From the File menu, choose New.
In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
The Create Java Class dialog box opens.
In the Name field, enter AppCloseHandler and click OK.
The AppCloseHandler.java file displays in the Source view.
Import the following libraries:
import oracle.adf.view.page.editor.event.CloseEvent; import oracle.adf.view.page.editor.event.CloseListener;
Add the following code:
public class AppCloseHandler
implements CloseListener
{
public void processClose(CloseEvent closeEvent)
{
AppNavigationUtils.redirectToSamePage();
}
}
After creating AppCloseHandler, you must register it in the Oracle Composer extension file, pe_ext.xml.
To register the event handler:
In the pe_ext.xml file, add the following entries:
<event-handlers> <event-handler event="close">view.AppCloseHandler</event-handler> </event-handlers>
Save the file.
For more information about event handlers, see Section 5.4, "Configuring Event Handlers for Oracle Composer UI Events."
To create AppModeBean:
From the File menu, choose New.
In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
The Create Java Class dialog box opens.
In the Name field, enter AppModeBean and click OK.
The AppModeBean.java file displays in the Source view.
Import the following libraries:
import javax.faces.event.ActionEvent;import oracle.adf.view.page.editor.mode.ModeContext;
Add the following code:
public class AppModeBean
{
public void edit(ActionEvent actionEvent)
{
ModeContext.getCurrent().setEditMode();
AppNavigationUtils.redirectToSamePage();
}
}
To see how the site customization layer functions, first run the JSF page in a browser. Then log in to the page as admin, and click the Edit link to switch to Edit mode. At runtime, customize the page. For example, drop a movable box, a hyperlink, and an image onto the page. The page should look like Figure 5-4.
Go to \mds\mdssys\cust\site\webcenter in your application directory, and open the pagename.jspx.xml file. This is where the site-level customizations that you made to the page are stored.
To use the user customization layer, log in to the page as scott and personalize the page in View mode. Then go to \mds\mdssys\cust\user\scott in your application directory, and open the pagename.jspx.xml file. This is where the user-level customizations (personalizations) that you made to the page are stored.
By default, customization is enabled on all components inside a Page Customizable component. You may want to change this to restrict customization on some components. MDS provides the customizationAllowed and customizationAllowedBy attributes to enable you to restrict customization of specific component instances.
The customizationAllowed attribute controls whether the component can be customized at runtime. If you set this attribute to false, then the component cannot be customized at runtime. That is, in the Component Properties dialog the properties are grayed out and do not allow editing.
The customizationAllowedBy attribute specifies the roles for which customization is enabled.
This section provides examples of enabling and restricting customization on a component. It contains the following subsections:
Section 5.6.2.1, "How to Enable Customization on an Image Component"
Section 5.6.2.2, "How to Restrict Customization on an Image Component"
For more information, see Extended Metadata and Annotation Properties in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
To enable customization on an Image component:
In the MyPage.jspx page that you created in Section 4.3, "Designing Editable Pages Using Oracle Composer Components: Example," add an ADF Faces Image component, for example, brandingImage.gif, inside the Panel Customizable called panelCustomizable1.
Customization is enabled automatically on the Image component since it is nested inside a Page Customizable component.
Run MyPage.jspx.
Switch to Edit mode of the page.
From the View menu, select Source to switch to Source view of the page.
Select the image in the component hierarchy in the Source View panel and click the Show the properties of Image icon.
The Component Properties dialog displays the image properties. You can edit any available property in this dialog. Edit a property and click OK. The property's editable value demonstrates that customization is enabled on the component.
You can restrict customization of an image on the page by setting the customizationAllowed attribute to false on the image component.
To restrict customization on the Image Component:
In Oracle JDeveloper, select the Image component that you added in the previous section, and in the Property Inspector set the value for customizationAllowed to false.
Run MyPage.jspx.
Switch to page Edit mode.
From the View menu, select Source to switch to the Source view of the page.
Select the image in the component hierarchy in the Source View panel, and click the Show the properties of Image icon.
In the Component Properties dialog, the properties are grayed out and cannot be edited.
This section discusses the steps you can take to enable sandbox creation and describes runtime behavior of a sandbox-enabled application. It contains the following subsections:
Section 5.7.1, "How to Enable Oracle Composer Sandbox Creation"
Section 5.7.6, "What Happens When You Enable Application Sandbox Creation"
For information about the sandbox, see Section 5.1.6, "Oracle Composer Sandbox."
You can enable a sandbox only if your application uses a database store. Therefore, you must ensure that you have configured a database store before performing the steps in this section. For information about setting up a database store, see Oracle Fusion Middleware Configuring and Managing JDBC for Oracle WebLogic Server.
This section describes how to enable the creation of an Oracle Composer sandbox. It contains the following subsections:
You must update the adf-config.xml file to define and configure namespaces for all the metadata for which you want to support sandbox creation. This section describes how.
|
Note: For information about the Oracle Composer-specific configurations you can make inadf-config.xml, see Section B.2.2, "adf-config.xml." |
To configure sandbox creation in adf-config.xml:
Open the adf-config.xml file located in the ADF META-INF folder under Descriptors in the Application Resources panel.
Under the <metadata-namespaces> element, ensure that <namespace> elements are defined for all metadata for which you want to enable sandbox creation, as shown in Example 5-10.
Example 5-10 Namespace Definitions in the adf-config.xml File
<!-- your jspx files -->
<namespace path="/test" metadata-store-usage="webcenter_metadata_db_store"/>
<!-- your pagedef customizations alone go here -->
<namespace path="/pageDefs" metadata-store-usage="webcenter_metadata_db_store">
<namespace-restriction type="CUSTOMIZATIONS"/>
</namespace>
Configure the database store, as shown in Example 5-11.
|
Note: Perform this step only if you plan to use WLS Administration Console to deploy your application EAR file. This configuration happens automatically if you deploy your application using Fusion Middleware Control or Oracle JDeveloper and select a database repository connection as the target MDS connection. For more information, see "Deploying WebCenter Applications" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter. |
Example 5-11 Metadata Store Configuration in the adf-config.xml File
<metadata-store class-name="oracle.mds.persistence.stores.db.DBMetadataStore">
<property name="jdbc-userid" value="userone"/>
<property name="jdbc-password" value="userone123"/>
<property name="jdbc-url" value="jdbc:oracle:thin:@host_name:1521:orcl"/>
<property name="partition-name" value="partitionName"/>
</metadata-store>
<!-- <metadata-store class-name="oracle.mds.persistence.stores.file.FileMetadataStore">
<property name="metadata-path" value="C:\JDeveloper\mywork\Application2\ViewController\public_html"/>
</metadata-store> -->
Add the <sandbox-namespaces> element and add individual <namespace> tags for all namespaces for which you want to enable sandbox creation, as show in Example 5-12.
Save the adf-config.xml file.
To ensure that a sandbox is created when you are in Edit mode of a page, you must create a filter in your application's web.xml file and set the appropriate filter mappings. All requests are then routed through this filter, and a sandbox is created for all Edit mode customizations. If you are using a file system metadata store, then there is no action performed on a filtered request.
|
Note: For information about the Oracle Composer-specific configurations you can make inweb.xml, see Section B.2.3, "web.xml." |
This section provides the example of defining a Composer-specific filter and its relevant filter mappings in your application's web.xml file. It describes how to add the filter, WebCenterComposerFilter.
To define a Composer-specific filter and the filter mappings:
Open the application_root/ViewController/public_html/WEB-INF/web.xml file.
Add ServletADFFilter and WebCenterComposerFilter before the adfBindings filter so that all requests are routed through these filters first:
<filter> <filter-name>ServletADFFilter</filter-name> <filter-class>oracle.adf.share.http.ServletADFFilter</filter-class> </filter> <filter> <filter-name>WebCenterComposerFilter</filter-name> <filter-class>oracle.adf.view.page.editor.webapp.WebCenterComposerFilter</filter-class> </filter>
Add corresponding <filter-mapping> elements before the filter mapping for adfBindings filter as shown in Example 5-13.
Example 5-13 Filter Mappings for Composer-Specific Filter
<filter-mapping> <filter-name>ServletADFFilter</filter-name> <servlet-name>Faces Servlet</servlet-name> <dispatcher>FORWARD</dispatcher> <dispatcher>REQUEST</dispatcher> </filter-mapping> <filter-mapping> <filter-name>WebCenterComposerFilter</filter-name> <url-pattern>/*</url-pattern> </filter-mapping> <filter-mapping> <filter-name>WebCenterComposerFilter</filter-name> <url-pattern>/faces/*</url-pattern> <dispatcher>FORWARD</dispatcher> <dispatcher>REQUEST</dispatcher> </filter-mapping>
The <url-pattern> tag is used to specify the pages that must pass through the WebCenterComposerFilter so that sandbox creation can be enabled when a page goes into Edit mode.
Save the web.xml file.
When a user switches to page Edit mode, the presence of a Save button on the Oracle Composer toolbar indicates that sandbox creation is enabled for the application. Changes made to the page are not saved until the user clicks Save. If the Save button is not rendered, the sandbox is not available and each change is committed immediately.
When editing component properties in the Component Properties dialog, clicking Apply results in the following:
If the sandbox is not available, then the page is refreshed to display the changes made to component properties and changes are saved to the back end.
If the sandbox is available, then the page is refreshed to display the changes made to component properties. To save changes, user must click Save.
Clicking Save or Close on the page results in the following events:
On clicking Save, the sandbox is committed and a new sandbox is created. The page remains in Edit mode.
On clicking Close, either of the following two events can occur:
If there are no changes since the last Save operation, then the sandbox is destroyed and Oracle Composer is closed, taking the user back to View mode.
If there are unsaved changes, then a Close Confirmation dialog displays, in which a user can select from the following options:
Click Save to commit the sandbox and close Oracle Composer.
Click Don't Save to destroy the sandbox and close Oracle Composer.
Click Cancel to close the dialog and return to Oracle Composer without saving the changes.
|
Notes: If a user navigates away from a page while editing it and then returns to the page, any unsaved changes are lost. |
What Happens During Concurrent Edits
If two or more users are editing a page at the same time, then during the next server request, changes made by all users are visible on the page. However, if two or more users edit the same page using the same customization layer, then their changes conflict. If this happens, the page displays a message that another user is editing the page. Changes that are saved last overwrite prior changes. For example, if users A and B are editing a page simultaneously, then concurrency issues are handled as follows:
If A saves the page first, then A's changes are committed to MDS. Later, when B saves the page, A's changes are overwritten with B's changes.
If A deletes a component while B is trying to personalize (say move) that same component in View mode, a WebCenter error page is displayed to B. B has to simply navigate back to the original page. The deleted component does not appear, and B can continue working on other components.
To ensure that changes are committed to the back end immediately, you can disable the sandbox.
To disable sandbox:
Open the adf-config.xml file located in the ADF META-INF folder under Descriptors in the Application Resources panel.
Under the <page-editor-config> element, add the <disable-sandbox> attribute and set it to true.
Save adf-config.xml.
When users edit a page at runtime, if the browser closes unexpectedly or the user navigates away from the page, the sandbox used in that session is still available. Any other user accessing the same page continues to see a concurrency message that another user is editing the same page. You can destroy such stale sandboxes to free some space in the database store and enhance performance.
You can ensure that a stale sandbox is destroyed when:
A session times out.
The <session-timeout> element in the application's web.xml file defines the time duration after which the sandbox is destroyed.
The user logs in to Edit mode of the page again, with the same user name.
In this case, a new sandbox is created when the same user switches to Edit mode. To ensure this happens, you must configure WebCenterComposerSessionListener in your application's web.xml file. This listener is called when a session times out. It creates a new sandbox when the same user renters page Edit mode.
To configure WebCenterComposerSessionListener:
Open the application_root/ViewController/public_html/WEB-INF/web.xml file.
Define a new listener, WebCenterComposerSessionListener, as shown in the following example:
<listener>
<description>Oracle Composer Http Session Listener</description>
<display-name>Oracle Composer Http Session Listener</display-name>
<listener-class>
oracle.adf.view.page.editor.webapp.WebCenterComposerSessionListener
</listener-class>
</listener>
Save the web.xml file.
For information about the Oracle Composer-specific configurations you can make in web.xml, see Section B.2.3, "web.xml."
If you enable sandbox creation at the application level, then Oracle Composer does not create its own sandbox when page Edit mode is invoked. Instead, the application sandbox is used. That is, a user interface provided by the application is used for committing and destroying the sandbox. To enable the application to provide a sandbox for Oracle Composer, you must first perform a set of configurations.
To enable an application sandbox for use in Oracle Composer:
Implement a ComposerSessionOptionsFactory class to provide MDSSessionOptions for each request.
For information about performing this task, see Section 5.6.1.4, "How to Implement the ComposerSessionOptionsFactory Class."
Register your implementation with Oracle Composer.
For information about performing this task, see Section 5.6.1.5, "How to Register the Implementation with Oracle Composer."
Configure WebCenterComposerFilter.
For information about performing this task, Section 5.6.1.6, "How to Configure WebCenterComposerFilter."
At runtime, the application-defined user interface enables users to save their changes to the back end or close Oracle Composer without saving the changes. In this case, Oracle Composer has no control over when customizations are canceled or committed to the back end.
The ability to customize an artifact, such as the page, a component, or an attribute of a component, is inherited from security definitions at the tag, page, component, and attribute levels. You can override the default security definitions at various levels in keeping with your business requirement. This section describes how to override the default security behavior. It contains the following subsections:
Section 5.8.1, "Applying Component-Level Restrictions by Defining Customization Policies"
Section 5.8.4, "Applying Action-Level Restrictions on Show Detail Component Actions"
|
Note: For information about the default security behavior of Oracle Composer components, see Section 4.1.5, "Security and Oracle Composer." |
By default, the MDS restricts all customizations. The Page Customizable component is available for lifting default customization restrictions on the Page Customizable and all its child components. Another way to configure customization on a set of component attributes is to use MDS type-level restrictions or instance-level restrictions. This section describes how. It contains the following subsections:
Section 5.8.1.1, "How to Define Type-Level Customization Policies"
Section 5.8.1.2, "How to Define Instance-Level Customization Policies"
You can enable type-level restrictions on components and their attributes in a standalone XML file and then register this file in the mds-config section of the adf-config.xml file. The standalone XML file contains annotations that match the types for which customization restrictions must be specified.
To enable customization of selected components or attributes at the type level:
Create an XML document, for example standalone.xml, add the following code, and replace the text in bold with appropriate values:
<?xml version="1.0" encoding="UTF-8" ?>
<grammarMetadata xmlns="http://xmlns.oracle.com/bali/xml/metadata"
xmlns:mds="http://xmlns.oracle.com/mds"
namespace="http://java.sun.com/JSP/Page">
<elementMetadata elementName="component_name">
<mds:customizationAllowed>true</mds:customizationAllowed>
<attributeMetadata attributeName="attribute_name">
<mds:customizationAllowedBy>security_roles</mds:customizationAllowedBy>
</attributeMetadata>
</elementMetadata>
</grammarMetadata>
The <customizationAllowedBy> tag can appear only once. Multiple values can be specified as a space-separated list of allowed policies as part of the declaration.
The <customizationAllowed> tag takes a Boolean as its value. A value of true for this tag means that anyone can customize the specified component, so long as other inherited customization polices allow it.
The <customizationAllowedBy> tags do not serve any purpose if the same object has been tagged with <customizationAllowed>false</ customizationAllowed>. Additionally, the customization must be allowed at the top level of the object tree. Otherwise the default behavior dictates that no customization can be permitted at a lower level.
Register this XML file in the mds-config section of the adf-config.xml file as follows:
<mds-config xmlns="http://xmlns.oracle.com/mds/config">
<type-config>
<standalone-definitions>
<classpath>File_Path/standalone.xml</classpath>
</standalone-definitions>
</type-config>
</mds-config>
Make the standalone files and associated XSDs available in a shared library JAR file; otherwise MDS cannot load them due to class loader restrictions.
You can enable customization on a component or any of its attributes at the instance level. To apply customization restriction at the component level, you can set the customizationAllowed and customizationAllowedBy attributes on the component in JDeveloper (see Section 5.6, "Performing MDS-Specific Configurations"). To apply restrictions on a component's attributes, perform the steps described in this section.
The code for instance-level customization policies is similar to that used in the type-level policy definitions. They have the same meaning at the instance level. However, instance level policies are subordinate to type restrictions. That is, all restrictions are inherited from the type, and no customization is allowed unless customization is enabled at the type level.
Instance-level policies for component attributes are defined in an RDF file. The RDF file is picked up by MDS, and the policies are implemented.
To define instance-level customization policies:
Create an RDF file with the same name as the JSPX file, but using the RDF extension, for example main.jspx.rdf.
Creating the RDF file in this folder structure ensures that the file is picked up by MDS and the policies defined here are implemented.
Include tags in the following format to apply restrictions on a component's attribute:
tag_id(xmlns(tag_prefix=tag_namespace))/@tag_prefix:attribute_name
The following example shows how to apply restriction on the text attribute of a Command Button component:
<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/elements/1.1/">
<rdf:Description rdf:about="/"/>
<!-- Opens the customization on a tag, for example, an af:commandButton whose ID is 'cb1'. -->
<rdf:Description rdf:about="cb1">
<customizationAllowedxmlns="http://xmlns.oracle.com/mds">false</customizationAllowed>
</rdf:Description>
<!-- Restricts customizations on the commandButton's attribute 'text'. -->
<rdf:Description
rdf:about="cb1(xmlns(af=http://xmlns.oracle.com/adf/faces/rich))/@af:text">
<customizationAllowedxmlns="http://xmlns.oracle.com/mds">false</customizationAllowed>
</rdf:Description>
At runtime, these policies are read and the artifacts are enabled for customization accordingly.
This section explains how you can use component-level restrictions to limit access to certain component functions, based on different user roles and responsibilities. Specifically, it describes how to apply an instance-level customization restriction to a Panel Customizable component to provide customization access to only the admin user. That is, when a user with admin privileges logs into the system at runtime, the user can customize the Panel Customizable on which the instance-level customization is applied.
In Oracle Composer's Property Inspector, the properties of the Panel Customizable appear gray to users who do not have admin privileges. These users cannot drop any Movable Box or Show Detail Frame into the Panel Customizable because of the applied restriction. Moreover, they cannot rearrange the Show Detail Frames inside this Panel Customizable.
To restrict a functionality based on user roles is one way to apply customization restrictions. You can also use expression language expressions (ELs), which provide roles-based results, to enable or restrict access to a component function.
|
Note: MDS customization restrictions can be applied only toPanel Customizable, Show Detail Frame, and Layout Customizable components. These restrictions cannot be applied to ADF Faces components, such as Splitter and showDetailItem. |
This section contains the following subsections:
Section 5.8.2.2, "How to Define Users and Grant Roles in the jazn-data.xml File"
Section 5.8.2.3, "How to Customize the SessionOptions Object to Include Customization Policy"
Section 5.8.2.4, "How to Register the Implementation with Oracle Composer"
Section 5.8.2.6, "How to Apply an Instance-Level Customization Restriction"
Before applying an instance-level customization restriction, you must secure your application using ADF security. For information, see Section 3.5.1, "How to Configure ADF Security."
In a previous section, a customization restriction is applied to a Panel Customizable component so that, at runtime, only the user with admin privileges can access all the features of Panel Customizable, and therefore, can customize its attributes.
In this section, two users are created, admin and customer, and roles are granted. All permissions are granted to both users. The admin user can customize the Panel Customizable (panelCustomizable1) component. However, because of the customization restriction you applied in an earlier section, customer does not have the rights to customize panelCustomizable1, and this user cannot use all the features of panelCustomizable1.
To define users in the jazn-data.xml file:
In the Application Resources, right-click the jazn-data.xml file and select Properties.
The Edit JPS Identity & Policy Store dialog box opens.
In Identity Store, under jazn.com, select Users.
Click Add.
The Add User dialog box opens.
In the Name field, specify a user name, for example, admin.
In the Credentials field, specify the password, for example, password.
Click OK.
Repeat steps 3 through 6 to add another user, for example, customer.
To grant roles, double-click the jazn-data.xml file to open it.
Select the Web Pages tab.
Grant all the permissions (View, Customize, Edit, Grant, Personalize) to both, admin and customer users.
For more information about creating users, see the section on enforcing ADF Security in a Fusion Web application in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.
To enable the expected runtime behavior of the Panel Customizable component, where only the user with admin role has access to all capabilities of the Panel Customizable, including the ability to customize it, the MDS session for this request must include the user roles in its customization policy. To achieve this, the following customization policy is included in the SessionOptions object:
SecurityContext stx = ADFContext.getCurrent().getSecurityContext(); cPol = new CustomizationPolicy(stx.getUserRoles());
Then the MDS session is created with this customization policy.
To implement the ComposerSessionOptionsFactory class:
From the File menu, choose New.
In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
The Create Java Class dialog box opens.
In the Name field, enter AppsSessionOptionsFactoryImpl.
Click OK.
The AppsSessionOptionsFactoryImpl.java file is rendered in the Source view.
Import the following libraries:
import oracle.adf.share.ADFContext; import oracle.adf.share.security.SecurityContext; import oracle.adf.view.page.editor.mds.ComposerSessionOptionsFactory; import oracle.adf.view.page.editor.mode.ModeContext; import oracle.mds.config.CustClassListMapping; import oracle.mds.config.CustConfig; import oracle.mds.core.SessionOptions; import oracle.mds.cust.CustClassList; import oracle.mds.cust.CustomizationClass; import oracle.mds.cust.CustomizationPolicy;
Add the following code to implement the ComposerSessionOptionsFactory class and provide SessionOptions:
public class AppsSessionOptionsFactoryImpl
implements ComposerSessionOptionsFactory
{
public AppsSessionOptionsFactoryImpl()
{
}
public SessionOptions createSessionOptions(SessionOptions sessionOptions,
String mode)
{ CustomizationClass[] custLayer;
CustConfig custConfig = null;
CustomizationPolicy cPol = null;
if (ModeContext.EDIT_MODE.equals(mode))
{
//Mode is Edit, change to SiteCC
custLayer = EDIT_LAYER;
}
else
{
//Mode is View, change to UserCC + SiteCC
custLayer = VIEW_LAYER;
}
try
{
CustClassList custClassList = new CustClassList(custLayer);
CustClassListMapping custClassListMapping =
new CustClassListMapping("/", null, null, custClassList);
custConfig = new CustConfig(new CustClassListMapping[]
{ custClassListMapping });
SecurityContext stx = ADFContext.getCurrent().getSecurityContext();
cPol = new CustomizationPolicy(stx.getUserRoles());
}
catch (Exception e)
{
e.printStackTrace();
}
if(sessionOptions.getServletContextAsObject() != null)
{
return new SessionOptions(sessionOptions.getIsolationLevel(),
sessionOptions.getLocale(), custConfig,
sessionOptions.getVersionContext(),
sessionOptions.getVersionCreatorName(),
cPol == null ?
sessionOptions.getCustomizationPolicy() : cPol,
sessionOptions.getServletContextAsObject());
}
else
{
return new SessionOptions(sessionOptions.getIsolationLevel(),
sessionOptions.getLocale(), custConfig,
sessionOptions.getVersionContext(),
sessionOptions.getVersionCreatorName(),
cPol == null ?
sessionOptions.getCustomizationPolicy() : cPol);
}
}
//Edit mode SiteCC
private static final CustomizationClass[] EDIT_LAYER =
new CustomizationClass[]
{ new SiteCC() };
//View mode SiteCC + USerCC
private static final CustomizationClass[] VIEW_LAYER =
new CustomizationClass[]
{ new SiteCC(), new UserCC() };
}
To register the implementation with Oracle Composer, perform the steps described in Section 5.6.1.5, "How to Register the Implementation with Oracle Composer."
To configure WebCenterComposerFilter, perform the steps described in Section 5.6.1.6, "How to Configure WebCenterComposerFilter."
In this section, you apply a customization restriction to a Panel Customizable component. At runtime, this restriction ensures that only the user with admin privileges can access all the features of the Panel Customizable, including customizing its attributes. Users who do not have admin privileges can use only a limited set of component features.
To apply an instance-level customization restriction:
In the JSPX page, add a Command Link.
In the Command Link (af:commandLink) component, add the #{appModeBean.edit} action listener you created in Section 5.6.1.7, "How to Redirect the Servlet to Enable Switch Between MDS Customization Layers."
Add a Page Customizable component.
Apply an instance-level customization restriction on the component panelCustomizable1 in the Page Customizable.
This restriction is stored in the following directory: public_html/mdssys/mdx/<pagename>.jspx.rdf.
The Source view should look like this:
<af:commandLink text="Edit the Page" id="cl1"
actionListener="#{appModeBean.edit}">
<af:clientListener method="togglePEPageMode" type="action"/>
<af:navigationPane id="np1"/>
</af:commandLink>
<pe:pageCustomizable id="pageCustomizable1">
<cust:panelCustomizable id="panelCustomizable1" layout="scroll"/>
<f:facet name="editor">
<pe:pageEditorPanel id="pep1"/>
</f:facet>
</pe:pageCustomizable>
<trh:script text="
function togglePEPageMode(event) { ComposerUtils.toggleMode(event); }
">
</trh:script>
The design view should look like Figure 5-5.
Figure 5-5 Design View: Customization Allowed
|
Note: For detailed information on how to add Oracle Composer components, see Section 3.3.2, "How to Create a Page in a Manually-Created WebCenter Application." |
What happens at runtime is influenced by which user is logged on. To see the difference, log in as one user and then the other. For example:
In the Application Navigator, right-click the JSPX page and select Run.
Log in to the page as admin, and switch to Edit mode. The Add Content button and the pencil icon are displayed on the outer panelCustomizable. As admin, you can switch to Source view and access the properties of the outer panelCustomizable, as shown in Figure 5-6. That is, the user admin can edit this component.
Log in to the page as customer, and switch to Edit mode. The Add Content button and the pencil icon are not available on the outer Panel Customizable. That is, this component is not editable for customer, as shown in Figure 5-7.
You can choose whether specific component attributes can be customized at runtime. Additionally, you can specify that the changes made to an attribute must be persisted to a persistence store, such as MDS. You can apply attribute-level security in the following ways:
By defining property filters
By persisting changes at the component level
This section describes how to persist changes at the component level. It contains teh following subsections:
For information about applying property filters, see Section 5.5.1, "How to Define Property Filters."
You can use the persist-changes attribute in the adf-config.xml file to specify whether changes to a specific attribute must be persisted.
|
Note: For information about the Oracle Composer-specific configurations you can make inadf-config.xml, see Section B.2.2, "adf-config.xml." |
Example 5-14 shows a sample adf-config.xml file with persist-changes attributes defined for some attributes.
Example 5-14 Using the persist-changes Attribute in the adf-config.xml File
<adf-config xmlns="http://xmlns.oracle.com/adf/config">
<adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
<persistent-change-manager>
<persistent-change-manager-class>
oracle.adf.view.rich.change.MDSDocumentChangeManager
</persistent-change-manager-class>
</persistent-change-manager>
<taglib-config>
<taglib uri="http://xmlns.oracle.com/adf/pageeditor">
<tag name="imageLink">
<attribute name="destination">
<persist-changes>true</persist-changes>
</attribute>
</tag>
<tag name="customAction">
<attribute name="text">
<persist-changes>true</persist-changes>
</attribute>
<attribute name="icon">
<persist-changes>true</persist-changes>
</attribute>
</tag>
</taglib>
</taglib-config>
</adf-faces-config>
</adf-config>
If you set persist-changes to true, then a change made to the component attribute is persisted in any instance of that component. If you set persist-changes to false, then even if you change the attribute value in the Component Properties dialog at runtime, the change is not saved.
The ability of a user to perform actions on Show Detail Frame components is inherited from page security. Inheritance is based on the value of the application-wide switch, enableSecurity, in the adf-config.xml file. If you select the WebCenter Application template when you create your application, then the adf-config.xml file is located in the ADF META-INF folder under Descriptors in the Application Resources panel.
This section describes how to apply action-level restrictions on Show Detail Frame component actions. It contains the following subsections:
Section 5.8.4.1, "How to Add an enableSecurity Section to adf-config.xml"
Section 5.8.4.2, "Defining Security at the Actions Category Level"
The enableSecurity element is not available by default in adf-config.xml. To override or extend the page-level security inheritance for Show Detail Frame components, you must add the customizableComponentsSecurity section in the adf-config.xml file, as shown in Example 5-15, and set the enableSecurity element in that section to true.
Example 5-15 enableSecurity Element in the Customizable Components Security Section in adf-config.xml
<cust:customizableComponentsSecurity xmlns="http://xmlns.oracle.com/adf/faces/customizable/config"> <cust:enableSecurity value="true"/> <cust:actionsCategory> .......................................... </cust:customizableComponentsSecurity>
Restrictions on actions on Show Detail Frame components can be implemented at the following levels:
Page level: You can define security for customizable components such that page-level privileges are inherited by these components. This is the default behavior.
By default, customizable components inherit allowable actions from the defined page-level permissions, such as edit, personalize, or customize. That is, a user who has edit, personalize, or customize privileges on a page can perform View mode personalizations on that page. The enableSecurity element enables you to override the security inheritance behavior. It can take either of the following values:
true: If set to true (the default when not specified), then the ability of a user to modify a component is first determined from the page permissions and then adjusted according to the current set of actions defined for that type of permission. For example, if a user has customize permission, then the actions that constitute the customize category (move, customize, and so on) are available to the user, but they are overridden by the actions that are defined in the adf-config.xml file.
false: If set to false, then all actions are available to users. A user's page permissions and actions configured in adf-config.xml are ignored.
Actions category level: You can define security on all actions for Show Detail Frame components.
You can add an actionsCategory element in the adf-config.xml file to define security on multiple actions simultaneously. Depending on the actionCategory attributes that you enable, appropriate privileges are provided on the Show Detail Frame components.
Actions level: You can define security on individual actions for Show Detail Frame components.
You can use the actions element in the adf-config.xml file to enable or disable individual actions. Depending on the actions attributes that you enable, appropriate privileges are provided on the Show Detail Frame components.
|
Notes:
|
You can define security for actions on Show Detail Frame components at the application level if enableSecurity is set to true in the adf-config.xml file. A value of true implies that permission checks are made in addition to the actionsCategory and actions values specified in the adf-config.xml.
You can add an actionsCategory element in the customizable components actions security section in the adf-config.xml file to define security on multiple Show Detail Frame components actions. Depending on the actionsCategory attributes that you enable, appropriate privileges are provided on the Show Detail Frame components.
The actions and actionsCategory elements in the adf-config.xml file have certain default mappings. Table 5-2 describes the different actionsCategory attributes and the actions they support by default.
Table 5-2 Actions Categories and Show Detail Frame Actions Mapping
| actionsCategory | Actions Supported |
|---|---|
|
|
showMoveAction showRemoveAction showMinimizeAction showResizer allowAction |
|
|
showEditAction showAddContentAction |
|
Note: For information about the Oracle Composer-specific configurations you can make inadf-config.xml, see Section B.2.2, "adf-config.xml." |
Example 5-16 shows the actionsCategory entry that you can add to the customizable components actions security section in the adf-config.xml file.
Example 5-16 actionsCategory Element in the Customizable Components Security Section
<cust:customizableComponentsSecurity
xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">
<cust:enableSecurity value="true"/>
<cust:actionsCategory>
<cust:actionCategory name="personalizeActionsCategory" value="false"/>
<cust:actionCategory name="customizeActionsCategory" value="true"/>
</cust:actionsCategory>
<cust:actions>
..........................................
</cust:actions>
</cust:customizableComponentsSecurity>
You can also use EL for these element values, as shown in Example 5-17.
Example 5-17 EL Used in Customizable Components an actionCategory Entry
<cust:actionsCategory>
<cust:actionCategory name="personalizeActionsCategory" value="#{appBusinessRules.InsideCorpNetwork}"/>
</cust:actionsCategory>
For reference, the managed bean, appBusinessRules, is defined as shown in Example 24-7 in Section 24.10, "Overriding Inherited Security on Portlets and Customizable Components."
You can use the actions element in the customizable components actions security section of the adf-config.xml file to enable or disable individual Show Detail Frame actions. Depending on the actions attributes that you enable, appropriate privileges are provided on the Show Detail Frame components.
|
Note: For information about the Oracle Composer-specific configurations you can make inadf-config.xml, see Section B.2.2, "adf-config.xml." |
Example 5-18 shows the actions entry that you can add to the customizable components actions section of the adf-config.xml file. You can use EL for element values.
Example 5-18 action Elements in the Customizable Components Security Section
<cust:customizableComponentsSecurity
xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">
<cust:enableSecurity value="true"/>
<cust:actionsCategory>
..........................................
</cust:actionsCategory>
<cust:actions>
<cust:action name="showMinimizeAction" value="true"/>
<cust:action name="showMoveAction" value="false"/>
</cust:actions>
</cust:customizableComponentsSecurity>
By default, Source view is enabled in applications. You can disable Source view if you want to prevent users from being able to edit any page components other than task flows, portlets, and layout components. This section describes how. It contains the following subsections:
|
Note: For information about the editing capabilities in Source view, see Section 4.1.3, "Editing Capabilities in Edit Mode." |
You can disable Source view by setting the enable-source-view entry to false in the application's adf-config.xml file.
|
Note: For information about the Oracle Composer-specific configurations you can make inadf-config.xml, see Section B.2.2, "adf-config.xml." |
To disable Source view:
Open the application's adf-config.xml file, located in the ADF META-INF folder under Descriptors in the Application Resources panel.
Add the enable-source-view property and set its value to false, as shown in Example 5-19.
Save the file.
At runtime, when you switch to page Edit mode, the page is rendered in Design view and the View menu is not displayed to the user, as shown in Figure 5-8.
Figure 5-8 Design View of Page without View Menu
This section provides information to assist you in troubleshooting problems you may encounter while using Oracle Composer.
Problem
Oracle Composer is not working on ADF application pages. Errors are reported in the logs when using Oracle Composer's Resource Catalog or Component Properties dialog. None of the customizations are saved. Objects are not getting added from the Resource Catalog.
Solution
Oracle Composer is compatible only with the change manager, MDSDocumentChangeManager. You must set the CHANGE_PERSISTENCE context parameter in the web.xml file to MDSDocumentChangeManager, as shown in the following example:
<context-param> <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name> <param-value>oracle.adf.view.rich.change.MDSDocumentChangeManager</param-value> </context-param>
If you use the FilteredPersistenceChangeManage change manager, then Oracle Composer cannot write any customizations.
If you configure Oracle Composer first, and then ADF Faces, then the value of CHANGE_PERSISTENCE is changed to oracle.adf.view.rich.change.FilteredPersistenceChangeManager.
You must change this value to oracle.adf.view.rich.change.MDSDocumentChangeManager.
If you configure ADF Faces first, and then Oracle Composer, the CHANGE_PERSISTENCE is automatically set to MDSDocumentChangeManager.
Problem
When you run a page, the following error displays:
java.lang.IllegalStateException: The expression "#{bindings.pageeditorpanel.regionModel}" (that was specified for the RegionModel "value" attribute of the region
component with id "pePanel") evaluated to null. This is typically due to an error in the configuration of the
objects referenced by this expression. If it helps, the expression "#{bindings.pageeditorpanel}" evaluates to "null".
If it helps, the expression "#{bindings}" evaluates to "view_untitled1PageDef". Now using an empty RegionModel instead.
Solution
This error occurs if a page containing the Page Customizable component does not have the required task flow binding in its page definition file. Ensure that the page definition file contains the following valid entry under the <executables> node:
<taskFlow id="pageeditorpanel" taskFlowId="#{pageEditorBean.pageEditorPanel}"xmlns="http://xmlns.oracle.com/adf/controller/binding"/>
This error may also occur if your page is based on a page template and that page template contains the Page Customizable component. In such a case, the af:pageTemplate tag does not contain the value="#{bindings.pageTemplateBinding}" attribute.
Ensure that the page definition file has the following entry under the <executables> node:
<page path="view.pageDefs.templateDef1PageDef" id="pageTemplateBinding" Refresh="ifNeeded"/>
Problem
Users cannot switch to Edit mode. The Edit link (Change Mode Link or Change Mode Button) appears disabled.
Solution
The user may have only view privilege on the page. Ensure that the user has the edit privilege on the page. For the page template on which the page is based, it is sufficient to have only view privilege.
Problem
Resource Catalog is empty.
Solution
The default catalog is not available to MDS. Ensure that the deployment profile contains the necessary entries to copy the default catalog file. Also, ensure that in the MDS section of adf-config.xml, a namespace entry points to the default catalog file.
Problem
A project task flow does not appear in the Resource Catalog.
Solution
The task flow must be packaged as an ADF Library (JAR file) and added to the project. You must also ensure that the task flow ID is given in the following format:
path_to_jar/ADF_TaskFlow/task_flow_path Ex. doclib-service-view.jar/ADF_TaskFlow/oracle+webcenter+doclib+view+jsf+taskflows+mainView.xml#doclib-document-library
Problem
When you view the properties of a component in the Component Properties dialog, properties appear disabled and you cannot edit property values.
Solution
Ensure that the component is not restricted by using MDS. For information, see Section 5.6.2, "Applying Tag-Level Security Using the customizationAllowed Attribute."
Problem
You added a global- or instance-level Custom Action. However, it neither displays on the chrome or in the Action menu on the Show Detail Frame.
Solution
Ensure the following:
The first child of the Show Detail Frame must be af:region.
The view currently displayed on the task flow must have an outcome in its task flow definition file that matches the action of Custom Action.
If the action has the prefix dialog:, the outcome in the task flow definition must also have the same prefix.
For information, see Section 4.2.13, "How to Enable Custom Actions on a Show Detail Frame Enclosing a Task Flow."
Problem
Your application is configured to use MDS sandbox. When you run the application, the sandbox either does not work or generates exceptions.
Solution
Ensure the following:
A database repository is used. Sandbox works only with a database-based repository, and not with a file-based repository.
Ensure that the order of filters in web.xml is correct. The <filter> entries must be in the correct order for sandbox to work correctly.
For information, see Section 5.7, "Using Oracle Composer Sandbox."
Problem
You created an add-on, but it does not appear on the Oracle Composer toolbar.
Solution
Ensure the following:
The pe_ext.xml file is in /META-INF folder in a JAR file or the application and is available in the class path.
The task flow binding ID specified while registering the panel in pe_ext.xml is correct.
An addon-panel entry exists under the page-editor-config section in the adf-config.xml file.
If the add-on is in a JAR file, ensure that the JAR file is created as an ADF Library.
For information about add-ons, see Section 5.2, "Creating Oracle Composer Add-Ons."
Problem
You have registered a custom property panel. However, it does not appear in the Component Properties dialog when your select a component to display its properties.
Solution
Ensure the following:
The pe_ext.xml file is in /META-INF folder in a JAR file or the application and is available in the class path.
The task flow binding ID specified while registering the panel in pe_ext.xml is correct.
The property-panel registration is correct and is specified against the component you want the panel to appear against. Further, the fully qualified class name of the component is correctly specified using the component node.
A duplicate property panel registration is not overriding your panel entry.
If the panel is configured to use the rendered attribute, ensure that the value or EL evaluates to true.
If the add-on is in a JAR file, ensure that the JAR file is created as an ADF Library.
For information about custom property panels, see Section 5.3, "Creating Custom Property Panels."
Problem
The Show Detail Frame and Panel Customizable do not show the Edit icon, or the Panel Customizable does not show the Add Content button. Also, you are not able to move the Show Detail Frame out of a Panel Customizable component or drop it into another Panel Customizable component.
Solution
Ensure that the Panel Customizable is not restricted by using MDS and the component actions are not secured by using entries in adf-config.xml.For information, see Section 5.8, "Overriding Default Security Behavior of Oracle Composer Components."
