9 Performing Advanced Oracle Composer Configurations

9.2.1 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 show 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.

9.2.2 How to Include an Additional Actions Facet

To include an Additional Actions facet:

1. Create a JSPX 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 9-1.

   Figure 9-1 Page1.jspx in Structure Navigator

   
   Description of "Figure 9-1 Page1.jspx in Structure Navigator"
   
   

8. Save the page.

9.2.3 How to Create a Redirection Page

To create the redirection page:

1. Create a JSPX 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.

9.2.4 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 button in the Managed Bean 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.

9.2.5 What Happens at Runtime

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

Figure 9-2 Customize Action on the Actions Menu

Description of "Figure 9-2 Customize Action on the Actions Menu "

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

Figure 9-3 Page with Option to Edit Text

Description of "Figure 9-3 Page with Option to Edit Text"

Clicking OK takes you back to Page1.jspx, which reflects the recent text changes, as shown in Figure 9-4.

Figure 9-4 Page1 with Updated text

Description of "Figure 9-4 Page1 with Updated text"

9.3.1 How to Define 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 Oracle Composer tag library. Custom actions are stored in the JSPX 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 Oracle 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 header.

   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 Table B-9 in Section B.1, "Oracle Composer Component Properties."

   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 one shown in Example 9-1.

   Example 9-1 Custom Action Code

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

   Notes:

   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 ADF Task Flows" in Oracle Fusion Middleware Fusion Developer's Guide for 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.

9.3.2 How to Define 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 for 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 shown in Example 9-2.

   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.

   Example 9-2 Custom Actions Definitions in the adf-config.xml File

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

   Notes:

   • If you implemented restrictions on the Show Detail Frame component's actions by performing the steps in Section 11.5, "Applying Action-Level Restrictions on Panel Customizable and Show Detail Component Actions," 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 Example 9-2.

   • 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 Section 9.4, "Enabling Custom Actions On a Show Detail Frame Enclosing a Task Flow: Example."

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:

• 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 Chapter 38, "Testing and Deploying Your WebCenter Application."

9.3.3 How to Configure 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 taskflow, 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 such 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"/>

Example 9-3 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>

Example 9-4 shows how you can specify an instance-level custom action corresponding to the task flow outcome by adding a Custom Action component from the Oracle Composer tag library to the JSPX 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> 

9.3.4 What Happens at Runtime

Custom actions corresponding to navigation outcomes of the current task flow view 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.

9.7.1 Overview of the Default Change Manager Configuration

The first time you add an Oracle Composer component to your application page, Oracle Composer does the following to enable change persistence:

• Adds the CHANGE_PERSISTENCE context parameter to the web.xml file, and sets the value to ComposerChangeManager. This context parameter registers the ChangeManager class to be used to handle persistence, as shown in the following example:

  <context-param>
    <param-name>org.apache.myfaces.trinidad.CHANGE_PERSISTENCE</param-name>
    <param-value>oracle.adf.view.page.editor.change.ComposerChangeManager</param-value>
  </context-param>
  

• Sets the persistent-change-manager element in the adf-config.xml file to the MDSDocumentChangeManager. Oracle Composer configures MDSDocumentChangeManager within the adf-faces-config section as follows:

  <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
    <persistent-change-manager>
      <persistent-change-manager-class>
        oracle.adf.view.rich.change.MDSDocumentChangeManager
      </persistent-change-manager-class>
    </persistent-change-manager>
    . . . 
  </adf-faces-config>
  

  The taglib-config section in the file lists component tags and attributes that are persisted by default, as shown in the following example:

  <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
      ...
      <taglib-config>
        <taglib uri="http://xmlns.oracle.com/adf/faces/customizable">
          <tag name="showDetailFrame">
            <persist-operations>all</persist-operations>
            <attribute name="expansionMode">
              <persist-changes>true</persist-changes>
            </attribute>
            <attribute name="contentStyle">
              <persist-changes>true</persist-changes>
            </attribute>
          </tag>
          <tag name="panelCustomizable">
            <persist-operations>all</persist-operations>
          </tag>
        </taglib>
        <taglib uri="http://xmlns.oracle.com/adf/pageeditor">
          <tag name="layoutCustomizable">
            <persist-operations>all</persist-operations>
            <attribute name="type">
              <persist-changes>true</persist-changes>
            </attribute>
          </tag>
        </taglib>
      </taglib-config>
    </adf-faces-config>
  

  You can further enable change persistence for other tags and attributes by defining them in this section and setting the persist-changes attribute to true. For more information, see Section 11.4.1, "How to Define Change Persistence at the Component Level."

  For a list of ADF Faces components and attributes that are implicitly persisted, see the chapter titled "Allowing User Customizations at Runtime" in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

ComposerChangeManager

A ChangeManager class is required for persisting customizations performed by end users. ComposerChangeManager handles change persistence both within a session and across sessions (to MDS). It delegates a users changes to the appropriate change manager as follows:

• View mode changes are routed to FilteredPersistenceChangeManager thereby ensuring that implicit customizations, such as column resizing and header collapse, work according to the filter rules configured in the application's adf-config.xml file.

• Edit mode changes are routed to MDSDocumentChangeManager thereby ensuring that both implicit and explicit customizations are always persisted and available across sessions.

9.7.2 How to Configure ComposerChangeManager in Existing 11.1.1.1 Applications

Release 11.1.1.1 WebCenter applications containing Oracle Composer-enabled pages use MDSDocumentChangeManager for persisting Edit mode changes by default. Since Oracle Composer now provides ComposerChangeManager to persist user personalizations and customizations, you can configure your existing applications to use ComposerChangeManager so that user personalizations (in View mode) are also persisted to MDS.

