8 Extending Runtime Editing Capabilities Using Oracle Composer

8.1.1 Oracle Composer Add-Ons

The Page Properties and Reset Page buttons on the Oracle Composer toolbar (Figure 8-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 such 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 8-1 Default Add-Ons on the Oracle Composer Toolbar

Description of "Figure 8-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 8.2, "Creating Oracle Composer Add-Ons."

8.1.2 Oracle Composer Custom Property Panels

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 8.3, "Creating Custom Property Panels."

8.1.3 Oracle Composer Events Handlers

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 workflows, such as clean up cached information and connections to resources. You can accomplish this with event handlers. For more information, see Section 8.4, "Configuring Event Handlers for Oracle Composer UI Events."

8.1.4 Drop Handlers

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. Drop handlers are Java classes registered with Oracle Composer and called when users click an Add link in the Oracle Composer 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. For more information, see Section 8.5, "Configuring Drop Handlers in the Oracle Composer Catalog."

8.1.5 Component Property Filters

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 8.6, "Defining Property Filters."

8.1.6 Oracle Composer Toolbar Customization

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 8-2.

Figure 8-2 Oracle Composer Toolbar with Default Elements

Description of "Figure 8-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 8.7, "Customizing the Oracle Composer Toolbar."

8.1.7 Configuration Files

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

8.2.1 How to Create and Register Add-Ons

You can create and register custom task flows that can be invoked from buttons on the Oracle Composer toolbar. All registered add-ons have an associated button that displays on the toolbar.

This section steps through the procedure of creating an add-on and registering it with Oracle Composer. It includes an example that demonstrates how to create an add-on that displays information about the Fusion Order Demo (FOD) application. The example add-on renders an About FOD button on the Oracle Composer toolbar (Figure 8-3) that users can click to invoke a task flow that contains information about FOD.

Figure 8-3 About FOD Button in Oracle Composer Toolbar

Description of "Figure 8-3 About FOD Button in Oracle Composer Toolbar"

This section contains the following subsections:

• Section 8.2.1.1, "Creating an Add-On Task Flow"

• Section 8.2.1.2, "Registering Add-Ons with Oracle Composer"

• Section 8.2.1.3, "Registering Add-Ons in adf-config.xml"

8.2.2 What Happens at Runtime

Custom add-ons that you register with Oracle Composer are rendered on the Oracle Composer toolbar along with the default add-ons.

In the example, an About FOD button is rendered on the Oracle Composer toolbar (Figure 8-4).

Figure 8-4 About FOD Button in Oracle Composer Toolbar

Description of "Figure 8-4 About FOD Button in Oracle Composer Toolbar"

Clicking this button displays the About FOD task flow (Figure 8-5).

Figure 8-5 About FOD Task Flow

Description of "Figure 8-5 About FOD Task Flow"

You can see a similar implementation in the StoreFrontModule in the Fusion Order Demo application. For information about this application, see Chapter 2, "Introduction to the WebCenter Sample Application."

8.2.3 How to Exclude Oracle Composer Default Add-Ons

You can choose to show or hide the Page Properties and Reset Page buttons in Oracle Composer. To display only the Page Properties or Reset Page button, you can selectively include the button's associated add-on in the adf-config.xml file. The built-in add-ons appear on the Oracle Composer toolbar as though they are configured in the adf-config.xml with the code shown in Example 8-4.

<!-- Page Properties add-on -->
<addon-panel name="oracle.adf.pageeditor.addonpanels.page-settings" />

<!-- Page Reset add-on -->
<addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" />

To exclude one of the built-in add-ons, you must explicitly add an entry for the other in the adf-config.xml file. In Example 8-5, to hide the Page Properties add-on, the Reset Page add-on entry is added to the file.

<addon-panels>
  <!-- Page Reset add-on -->
  <addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" />
  
  . . . 
  
</addon-panels>

The excluded add-on (Page Properties) is not displayed on the Oracle Composer toolbar. The included add-ons are displayed on the toolbar in the order in which they are defined in the adf-config.xml file.

8.2.4 How to Selectively Display Add-Ons

Depending on your business requirement, you may need to selectively hide the add-ons available to different users in Oracle Composer. To hide an add-on, you must set the rendered attribute for the panel to false using a constant value or an EL expression, as shown in Example 8-6.

<addon-panels>
  <addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" 
               rendered="#{securityBean.userInPageResetRole}" />  
  . . . 
</addon-panels>

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.

8.3.1 How to Create and Register Custom Property Panels

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 8.3.1.1, "Creating a Custom Property Panel"

• Section 8.3.1.2, "Registering a Custom Property Panel for a Component"

• Section 8.3.1.3, "Registering a Custom Property Panel for a Task Flow"

8.3.2 What Happens at Runtime

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.

8.3.3 How to Exclude Default Property Panels

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 8-9 shows the rendered attribute set to false for the Content Style property tab of a Command Button component. For information about default property panels, see Section B.3, "Oracle Composer Default Add-Ons and Property Panels."

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

8.3.4 How to Override Default Property Panels

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

8.3.5 How to Selectively Render 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}">

