1. Developing for Oracle WebCenter Portal
  2. Additional WebCenter Portal Customizations
  3. Extending Oracle Composer

17 Extending Oracle Composer

Extend Oracle Composer (referred to as the page editor in WebCenter Portal) using JDeveloper.

Topics:

Adding Custom Actions to Components

To augment the built-in actions available to users when editing components in a portal, you can add custom actions to a component.

Figure 17-1 Actions Menu on a Component

Description of Figure 17-1 follows
Description of "Figure 17-1 Actions Menu on a Component"

There are three types of custom actions that you can add to a component:

Adding a Java-Based Custom Action to a Show Detail Frame Component in Design View

You can add a custom action that displays in an Actions menu in the chrome of a Show Detail Frame component in Design View in Composer. The custom action is a Java class that implements interface CustomActionListener. When the action is selected from the menu, the method processAction performs the indicated operation on the component (such as opening a dialog, for example).

To add a custom action to a Show Detail Frame component in Composer's Design view:

  1. Implement interface CustomActionListener, using method processAction() to implement the custom action.

    Method processAction takes class CustomActionEvent as parameter. The public methods in CustomActionEvent are:

    • getPagePath. Returns the path of the page that the component is on.

    • getComponent. Returns the selected component from Design view.

    • setMessageSeverity. Sets the severity level for FacesMessage.

    • setShowMessage. Sets the flag to show message after processing the custom action.

    • setMessageSummary. Sets the message summary.

    • setMessageDetail. Sets the message detail.

    For example:

    package custom
public class SaveTaskflowToCatalog implements CustomActionListener
{
  public void processAction(CustomActionEvent event)
  {
     // get the the page the component is on
     String pagePath = event.getPagePath();
     // get the SDF component
     UIComponent sdf = event.getComponent();
     try
     {
         // process the task flow and save to the cata log
 
         // set the error message in case exception occurs
         event.setErrorSummary("Failed to save the task flow to the resource catalog");
     }
     catch(AbortProcessingException ae)
    {
      throw ae; 
    }
    catch(Exception ee)
    {
      throw new AbortProcessingException("unexpected error");
     }
  }
}
  2. Configure the custom action in pe_ext.xml. For example:
    <event-handlers>
   <event-handler event="custom-action">custom.SaveTaskflowToCatalog</event-handler>
</event-handlers>
  3. To configure a custom action for an individual Show Detail Frame component on a page. For example:
    <cust:showDetailFrame shortDesc="Mac Rumors " displayHeader="true"    
               id="showDetailFrame1"  text="Mac Romors">  
  <af:region value="#{bindings.customactionstaskflowdefinition1.regionModel}"=
                           id="r1"/>
  <cust:customAction location="menu" action="custom.SaveTaskflowToCatalog" 
                 id="ca1"  text="Save to Catalog"/>
</cust:showDetailFrame>
  4. To configure a custom action for all Show Detail Frame components, add the custom action definition in adf-config.xml. For example:
    <cust:adf-config-child xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">   
  <enableSecurity value="true" />
    <customActions>
      <cust:customAction action="custom.SaveTaskflowToCatalog" 
                    displayName="Save to Catalog"
                    location="menu" 
                    rendered="#{custom.util.isSaveToCatalogEnabled}"/>
    </customActions>

Adding a Java-Based Direct Select Custom Action to a Component in Select View

You can add a direct select custom action to a component that displays in a popup menu when the component is selected in Select view in Composer. The custom action is a Java class that implements interface SelectActionListener. When the action is selected from the menu, the method processAction performs the indicated operation on the component (such as opening a dialog, for example).

To add a direct select custom action to a component in Composer's Select view:

  1. Implement interface SelectActionListener, using method processAction() to implement the custom action.

    Method processAction takes class SelectActionEvent as parameter. The public methods in CustomActionEvent are:

    • getPagePath. Returns the path of the page that the component is on.

    • getComponent. Returns the selected component from Select view.

    • setMessageSeverity. Sets the severity level for FacesMessage.

    • setShowMessage. Sets the flag to show message after processing the custom action.

    • setMessageSummary. Sets the message summary.

    • setMessageDetail. Sets the message detail.

    For example:

    package custom
public class RemoveSelectedComponent implements SelectActionListener
{
  public void processAction(SelectActionEvent event)
  {
     // get the the page the component is on
     String pagePath = event.getPagePath();
     // get the selected component
     UIComponent comp = event.getComponent();
     try
     {
         // set the error message in case exception occurs
         event.setErrorSummary("Failed to delete the component");
 
        // popup deletion confirmation dialog or delete the component here    
     }
     catch(AbortProcessingException ae)
    {
      throw ae; 
    }
    catch(Exception ee)
    {
      throw new AbortProcessingException("unexpected error");
     }
  }
}
  2. Optionally, sequence the menu items using the seq attribute set to first, last, or an integer representing an item's position on the menu.

    If no seq attribute is specified, actions are positioned in the order defined in the configuration.

    The actions with a seq value will be listed before those that do not have seq value. If a property panel is configured, the built-in actions Edit Component and Edit Parent Component will always be listed before other custom actions.

    For example:

    <selection-config>
  <selection-taglib-filter namespace="http://xmlns.oracle.com/adf/faces/rich">
         <tag name="inputText">
      <selection view="design" enabled="true"/>
      <operation name="view.SelectActionText2"
                 label="InputText Action2" 
                 seq="2"
                 filtered="false"/>
      <operation name="view.SelectActionTest3"
                 label="InputText Action3" 
                 seq="3"
                 filtered="false"/>
      <operation name="view.SelectActionTest"
                 label="InputText Action1" 
                 seq="first"
                 filtered="false"/>
      <operation name="separator" seq="1" filtered="false"/>
    </tag>
   </selection-taglib-filter>