This section contains the following sections:

• Section 9.7.2.1, "Updating CHANGE_PERSISTENCE Context Parameter in the web.xml File"

• Section 9.7.2.2, "Adding Relevant Entries to the adf-config.xml File"

9.8.1 Overview of the Resource String Editor

At runtime, for component display options that can take String values, the Edit menu next to the property field provides a Select Text Resource option. Clicking this option opens the resource string editor, which provides options to search existing resources, edit or delete resource keys, and add new resource key/value pairs. For information about editing resource strings at runtime, see Section 5.4.5, "Edit Resource Strings."

Changes made to resource strings in Oracle Composer are saved into an application override bundle. This bundle is sent for translation and the translated versions are imported back into the application. This way, users are able to see the property values in their language.

The ComposerOverrideBundle.xlf is an empty XLIFF file that is packaged with Oracle Composer libraries. This bundle becomes available to the application when you add Oracle Composer components to the page at design time. At runtime, Oracle Composer uses this bundle internally to read from and write to the application override bundle while editing resource strings.

New and updated property values are saved into the override bundle. A user must specify a key, value, and description for each string being created or modified. All resource string changes made in an application are saved in a single override bundle. To distinguish runtime changes made in different layers, the key value is prefixed with the MDS layer name and value and must be in the format, RT_<MDS Layer Name><MDS Layer Value>_Key Name. For example, RT_sitewebcenter_WELCOME_MESSAGE. For a selected property, users can search and use resource strings created in any MDS layer. However, they can edit only those resource strings that were created in the same MDS layer. In addition to searching the override bundle, users can also search for strings created and used in the JSPX page at design time. Internally, Oracle Composer searches for all resource bundles defined using c:set tags in the JSPX file.

Runtime resource string changes in English are saved to the default application override bundle. Users can change the language and create or edit a resource string in that language. A separate override bundle is created for each language in which a user writes a resource string and the file name is suffixed with the initials for that language. For example, resource strings edited in French in Application1 are saved in a bundle named Application1OverrideBundle_fr.xlf.

Current Limitations of the Resource String Editor

• Oracle Composer supports creation of around 500 resource strings at runtime. Beyond this number, application performance slows down

• The search criteria in the resource string editor is case-sensitive.

• To search for the description of a resource string, the user must provide the complete string value in the search criteria.

• The resource string editor does not display string descriptions for entries created in Properties bundle or List Resource bundle formats in JDeveloper.

• The option to edit resource strings is disabled for properties on the Parameters and Events tabs.

  If the EL value for an ADF resource is referenced in a page definition parameter, such as page parameter, taskflow parameter, or portlet parameter, then the binding EL returns an empty value. Users must avoid referencing ADF resource EL values in page definition parameters.

9.8.2 How to Enable the Resource String Editor in Your Application

To enable resource string editing in your application, you must add a resource-string-editor element in the page-editor-config section of your application's adf-config.xml file, as follows:

<pe:page-editor-config>
  <resource-string-editor>
    <enabled>true</enabled>
  </resource-string-editor>
</pe:page-editor-config>

If you want to enable resource string selectively, based on specific criteria, such as the page being edited or the user or role, you can use an EL value for the enabled attribute.

9.8.3 How to Configure the Override Bundle

If you enable resource string editing in your application, you must configure your application to use the override bundle, oracle.adf.view.page.editor.resource.ComposerOverrideBundle.xlf, which is available in the pageeditor.jar file. This override bundle is used for reading and writing to the application override bundle when users create or edit resource strings at runtime.

To configure the override bundle:

1. Open your application in JDeveloper.

2. Form the Application menu, select Application Properties.

3. Select Resource Bundles in the left panel of the Application Properties dialog (Figure 9-7).

   Figure 9-7 Application Properties Dialog

   
   Description of "Figure 9-7 Application Properties Dialog"
   
   

4. Click the Add button.

5. In the File Name field in the Select Resource bundle dialog, enter oracle.adf.view.page.editor.resource.ComposerOverrideBundle.xlf, as shown in Figure 9-8, and click Open.

   Figure 9-8 Select Resource Bundle Dialog

   
   Description of "Figure 9-8 Select Resource Bundle Dialog"
   
   

6. In the Application Properties dialog, select the Override check box.

   This ensures that the file is available to users at runtime.

7. Click OK.

Repeat the steps in this section to expose any of the resource bundles in your application to users at runtime.

9.8.4 What Happens at Runtime

When a user clicks the Edit icon next to a property that takes a String value, the Select Text Resource option is available. Clicking this option opens the resource string editor in which the user can create, modify, or delete resource strings. For more information, see Section 5.4.5, "Edit Resource Strings."

9.9.1 How to Disable Source View

You can disable Source view by setting the enable-source-view entry to false in the application's adf-config.xml file.

To disable Source view:

1. Open the application's adf-config.xml file, located in the ADF META-INF folder under Descriptors in the Application Resources panel.

2. Add the enable-source-view property and set its value to false, as shown in Example 9-5.

   Example 9-5 Disabling Source View in adf-config.xml

   <page-editor-config xmlns="http://xmlns.oracle.com/adf/pageeditor/config">
     <enable-source-view>false</enable-source-view>
   </page-editor-config>
   

3. Save the file.

9.9.2 What Happens at Runtime

At runtime, when you switch to page Edit mode, the page is rendered in Design view and the View menu is not displayed to the user, as shown in Figure 9-9.

Figure 9-9 Design View of Page without View Menu

Description of "Figure 9-9 Design View of Page without View Menu"