8.4.1 How to Create and Register Handlers for Composer UI Events

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 8.4.1.1, "UI Events that Support Event Handler Registration"

• Section 8.4.1.2, "Creating a Save Event Handler: Example"

• Section 8.4.1.3, "Registering an Event Handler with Oracle Composer"

8.4.2 What Happens When You Create and Register Event Handlers

At runtime, registered event handlers are called according to the sequence in the extension file and according to the order in which they were found on the class path. Oracle Composer's native event handler is called last.

On invocation of an event handler's processEventName method, if an event handler throws AbortProcessingException, then the event is canceled and no further event handlers are called, including Composer's native event handlers.If, however, an error occurs while instantiating an event handler, then Oracle Composer continues with the next event handler. A warning message is logged.

8.4.3 Performing Additional Oracle Composer Event Handler Configurations

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:

1. In the application's pe_ext.xml file, locate the event-handler element for the handler that you want to sequence.

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

3. 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 8-10.

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)
      }
    }
  }
  ...
}

8.5.1 How to Create and Register Drop Handlers

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 contains the following subsections:

• Section 8.5.1.1, "Creating a Drop Handler"

• Section 8.5.1.2, "Registering a Drop Handler with Oracle Composer"

8.5.2 What Happens at Runtime

When a user clicks the Add link against a component in the Oracle Composer 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 8-7 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 8-7 Drop Handlers on an XML Component in the Catalog

Description of "Figure 8-7 Drop Handlers on an XML Component in the Catalog"

8.6.1 How to Define Property Filters

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:

1. In the pe_ext.xml file, add the filter-config element as shown in the following example:

   Note:

   For information about creating the pe_ext.xml file, see Section 8.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>
   

2. Save the file.

8.6.2 What Happens at Runtime

At runtime, when you edit a component's properties, the properties that were filtered out are not rendered in the Component Properties dialog.

8.6.3 How to Remove Property Filters

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.

To remove a property filter:

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

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

3. Save the file.

8.7.1 How to Rearrange or Hide Toolbar Elements

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:

1. Open your customizable JSPX page in JDeveloper and select the Page Customizable component in the Structure window.

2. In the Property Inspector, specify space-separated values for the toolbarLayout attribute.

   The section names in Table 8-2 are valid values for this attribute.

   Note:

   You can add only one stretch 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>
   

3. Save the JSPX file.

8.7.2 What Happens at Runtime

At runtime, the toolbar displays the sections you specified in the order you specified them (Figure 8-9).

Figure 8-9 Customized Oracle Composer Toolbar

Description of "Figure 8-9 Customized Oracle Composer Toolbar"

8.7.3 How to Add New Sections to the 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:

1. Open the JPSX page for which you want to customize the toolbar.

2. Add a facet inside the Page Customizable and name it bugreport.

3. Add a Command Toolbar Button component inside the facet and set the text attribute to Report a Bug.

4. To add an image to the button, specify the path to the image using the icon attribute.

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

6. Save the page.

   At runtime, the Oracle Composer toolbar displays a Report a Bug button, as shown in Figure 8-10.

   Figure 8-10 Oracle Composer Toolbar with Custom Section

   
   Description of "Figure 8-10 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.

8.7.4 How to Override a Toolbar Section to Display Custom Content

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 8-11 shows the Oracle Composer toolbar displayed for the page at runtime.

Figure 8-11 Oracle Composer Toolbar with a Custom Message

Description of "Figure 8-11 Oracle Composer Toolbar with a Custom Message"