</selection-config>
  3. Optionally, add separators to the custom actions menu by setting the operation name to separator in the selection configuration. For example:
      <selection-taglib-filter namespace="http://xmlns.oracle.com/adf/faces/rich">
    <tag name="goLink">
      <selection view="design" enabled="true"/>
      <operation name="oracle.adf.pageeditor.pane.inline-style-editor"
                        label="Inline Style"
                        filtered="false"/>
      <operation name="separator" filtered="false"/>
      <operation name="custom.action1" label="Action 1" filtered="false" icon="icon.png"/>
      <operation name="separator" filtered="false"/>
      <operation name="custom.action2" label="Action 2" filtered="false"/>
    </tag>
  </selection-taglib-filter>
  4. Include custom actions in Select view on an individual component, or globally for all component instances, by adding the adf-custom-actions operation in the select configuration for the component.

    For example:

    <selection-config>
  <global-filter>
    <selection view="design" enabled="false"/>
    <operation name="oracle.adf.pageeditor.pane.generic-property-inspector" 
                 label="Change Property"
                 filtered="false"/>
    <operation name="oracle.adf.view.page.editor.event.SelectRemoveListener"
               label="Remove" 
               icon="/adf/images/composer_delete_ena.png"
               filtered="#{testBean.compSelected ? 'false' : 'true'}"/>
  </global-filter>
 
  <selection-taglib-filter namespace="http://xmlns.oracle.com/adf/faces/rich">
    <tag name="goLink">
      <selection view="design" enabled="true"/>
      <operation name="oracle.adf.pageeditor.pane.inline-style-editor"
                 label="Inline Style"
                 filtered="false"/>
      <operation name="view.SelectActionTest"
                 label="#{testBean.goLinkActionLabel}1" 
                 seq="last"
                 filtered="false"/>
      <operation name="view.SelectActionTest2"
                 label="#{testBean.goLinkActionLabel}2" 
                 filtered="false"/>
      <operation name="separator" seq="first" filtered="false"/>
    </tag>
  </selection-taglib-filter>
 
</selection-config>
  5. In pe_ext.xml, configure the custom action.

    For example:

    <selection-taglib-filter namespace="http://xmlns.oracle.com/adf/faces/rich">
  <tag name="inputText">
       <selection view="design" enabled="true"/>
       <operation name="oracle.adf.pageeditor.pane.generic-property-inspector" 
                               label="Change Property"
                               filtered="false"/>
       <operation name="custom.RemoveSelectedComponent" 
                               label="Remove"
                               filtered="false"/>
  </tag>
</selection-taglib-filter>
  6. In pe_ext.xml, register the event handler.

    For example:

    <event-handlers>
  <event-handler event="select-action">
     oracle.adf.view.page.editor.event.SelectRemoveListener</event-handler> 
</event-handlers>

Adding Custom Actions to a Show Detail Frame Component by Using Facets

You can use the Show Detail Frame component's facets to define and display custom actions on Show Detail Frame components. For example, if your Show Detail Frame contains a list of services provided in your application, you can add a custom action, Show Detailed Information, which opens up a task flow containing details about the various services.

Oracle JDeveloper displays all facets available to the Show Detail Frame component in the Structure window, however, only those that contain UI components appear activated.

To add a Show Detail Frame facet:

  1. Right-click a Show Detail Frame component in the Structure window, and select Facets - Show Detail Frame, and click the arrow displayed to the right of this option.
  2. From the list of supported facets, select the facet you want to add.

    Note:

    A check mark next to a facet name means the facet is already inserted in the Show Detail Frame component. Selecting that facet name again would result in the facet getting deleted from the page.

    The f:facet element for that facet is inserted in the page.

  3. Add components in the facet according to your design requirements.

    For an end-to-end example of creating and using Show Detail Frame facets, see Example: Adding a Custom Action to a Show Detail Frame Component by Using Facets.

Example: Adding a Custom Action to a Show Detail Frame Component by Using Facets

Assume a JSF page, Page1.jspx, with a Panel Customizable component. Inside the Panel Customizable is a Show Detail Frame component (showDetailFrame1). Inside the Show Detail Frame is an ADF task flow. The Panel Customizable has two other Show Detail Frame components, one above and the other below showDetailFrame1. The task flow displays two Output Text components on the page.

