Oracle® Fusion Middleware Developer's Guide for Oracle WebCenter 11g Release 1 (11.1.1.4.0) E10148-12 |
|
![]() Previous |
![]() Next |
This chapter describes how to use Oracle Composer's declarative and programmable extensibility mechanism to customize Oracle Composer to suit your business needs. It contains the following sections:
Section 20.5, "Configuring Custom LOVs or Pickers for Task Flow Parameters"
Section 20.6, "Configuring Event Handlers for Oracle Composer UI Events"
Section 20.7, "Configuring Drop Handlers in the Resource Catalog"
Section 20.9, "Enabling Parameter Support on the Customization Manager Task Flow"
Section 20.11, "Troubleshooting Problems with Oracle Composer Extensibility Features"
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. You must configure the extensions in your application's adf-config.xml
file and the Oracle Composer extension file, pe_ext.xml
. For information about these files, see Section 20.1.8, "Configuration Files."
This section describes the options available for extending Oracle Composer runtime capabilities declaratively. It contains the following subsections:
The Page Properties and Reset Page buttons on the Oracle Composer toolbar (Figure 20-1) are examples of add-ons. Click these buttons to display panels for editing page properties and resetting page customizations. Typically, add-ons are custom task flows that are rendered as buttons on the Oracle Composer toolbar in page Edit mode. You can create add-ons that appear along with the Page Properties and Reset Page add-ons. For example, you can create an add-on to display page revision history so that it displays a Revisions button on the Oracle Composer toolbar. Clicking this button would display the page's revision history. You can also replace the Page Properties and Reset Page add-ons with custom add-ons that you create.
Figure 20-1 Default Add-Ons on the Oracle Composer Toolbar
The process of configuring custom add-ons includes creating the task flows, packaging them into JAR files, and defining them in the Oracle Composer extension file. For more information, see Section 20.2, "Creating Oracle Composer Add-Ons."
The Component Properties dialog displays categories of attributes on different tabs. Each tab can be referred to as a property panel. The default Component Properties dialog in Oracle Composer is analogous to the Oracle JDeveloper Property Inspector. You can create and register custom property panels for a component, populate them with component properties, and display them as tabs along with the default tabs in the Component Properties dialog.
The process of configuring 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 20.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. When a user clicks a button or icon in Oracle Composer, an event handler ensures that a specific action is performed. An event handler is the code that is called back by Oracle Composer when a composer event is invoked. Each UI event in Oracle Composer is associated with an event handler. Sometimes it may be necessary to augment Oracle Composer's innate capabilities by performing a different action or multiple actions on invoking an event. 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 tasks such as cleaning up cached information and connections to resources. You can accomplish this with event handlers. For more information, see Section 20.6, "Configuring Event Handlers for Oracle Composer UI Events."
Oracle Composer Catalog provides resources that users can add to their pages. An Add link next to a resource name enables users to add it to the page. Oracle Composer provides drop handlers to handle the add operation in the Catalog. By default, a drop handler is configured for each resource in the Catalog. If you want to provide complete control of the drop action to the resource, you can create additional drop handlers for that resource. The Add link then displays a context menu with different options for adding the resource to the page. You can create one or more drop handlers to handle different flavors for resources in your Catalog.
You can add the following types of drop handlers:
Java classes registered with Oracle Composer and called when users click an Add link in the Oracle Composer Catalog. In this case, the resource is added to the page based on the data flavor selected.
Task flows registered with Oracle Composer and called when users click an Add link in the Oracle Composer Catalog. In this case, a task flow is invoked, which enables users to decide what information from the resource must be displayed on the page.
For more information, see Section 20.7, "Configuring Drop Handlers in the Resource Catalog."
The Component Properties dialog displays properties of a selected component. By default, Oracle Composer filters certain component properties and displays a subset of properties to users. You can define filters declaratively to further hide properties that the user need not see, or to show properties that are hidden. For more information, see Section 20.8, "Defining Property Filters."
Customization Manager is a task flow that enables users to download, upload, reset, and delete application customizations on objects like pages and task flows. You can configure the Customization Manager either in Oracle Composer or outside of it, on some administrative page. For information about configuring and using Customization Manager, see Section 20.9, "Enabling Parameter Support on the Customization Manager Task Flow."
The default Oracle Composer toolbar displays elements on two rows. The first row displays the page name and status indicator, and the second row displays the View menu, Page Properties button, Reset Page button, and Close button, as shown in Figure 20-2.
Figure 20-2 Oracle Composer Toolbar with Default Elements
You can customize the toolbar by adding, deleting, or rearranging elements. You can also override existing elements with custom elements. For example, you can remove the message showing the page name if you do not want users to see the name of the page they are editing.
For information about customizing the Oracle Composer toolbar, see Section 20.10, "Customizing the Oracle Composer Toolbar."
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_ext.xml
)
The Oracle Composer extension file, pe_ext.xml
, enables you to extend the editing capabilities provided by Oracle Composer. Within this file you can add elements to register new Oracle Composer add-ons and custom property panels, selectively render panels, register event handlers, and define property filters. 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 or in the application_home
/
project
/src/META-INF
directory. When you run the application, the pe_ext.xml
file is picked up from the JAR file included in the application classpath. Your application can include more than one extension file. However, you must ensure that the JARs containing the extension files are available on the application classpath so that the pe_ext.xml
files are picked up for processing. 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
The adf-config.xml
file specifies application-level settings that are usually determined at deployment and often changed at runtime. When you perform such tasks as registering new add-ons and custom property panels in Oracle Composer, or creating customization layers, you must add appropriate entries in the adf-config.xml
file. The adf-config.xml
file is created automatically when you create an application, and when you add a Page Customizable
component to the page, certain configurations are added to this 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 add-ons for runtime editing:
Page Properties
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
The Reset Page dialog opens when users click the Reset Page button on the Oracle Composer toolbar. The Reset Page dialog enables users to remove application customizations made to a page and reset it to a previously-saved version or to its original out-of-the-box state. For more information, see Section 17.4.11, "Reset Page."
In addition to these, you can register new add-ons with Oracle Composer. For example, you can create an add-on to display page revision history so that it displays a Revisions button on the Oracle Composer toolbar. Clicking this button would display the page's revision history.
This section contains the following topics:
Section 20.2.3, "How to Exclude Oracle Composer Default Add-Ons"
Section 20.2.4, "How to Display the Customization Manager Add-On"
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 application. The example add-on renders an About button on the Oracle Composer toolbar (Figure 20-3) that users can click to invoke a task flow that contains information about the application.
Figure 20-3 About 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 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, expand Web Tier, select JSF, then JSF Page or JSF Fragment.
Click OK.
Design the fragment by adding code similar to what is shown in Example 20-1.
Example 20-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" height="20" /> <af:image id="customimage" source="/images/DemoLogo.jpg" shortDesc="Demo Logo"/> <af:spacer id="sp2" height="20"/> <af:outputText id="output1" value="This is a sample shopping cart application based on Oracle ADF Framework. It also uses the Webcenter Framework to enable collaboration, application customization and user customization features."/> <af:spacer id="sp3" height="20"/> <af:outputText id="output2" value="Build : 11.1.1" inlineStyle="font-weight:bold;"/> </af:panelGroupLayout> </jsp:root>
Note: At runtime, the add-on panel is automatically sized to fit the content in this fragment. |
Create a task flow definition called custom-panel-task-flow
:
From the File menu, choose New.
In the New Gallery dialog, 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.
Optionally, if you create the task flow in one application but want to consume it in another application, you must first package the task flow in an ADF library and add the resulting JAR in the consuming application.
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\
.
You can add this JAR file to any application in which you want to consume the add-on.
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 (for example, in the APPLICATION_HOME
\ViewController\src\META-INF
directory):
From the File menu, select New.
In the New Gallery dialog, expand General, select XML, then XML Document.
Click OK.
Name the file pe_ext.xml
.
Add an <addon-config>
element in the file, with a nested <panels>
element.
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 20-2 shows the code of the extension file with a <panel>
entry.
Example 20-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.custom.panel" title="About" 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."
Optionally, register event handlers for the custom panel by adding an event-handlers
element within the panel
element as shown in the following example:
<event-handlers> <event-handler event="close"> oracle.custom.TaskFlowEventHandler </event-handler> </event-handlers>
For more information, see Section 20.6, "Configuring Event Handlers for Oracle Composer UI Events."
Save the pe_ext.xml
file.
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 the adf-config.xml
file:
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 the namespace and include an <addon-panels>
entry inside it.
When you register a custom add-on, the default add-ons are not displayed in Oracle Composer by default. To display all the default add-ons, you must set the show-default-addons
attribute on the <addon-panels>
tag to true
. The default value for this attribute is false
.
Within <addon-panels>
, add <addon-panel>
entries for the new panels, as shown in Example 20-3.
The name
attribute must contain the name you used to register the panel in the Oracle Composer extension file.
Example 20-3 New Add-On Referenced in adf-config.xml
<pe:page-editor-config xmlns="http://xmlns.oracle.com/adf/pageeditor/config"> <addon-panels show-default-addons="true"> <addon-panel name="oracle.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 button is rendered on the Oracle Composer toolbar (Figure 20-4).
Figure 20-4 About Button in Oracle Composer Toolbar
Clicking this button displays the About the Application task flow (Figure 20-5).
Note: The add-on panel is automatically sized to fit the content inside the task flow. |
Figure 20-5 About the Application Task Flow
You can choose to show or hide the Page Properties, Reset Page, and Customization Manager buttons on Oracle Composer toolbar. To hide any of these add-ons, you must set the show-default-addons
attribute on <addon-panels>
to true
, add an entry for the default add-on you want to hide, and set the rendered
attribute on that add-on to false
.
Example 20-4 shows the code to hide the Page Properties add-on.
Example 20-4 The adf-config.xml File with the Reset Page Option Excluded
<addon-panels show-default-addons="true"> <!-- Hide the Reset Page add-on --> <addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" rendered="false"/> . . . </addon-panels>
The excluded add-on (Reset Page) is not displayed on the Oracle Composer toolbar. The other default add-ons are displayed on the toolbar in the default order.
The Customization Manager is an Oracle Composer add-on that enables users to manage application customizations on task flows, pages, and page fragments on a given page. For more information, see Section 17.4.14, "Manage Application Customizations."
The Customization Manager add-on is available in the Oracle Composer library, but is not rendered by default. You can enable it by configuring it in your application's adf-config.xml
file using an <addon-panel>
element inside <pe:page-editor-config>
, as shown in the following example:
<pe:page-editor-config xmlns="http://xmlns.oracle.com/adf/pageeditor/config">
<addon-panels show-default-addons="true">
<addon-panel name="oracle.adf.pageeditor.addonpanels.customization-manager"/>
. . .
</addon-panels>
. . .
</pe:page-editor-config>
This configuration ensures that the Oracle Composer toolbar displays the Customization Manager button as shown in Figure 20-6.
Depending on your business requirement, you may need to selectively hide the add-ons available to different users in Oracle Composer. To selectively hide an add-on, you must set the show-default-addons
attribute on <addon-panels>
to true
, add an entry for the default add-on you want to hide, and set the rendered
attribute for that add-on to false
using an EL expression, as shown in Example 20-5.
Example 20-5 rendered Attribute Setting in the adf-config.xml File
<pe:page-editor-config xmlns="http://xmlns.oracle.com/adf/pageeditor/config"> <addon-panels show-default-addons="true"> <addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" rendered="#{securityBean.userInPageResetRole}" /> . . . </addon-panels> . . . </pe:page-editor-config>
In this example, the securityBean
backing bean returns either true
or false
, depending on the role of the logged-in user. If the returned value is false
, Oracle Composer does not display the Reset Page button on the Oracle Composer toolbar. If the returned value is true
, Oracle Composer displays the Reset Page button.
Note: If you hide the Reset Page button on the Oracle Composer toolbar, the Reset Task Flow button displayed while editing task flow content is also hidden.The default value for |
Oracle Composer displays the properties of a component in the Component Properties dialog when a user clicks the Edit icon on the component. The Component Properties dialog provides a series of tabs. Each tab displays a group of related attributes. The attributes have associated values that control a component's behavior and visual style properties. For example, the Style tab displays the component's style-related properties, such as width, height, and background color.
Similarly, when a user clicks the Page Properties button, a Page Properties dialog opens with its own series of tabs. These tabs contain display-related page properties, page parameters, and security settings.
You can create and register custom property panels to render along with the tabs displayed in the Component Properties or Page Properties dialog. In addition, you can remove the default panels or replace them with custom property panels. For example, you can develop a friendlier property panel for an Image
component by displaying a picker for its Source
property. This would make it easier for users to select an image from the available options.
This section describes how to create custom property panels. It also describes how to exclude, override, and selectively render default property panels. It contains the following subsections:
Section 20.3.1, "How to Create and Register Custom Property Panels"
Section 20.3.6, "How to Display Properties and Parameters in a Custom Property Panel"
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 display in the Component Properties dialog always. Alternatively, you can configure the panel to display 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 20.3.1.2, "Registering a Custom Property Panel for a Component"
Section 20.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, a user can click the Edit icon on a selected task flow and modify its parameter values and change its visual attributes in the Component 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.
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 detailed information, see Section 20.2.1.1, "Creating an Add-On Task Flow" and Section 20.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:
Create an Oracle Composer extension file, pe_ext.xml
, if it does not already exist.
For information about creating the extension file, see Section 20.2.1.2, "Registering Add-Ons with Oracle Composer."
Add a <property-panels>
element inside the <addon-config>
section in the pe_ext.xml
file.
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 20-6 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 20-6 Code to Register a Property Panel for a Component
<pe-extension xmlns="http://xmlns.oracle.com/adf/pageeditor/extension"> <addon-config> <property-panels> <property-panel name="cmdbtn"> <component>oracle.adf.view.rich.component.rich.nav.RichCommandButton</component> <panel name="prop.panel.cmdbtn" /> <panel name="prop.panel.generic" /> </property-panel> </property-panels> </addon-config> . . . </pe-extension>
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.To configure multiple property panels for a component, you can include multiple |
You can define custom property panels for a task flow by registering it with the Oracle Composer extension file. Example 20-7 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 within the <addon-config>
element in the pe_ext.xml
file.
For information about creating the extension file, see Section 20.2.1.2, "Registering Add-Ons with Oracle Composer."
Add a property-
panel
declaration within this.
You can have multiple property-panel
entries.
Add taskflow-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 20-7 shows a custom property panel associated with a dashboard
task flow.
Example 20-7 Code to Register a Property Panel for a Task Flow Instance
<pe-extension xmlns="http://xmlns.oracle.com/adf/pageeditor/extension"> <addon-config> <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> </addon-config> . . . </pe-extension>
Notes:
|
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.
Note: In the Component Properties and Page Properties dialogs, custom panels are sized by the tab component containing the task flows. The size of the tab component itself is determined by a rule in the currently-applied skin. This rule is calledaf|panelTabbed.ComposerTab . |
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 20-8 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 20-8 rendered Attribute for a Property Panel
<pe-extension xmlns="http://xmlns.oracle.com/adf/pageeditor/extension">
<addon-config>
<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>
</addon-config>
. . .
</pe-extension>
You can override a default property panel with a custom panel by setting the rendered
attribute on the default panel to false
and registering your custom panel with the same title that was used for the default panel in the Component Properties or Page Properties dialog. That is, provide the title of the default panel as the value for the title
attribute within the panel
element. Your custom property panel is then rendered on the default tab in lieu of the tab's default properties.
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. You can configure your application to render a property panel selectively based on different criteria like the role of a logged-in user, the page being viewed, and so on. To display property panels selectively, you can use an EL value in the property-panel
's rendered
attribute as shown in the following example:
<property-panel name="global-but-just" rendered="#{bean.showProperty}">
If you are building a custom property panel for a component, you can use Show Property
components, available from the Oracle Composer tag library, to expose the component's attributes on the custom panel. In the page fragment defining the custom panel task flow, you must add one Show Property
component for each attribute that you want to expose. Show Property
is a declarative component that reads a property value on the component or task flow (for which you have created the custom panel), and displays an input field for that property in the custom panel. Users can edit property values in the panel using the input fields.
For more information about custom panels, see Section 20.3.1.1, "Creating a Custom Property Panel."
To add a Show Property
component:
Open the page fragment that you created for the custom panel task flow.
From the Component Palette, select Oracle Composer.
Drag and drop a Show Property
component for each component attribute that you want to expose in the custom panel.
To ensure that the attribute displays correctly in the custom panel, set the attributes on each Show Property
component by referring to Section B.1.7, "Show Property."
Note: You can use theShow Property component even on pages outside of Oracle Composer. |
Example
Consider an example of a weather widget that is included inside a Show Detail Frame
component. A custom property panel is created to enable users to edit the Text, Auto Refresh, and Refresh Interval attributes on the weather widget. It includes three fields for users to provide values for these attributes. To enable users to set the three attributes on the weather widget, one Show Property
component is added for each attribute that is exposed in the panel. When a user edits the weather widget at runtime, the Component Properties dialog displays the custom panel with the three attributes, as shown in Figure 20-7.
The weather widget is consumed in a page along with a Poll
component as shown in the following example:
<cust:showDetailFrame text="Weather" id="sdf1" contentStyle="height:220.0px;" partialTriggers="p1"> <af:region value="#{bindings.weathertaskflowdefinition1.regionModel}" id="r1"/> <af:poll id="p1" interval="60000"/> </cust:showDetailFrame>
The Poll
component is used to deliver refreshed content to the weather widget at fixed intervals. The default interval is 60000 milliseconds.
The custom panel contains three panelLabelandMessage
components to provide input fields for the Text
, Auto Refresh
, and Refresh Interval
attributes. The fields on this panel are implemented as follows:
A showProperty
component is added to each panelLabelandMessage
component as shown in the following example:
<!-- Input field for setting the Text attribute, which displays on the component header --> <af:panelLabelAndMessage label="Text" id="plam2"> <pedc:showProperty label="Text" id="sp1" simple="true" value="#{sdfCustomPanel.text}"/> </af:panelLabelAndMessage> <!-- Checkbox to enable auto refresh, which controls whether the widget must be refreshed --> <af:panelLabelAndMessage label="Auto Refresh" id="plam3"> <pedc:showProperty label="Auto Refresh" id="sp2" simple="true" type="boolean" autoSubmit="true" value="#{sdfCustomPanel.autoRefresh}"/> </af:panelLabelAndMessage> <!-- LOV to display values for Refresh Interval when auto refresh is enabled --> <af:panelLabelAndMessage label="Refresh Interval" id="plam4"> <pedc:showProperty label="Refresh Interval" id="sp3" simple="true" type="list" disabled="#{!sdfCustomPanel.autoRefresh}" value="#{sdfCustomPanel.refreshInterval}" selectItems="#{sdfCustomPanel.selectItems}" binding="#{sdfCustomPanelRequestBean.refreshIntervalShowProp}"/> </af:panelLabelAndMessage>
where sdfCustomPanel
references a managed bean, SDFCustomPanelBean.java
.
The task flow definition of the custom panel contains a reference to the bean:
<managed-bean id="mb1">
<managed-bean-name id="mb1_name">sdfCustomPanel</managed-bean-name>
<managed-bean-class id="mb1_class">portal.weather.panel.SDFCustomPanelBean</managed-bean-class>
<managed-bean-scope id="mb1scope">session</managed-bean-scope>
</managed-bean>
The SDFCustomPanelBean.java
bean provides the logic to handle values for the different attributes exposed in the panel. In the bean, the SelectionContext
API is used to read and write values for each attribute as follows:
Get hold of the selected component, that is, the component on which the properties are displayed; in this example, a Show Detail Frame
component, as the weather widget is included inside one.
Read the attribute value on the selected component.
Get the attribute value that the user specifies and set that value for the component attribute.
For example, the Refresh Interval
attribute is enabled only if Auto Refresh
in selected, and it displays a dropdown menu with the values defined in the managed bean. The Poll
component on the page is wired to the Show Property
component so that the widget refresh is driven by the value of the Show Property component. The code to handle the value for the Refresh Interval
property is as follows:
. . . /** Set the refresh interval attribute value on the component public void setRefreshInterval(String _refreshInterval) { this._refreshInterval = _refreshInterval; } **/ public String getRefreshInterval() { if (_autoRefresh == true && _refreshInterval != null) return _refreshInterval; // Get hold of the component whose properties you want to edit SelectionContext selCtx = ComposerContext.getCurrentInstance().getSelectionContext(); UIComponent selComp = selCtx.getSelectedComponent().getUIComponent(); if (selComp instanceof ShowDetailFrame) { // Get the refresh interval value specified for the Poll component RichPoll pollComp = (RichPoll) selComp.findComponent("p1"); if (_autoRefresh == false) _refreshInterval = "Refresh interval not applicable"; else if (pollComp.getInterval() < 0) _refreshInterval = "60000"; else _refreshInterval = Integer.toString(pollComp.getInterval()); } return _refreshInterval; } . . . public List<SelectItem> getSelectItems() { return _selectItems; } . . . private static List<SelectItem> _selectItems; static { _selectItems = new ArrayList<SelectItem>(); SelectItem si = new SelectItem("60000", "1 Minutes"); _selectItems.add(si); si = new SelectItem("120000", "2 Minutes"); _selectItems.add(si); si = new SelectItem("180000", "3 Minutes"); _selectItems.add(si); }
When a user selects a value for the Refresh Interval
property and clicks Apply in the Component Properties dialog, the save listener is called and the save
event handler ensures that the value is saved back to the bean. The relevant code in the save event handler implementation is as follows:
public void save() { . . . if (_autoRefresh) { aa = new AttributeComponentChange("interval", Integer.parseInt(_refreshInterval)); changeManager.addComponentChange(context, pollComp, aa); aa.changeComponent(pollComp); } else { aa = new AttributeComponentChange("interval", new Integer(-1)); changeManager.addComponentChange(context, pollComp, aa); aa.changeComponent(pollComp); } }
All properties on the Parameters and Display Options tabs in the Component Properties dialog can take Expression Language (EL) expressions. The Expression Builder option available on such parameters opens the Edit dialog, which is a simple expression builder as shown in Figure 20-8. The expression builder is particularly useful when you want a value that is retrievable but otherwise unknown, for example, when you want a value to be the name of the current user or the current application skin.
You can customize the expression builder to provide more options by making the necessary entries in the Oracle Composer extension file, pe_ext.xml
. This section explains how to extend the expression builder to add custom capabilities. It contains the following subsections:
You can extend the expression builder by adding custom options to the expression value dropdown list. Custom options must be defined and included in the pe_ext.xml
file. For each new option you want to add, you must define and include a <selector>
element in the pe_ext.xml
file.
To configure custom options in the Oracle Composer extension file:
Create a Java bean, for example UserInformation.java
, with the logic to populate the expression dialog with your custom options. Example 20-9 shows the code of a sample Java bean used to display a new string, User Name
, as a custom value in the expression dialog.
Example 20-9 Sample Code to Add a Custom Value in the Expression Dialog
package view; import java.util.ArrayList; import java.util.List; import oracle.adf.view.page.editor.elbuilder.ELParameter; import oracle.adf.view.page.editor.elbuilder.ELParameterValue; public class UserInformation implements ELParameter { public String getName() { return mName; } public List<ELParameterValue> getValues() { if (mValues == null) { mValues = new ArrayList<ELParameterValue>(); for(String[] args : mValueList) { mValues.add(new ELParameterValue(args[0], args[1])); } } return mValues; } private static String[][] mValueList = {new String[]{"User Name", "#{securityContext.userName}"}}; private String mName = "User Name"; private List<ELParameterValue> mValues; }
Add an <elbuilder-config>
element in the pe_ext.xml
file to register the bean.
For information about creating the extension file, see Section 20.2.1.2, "Registering Add-Ons with Oracle Composer."
Add a <selector>
element within the <elbuilder-config>
section, and provide details about the bean you created, as shown in the following example:
<elbuilder-config> <!-- define selector --> <selector id="UserInformation"> view.UserInformation </selector> <!-- include selector --> <selectors> <selector id="UserInformation" rendered="true"/> </selectors> </elbuilder-config>
You can have multiple <selector>
entries for different custom options.
Custom options display for all attributes by default. You can use the rendered
attribute on <selector>
to display an option conditionally, based on specific criteria.
Save the pe_ext.xml
file.
The selector in the runtime expression builder displays the custom value along with the default values, as shown in Figure 20-9.
Figure 20-9 Expression Builder Displaying a Custom Value
Typically, while editing a task flow parameter in Oracle Composer, the user enters a value in the text box provided in the Component Properties dialog, as shown in Figure 20-10. However, many a time the user is confused about what value to specify in a particular field. Rather than leave them guessing, as a developer who knows the values that each parameter can take, you can make it easier for users by listing all valid options, wherever possible. You can configure Oracle Composer to display a list of values (LOV) or a picker against any parameter.
Figure 20-10 Parameters Tab on the Component Properties Dialog for a Task Flow
You can display a predefined set of values for a parameter using the following options:
Static LOV
To display a list of predefined values.
Dynamic LOV
To display a list of values generated by evaluating an EL value that is computed when the page is run.
Global LOV
To display a global list of values that can be used in any task flow in the application.
Picker
To display all values in a picker format, for example, a document picker.
This section describes how to configure different types of LOVs for task flow parameters. It contains the following subsections:
Example Used to Describe the Procedures in This Section
Some of the procedures in this section use the example of a simple weather task flow, weather-task-flow-definition
, which displays weather information for a selected city, as shown in Figure 20-11.
The task flow provides two parameters, zipCode
and tempUnits
, that users can modify to display weather details for a selected city and in a selected temperature unit (Fahrenheit or Celsius) respectively. This weather task flow example is used to explain how to configure the following types of LOVs:
A static LOV with the values Celsius
and Fahrenheit
for the tempUnits
parameter, as shown in Figure 20-12.
A picker with two fields that enable users to specify a city name or ZIP code (Figure 20-13) to view corresponding details in the weather task flow.
Alternatively, a dynamic LOV for the zipCode
parameter to display values (Figure 20-14) based on an EL value that is evaluated at runtime.
The weather task flow includes a task flow definition file, weather-task-flow-definition.xml
, with the code shown in Example 20-10.
Example 20-10 The weather-task-flow-definition.xml FIle
<?xml version="1.0" encoding="US-ASCII" ?> <adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2"> <task-flow-definition id="weather-task-flow-definition"> <default-activity id="defaultactivity1">weather</default-activity> <input-parameter-definition id="inputparam1"> <name id="inputparam1name">zipcode</name> <value>#{pageFlowScope.zipcode}</value> <class>java.lang.String</class> <required/> </input-parameter-definition> <input-parameter-definition id="inputparam2"> <name id="ip2name">tempUnits</name> <value>#{pageFlowScope.tempUnits}</value> <class>java.lang.String</class> </input-parameter-definition> <view id="weather"> <page>/weather.jsff</page> </view> <use-page-fragments/> </task-flow-definition> </adfc-config>
The parameters, shown in bold text, are defined in such a way that values provided by users at runtime are stored in a session bean, pageFlowScope
, from where they can be read by other components.
When you edit the task flow at runtime, the Parameters tab displays two input text fields to provide parameter values. The following sections explain how to enable LOVs for these task flow parameters so that users can choose from a list of predefined of options.
This section describes how to configure different types of LOVs for task flow parameters. It includes the following subsections:
Use a static LOV to display a list of predefined values against a parameter. You can configure a static LOV by defining an <lov-config>
section with nested <enumeration>
elements in the Oracle Composer extension file, pe_ext.xml
. This section uses the weather task flow example and describes how to configure a static LOV for the tempUnits
parameter.
To configure a static LOV:
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 (for example, in the APPLICATION_HOME
\Portal\adfmsrc\META-INF
directory):
From the File menu, select New.
In the New Gallery dialog, expand General, select XML, then XML Document.
Click OK.
Name the file pe_ext.xml
.
Add an <lov-config>
section and include the task flow definition with nested <enumeration>
elements, as shown in the following code example:
<lov-config> <!-- Entry for the task flow in which you are configuring the LOV --> <task-flow-definition taskflow-id="/WEB-INF/weather-task-flow-definition.xml#weather-task-flow-definition"> <!-- Specifying the parameter for which you want to define a static LOV --> <input-parameter-definition> <name>tempUnits</name> <!-- List of values to be displayed for the parameter --> <enumeration inline="true"> <item> <name>Celcius</name> <value>c</value> <description>Temperature in Celcius</description> </item> <item> <name>Fahrenheit</name> <value>f</value> <description>Temperature in Fahrenheit</description> </item> </enumeration> </input-parameter-definition> </task-flow-definition> </lov-config>
You can configure any number of static LOVs within the <lov-config>
section.
Note: To allow translatable strings to be provided for a parameter name, you can use an EL value for the name, for example,#{resourceBundle.temp_units} . |
Save the file.
Use a dynamic LOV to display a list that is generated dynamically at runtime by evaluating an EL value. This section uses the weather task flow example and describes how to configure a dynamic LOV for the zipCode
parameter. To keep the example simple, the managed bean only provides static values that are displayed on the Zipcode
field at runtime.
To configure a dynamic LOV:
Create a bean, for example, weatherBean
, and define the list of values for the Zipcode
parameter. The following example shows the relevant code snippet:
package portal.weather; . . . public List<SelectItem> getCitiesList() { return citiesList; } private static final String F = "°F"; private static final String C = "°C"; private static final String [][] selectItems = {{"Redwood City", "94065"}, {"Novi, MI", "48375"}, {"Los Angeles", "90001"}, {"New York", "10036"}}; private static final List<SelectItem> citiesList = new ArrayList<SelectItem>(); static { for (String[] city : selectItems){ citiesList.add(new SelectItem(city[1], city[0])); } }
Register weatherBean
in the application's faces-config.xml
file, as shown in the following example:
<managed-bean> <managed-bean-name>weatherBean</managed-bean-name> <managed-bean-class>portal.weather.WeatherBean</managed-bean-class> <managed-bean-scope>request</managed-bean-scope> </managed-bean>
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 (for example, in the APPLICATION_HOME
\Portal\adfmsrc\META-INF
directory):
From the File menu, select New.
In the New Gallery dialog, expand General, select XML, then XML Document.
Click OK.
Name the file pe_ext.xml
.
Add an <lov-config>
section, include the task flow definition with an <enumeration>
element, and reference the managed bean for the parameter value, as shown in the following example:
<lov-config> <task-flow-definition taskflow-id="/WEB-INF/weather-task-flow-definition.xml#weather-task-flow-definition"> <input-parameter-definition> <name>zipcode</name> <value>90001</value> <enumeration items="#{weatherBean.citiesList}"/> <input-parameter-definition> </task-flow-definition> </lov-config>
You can configure any number of dynamic LOVs within the <lov-config>
section.
Save the file.
Typically, a picker enables users to select a value from a popup dialog that displays all available options, for example, a color picker or date picker. Configuring a picker for a task flow parameter involves the following high level tasks:
Create the picker task flow with a UI of your choice.
Define parameters on the picker task flow. These parameters are used to populate the main task flow parameter (the one for which you are configuring the picker).
Configure the main task flow parameter to display the picker that you created. You must add this configuration in the pe_ext.xml
file.
This section explains these steps in detail using the weather task flow as an example. It shows how to configure a city picker for the zipCode
parameter. The picker task flow enables users to specify the city name and get the ZIP code for that place. The ZIP code from the picker is then pushed to the Zipcode field in the weather task flow. This section includes the following subsections:
Create a picker task flow with a JSFF fragment. Design the fragment to display fields or options of your choice.
To create the picker task flow:
In your WebCenter application project, create an ADF task flow, for example, weather-picker-task-flow-definition
:
From the File menu, choose New.
In the New Gallery dialog, expand Web Tier, select JSF, then ADF Task Flow.
Click OK.
Add a view
object to the task flow, for example, weatherPicker
.
Double-click the view to create the weatherPicker.jsff
fragment.
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. |
Design the fragment with components of your choice. Example 20-11 shows a sample task flow containing two Input Text
components that enable users to search for ZIP codes in an XML file, and two UI controls, OK
and Cancel
.
Example 20-11 Sample code in the Picker 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" xmlns:f="http://java.sun.com/jsf/core"> <af:panelStretchLayout id="psl1"> <f:facet name="center"> <af:panelGroupLayout id="pgl1" layout="vertical"> <af:panelGroupLayout id="pgl2" layout="horizontal"> <!-- Text field and Search button to search for a city by specifying the ZIP code --> <af:inputText label="Enter Zip Code" id="it1" value="#{pageFlowScope.weatherPicker.searchZipcode}"/> <af:commandButton text="Search By Zipcode" id="cb1" actionListener="#{pageFlowScope.weatherPicker.zipcodeSearch}"/> </af:panelGroupLayout> <af:panelGroupLayout id="pgl3" layout="horizontal"> <!-- Text field and Search button to search for a city by specifying the city name --> <af:inputText label="Enter City" id="it2" value="#{pageFlowScope.weatherPicker.searchCity}"/> <af:commandButton text="Search By City" id="cb2" actionListener="#{pageFlowScope.weatherPicker.citySearch}"/> </af:panelGroupLayout> <!-- Output components to display the result from the search --> <af:outputFormatted value="#{pageFlowScope.weatherPicker.city}" id="of2"/> <af:outputFormatted value="#{pageFlowScope.weatherPicker.zipcode}" id="of3"/> </af:panelGroupLayout> </f:facet> <f:facet name="bottom"> <af:panelGroupLayout layout="horizontal" halign="end" id="pkrPgl"> <!-- OK button --> <af:commandButton action="ok" actionListener="#{pageFlowScope.weatherPicker.populateReturnValue}" text="#{composerBundle.OK_BUTTON_TEXT}" id="okBtn"/> <af:spacer width="5" id="s1"/> <!-- Cancel button --> <af:commandButton actionListener="#{pageFlowScope.weatherPicker.closePickerPopup}" text="#{composerBundle.CANCEL_BUTTON_TEXT}" id="cnclBtn"/> </af:panelGroupLayout> </f:facet> </af:panelStretchLayout> </jsp:root>
The action listeners on the OK
and Cancel
buttons reference a managed bean, weatherPicker
. This bean also contains the logic to populate the parameter on the main task flow with the value specified in the picker.
Create the bean that you referenced in the picker task flow definition and add the logic to return values to the main task flow.
The following example shows the relevant code snippet of the weatherPicker
bean, which contains the logic to search for a city by name and return the ZIP code:
package portal.weather.picker; . . . public void populateReturnValue(ActionEvent ae) { Map map = (Map)RequestContext.getCurrentInstance().getPageFlowScope().get("outParam"); if (map != null) map.put("outParamVal", _zipcode); } public void closePickerPopup(ActionEvent ae) { UIComponent component = ae.getComponent(); while (!(component instanceof RichPopup)) component = component.getParent(); if (component != null) ((RichPopup)component).cancel(); } . . .
Register the weatherPicker
bean in the task flow definition file, as shown in the following example:
<managed-bean id="pickerbean"> <managed-bean-name id="pickerbeanname">weatherPicker</managed-bean-name> <managed-bean-class id="pickerbeanclass">portal.weather.picker.WeatherPicker</managed-bean-class> <managed-bean-scope id="pickerbeanscope">pageFlow</managed-bean-scope> </managed-bean>
Define two input parameters, inParamVal
and outParam
, on the picker task flow, as shown in the following example:
<!-- Parameter used to store the value that must be passed to the main task flow --> <input-parameter-definition id="pickerip1"> <name id="pickerip1name">outParam</name> <value>#{pageFlowScope.outParam}</value> <class>java.util.Map</class> </input-parameter-definition> <!-- Parameter used to store the value specified by the user in the picker --> <input-parameter-definition id="pickerip2"> <name id="pickerip2name">inParamVal</name> <value>#{pageFlowScope.inParamVal}</value> <class>java.lang.String</class> </input-parameter-definition>
These parameters are referenced in pageFlowScope
and will be used to read and populate the main task flow parameter, zipCode
. When a user clicks the picker icon next to the Zip Code field, the current value of the field is passed to the session bean using inParamVal
. When a user specifies a city name in the picker task flow and clicks OK, the bean gets the ZIP code for that city and passes it to the main weather task flow using outParam
.
Define task flow return activities and control flow rules for the OK
and Cancel
buttons. These activities and rules ensure that control is returned to the task flow when either of the buttons is clicked. You can define task flow return activities and control flow rules as shown in the following example:
<!-- The outcome to be returned to the task flow if a user clicks OK --> <task-flow-return id="ok"> <outcome id="ok1"> <name id="okayed">ok</name> </outcome> </task-flow-return> <!-- The outcome to be returned to the task flow if a user clicks Cancel --> <task-flow-return id="cancel"> <outcome id="cancel1"> <name id="canceled">cancel</name> </outcome> </task-flow-return> <!-- Rules to pass control flow to the ok activity if the user clicks OK and to the cancel activity if the user clicks Cancel --> <control-flow-rule id="flowrule1"> <from-activity-id id="fromactivity1">weatherPicker</from-activity-id> <control-flow-case id="flowcase1"> <from-outcome id="fromoutcome1">ok</from-outcome> <to-activity-id id="toactivity1">ok</to-activity-id> </control-flow-case> <control-flow-case id="flowcase2"> <from-outcome id="fromoutcome2">cancel</from-outcome> <to-activity-id id="toactivity2">cancel</to-activity-id> </control-flow-case> </control-flow-rule>
The task flow definition will now have code similar to the following example:
<?xml version="1.0" encoding="US-ASCII" ?> <adfc-config xmlns="http://xmlns.oracle.com/adf/controller" version="1.2"> <task-flow-definition id="weather-picker-task-flow-definition"> <default-activity id="pickeractivity1">weatherPicker</default-activity> <input-parameter-definition id="pickerip1"> <name id="pickerip1name">outParam</name> <value>#{pageFlowScope.outParam}</value> <class>java.util.Map</class> </input-parameter-definition> <input-parameter-definition id="pickerip2"> <name id="pickerip2name">inParamVal</name> <value>#{pageFlowScope.inParamVal}</value> <class>java.lang.String</class> </input-parameter-definition> <managed-bean id="pickerbean"> <managed-bean-name id="pickerbeanname">weatherPicker</managed-bean-name> <managed-bean-class id="pickerbeanclass">portal.weather.picker.WeatherPicker</managed-bean-class> <managed-bean-scope id="pickerbeanscope">pageFlow</managed-bean-scope> </managed-bean> <view id="weatherPicker"> <page>/weatherPicker.jsff</page> </view> <task-flow-return id="ok"> <outcome id="ok1"> <name id="okayed">ok</name> </outcome> </task-flow-return> <task-flow-return id="cancel"> <outcome id="cancel1"> <name id="canceled">cancel</name> </outcome> </task-flow-return> <control-flow-rule id="flowrule1"> <from-activity-id id="fromactivity1">weatherPicker</from-activity-id> <control-flow-case id="flowcase1"> <from-outcome id="fromoutcome1">ok</from-outcome> <to-activity-id id="toactivity1">ok</to-activity-id> </control-flow-case> <control-flow-case id="flowcase2"> <from-outcome id="fromoutcome2">cancel</from-outcome> <to-activity-id id="toactivity2">cancel</to-activity-id> </control-flow-case> </control-flow-rule> <use-page-fragments/> </task-flow-definition> </adfc-config>
Save the task flow definition file.
To display a custom picker for a task flow parameter, you must configure the picker for that parameter in the Oracle Composer extension file, pe_ext.xml
.
To configure a picker for a task flow parameter:
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 (for example, in the APPLICATION_HOME
\Portal\adfmsrc\META-INF
directory):
From the File menu, select New.
In the New Gallery dialog, expand General, select XML, then XML Document.
Click OK.
Name the file pe_ext.xml
.
Add an <lov-config>
section and include the task flow definition with an <enumeration>
element referencing the picker task flow, as shown in the following code example:
<?xml version="1.0" encoding="UTF-8"?> <pe-extension xmlns="http://xmlns.oracle.com/adf/pageeditor/extension"> <lov-config> <task-flow-definition taskflow-id="/WEB-INF/weather-task-flow-definition.xml#weather-task-flow-definition"> <!-- Parameter for which you defined the picker --> <input-parameter-definition> <name>zipCode</name> <value>null</value> <!-- enumeration items coming from the picker task flow --> <enumeration picker="/WEB-INF/weather-picker-task-flow-definition.xml#weather-picker-task-flow-definition"/> </input-parameter-definition> </task-flow-definition> </lov-config> </pe-extension>
You can configure pickers for any number of parameters within the <lov-config>
section.
Save the file.
When you edit the main task flow at runtime, the Component Properties dialog displays a magnifier icon next to that parameter. Clicking the icon invokes the picker task flow, in which users can select a value.
If you want to reuse an LOV in different task flow parameters within the application, you can define the LOV at a global level and reference it from the task flow parameters.
To configure an LOV from a global list:
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 (for example, in the APPLICATION_HOME
\Portal\adfmsrc\META-INF
directory):
From the File menu, select New.
In the New Gallery dialog, expand General, select XML, then XML Document.
Click OK.
Name the file pe_ext.xml
.
Add an <lov-config>
section and list the values within an <enumeration>
element (outside of the task flow definition), as shown in the following code example:
<lov-config>
<!-- Global enumerations ->
<enumeration id="temperature">
<item>
<name>Celcius</name>
<value>c</value>
<description>Temperature in Celcius</description>
</item>
<item>
<name>Fahrenheit</name>
<value>f</value>
<description>Temperature in Fahrenheit</description>
</item>
</enumeration>
<task-flow-definition . . . >
. . .
<lov-config>
You can configure any number of global LOVs within the <lov-config>
section.
Reference this global LOV from any input parameter definition in the pe_ext.xml
file, as shown in the following example:
<task-flow-definition taskflow-id="/WEB-INF/weather-task-flow-definition.xml#weather-task-flow-definition">
<input-parameter-definition>
<name>tempUnits</name>
<value>Celsius</value>
<enumeration ref="temperature"/>
</input-parameter-definition>
</task-flow-definition>
Save the file.
Depending on the type of LOV you configured for the task flow parameter, users will see different options to specify parameter values.
The Temp Units field, shown in Figure 20-15, lists values from the static LOV that you defined in the pe_ext.xml
file.
If you configured a picker for the Zipcode field, the field shows a magnifier icon to its right. This icon invokes a picker, as shown in Figure 20-16, that allows users to select a city by providing a name or ZIP code.
Event handlers are Java classes registered with Oracle Composer and called when a users performs an action on the page. For example, when a user clicks a Save button, Oracle Composer calls back into the application code to give the application a chance to respond to the Save action—or event. In addition to the event handlers that Oracle Composer provides by default, you might want to configure the application to perform additional workflows. This is useful in performing application-specific tasks on such events. Moreover, this is the recommended approach to, for example, save 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 20.6.1, "How to Create and Register Handlers for Composer UI Events"
Section 20.6.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 20.6.1.1, "UI Events that Support Event Handler Registration"
Section 20.6.1.3, "Registering an Event Handler with Oracle Composer"
Table 20-1 lists the UI events for which Oracle Composer currently supports registering of handlers.
Table 20-1 Events for Which Registering Handlers are Supported
Event | Cause | Event Type | Listener Interface to Be Implemented | Method to Be Implemented | Event Parameters |
---|---|---|---|---|---|
Save |
Invoked when a user clicks the Save or Save and Label 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 20-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
. The isCommit
method of the Save event can be used to differentiate between changes made to the page and to component properties. A value of true
implies that the user clicked the Save button on the Oracle Composer toolbar to save changes made to the page. A value of false
implies that the user clicked the Apply or OK button in the Component Properties dialog to save changes made to component properties.
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.
Note: If you are not able to see theoracle.adf.view.page.editor classpath, make sure that Oracle Composer is included in the project's libraries and classpath. To do this, right-click the project in the Application Navigator and select Project Properties. In the Project Properties dialog, select Libraries and Classpath, and add Oracle Composer to the list. |
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 SaveHandler 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 canceling 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.
Tip: You can use theSaveEvent.isCommit method to |
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 20.2.1.2, "Registering Add-Ons with Oracle Composer."
To register an event handler:
In the application's 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 process
EventName
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.
For every UI event triggered on the page in Oracle Composer, the corresponding event handler calls back a method from a listener registered with the application. By performing some additional configurations, you can specify the sequence in which event handlers must be executed and configure a listener to terminate a process or notify Oracle Composer that the event has been handled.
Specify a Sequence Number for an Event Handler
By specifying the sequence for event handlers, you can decide on the order in which the event handlers, and therefore the listeners, are called. You can assign a sequence number to a listener or modify the default value by defining a sequence
attribute against the registered event handler in the pe_ext.xml
file.
To specify a sequence number for a listener:
In the application's pe_ext.xml
file, locate the event-handler
element for the handler that you want to sequence.
Add a sequence
attribute as follows:
<event-handlers> <event-handler event="save" sequence="101">view.SaveHandler</event-handler> </event-handlers>
The value for the sequence
attribute must be a positive integer. If you do not define this attribute, the event handler is internally assigned a default sequence number of 100
.
Oracle Composer built-in listeners and listeners with no sequence numbers are assigned a default sequence number of 100
. If you want your event handler to be called before other event handlers, you must specify a value lesser than 100
.
Save the file.
Stop Event Processing and Notify Oracle Composer
You can configure an event handler to terminate processing of the current event and all subsequent events by throwing an exception. For this, you must declare the method used while implementing the listener as throws AbortProcessingException
. In addition, you can configure the handler to notify Oracle Composer that the event has been processed by using the Event.setEventHandled(true)
method.
For example, you can configure a delete
event handler to terminate the current event and all pending delete events and throw an exception when a user attempts to delete a component in Oracle Composer. To enable this, you must implement the DeletionListener
interface as shown in Example 20-12.
Example 20-12 DeletionListener Implementation
public class DeleteHandler implements DeletionListener { ... public void processDeletion(DeletionEvent delEvent) throws AbortProcessingException { // Get the component that must be deleted UIComponent comp = delEvent.getComponent(); if (comp != null) { try { // Assuming that a custom method, handleDelete(comp), handles deletion of // a component and returns true on successful deletion and false in case // of failure boolean deleteSucceeded = handleDelete(comp); // If deletion failed, then notify Oracle Composer that the delete event // has been handled. No further events are processed. if (!deleteSucceeded) delEvent.setEventHandled(true); } catch (Exception e) { // Catch Exception throw by handleDelete(comp) and handle it by throwing // AbortProcessingException to stop processing of delete events. throw new AbortProcessingException(e) } } } ... }
Drop handlers are Java classes registered with Oracle Composer and called when users click an Add link in the Resource Catalog. A drop handler declares the data flavors it can handle. Each resource in the Resource Catalog has a flavor. When a user clicks an Add link next to a resource, Oracle Composer queries all the registered drop handlers to check if they can handle the flavor. If only one drop handler can handle that flavor, then control is passed to that drop handler and the resource is added to the page immediately. If more than one drop handler can handle the flavor, then a context menu displays available drop handlers to users. The resource is dropped on the page when a user selects a Java drop handler from the context menu.
An example for a resource with multiple Java drop handlers is the Personal Documents subfolder available within the Documents folder, if you configured the Documents service in your catalog. This subfolder can be added as a Content Presenter, Document List Viewer, or Document Library.
Note: TheAdditionListener mechanism used to handle an Add operation in release 11.1.1.1 is still available, but now Oracle Composer calls drop handlers first to handle an Add operation in the catalog. It is recommended that you convert existing AdditionListener s to drop handlers. |
This section describes the procedure to create and register drop handlers in your application. It contains the following subsections:
This section describes how to create a sample drop handler for adding XML content from the Oracle Composer Catalog and register the drop handler with Oracle Composer. It includes the following subsections:
To create a drop handler with Oracle Composer, you must first extend the abstract base class, DropHandler
, and implement the getName()
, getAcceptableFlavors()
, and handleDrop()
methods. This section describes an example to add an XML component called Test
to the Resource Catalog and create a drop handler named Custom XML
for adding XML content.
To create a drop 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, TestDropHandler
.
In the Extends field, enter or browse to select the Drophandler
class, oracle.adf.view.page.editor.drophandler.DropHandler
.
Note: If you are not able to see theoracle.adf.view.page.editor classpath, make sure that Oracle Composer is included in the project's libraries and classpath. To do this, right-click the project in the Application Navigator and select Project Properties. In the Project Properties dialog, select Libraries and Classpath, and add Oracle Composer to the list. |
Add the required import statements and click OK.
The Java class source must look like the following:
package test; import java.awt.datatransfer.DataFlavor; import java.awt.datatransfer.Transferable; import java.io.ByteArrayInputStream; import javax.faces.component.UIComponent; import javax.faces.context.FacesContext; import javax.xml.parsers.DocumentBuilder; import javax.xml.parsers.DocumentBuilderFactory; import oracle.adf.rc.component.XmlComponentFactory; import oracle.adf.view.page.editor.drophandler.DropEvent; import oracle.adf.view.page.editor.drophandler.DropHandler; import org.apache.myfaces.trinidad.change.AddChildDocumentChange; import org.apache.myfaces.trinidad.change.ChangeManager; import org.apache.myfaces.trinidad.change.DocumentChange; import org.apache.myfaces.trinidad.context.RequestContext; import org.w3c.dom.Document; import org.w3c.dom.DocumentFragment; public class TestDropHandler extends DropHandler { public TestDropHandler() { super(); } public String getName() { return null; } public DataFlavor[] getAcceptableFlavors() { return new DataFlavor[0]; } public boolean handleDrop(DropEvent dropEvent) { return false; } }
Implement the getName()
method as follows to return the name of the drop handler:
public class TestDrophandler extends DropHandler { public TestDrophandler() { super(); } public String getName() { return "Custom XML"; } . . .
This value (Custom XML
) appears in the context menu on the Add link next to the XML component in the Oracle Composer Catalog.
Implement the getAcceptableFlavors()
method as follows to get a list of supported data flavors for the XML component:
public class TestDropHandler extends DropHandler { private static final DataFlavor[] ACCEPTABLE_FLAVORS = { XmlComponentFactory.XML_STRING_FLAVOR }; . . . public DataFlavor[] getAcceptableFlavors() { return ACCEPTABLE_FLAVORS; } . . .
Implement the handleDrop(DropEvent)
method as shown in the following sample file to handle the drop event and add the XML component to the page.
public class TestDropHandler extends DropHandler
{
. . .
public boolean handleDrop(DropEvent de) {
Transferable transferable = de.getTransferable();
UIComponent container = de.getContainer();
int index = de.getDropIndex();
try {
FacesContext context = FacesContext.getCurrentInstance();
RequestContext rctx = RequestContext.getCurrentInstance();
String fragMarkup = null;
// Get the TransferData from the Transferable (expecting a String)
Object data = getTransferData(transferable);
if (data instanceof String) {
fragMarkup = "<?xml version='1.0' encoding='UTF-8'?>" + (String)data;
} else {
return false;
}
// Get a DocumentBuilder
DocumentBuilderFactory factory = DocumentBuilderFactory.newInstance();
factory.setNamespaceAware(true);
factory.setValidating(false);
DocumentBuilder builder = factory.newDocumentBuilder();
// Parse the xml string into a Document object using DocumentBuilder
byte[] markupBytes = fragMarkup.getBytes();
Document newDoc =
builder.parse(new ByteArrayInputStream(markupBytes));
// Transform the Document into a DocumentFragment
DocumentFragment docFrag = newDoc.createDocumentFragment();
docFrag.appendChild(newDoc.getDocumentElement());
// Create an "add child" document change, that is, insert the fragment
DocumentChange change = null;
if (index < container.getChildCount()) {
// Get the ID of the component we'll be adding just before
String insertBeforeId = container.getChildren().get(index).getId();
change = new AddChildDocumentChange(insertBeforeId, docFrag);
} else {
change = new AddChildDocumentChange(docFrag);
}
// Apply the "add child" DocumentChange using ChangeManager
ChangeManager changeManager = rctx.getChangeManager();
changeManager.addDocumentChange(context, container, change);
// Refresh the target container using PPR
rctx.addPartialTarget(container);
// Mark the drop as completed.
return true;
} catch (Exception e) {
return false;
}
}
In this example, a DropEvent
parameter is passed to the handleDrop
method. This parameter has three attributes that can be described as follows:
transferable
, like DataFlavor
, is a standard Java class that contains the data being added.
container
is the container into which component must be dropped.
index
is the position of the component inside the container. For example, first, second, and so on.
Save the TestDropHandler.java
file.
After implementing the drop handler, you must register it with Oracle Composer. Registration is necessary for ensuring that the handler is called by Oracle Composer when a user clicks an Add link in the Catalog. Register drop handlers in the Oracle Composer extension file, /META-INF/pe_ext.xml
. For more information about creating this file, see Section 20.2.1.2, "Registering Add-Ons with Oracle Composer."
To register a drop handler:
In the pe_ext.xml
file, add the following entries:
<drop-handlers> <drop-handler>test.TestDropHandler</drop-handler> </drop-handlers>
where TestDropHandler
is the name of the drop handler implementation.
Save the file.
You can register any number of drop handlers in the extension file by adding that many <drop-handler>
elements.
Since you created a drop handler for XML components generated by the XmlComponentFactory
class, you can test how the drop handler works at runtime by adding an XML component to the Resource Catalog and then adding that component to your page at runtime.
To add an XML component to the Catalog:
Open the default catalog definition file, default-catalog.xml
.
For information about the location of this file, see "Default Resource Catalog Configuration".
Add the following code within the <contents>
section of the file:
<component id="pc" factoryClass="oracle.adf.rc.component.XmlComponentFactory"> <attributes> <attribute attributeId="Title" value="Test"/> <attribute attributeId="Description" value="XML content you can add to application pages"/> <attribute attributeId="IconURI" value="/adf/pe/images/elementtext_qualifier.png"/> </attributes> <parameters> <parameter id="xml"> <af:outputText value="Hello!" xmlns:af="http://xmlns.oracle.com/adf/faces/rich"/> </parameter> </parameters> </component>
Save the default-catalog.xml
file.
At runtime, the Oracle Composer Catalog shows the XML component, as shown in Figure 20-17. For more information, see Section 15.2.3.4, "Adding a Component."
Figure 20-17 XML Component in the Catalog
When a user clicks the Add link against a component in the Resource Catalog, all drop handlers supporting that flavor are displayed as options on the context menu of the Add link. However, if only a single drop handler is available to handle that flavor, then the resource is added to the page immediately.
Figure 20-18 shows the context menu displayed on clicking the Add link of the Test
XML component with the Custom XML
option and the default XML option.
Figure 20-18 Drop Handlers on an XML Component in the Catalog
Some component properties are not displayed in Oracle Composer's Component Properties dialog 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 20.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.
If you enable parameter passing on the task flow, administrators can customize Customization Manager by setting certain parameters. By default, an administrator cannot pass parameters to the Customization Manager task flow in Oracle Composer. Table 20-2 describes the parameters supported by the Customization Manager task flow.
Table 20-2 Customization Manager Task Flow Parameters
Parameter Name | Value | Description |
---|---|---|
defaultPage |
Page URI |
Used to specify the default page to be managed. If this value is null, the current page will be used. |
dynamicNodeMap |
|
Used to return a list of pages, XML documents, or task flows on a given page or fragment, using the following format: Page1.jspx -> List of {CustomizationManagerTaskFlowNode or CustomizationManagerPageNode or CustomizationManagerXMLNode} Use Use Use Note: Custom implementations of Collection classes such as |
showBase |
true/false Default: false |
Used to show or hide the column for the base document. |
showCurrentLayers |
true/false Default: true |
Used to show or hide the column showing details about the currently used layer. |
showAllLayers |
true/false Default: true |
Used to show or hide the column showing details about layers other than the current one. |
showLayersforCurrent |
Default: true |
Used to specify a list of layers that must be available in the Current Context column. This parameter takes the layer name and list of layer values and patterns that must be shown in the Current Context column. See Example 20-13 for more information. Note: Custom implementations of Collection classes such as |
showLayersforAll |
Default: false |
Used to specify a list of layers that must be available in the All Layers column. This parameter takes the layer name and list of layer values and patterns that must be shown in the All Layers column. See Example 20-13 for more information. Note: Custom implementations of Collection classes such as |
showDownload |
true/false Default: true |
Used to show or hide the Download link. |
showUpload |
true/false Default: true |
Used to show or hide the Upload link. |
showDelete |
true/false Default: true |
Used to show or hide the Delete link. |
showPromote |
true/false Default: true |
Used to show or hide the Promote link. |
This section describes the steps to enable parameter editing on the Customization Manager task flow. It contains the following subsections:
Section 20.9.1, "How to Set the Customization Manager Task Flow Parameters"
Section 20.9.2, "What Happens When You Enable Parameter Support"
To pass parameters to the Customization Manager task flow, you must define the parameters
attribute as part of the Customization Manager add-on panel configuration in your application's adf-config.xml
file.
To enable parameter editing on the task flow:
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 the namespace and include an <addon-panels>
entry.
Within <addon-panels>
, add an <addon-panel>
entry for the default Customization Manager panel and define the parameters
attribute by setting it to appUtilBean.customizationManagerParams
, as shown in Example 20-13.
Example 20-13 Customization Manager Add-On Referenced in adf-config.xml
<pe:page-editor-config xmlns="http://xmlns.oracle.com/adf/pageeditor/config">
<addon-panels>
<addon-panel name="oracle.adf.pageeditor.addonpanels.customization-manager" parameters="#{AppUtilBean.customizationManagerParams}"/>
. . .
</addon-panels>
</pe:page-editor-config>
where AppUtilBean
is a sample implementation of the AppUtilBean
class, and is as shown in the following example:
public Map<String, Object> getCustomizationManagerParams() { Map<String, Object> paramMap = new HashMap<String, Object>(); Map<String, List<String>> showLayersForCurrent = new HashMap<String, List<String>>(); showLayersForCurrent.put("user", Arrays.asList("admin%", "weblogic")); paramMap.put("showLayersForCurrent", showLayersForCurrent); Map<String, List<String>> showLayersForAll = new HashMap<String, List<String>>(); showLayersForAll.put("enterprise", Arrays.asList("Frys")); paramMap.put("showLayersForAll", showLayersForAll); return paramMap; }
Save the adf-config.xml
file.
Customization Manager displays options to users based on the new parameter settings.
You can customize the default Oracle Composer toolbar by adding, removing, or rearranging elements and overriding existing elements. To enable toolbar extensibility, the Oracle Composer toolbar elements have been grouped into sections. You can work with these sections to customize your toolbar. Each section has a specific name and contains one or more elements inside it, as shown in Figure 20-19.
Notes: The Save button is displayed on the toolbar only if the application is configured to use a sandbox. For more information, see Section 22.2, "Using Oracle Composer Sandbox."The Help icon is displayed on the toolbar only if you have configured a help provider in your application or hooked up help from Oracle Composer panels or dialogs. For more information, see Section B.4, "Oracle Composer Help Topic IDs." The Oracle Composer toolbar is created using the ADF Faces |
Table 20-3 describes the toolbar areas.
Table 20-3 Toolbar Areas
Section or Area | Description |
---|---|
|
Area containing the message with the page name. |
|
Area containing the status indicator. |
|
Area containing the View menu that allows users to switch between Design view and Source view. |
|
Area containing Oracle Composer add-ons. The add-ons are all displayed in a sequence within this area. For more information, see Section 20.2, "Creating Oracle Composer Add-Ons." |
|
Area containing the Help icon. |
|
Area containing the Save and Close buttons. |
|
Wide space between two sections. |
|
A line break between sections. All sections after a line break are pushed to a new line on the toolbar. |
Using toolbar sections, you can customize the Oracle Composer toolbar in the following ways:
Rearrange and hide built-in elements
Add new sections with custom elements
Modify default sections to display custom elements
This section describes the steps to customize the Oracle Composer toolbar. It contains the following sections:
Section 20.10.1, "How to Rearrange or Hide Toolbar Elements"
Section 20.10.4, "How to Override a Toolbar Section to Display Custom Content"
Use the toolbarLayout
attribute on a Page Customizable
component to control which toolbar sections are displayed and the order in which they appear.
To customize the toolbar for all editable pages in the application, you can create a template, add a Page Customizable
component to the template, and specify the toolbarLayout
attribute against the Page Customizable
component. You can then base all the pages in the application on that template.
If you do not specify a value for toolbarLayout
, this attribute is internally set to message stretch statusindicator newline menu addonpanels stretch help button
, which is the default layout for the Oracle Composer toolbar sections.
To customize the toolbar on an application page:
Open your customizable JSPX page in JDeveloper and select the Page Customizable
component in the Structure window.
In the Property Inspector, specify space-separated values for the toolbarLayout
attribute.
The section names in Table 20-3 are valid values for this attribute.
Note: You can add only onestretch value per row on the toolbar. If you add more than one stretch value, only the first one is displayed; all others are ignored. |
In Source view, the toolbarLayout
attribute appears as shown in the following example:
<pe:pageCustomizable id="pageCustomizable1"
toolbarLayout="button stretch statusindicator menu"
<cust:panelCustomizable id="panelCustomizable1" layout="scroll"/>
<f:facet name="editor">
<pe:pageEditorPanel id="pep1"/>
</f:facet>
</pe:pageCustomizable>
Save the JSPX file.
At runtime, the toolbar displays the sections you specified in the order you specified them (Figure 20-20).
Figure 20-20 Customized Oracle Composer Toolbar
You can add custom sections by creating facets and specifying the facet names in the toolbarLayout
attribute. Populate the new facets with elements you want to display on the toolbar. The following example shows you how to create a section; specifically, how to add a Report a Bug button that opens a popup that enables users to report a bug.
To add a custom section:
Open the JPSX page for which you want to customize the toolbar.
Add a facet
inside the Page Customizable
and name it bugreport
.
Add a Command Toolbar Button
component inside the facet and set the text
attribute to Report a Bug
.
To add an image to the button, specify the path to the image using the icon
attribute.
Add the Show Popup Behavior
component to invoke a popup on clicking the Command Toolbar Button
.
In Source view, the Page Customizable
would appear as follows:
<pe:pageCustomizable id="pageCustomizable1" toolbarLayout="message stretch bugrep newline menu stretch button" <f:facet name="bugrep"> <af:commandToolbarButton id="cmd1" text="Report a bug" icon="/images/bug.png" clientComponent="true"> <af:showPopupBehavior popupId="p1" triggerType="action"/> </af:commandToolbarButton> </f:facet> . . . <af:popup id="p1"> <af:dialog id="dlg1" title="File a Bug" affirmativeTextAndAccessKey="File"> <af:panelFormLayout labelWidth="30%" id="pfl1"> <af:inputText id="it0" maximumLength="80" label="Product/Component" required="true"/> <af:inputText id="it1" maximumLength="80" label="Subject" required="true"/> <af:inputText id="it2" rows="3" label="Problem" required="true"/> <af:inputText id="it3" rows="3" label="Steps" required="true"/> </af:panelFormLayout> </af:dialog> </af:popup> . . . </pe:pageCustomizable>
Save the page.
At runtime, the Oracle Composer toolbar displays a Report a Bug button, as shown in Figure 20-21.
Figure 20-21 Oracle Composer Toolbar with Custom Section
Clicking the Report a Bug button displays the File a Bug dialog that enables users to report a bug.
You can display custom content in a default toolbar section by adding a facet of the same name as the section and populating it with custom content. The facet content overrides the content of the default section. For example, to display a custom message to users in place of the Editing Page:
Page_Name
message, you can create a custom facet named message
and include an Output Text
component with the text you want to display to users. The Output Text
component then displays in place of the default message. The following example shows a Page Customizable
component with a custom toolbar message:
<pe:pageCustomizable id="pageCustomizable1"
toolbarLayout="message newline button stretch statusindicator menu"
<cust:panelCustomizable id="panelCustomizable1" layout="scroll"/>
<f:facet name="message">
<af:outputText value="Welcome!"/>
</f:facet>
<f:facet name="editor">
<pe:pageEditorPanel id="pep1"/>
</f:facet>
</pe:pageCustomizable>
Figure 20-22 shows the Oracle Composer toolbar displayed for the page at runtime.
Figure 20-22 Oracle Composer Toolbar with a Custom Message
This section provides information to assist you in troubleshooting problems you may encounter while using the Oracle Composer extensibility features.
For information about configuring logging, see "Configuring ADF Logging for Oracle Composer".
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.xm
l 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 20.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.xm
l 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 20.3, "Creating Custom Property Panels."
Problem
You do not see some properties of a component in the Component Properties dialog.
Solution
Ensure that the component properties are not filtered or restricted. For more information, see Section 20.8.1, "How to Define Property Filters" and Section 23.4, "Applying Attribute-Level Security."