You can configure an Additional Actions facet on the Show Detail Frame component to display a Customize action on the Actions menu along with the Move Up and Move Down actions. At runtime, the Customize action enables users to customize the text in the Output Text components. This section describes the steps you take to achieve this effect. It contains the following subsections:

How to Create an ADF Task Flow

To create an ADF task flow:

  1. From the File menu, select New.
  2. In the New dialog, select JSF under Web Tier node, and select ADF Task Flow under Items.
  3. Click OK.
  4. In the Create Task Flow dialog, click OK to create a task flow definition file by accepting the default values.
  5. From the ADF Task Flow tag library in the Component Palette, drop two view elements, view1 and view2, onto the task flow definition file.
  6. Drop a Control Flow Case from view1 to view2.
  7. Click the first view element and then click the second view element to draw the control flow line.

    Name this control flow case next.

  8. Similarly, drop a Control Flow Case from view2 back to view1 and name it prev.
  9. Create a backing bean called BackingBean.java to contain values for two variables view1 and view2.

    view1 and view2 are initialized with initialValue1 and initialValue2 respectively. Ensure that the code of the bean is as shown in the following example: 

    package view;

public class BackingBean {
    public BackingBean() {
    }
    
    private String view2 ="initial Value1";
    private String view1 = "initial Value2";

    public void setView2(String view2) {
        this.view2 = view2;
    }

    public String getView2() {
        return view2;
    }

    public void setView1(String view1) {
        this.view1 = view1;
    }

    public String getView1() {
        return view1;
    }
}
  10. In the task flow definition file, double-click view1 to create the page fragment (view1.jsff) for that element.
  11. Add a Panel Group Layout and two Output Text components to view1.jsff.
  12. Specify the Value for the first Output Text component to be #{backingBean.view1}, and specify the Value for the second Output Text component to be #{backingBean.view2}.
  13. Save view1.jsff, and close it.
  14. In the task flow definition file, double-click view2 to create the page fragment (view2.jsff) for that element.
  15. Add just one Output Text component to view2.jsff, and specify Value to be #{backingBean.view2}.
  16. Save view2.jsff, and close it.
How to Include an Additional Actions Facet

To include an Additional Actions facet:

  1. Create a JSF page, Page1.jspx, with a Panel Customizable component and a nested Show Detail Frame component.
  2. Add two more Show Detail Frame components, above and below the existing Show Detail Frame component.

    The purpose of adding three Show Detail Frame components is to enable the display of Move Up and Move Down actions along with the additional action on the first Show Detail Frame component, showDetailFrame1.

  3. Add the task flow definition file that you created in the previous step inside showDetailFrame1.
  4. Right-click the first Show Detail Frame in the Structure window, and select Facets - Show Detail Frame.
  5. Click the arrow to the right of this option, and from the list of supported facets, select Additional Actions.

    The f:facet-additionalActions element for that facet is inserted in the page.

  6. Add a Panel Group Layout inside the Additional Actions facet, and add a Button component inside the Panel Group Layout component.
  7. Set the Text attribute for the Button to Customize, and specify customize as the Action value.

    The page in the structure navigator should appear as shown in Figure 17-2.

    Figure 17-2 Page1.jspx in Structure Navigator

    Description of Figure 17-2 follows
    Description of "Figure 17-2 Page1.jspx in Structure Navigator"
  8. Save the page.
How to Create a Redirection Page

To create the redirection page:

  1. Create a JSF page called Page2.jspx, and add two Input Text components and a Button component.
  2. Specify the Value for the first Input Text component to #{backingBean.view2}, and set the Value attribute for the second Input Text component to #{backingBean.view1}.

    The purpose of adding Input Text components with references to the backing bean is to enable the passing of a user's input to the bean so that it can be reflected in the Output Text components on Page1.jspx.

  3. On the Button component, set the Text attribute to OK and specify back as the Action value.
  4. Save the page.

    You can now enable switching between the two pages by defining navigation rules.

How to Create Navigation Rules Between Pages

To define navigation rules between the pages:

  1. In the Application Navigator, under the project's WEB-INF folder, double-click the faces-config.xml file to open it.
  2. Click the Overview tab to view the file in Overview mode.
  3. Click the Add icon in the Managed Beans section.
  4. In the Create Managed Bean dialog, specify backingBean as the name.
  5. For the Class Name field, click the Browse button adjacent to it and browse to the BackingBean Java class that you created earlier. Click OK.
  6. Click OK.
  7. From the Scope list, select session and click OK.
  8. Select the Navigation Rules tab on the page.
  9. In the From Views table, select Page1.jspx.
  10. Under Navigation Cases, select Page2.jspx in the To View ID column, customize in the From Outcome column, and true in the Redirect column.
  11. In the From Views table, select Page2.jspx.
  12. Under Navigation Cases, select Page1.jspx in the To View ID column, back in the From Outcome column, and true in the Redirect column.

    In Source view, these entries appear as follows:

    <managed-bean>
    <managed-bean-name>backingBean</managed-bean-name>
    <managed-bean-class>view.BackingBean</managed-bean-class>
    <managed-bean-scope>session</managed-bean-scope>
  </managed-bean>
  <navigation-rule>
  <from-view-id>/Page1.jspx</from-view-id>
  <navigation-case>
    <from-outcome>customize</from-outcome>
    <to-view-id>/Page2.jspx</to-view-id>
      <redirect/>
    </navigation-case>
  </navigation-rule>
  <navigation-rule>
    <from-view-id>/Page2.jspx</from-view-id>
  <navigation-case>
    <from-outcome>back</from-outcome>
    <to-view-id>/Page1.jspx</to-view-id>
      <redirect/>
    </navigation-case>
</navigation-rule>
  13. Save the file.
What Happens at Runtime

In JDeveloper, run Page1.jspx. The Actions menu on the showDetailFrame1 component displays the Customize action, as shown in Figure 17-3.

Figure 17-3 Customize Action on the Actions Menu

Description of Figure 17-3 follows
Description of "Figure 17-3 Customize Action on the Actions Menu "

Clicking Customize takes you to Page2.jspx (Figure 17-4), where you can update the values for Label1 and Label2.

Figure 17-4 Page with Option to Edit Text

Description of Figure 17-4 follows
Description of "Figure 17-4 Page with Option to Edit Text"

Clicking OK takes you back to Page1.jspx, which reflects the recent text changes.

Adding Custom Actions to a Task Flow

You can customize a task flow by including it in a Show Detail Frame component. The Show Detail Frame component provides certain default actions to rearrange, show, and hide components. Further, you can define custom actions to trigger the desired navigational flow within the task flow at runtime. There are two ways in which you can enable custom actions on a task flow:

  • Enable custom actions directly on the task flow so that they are displayed on the Show Detail Frame component's Actions menu.

  • Enable custom actions on the Show Detail Frame component enclosing the task flow so that they are displayed on the Show Detail Frame component's Actions menu.

This section describes both approaches. It contains the following subsections:

Adding a Custom Action Directly on a Task Flow

Perform the steps in this section if you want the task flow to be self-contained, without the need to inherit global custom actions defined at the application level. You can define custom actions on a task flow by configuring a <customComps-config> section with a nested <customActions> element in the adf-settings.xml file. The additional custom actions specified in the adf-settings.xml file are displayed on the Show Detail Frame component that surrounds this task flow.

Typically, task flows are packaged and deployed as ADF libraries. When you create an adf-settings.xml file containing custom actions for a task flow, this file is also packaged in the ADF library.

To enable custom actions on a task flow:

  1. If it does not already exist, create the adf-settings.xml file in the META-INF directory under the project's Web context root (for example, in the APPLICATION_ROOT/Portal/src/META-INF directory):

    1. From the File menu, select New.

    2. In the New Gallery dialog, expand General, select XML, then XML Document.

    3. Click OK.

    Name the file adf-settings.xml.

  2. Add a <custComps-config> section in the file, with a nested <customActions> element.

  3. Add one <customAction> element for each internal task flow action that you want to display as a custom action on the Show Detail Frame Actions menu.

    You can add any number of custom actions under the <customActions> element.

    The following example shows the code of the adf-settings.xml file with a <customAction> entry. 

    <cust:custComps-config xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">
  <customActions>
   <customAction action="next" location="chrome"
                 rendered="true"
                 icon="/adf/webcenter/editheader_ena.png"
                 text="Next"
                  taskFlowId="/WEB-INF/task-flow-definition.xml#task-flow-definition"
                 shortDesc="next"/>
    <customAction action="prev" location="chrome"
                 rendered="true"
                 icon="/adf/webcenter/editheader_ena.png"
                 text="Previous"
 taskFlowId="/WEB-INF/task-flow-definition.xml#task-flow-definition"
                 shortDesc="prev"/>
  </customActions>
 </cust:custComps-config>

    Custom action definitions are similar at the task flow-level and application-level, except for the taskFlowId attribute that is used in the task flow-level setting. This attribute is used to identify the task flow on which the custom action must be defined. As an ADF library may have multiple task flows, this attribute helps identify the task flow that must render the custom action.

    Note:

    • If you are defining an icon for the custom action, you must ensure that the image you specify is available in the project root folder.

    • You can define custom actions for the internal actions defined in all task flows on your page; however, at runtime, the Show Detail Frame displays only those custom actions that correspond to the ADFc outcomes of the current view of the task flow.

  4. Save the adf-settings.xml file.

Adding a Custom Action on a Show Detail Frame Enclosing a Task Flow

You can define custom actions for a task flow on the enclosing Show Detail Frame component. When these actions are invoked at runtime, they trigger the desired navigational flow in the task flow. For example, you can define a custom action on a Show Detail Frame that specifies that the target task flow fragment opens in a separate browser window rather than inside the Show Detail Frame.

You can specify custom actions on Show Detail Frame components by adding Custom Action components as children of a Show Detail Frame component on the page. Custom actions defined in this way would be available only on the Show Detail Frame instance, which has the custom action as its child. Alternatively, you can specify custom actions in the application's adf-config.xml file. Custom actions defined in this way are available on all Show Detail Frame instances in the application.

This section provides information about defining custom actions on a Show Detail Frame. It contains the following subsections:

Defining Custom Actions at the Instance Level

Define custom actions on a particular Show Detail Frame component instance using the Custom Action component. You can find the Custom Action component in the Composer tag library. Custom actions are stored in the JSF page definition file of the page that contains the Show Detail Frame.

To define custom actions at the instance level:

  1. From the Component Palette, select Composer.
  2. Drag a Custom Action and drop it on the page inside the Show Detail Frame component, below the af:region element.

    Add one Custom Action component for each internal task flow action you want to display as a custom action on the Show Detail Frame Actions menu.

    Note:

    Add Custom Action components below the af:region element. You may face problems if the region is not the first child component of the Show Detail Frame.

  3. Define attributes for the Custom Action by referring to

    Ensure that you populate the Action attribute of each Custom Action with the correct ADFc outcomes of the associated task flow. The code should be similar to the following: 

    <cust:showDetailFrame text="showDetailFrame 1" id="sdf1">
  <af:region value="#{bindings.taskflowdefinition1.regionModel}"
             id="r1"/>
  <cust:customAction action="navigatefromview1" id="ca1"
                     location="both" icon="/Logo1.JPG"
                     text="View1 Action"
                     shortDesc="Custom View1 Action"/>
  <cust:customAction action="navigatefromview2"
                     location="both" id="ca2"
                     icon="/Logo2.JPG" text="View2 Action"
                     shortDesc="Custom View2 Action"/>
</cust:showDetailFrame>

    Note:

    You can add custom actions for all of the task flow's ADFc outcomes, but depending on the task flow view that is displayed, several or none of the custom actions are available at runtime.

    If you define a custom action without a corresponding task flow action, then the custom action is not rendered on the Show Detail Frame header at runtime.

    See Also:

    Creating a Task Flow in Developing Fusion Web Applications with Oracle Application Development Framework

  4. Save and run the page.

At runtime, when you select an action from the Show Detail Frame's Actions menu, the associated control flow rule is triggered and the target task flow fragment is rendered.

Defining Custom Actions at the Global Level

Defining custom actions at the global level means making those custom actions available for all Show Detail Frame instances in an application. Though global-level custom actions are available on all Show Detail Frame components in an application, at runtime the header of any Show Detail Frame displays only those custom actions that correspond to the ADFc outcomes of the current view of the task flow.

Define global-level custom actions in your application's adf-config.xml file.

To define custom actions at the global level:

  1. Open the application's adf-config.xml file, located in the ADF META-INF folder under Descriptors in the Application Resources panel.
  2. Define custom actions using the <customActions> element with nested <customAction> tags for each action, as follows:

    Tip:

    To render a custom action only in page Edit mode, you can set the rendered attribute on the <customAction> tag to #{composerContext.inEditMode}. This returns a value of true if the page is in Edit mode. 

    <cust:adf-config-child xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">
  <enableSecurity value="true" />
  <customActions>
    <cust:customAction action="forward" displayName="Move Forward"
                       location="menu" rendered="true"
                       icon="/move_forward.png"/>
    <cust:customAction action="backward" tooltip="Move Backward" 
                       location="chrome" rendered="true"
                       icon="/move_backward.png"/>
  </customActions>
</cust:adf-config-child>

    Note:

    • If you implemented restrictions on the Show Detail Frame component's actions by performing the steps in ??? you already have a cust:customizableComponentsSecurity section in the adf-config.xml file. You can define custom actions in that section itself instead of the cust:adf-config-child section shown in the example.

    • If you are defining an icon for the custom action, you must ensure that the image you specify is available in the project root folder.

    • You can define custom actions for the internal actions defined in all task flows on your page; however, at runtime, the header of any Show Detail Frame displays only those custom actions that correspond to the ADFc outcomes of the current view of the task flow.

  3. Save the adf-config.xml file.

For additional information about defining custom actions, see Example: Adding a Custom Action to a Show Detail Frame Enclosing a Task Flow.

Resolving Conflicts Between Global-Level and Instance-Level Custom Actions

Each custom action is uniquely identified by the value of its action attribute. If you have defined custom actions with the same action attribute value at the global and instance levels, then there may be conflicts in how these custom actions are invoked at runtime, depending on other attribute values. At such times, the inheritGlobalActions attribute of the Show Detail Frame defines the behavior of other custom action attributes (other than the action attribute) as follows:

Note:

Regardless of the inheritGlobalActions setting (true or false) on the Show Detail Frame component:

  • The rendered attribute is not inherited even if it is not specified at the instance level.

  • The location attribute at the global or instance level should be set to the same value at both the global and instance levels.

  • If inheritGlobalActions=true, or you have not specified a value for inheritGlobalActions (defaults to false), the behavior of custom action attributes is as follows:

    • If you defined a custom action attribute at the global and instance levels, then the attribute value specified at the instance level is used.

    • If you defined a custom action attribute only at the instance level, then that attribute value is used.

    • If you defined a custom action attribute only at the global level, then that value is ignored and the default value is used.

  • If inheritGlobalActions=true, the behavior of custom action attributes is as follows:

    • If you defined a custom action attribute at the instance level, then its value is used regardless of whether the same attribute is specified at the global level.

    • If you defined a custom action attribute only at the global level, then that value is used.

    • If you have not defined a custom action attribute at the global or instance levels, then the attribute's default value is used.

After you have designed your application pages, you must deploy the application to the production environment. For more information, see ???

Note:

Runtime customizations that you perform on the page in the development environment are not carried over when you deploy the application to a target server.

Configuring Custom Actions that Display Task Flow Views in a Separate Browser Window

Custom actions typically display the target task flow views in place, inside the Show Detail Frame component. However, you can define a custom action to display a task flow view in a separate browser window.

To display a task flow view in a separate browser window, the control flow rule to that view must be prefixed with dialog: in the task flow definition file and in the action attribute of the custom action corresponding to that view. The following example shows an action attribute definition: 

<cust:customAction action="dialog:Next" id="ca1"
                   location="both" icon="/move_forward.png"
                   text="Next Action"
                   shortDesc="Next Action"/>

Setting Properties on the Popup Window

For a command component inside a task flow region, you can specify the default behavior using the useWindow, windowEmbedStyle, windowHeight, windowWidth, and returnListener attributes. The command component may have other such attributes that you can use. If you specify a return listener, on closing the dialog a particular action event is called to decide on the next navigation outcome. By default, without this setting, a dummy Rich Command Link component is created to trigger the task flow action.

When you define a listener on a command component, you must also configure the custom action to call the action event on this component. The actionComponent attribute on a custom action definition (global- and instance-level) enables you to specify the ID of the command component that must be queued for the action event. When the actionComponent attribute is specified, the Show Detail Frame component queues the action event on this component. Since this command component is inside your task flow, you change its attribute values at any time.

Example

Consider an example where you have included a task flow inside a Show Detail Frame component and defined a Simple Edit custom action corresponding to the task flow's navigation outcomes. A Command Button component inside the task flow is configured to launch a modal inline popup of size 300x200 on clicking the Simple Edit custom action. A return listener is configured on the command component so that it is called whenever the popup is closed.

The source code of the Command Button component inside the region is as follows: 

<af:commandButton text="dialog:simpleEditPoup"
                  id="SDFCustomActionCmd_simpleEditPoup"
                  action="dialog:simpleEditPoup" useWindow="true"
                  windowEmbedStyle="inlineDocument" windowWidth="300"
                  windowHeight="200"
                  windowModalityType="applicationModal"
                  returnListener="#{pageFlowScope.recentPagesBean.refreshMainView}"
                  visible="false"/>

The following example shows how you can specify a global custom action corresponding to the task flow outcome by defining the custom action in the adf-config.xml file. The ID of the Command Button component is specified against the actionComponent attribute on the custom action. 

<customizableComponentsSecurity xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">
  <enableSecurity value="true"/>
    <customActions>
     <customAction action="dialog:simpleEditPoup"
                   text="Simple Edit"
                   shortDesc="Simple Edit"
                   location="menu"
                   rendered="#{!changeModeBean.inEditMode}"
                   icon="/adf/pe/images/editproperties_ena.png"
                   actionComponent="SDFCustomActionCmd_simpleEditPoup"/>
    </customActions>
</customizableComponentsSecurity>

The following example shows how you can specify an instance-level custom action corresponding to the task flow outcome by adding a Custom Action component from the Composer tag library to the JSF page. The ID of the Command Button component is specified against the actionComponent attribute on the custom action. 

<cust:showDetailFrame id="sdf_for_RecentPagesTF1"
                      text="Recent Pages" stretchContent="false"
                      showResizer="never">
  <af:region id="RecentPagesTF1"
             value="#{bindings.regionBinding1.regionModel}"/>
  <cust:customAction action="dialog:simpleEditPoup"
                     text="My Simple Edit"
                     shortDesc="Simple Edit"
                     location="menu"
                     rendered="#{!changeModeBean.inEditMode}"
                     icon="/adf/pe/images/editproperties_ena.png"
                     actionComponent="SDFCustomActionCmd_simpleEditPoup"/>
</cust:showDetailFrame>

Note:

A custom action that is launched in a popup dialog is sent as a new request to the server. If you are using a Composer sandbox and are in Edit mode of a page, ensure that this request is launched in View mode by adding code in your servlet filter so that a new sandbox is not created for this page.

What Happens at Runtime

Custom actions configured in the adf-settings.xml file are merged with the custom actions configured in the adf-config.xml file and all actions relevant to the current view of the selected task flow are displayed on the parent Show Detail Frame component's Actions menu.

If you enabled custom actions at a global level, then the header of any Show Detail Frame displays these custom actions if they correspond to the navigation outcomes of the current view of the child task flow.

If you prefixed the action attribute value with dialog:, then the target view of the task flow opens in a separate browser window.

Example: Adding a Custom Action to a Show Detail Frame Enclosing a Task Flow

In this example, assume that your application contains a task flow, customactions, residing inside a Show Detail Frame. The task flow includes three view elements, view_gadget, edit_settings, and about_gadget, and three associated control flow rules, ViewGadget, EditSettings, and AboutGadget. Your object is to define custom actions so that the control flow rules are available as actions on the Actions menu of the Show Detail Frame component.

In this example, the control flow rules are added in such a way that users can navigate back and forth between the three views. Each view element has an associated page fragment of the same name:

  • The view_gadget.jsff fragment has a Panel Stretch Layout component. The center facet of this component is populated with an Active Output Text component whose Value attribute is set to View Gadget.

  • The edit_settings.jsff fragment has a Panel Stretch Layout component. The center facet of this component is populated with an Active Output Text component whose Value attribute is set to Edit Gadget Settings.

  • The about_gadget.jsff fragment has a Panel Stretch Layout component. The center facet of this component is populated with an Active Output Text component whose Value attribute is set to About This Gadget.

To enable custom actions on the task flow:

  1. Place the customactions task flow inside a Show Detail Frame component on a customizable page, MyPage.jspx.

    For information about creating a customizable page, see ???

  2. Add a Custom Action component from the Composer tag library as a child of the Show Detail Frame component, and set the Action and Text attributes to ViewGadget and View Gadget respectively.

  3. Add two more Custom Action components to the Show Detail Frame:

    • Set the Action and Text attributes for the first component to EditSettings and Edit Settings respectively.

    • Set the Action and Text attributes for the second component to AboutGadget and About Gadget respectively.

  4. Save and run MyPage.jspx.

    The view_gadget page fragment is rendered in the Show Detail Frame component (named My Gadget) on the page. The Actions menu displays the About Gadget and Edit Settings options. Click About Gadget to navigate to the about_gadget fragment. Note that the Actions menu now displays the navigation rules for the other two fragments (Figure 17-5).

    Figure 17-5 Custom Actions on a Show Detail Frame Enclosing a Task Flow

    Description of Figure 17-5 follows
    Description of "Figure 17-5 Custom Actions on a Show Detail Frame Enclosing a Task Flow"

To see this in action, look at the Composer Custom Actions sample application, ComposerCustomActions.jws, on the Oracle WebCenter Suite 11g Demonstrations and Samples page on Oracle Technology Network (OTN).

Adding Custom Actions that Display on Task Flows in the Component Navigator

The component navigator in Composer Structure view provides an option to zoom into a task flow and display the components on its page or fragment, as shown in Figure 17-6.

Figure 17-6 Edit Action on a Task Flow Instance

Description of Figure 17-6 follows
Description of "Figure 17-6 Edit Action on a Task Flow Instance"

Users can zoom in, edit the page or fragment, and zoom out of the task flow to navigate back to the page containing the task flow. In addition to the Edit Task Flow and Close links displayed next to a task flow name, you can configure your application to also display custom actions next to a task flow name, as shown in Figure 17-7.

Figure 17-7 Custom Action on a Task Flow Instance

Description of Figure 17-7 follows
Description of "Figure 17-7 Custom Action on a Task Flow Instance"

This section describes the procedure to enable custom actions on task flows in the component navigator. It contains the following sections:

How to Configure Custom Actions in the Component Navigator

To display custom actions against a task flow in the component navigator, you must create a Java bean that defines the custom action behavior and call this bean from the application page containing the task flow. This section describes the steps to do so in detail. It contains the following subsections:

Defining the Logic for the Custom Action

To begin with, you must decide on the custom action you want to provide to users and create a Java bean with the logic to be implemented when a user selects the custom action. This section describes the steps to implement simple logic to display a message to users on clicking the custom action. The sample bean also contains the code to display the Close/Edit Task Flow links along with the custom link.

To create a Java bean:

  1. From the File menu, choose New.
  2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.
  3. In the Create Java Class dialog, enter BackingBean in the Name field and click OK.

    The BackingBean.java file displays in Source view.

  4. Import the required libraries as follows:
    import javax.faces.application.FacesMessage;
import javax.faces.context.FacesContext;
import javax.faces.event.ActionEvent;
import oracle.adf.view.page.editor.sourceview.ComponentInfo;
  5. Add the following code:
    public class BackingBean {
  public BackingBean() {
  }

  public void action(ActionEvent actionEvent) {
      FacesContext context = FacesContext.getCurrentInstance();
      context.addMessage(null,
                         new FacesMessage(FacesMessage.SEVERITY_INFO, "Sample message to test whether the custom action works.",
                                          null));
  }

  public boolean isRendered() {
      return ComponentInfo.isRegion();
  }

  public String getZoomText() {
      return ComponentInfo.isRootNode() ? "Close" : "Edit Task Flow";
  }
}

    With this logic, the sample message you defined is displayed when a user clicks the custom action link against a task flow region.

    Use the isRegion() API to ensure that the custom action link is displayed only against task flow regions on the page. Use the isRootNode() API to ensure that the Edit Task Flow or Close link is displayed against the root component of the task flow.

  6. Save the bean.
Creating a JSF Page Containing the Custom Action

This section describes the procedure to create a JSF page containing the custom action that you want to display to users in Composer.

To create the JSF page:

  1. In your application project, create a JSF page called customList.jspx:

    1. From the File menu, select New.

    2. In the New Gallery dialog, expand Web Tier, select JSF, then JSF Page.

    3. Enter a name for the page and click OK.

  2. Design the custom action UI using components like Output Text and Command Link, as shown in the following sample page: 

    <?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
  <jsp:directive.page contentType="text/html;charset=UTF-8"/>
  <af:componentDef var="attrs" componentVar="component">
    <af:panelGroupLayout id="dc_pgl1" rendered="#{backingBean.rendered}">
      <af:outputText value="[" id="dc_ot1"/>
      <af:commandLink text="Test" id="dc_cl1"
                      actionListener="#{backingBean.action}"
                      binding="#{backingBean.customLink}"/>
      <af:outputText value="]" id="dc_ot2"/>
      </af:panelGroupLayout>
    </af:componentDef>
</jsp:root>

    This sample creates a custom action called Test. The actionListener and binding attributes on this action are bound to BackingBean, which you created earlier.

  3. To ensure that the default Edit Task Flow/Close options are also displayed next to the task flow, you must define a facet called zoom, as shown in the following example: 

    <af:xmlContent>
  <component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
    <facet>
      <facet-name>zoom</facet-name>
    </facet>
  </component>
</af:xmlContent>

  4. Include the zoom facet in the page content as shown in the following example: 

    <af:outputText value="[" id="dc_ot3"/>
<af:facetRef facetName="zoom"/>
<af:outputText value="]" id="dc_ot4"/>

    The source of the customLink.jspx page is as follows: 

    <?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
  <jsp:directive.page contentType="text/html;charset=UTF-8"/>
  <af:componentDef var="attrs" componentVar="component">
    <af:panelGroupLayout id="dc_pgl1" rendered="#{backingBean.rendered}">
      <af:outputText value="[" id="dc_ot1"/>
      <af:commandLink text="Test" id="dc_cl1"
                      actionListener="#{backingBean.action}"
                      binding="#{backingBean.customLink}"/>
      <af:outputText value="]" id="dc_ot2"/>
      <af:outputText value="[" id="dc_ot3"/>
      <af:facetRef facetName="zoom"/>
      <af:outputText value="]" id="dc_ot4"/>
      </af:panelGroupLayout>
      <af:xmlContent>
        <component xmlns="http://xmlns.oracle.com/adf/faces/rich/component">
          <facet>
            <facet-name>zoom</facet-name>
          </facet>
        </component>
      </af:xmlContent>
    </af:componentDef>
</jsp:root>

  5. Save the JSF page.

Calling the JSF Page from the Application Page Containing the Task Flow

Let us assume that you have a simple JSF page, MyPage.jspx, containing a task flow. The source of the page is as shown in the following example: 

<?xml version='1.0' encoding='UTF-8'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
          xmlns:pe="http://xmlns.oracle.com/adf/pageeditor"
          xmlns:cust="http://xmlns.oracle.com/adf/faces/customizable">
  <jsp:directive.page contentType="text/html;charset=UTF-8"/>
  <f:view>
    <af:document id="d1">
      <af:form id="f1">
        <af:panelStretchLayout topHeight="50px" id="psl1">
          <f:facet name="top">
            <pe:changeModeLink id="cml1"/>
          </f:facet>
          <f:facet name="center">
            <!-- id="af_one_column_header_stretched"  -->
            <pe:pageCustomizable id="pageCustomizable1">
              <cust:panelCustomizable id="panelCustomizable1" layout="scroll">
                <af:region value="#{bindings.taskflowdefinition1.regionModel}"
                           id="r1"/>
              </cust:panelCustomizable>
              <f:facet name="editor">
                <pe:pageEditorPanel id="pep1"/>
              </f:facet>
            </pe:pageCustomizable>
          </f:facet>
        </af:panelStretchLayout>
      </af:form>
    </af:document>
  </f:view>
</jsp:root>

The task flow, taskflowdefinition1, contains the following view.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 layout="scroll" id="pgl1">
    <af:commandButton text="commandButton 1" id="cb1"/>
    <af:commandButton text="commandButton 2" id="cb2"/>
  </af:panelGroupLayout>
</jsp:root>

To display the custom action that you created, you must ensure that the customLink.jspx page is called from within Composer. Use the sourceViewNodeAction attribute on the Page Customizable component to reference the JSF page containing the custom action.

The Page Customizable tag appears as follows in the page source: 

<pe:pageCustomizable id="pageCustomizable1"
                     sourceViewNodeAction="/customLink.jspx">

The sourceViewNodeAction attribute can take the name of a JSF (.jspx) file or an EL value that evaluates to a JSF (.jspx) file name.

What Happens at Runtime

When you run MyPage.jspx to the browser and open the page in Composer Structure view, the component navigator displays a Test link and an Edit Task Flow link next to each task flow instance on the page