5 Extending Runtime Editing Capabilities Using Oracle Composer

5.2.1.1 Creating an Add-On

Oracle Composer add-ons are task flows you create using JSPX pages or page fragments. To complete the process, you package the task flows into JAR files and register them with Oracle Composer and the adf-config.xml file.

To create an add-on:

1. In your WebCenter application project, create a JSFF file called custompanelview.jsff:

   1. From the File menu, select New.

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

   3. Click OK.

2. Design the fragment by adding the code shown in Example 5-1.

   Example 5-1 Sample code in the JSFF Fragment

   <?xml version='1.0' encoding='UTF-8'?>
   <jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.1"
             xmlns:af="http://xmlns.oracle.com/adf/faces/rich">
     <af:panelGroupLayout id="pnlgrp1" layout="vertical" halign="center">
       <af:spacer id="sp1" width="10" height="20" />
       <af:image id="customimage"              source="/images/FusionOrderDemoLogo.jpg"/>
       <af:spacer id="sp2" width="10" height="20"/>
       <af:outputText id="actoutput1" value="Fusion Order Demo (FOD) is a sample shopping cart application based on Oracle ADF Framework.
   It also uses the Webcenter Framework to enable Collaboration,Customization and Personalization features."
                      inlineStyle="font-size:small;"/>
       <af:spacer id="sp3" width="10" height="20"/>
       <af:outputText id="actoutput2" value="Build : 11.1.1.1"
                      inlineStyle="font-size:medium; font-weight:bolder;
                      text-decoration:none; font-style:normal; 
                      background-color:White; color:Blue; font-family:garamond;"/>
     </af:panelGroupLayout>
   </jsp:root>
   

3. Create a task flow definition called custom-panel-task-flow:

   1. From the File menu, choose New.

   2. In the New Gallery dialog box, expand Web Tier, select JSF, then ADF Task Flow.

   3. Click OK.

4. Drop the custompanelview.jsff fragment that you created onto the task flow definition.

   See Also:

   "Getting Started with ADF Task Flows" in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework for information about creating task flows.

5. Save the task flow definition file.

To package the task flow in an ADF library:

1. Create a deployment profile for the task flow:

   1. Right-click ViewController and choose New.

   2. In the New Gallery, expand General, select Deployment Profile, and then ADF Library JAR File, and click OK.

   3. In the Create Deployment Profile -- ADF Library JAR File dialog, enter a name for your deployment profile and click OK.

   4. In the ADF Library JAR Deployment Profile Properties dialog, click OK.

   5. In the Project Properties dialog, click OK.

2. In the Application Navigator, right-click the project folder, choose Deploy, deployment profile name, to, and then choose to ADF Library JAR file. This creates a deploy folder including the JAR file, in the project folder located at <Application_Root>\ViewController\deploy\.

5.2.1.2 Registering Add-Ons with Oracle Composer

After you create the task flows, you must register them with Oracle Composer so that they are displayed on the Oracle Composer toolbar along with the default options.

To register an add-on with Oracle Composer:

1. If it does not already exist, create the Oracle Composer extension file, pe_ext.xml in the META-INF directory under the project's Web context root:

   1. From the File menu, select New.

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

   3. Click OK.

   Name the file pe_ext.xml.

2. Add one <panel> element for each task flow that you want to register as an add-on.

   Any number of panels can be declared under the <panels> element in the extension file.

   Example 5-2 shows the code of the extension file with a <panel> entry.

   Example 5-2 Oracle Composer Extension File

   <?xml version="1.0" encoding="US-ASCII" ?>
   <pe-extension xmlns="http://xmlns.oracle.com/adf/pageeditor/extension">
     <addon-config>
       <panels>
         <panel name="oracle.fod.custom.panel" title="About FOD"
                icon="http://myforums.oracle.com/jive3/images/question-pts-available-16x16.gif"
                taskflow-id="/WEB-INF/custom-panel-task-flow.xml#custom-panel-task-flow" />
       </panels>
     </addon-config>
   </pe-extension>
   

   For more information about the addon-config and other nested elements, see Section B.2.1.1, "addon-config."

5.2.1.3 Registering Add-Ons in adf-config.xml

To register an add-on, you must add a reference to it in the application's adf-config.xml file. Add the addon-panels entry to define new add-ons.

To register add-ons in adf-config.xml:

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 following namespace within the adf-config element in the file:

   xmlns:pe="http://xmlns.oracle.com/adf/pageeditor/config"
   

3. Add a <page-editor-config> entry with an <addon-panels> entry.

   Within page-editor-config, add <addon-panel> entries for the default options and the new panels, as shown in Example 5-3.

   You must include entries for the default add-ons along with those for new panels. Without these entries, the default add-ons are not displayed in Oracle Composer.

   The name attribute must contain the name you used to register the panel in the Oracle Composer extension file.

   Example 5-3 New Add-Ons Referenced in adf-config.xml

   <pe:page-editor-config>
     <addon-panels>
       <!-- Page Properties add-on -->
       <addon-panel name="oracle.adf.pageeditor.addonpanels.page-settings" />
       
       <!-- Page Reset add-on -->
       <addon-panel name="oracle.adf.pageeditor.addonpanels.page-reset" />
     
       <addon-panel name="oracle.fod.custom.panel" />
     
     </addon-panels>
   </pe:page-editor-config>
   

   Note:

   If you do not specify any <addon-panel> entries under <addon-panels>, then only the default options are displayed in Oracle Composer.

For information about the Oracle Composer-specific configurations you can make in adf-config.xml, see Section B.2.2, "adf-config.xml."

5.3.1.1 Creating a Custom Property Panel

Property panels provide a means of editing page or component properties. For example, the end user may click the Edit icon on a selected portlet and then modify its parameter values and change its visual attributes in the resulting properties dialog.

Oracle Composer enables you to associate property panels with components and task flows. When a user clicks the Edit icon on the component or task flow, Oracle Composer opens the Component Properties dialog and displays the custom property panels you associated with the object along with the default property panels. If you do not associate a property panel with a particular component or task flow, then that panel is rendered for all pages, components and task flows in the Component Properties and Page Properties dialogs.

The steps for creating a custom property panel and declaring it in the Oracle Composer extension file are similar to those for creating and declaring Oracle Composer add-ons. For information about these tasks, see Section 5.2.1.1, "Creating an Add-On" and Section 5.2.1.2, "Registering Add-Ons with Oracle Composer."

5.3.1.2 Registering a Custom Property Panel for a Component

After declaring a custom property panel in the extension file, you must also register it in the extension file and associate it with a component, if required. Registering a custom property panel ensures that the panel displays automatically in the Oracle Composer Component Properties and Page Properties dialog.

Use the property-panels element to register the custom property panel in the pe_ext.xml file and to associate the custom panel with a component.

To register a property panel for a component:

1. Add a <property-panels> element in the pe_ext.xml file.

   For information about creating the extension file, see Section 5.2.1.2, "Registering Add-Ons with Oracle Composer."

2. Add a property-panel declaration within the <property-panels> element.

   You can have multiple property-panel entries.

3. Within the property-panel element, add a component element to specify the runtime class name of the component (optional) and a panel element to specify the name you used to declare the panel in the addon-config section of the file.

   Example 5-7 shows a custom property panel that is associated with a Command Button component by specifying the component's fully qualified class name. For information about Oracle ADF components and their runtime classes, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

   Example 5-7 Code to Register a Property Panel for a Component

   <property-panels>
     <property-panel name="cmdbtn">
       <component>oracle.rich.CommandButton</component>
       <panel name="prop.panel.cmdbtn" />
       <panel name="prop.panel.generic" /> 
     </property-panel>
   </property-panels>
   

   Note:

   When registering a property panel, if you do not associate it with a component or task flow, then the registered panel is rendered for all pages, task flows, and components in the Component Properties and Page Properties dialogs.

   You can register multiple panel elements within a property-panel element. For more information about the property-panels element and its nested elements, see Section B.2.1.2, "property-panels."

5.3.1.3 Registering a Custom Property Panel for a Task Flow

You can define custom property panels for a task flow by registering it with the Oracle Composer extension file. Example 5-8 shows the sample code used to register a custom property panel for a task flow.

A custom property panel registered for a specific task flow appears only when its associated task flow is selected. Otherwise, default property panels appear.

To register a property panel for a task flow:

1. Add a <property-panels> element in the pe_ext.xml file.

   For information about creating the extension file, see Section 5.2.1.2, "Registering Add-Ons with Oracle Composer."

2. Add a property-panel declaration within this.

   You can have multiple property-panel entries.

3. Addtaskflow-id and panel elements within the property-panel element.

   Add the taskflow-id element to specify the task flow name. Add the panel element to specify the name you used to declare the property panel in the addon-config section of the file.

   Example 5-8 shows a custom property panel associated with a dashboard task flow.

   Example 5-8 Code to Register a Property Panel for a Task Flow Instance

   <property-panels>
     <property-panel name="dashboard">
       <taskflow-id>/WEB-INF/dashboard-taskflow#prop-panel</taskflow-id>
       <panel name="dashboard.prop-panel" />
     </property-panel>
   </property-panels>
   

   Note:

   When registering a property panel, if you do not associate it with a component or task flow, then the registered panel is rendered for all pages, task flows, and components in the Component Properties and Page Properties dialogs.

   You can register multiple panel elements within a property-panel element. For more information about the property-panels element and its nested elements, see Section B.2.1.2, "property-panels."

5.4.1.1 UI Events that Support Event Handler Registration

Table 5-1 lists the UI events for which Oracle Composer currently supports registering of handlers.

5.4.1.2 Creating a Save Event Handler: Example

To register an event with Oracle Composer, you must first create a Java class and implement the appropriate listener for the event handler. This section describes the steps to create a Save event handler. You can perform similar steps to create event handlers for all the supported events listed in Table 5-1.

A Save event handler is called when a user clicks the Save button on the Oracle Composer toolbar or the Apply or OK button in the Component Properties or Page Properties dialog. A Save event handler must implement oracle.adf.view.page.editor.event.SaveListener.

To create a Save event handler:

1. In JDeveloper, select the ViewController project, and 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, specify a name for the class, for example, SaveHandler.

4. Under the Optional Attributes section, add the oracle.adf.view.page.editor.event.SaveListener interface.

5. Click OK.

   The Java class source looks like the following:

   package view;
   
   import javax.faces.event.AbortProcessingException;
   
   import oracle.adf.view.page.editor.event.SaveEvent;
   import oracle.adf.view.page.editor.event.SaveListener;
   
   public class Class1 implements SaveListener {
     public Class1() {
       super();
     }
     public void processSave(SaveEvent saveEvent) throws AbortProcessingException {
   // Your implementation goes here
     }
   }
   

   You must declare the processSave method as throws AbortProcessingException because the method may throw this exception if the event must be canceled. You can include the reason for cancelling this event in the Exception object when you create it.

   On throwing this exception, further processing of this event is canceled and the listeners that are in the queue are skipped.

You can create event handlers for all supported events by performing steps similar to these.

5.4.1.3 Registering an Event Handler with Oracle Composer

After creating and implementing an event handler, you must register it with Oracle Composer. Registration is necessary for ensuring that the handler is called back by Composer when the corresponding event occurs in the UI.

Register event handlers in the Oracle Composer extension file, /META-INF/pe_ext.xml. For more information about creating this file, see Section 5.2.1.2, "Registering Add-Ons with Oracle Composer."

To register an event handler:

1. In the pe_ext.xml file, add the following entries:

   <event-handlers>
     <event-handler event="save">view.SaveHandler</event-handler>
   </event-handlers>
   

   The values you provide for the event attribute and between the event-handler tags are unique to the type of event being entered and the name you specified for the event class.

2. Save the file.

5.6.1.1 How to Add Oracle Composer to a JSF Page

This section describes how to add the Page Customizable component to a JSF page. The purpose of this exercise is to provide Oracle Composer in the Edit mode at runtime so that the admin user can perform customizations at the site level. This section includes the addition of a Change Mode Link to enable switching from View mode to Edit mode at runtime.

To add Oracle Composer to a JSF Page:

1. Open the JSPX page and select Oracle Composer from the Component Palette.

2. Select Change Mode Link and drop it onto the page.

3. Select Page Customizable and drop it onto the page.

   The Source view should like this:

   <af:form id="f1">
     <pe:changeModeLink id="cml1"/>
     <pe:pageCustomizable id="pageCustomizable1">
       <cust:panelCustomizable id="panelCustomizable1" layout="scroll"/>
         <f:facet name="editor">
           <pe:pageEditor id="pep1"/>
         </f:facet>
     </pe:pageCustomizable>
   </af:form>
   

   When you drop these components onto the page, the default UserCC tip layer is extended by the ADF. Consequently, the adf-config.xml file is updated with this customization class:

   <cust-config>
     <match>
       <customization-class name="oracle.adf.share.config.UserCC" />
     </match>
   </cust-config>
   

5.6.1.2 How to Create a SiteCC Tip Layer

This section describes how to create a SiteCC tip layer, site, in which all site-level customizations performed in Edit mode are stored. In this sample application, site-level customizations are stored in the /mds/mdssys/cust/site/webcenter/pagename.jspx.xmldirectory.

To create the site tip layer:

1. From the File menu, choose New.

2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

   The Create Java Class dialog box opens.

3. In the Name field, enter SiteCC.

4. In the Extends field, enter CustomizationClass.

   This imports oracle.mds.cust.CustomizationClass.

5. Click OK.

   The SiteCC.java file is rendered in the Source view.

6. To implement the getCacheHint, getName, and getValue methods, double-click the bulb on the left corner and select Implement Methods.

7. In the Implement Methods dialog, click OK.

8. In the Source view, press Enter after public class SiteCC extends CustomizationClass, and add the following string:

   {
     private static final String DEFAULT_LAYER_NAME = "site";
     private String mLayerName = DEFAULT_LAYER_NAME;
     private String mLayerValue = "webcenter";
   

   The following libraries are imported:

   import oracle.mds.core.MetadataObject;
   import oracle.mds.core.RestrictedSession;
   import oracle.mds.cust.CacheHint;
   

9. Update the code as shown in bold here:

   public class SiteCC extends CustomizationClass
   {
     private static final String DEFAULT_LAYER_NAME = "site";
     private String mLayerName = DEFAULT_LAYER_NAME;
     private String mLayerValue = "webcenter"; 
     Note: You can provide any site name.
   
     public CacheHint getCacheHint()
     {
       return CacheHint.ALL_USERS;
     }
   
     public String getName()
     {
       return mLayerName;
     }
   
     public String[] getValue(RestrictedSession mdsSession, MetadataObject mo)
     {
       return new String[] { mLayerValue };
     }
   }
   

10. Save the SiteCC.java file.

5.6.1.3 How to Create a Custom UserCC Tip Layer

The ADF extends a default UserCC (user) tip layer when you drop Oracle Composer components onto a JSF page. Subsequently, the adf-config.xml file is updated to include the UserCC customization class.

This section describes how to create a custom user tip layer for a user, scott. This layer is applied on top of the site layer. The personalizations that a user performs in View mode are saved in this user tip layer in a folder created specifically for the logged-in user. In this example, the personalizations performed in View mode are saved in the /mds/mdssys/cust/user/scott/pagename.jspx.xmldirectory.

To create the user tip layer:

1. From the File menu, choose New.

2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

   The Create Java Class dialog box opens.

3. In the Name field, enter UserCC.

4. In the Extends field, enter CustomizationClass.

   This imports the oracle.mds.cust.CustomizationClass.

5. Click OK.

   The UserCC.java file displays in the Source view.

6. To implement the getCacheHint, getName, and getValue methods, double-click the bulb on the left corner and select Implement Methods.

7. In the Implement Methods dialog box, click OK.

8. In the Source view, press Enter after public class SiteCC extends CustomizationClass, and add the following string:

   {
     private static final String DEFAULT_LAYER_NAME = "user";
     private String mLayerName = DEFAULT_LAYER_NAME;
     private String mLayerValue = "scott"; //The name of the logged-in user
   in this example. The logged-in user name can be acquired dynamically.
   

   The following libraries are imported:

   import oracle.mds.core.MetadataObject;
   import oracle.mds.core.RestrictedSession;
   import oracle.mds.cust.CacheHint;
   

9. Update the code as shown in bold here:

   public class UserCC extends CustomizationClass
   {
     private static final String DEFAULT_LAYER_NAME = "user";
     private String mLayerName = DEFAULT_LAYER_NAME;
     private String mLayerValue = "scott";
   
     public CacheHint getCacheHint()
     {
       return CacheHint.USER;
     }
   
     public String getName()
     {
       return mLayerName;
     }
   
     public String[] getValue(RestrictedSession mdsSession, MetadataObject mo)
     {
       return new String[]{mLayerValue};
     }
   }
   

10. Save the UserCC.java file.

5.6.1.4 How to Implement the ComposerSessionOptionsFactory Class

In this section, the ComposerSessionOptionsFactory class provided by the ADF is implemented in order to supply MDS SessionOptions for each HTTP request.

To implement the ComposerSessionOptionsFactory class:

1. From the File menu, choose New.

2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

   The Create Java Class dialog box opens.

3. In the Name field, enter AppsSessionOptionsFactoryImpl.

4. Click OK.

   The AppsSessionOptionsFactoryImpl.java file is rendered in the Source view.

5. Import the following libraries:

   import oracle.adf.view.page.editor.mds.ComposerSessionOptionsFactory;
   import oracle.adf.view.page.editor.mode.ModeContext;
   import oracle.mds.config.CustClassListMapping;
   import oracle.mds.config.CustConfig;
   import oracle.mds.core.SessionOptions;
   import oracle.mds.cust.CustClassList;
   import oracle.mds.cust.CustomizationClass;
   

6. Add the following code to implement the ComposerSessionOptionsFactory class and provide SessionOptions:

   public class AppsSessionOptionsFactoryImpl
     implements ComposerSessionOptionsFactory
   {
   
     public SessionOptions createSessionOptions(SessionOptions defaultSessionOptions, String mode)
     {
       CustomizationClass[] custLayer;
       CustConfig custConfig = null;
   
       if (ModeContext.EDIT_MODE.equals(mode))
       {
         //Mode is Edit, change to SiteCC
         custLayer = EDIT_LAYER;
       }
       else
       {
         //Mode is View, change to UserCC + SiteCC
         custLayer = VIEW_LAYER;
       }
   
       try
       {
         CustClassList custClassList = new CustClassList(custLayer);
         CustClassListMapping custClassListMapping =
           new CustClassListMapping("/", null, null, custClassList);
         custConfig = new CustConfig(new CustClassListMapping[]
           { custClassListMapping });
       }
       catch (Exception e)
       {
         e.printStackTrace();
   
       }
   if(defaultOptions.getServletContextAsObject() != null){ 
       return new SessionOptions(defaultSessionOptions.getIsolationLevel(),
                                 defaultSessionOptions.getLocale(), custConfig,
                                 defaultSessionOptions.getVersionContext(),
                                 defaultSessionOptions.getVersionCreatorName(),
                                 defaultSessionOptions.getCustomizationPolicy());
                                 sessionOptions.getServletContextAsObject());
     }
       else
       {
         return new SessionOptions(sessionOptions.getIsolationLevel(),
                                 sessionOptions.getLocale(), custConfig,
                                 sessionOptions.getVersionContext(),
                                 sessionOptions.getVersionCreatorName(),
                                 sessionOptions.getCustomizationPolicy());
       }
     }
   
     //Edit mode SiteCC
     private static final CustomizationClass[] EDIT_LAYER =
       new CustomizationClass[]
       { new SiteCC() };
   
     //View mode SiteCC + USerCC
     private static final CustomizationClass[] VIEW_LAYER =
       new CustomizationClass[]
       { new SiteCC(), new UserCC() };
   
   }
   

5.6.1.5 How to Register the Implementation with Oracle Composer

For the site and user customization layers to function, you must register the ComposerSessionOptionsFactory class with Oracle Composer. For example, if the concrete class is view.AppsSessionOptionsFactoryImpl, the following snippet must be added to the adf-config.xml file located in the \.adf\META-INF folder in your application directory:

<page-editor-config xmlns="http://xmlns.oracle.com/adf/pageeditor/config">
  <session-options-factory>view.AppsSessionOptionsFactoryImpl</session-options-factory>
</page-editor-config>

5.6.1.6 How to Configure WebCenterComposerFilter

You must configure the WebCenterComposerFilter filter in the web.xml file located in the ViewController\public_html\WEB-INF folder in your application directory. This filter registers Oracle Composer's concrete SessionOptionsFactory with the ADF for every HTTP request. When the filter receives a call from the ADF, it forwards the request to the WebCenter application and gets the SessionOptions with the new customized layer. If you have not set the Sandbox or VersionContext in the SessionOptions, then Oracle Composer sets its own Sandbox and returns it to the ADF. For more information on Sandbox, see Section 5.7.1, "How to Enable Oracle Composer Sandbox Creation." The composerFilter and its filter mapping must be configured after ServletADFFilter and before ADFBindingFilter. For example, see the following web.xml file:

....

  <filter>
    <filter-name>ServletADFFilter</filter-name>
    <filter-class>oracle.adf.share.http.ServletADFFilter</filter-class>
  </filter>
  <!-- WebCenterComposerFilter goes here -->
  <filter>
    <filter-name>composerFilter</filter-name>
  <filter-class>oracle.adf.view.page.editor.webapp.WebCenterComposerFilter</filter-class>
  </filter>
  <filter>
    <filter-name>adfBindings</filter-name>
    <filter-class>oracle.adf.model.servlet.ADFBindingFilter</filter-class>
  </filter>
.....
  <filter-mapping>
    <filter-name>ServletADFFilter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>

  <!-- WebCenterComposerFilter mapping goes here -->
  <filter-mapping>
    <filter-name>composerFilter</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>
  <filter-mapping>
    <filter-name>adfBindings</filter-name>
    <servlet-name>Faces Servlet</servlet-name>
    <dispatcher>FORWARD</dispatcher>
    <dispatcher>REQUEST</dispatcher>
  </filter-mapping>
....

For information about the Oracle Composer-specific configurations you can make in web.xml, see Section B.2.3, "web.xml."

5.6.1.7 How to Redirect the Servlet to Enable Switch Between MDS Customization Layers

To redirect the servlet, that is, to refresh the full page at runtime, you must create:

• The AppNavigationUtils class, which calls the AppNavigationUtils.redirectToSamePage() method

• The AppCloseHandler CloseListener, which uses the AppNavigationUtils class

• The AppModeBean, which displays Edit mode

This section describes how to create these objects. It contains the following subsections:

• Section 5.6.1.7.1, "How to Create the AppNavigationUtils Class"

• Section 5.6.1.7.2, "How to Create AppCloseHandler"

• Section 5.6.1.7.3, "How to Register the AppCloseHandler"

• Section 5.6.1.7.4, "How to Create AppModeBean"

5.6.1.8 What Happens at Runtime

To see how the site customization layer functions, first run the JSF page in a browser. Then log in to the page as admin, and click the Edit link to switch to Edit mode. At runtime, customize the page. For example, drop a movable box, a hyperlink, and an image onto the page. The page should look like Figure 5-4.

Figure 5-4 Customized Page

Description of "Figure 5-4 Customized Page"

Go to \mds\mdssys\cust\site\webcenter in your application directory, and open the pagename.jspx.xml file. This is where the site-level customizations that you made to the page are stored.

To use the user customization layer, log in to the page as scott and personalize the page in View mode. Then go to \mds\mdssys\cust\user\scott in your application directory, and open the pagename.jspx.xml file. This is where the user-level customizations (personalizations) that you made to the page are stored.

5.6.2.1 How to Enable Customization on an Image Component

To enable customization on an Image component:

1. In the MyPage.jspx page that you created in Section 4.3, "Designing Editable Pages Using Oracle Composer Components: Example," add an ADF Faces Image component, for example, brandingImage.gif, inside the Panel Customizable called panelCustomizable1.

   Customization is enabled automatically on the Image component since it is nested inside a Page Customizable component.

2. Run MyPage.jspx.

3. Switch to Edit mode of the page.

4. From the View menu, select Source to switch to Source view of the page.

5. Select the image in the component hierarchy in the Source View panel and click the Show the properties of Image icon.

   The Component Properties dialog displays the image properties. You can edit any available property in this dialog. Edit a property and click OK. The property's editable value demonstrates that customization is enabled on the component.

5.6.2.2 How to Restrict Customization on an Image Component

You can restrict customization of an image on the page by setting the customizationAllowed attribute to false on the image component.

To restrict customization on the Image Component:

1. In Oracle JDeveloper, select the Image component that you added in the previous section, and in the Property Inspector set the value for customizationAllowed to false.

2. Run MyPage.jspx.

3. Switch to page Edit mode.

4. From the View menu, select Source to switch to the Source view of the page.

5. Select the image in the component hierarchy in the Source View panel, and click the Show the properties of Image icon.

   In the Component Properties dialog, the properties are grayed out and cannot be edited.

5.7.1.1 Updating Your Application's adf-config.xml File

You must update the adf-config.xml file to define and configure namespaces for all the metadata for which you want to support sandbox creation. This section describes how.

To configure sandbox creation in adf-config.xml:

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

2. Under the <metadata-namespaces> element, ensure that <namespace> elements are defined for all metadata for which you want to enable sandbox creation, as shown in Example 5-10.

   Example 5-10 Namespace Definitions in the adf-config.xml File

   <!-- your jspx files -->  
      <namespace path="/test" metadata-store-usage="webcenter_metadata_db_store"/>
   <!-- your pagedef customizations alone go here -->
      <namespace path="/pageDefs" metadata-store-usage="webcenter_metadata_db_store">
        <namespace-restriction type="CUSTOMIZATIONS"/>
        </namespace>
   

3. Configure the database store, as shown in Example 5-11.

   Note:

   Perform this step only if you plan to use WLS Administration Console to deploy your application EAR file. This configuration happens automatically if you deploy your application using Fusion Middleware Control or Oracle JDeveloper and select a database repository connection as the target MDS connection. For more information, see "Deploying WebCenter Applications" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

   Example 5-11 Metadata Store Configuration in the adf-config.xml File

   <metadata-store class-name="oracle.mds.persistence.stores.db.DBMetadataStore">
     <property name="jdbc-userid" value="userone"/>
     <property name="jdbc-password" value="userone123"/>
     <property name="jdbc-url" value="jdbc:oracle:thin:@host_name:1521:orcl"/>
     <property name="partition-name" value="partitionName"/>
   </metadata-store>
   <!-- <metadata-store class-name="oracle.mds.persistence.stores.file.FileMetadataStore">
     <property name="metadata-path" value="C:\JDeveloper\mywork\Application2\ViewController\public_html"/>
   </metadata-store> -->
   

4. Add the <sandbox-namespaces> element and add individual <namespace> tags for all namespaces for which you want to enable sandbox creation, as show in Example 5-12.

   Example 5-12 Configuring Namespaces for Sandbox Creation

   <sandbox-namespaces>
     <namespace path="/test"/>
     <namespace path="/pageDefs"/>
   </sandbox-namespaces>
   

5. Save the adf-config.xml file.

5.7.1.2 Updating Your Application's web.xml File

To ensure that a sandbox is created when you are in Edit mode of a page, you must create a filter in your application's web.xml file and set the appropriate filter mappings. All requests are then routed through this filter, and a sandbox is created for all Edit mode customizations. If you are using a file system metadata store, then there is no action performed on a filtered request.

This section provides the example of defining a Composer-specific filter and its relevant filter mappings in your application's web.xml file. It describes how to add the filter, WebCenterComposerFilter.

To define a Composer-specific filter and the filter mappings:

1. Open the application_root/ViewController/public_html/WEB-INF/web.xml file.

2. Add ServletADFFilter and WebCenterComposerFilter before the adfBindings filter so that all requests are routed through these filters first:

   <filter>
     <filter-name>ServletADFFilter</filter-name>
     <filter-class>oracle.adf.share.http.ServletADFFilter</filter-class>
   </filter>
   <filter>
     <filter-name>WebCenterComposerFilter</filter-name>
      <filter-class>oracle.adf.view.page.editor.webapp.WebCenterComposerFilter</filter-class>
   </filter>
   

3. Add corresponding <filter-mapping> elements before the filter mapping for adfBindings filter as shown in Example 5-13.

   Example 5-13 Filter Mappings for Composer-Specific Filter

   <filter-mapping>
     <filter-name>ServletADFFilter</filter-name>
     <servlet-name>Faces Servlet</servlet-name>
     <dispatcher>FORWARD</dispatcher>
     <dispatcher>REQUEST</dispatcher>
   </filter-mapping>
   <filter-mapping>
     <filter-name>WebCenterComposerFilter</filter-name>
     <url-pattern>/*</url-pattern>
   </filter-mapping>
   <filter-mapping>
     <filter-name>WebCenterComposerFilter</filter-name>
     <url-pattern>/faces/*</url-pattern>
     <dispatcher>FORWARD</dispatcher>
     <dispatcher>REQUEST</dispatcher>        
   </filter-mapping>    
   

   The <url-pattern> tag is used to specify the pages that must pass through the WebCenterComposerFilter so that sandbox creation can be enabled when a page goes into Edit mode.

4. Save the web.xml file.

5.8.1.1 How to Define Type-Level Customization Policies

You can enable type-level restrictions on components and their attributes in a standalone XML file and then register this file in the mds-config section of the adf-config.xml file. The standalone XML file contains annotations that match the types for which customization restrictions must be specified.

To enable customization of selected components or attributes at the type level:

1. Create an XML document, for example standalone.xml, add the following code, and replace the text in bold with appropriate values:

   <?xml version="1.0" encoding="UTF-8" ?> 
   <grammarMetadata xmlns="http://xmlns.oracle.com/bali/xml/metadata"
                    xmlns:mds="http://xmlns.oracle.com/mds"
                    namespace="http://java.sun.com/JSP/Page">
     <elementMetadata elementName="component_name">
       <mds:customizationAllowed>true</mds:customizationAllowed>
         <attributeMetadata attributeName="attribute_name">
           <mds:customizationAllowedBy>security_roles</mds:customizationAllowedBy>
         </attributeMetadata>
     </elementMetadata>
   </grammarMetadata>
   

   The <customizationAllowedBy> tag can appear only once. Multiple values can be specified as a space-separated list of allowed policies as part of the declaration.

   The <customizationAllowed> tag takes a Boolean as its value. A value of true for this tag means that anyone can customize the specified component, so long as other inherited customization polices allow it.

   The <customizationAllowedBy> tags do not serve any purpose if the same object has been tagged with <customizationAllowed>false</ customizationAllowed>. Additionally, the customization must be allowed at the top level of the object tree. Otherwise the default behavior dictates that no customization can be permitted at a lower level.

2. Register this XML file in the mds-config section of the adf-config.xml file as follows:

   <mds-config xmlns="http://xmlns.oracle.com/mds/config">
     <type-config>
       <standalone-definitions>
         <classpath>File_Path/standalone.xml</classpath>
       </standalone-definitions>
     </type-config>
   </mds-config>
   

3. Make the standalone files and associated XSDs available in a shared library JAR file; otherwise MDS cannot load them due to class loader restrictions.

5.8.1.2 How to Define Instance-Level Customization Policies

You can enable customization on a component or any of its attributes at the instance level. To apply customization restriction at the component level, you can set the customizationAllowed and customizationAllowedBy attributes on the component in JDeveloper (see Section 5.6, "Performing MDS-Specific Configurations"). To apply restrictions on a component's attributes, perform the steps described in this section.

The code for instance-level customization policies is similar to that used in the type-level policy definitions. They have the same meaning at the instance level. However, instance level policies are subordinate to type restrictions. That is, all restrictions are inherited from the type, and no customization is allowed unless customization is enabled at the type level.

Instance-level policies for component attributes are defined in an RDF file. The RDF file is picked up by MDS, and the policies are implemented.

To define instance-level customization policies:

1. Create an RDF file with the same name as the JSPX file, but using the RDF extension, for example main.jspx.rdf.

   Creating the RDF file in this folder structure ensures that the file is picked up by MDS and the policies defined here are implemented.

2. Include tags in the following format to apply restrictions on a component's attribute:

   tag_id(xmlns(tag_prefix=tag_namespace))/@tag_prefix:attribute_name
   

   The following example shows how to apply restriction on the text attribute of a Command Button component:

   <?xml version="1.0" encoding="UTF-8"?>
   <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dc="http://purl.org/dc/elements/1.1/">
   <rdf:Description rdf:about="/"/>
   <!-- Opens the customization on a tag, for example, an af:commandButton whose ID is 'cb1'.  -->
   <rdf:Description rdf:about="cb1">
     <customizationAllowedxmlns="http://xmlns.oracle.com/mds">false</customizationAllowed>
   </rdf:Description>
    
   <!-- Restricts customizations on the commandButton's attribute 'text'. -->
   <rdf:Description
   rdf:about="cb1(xmlns(af=http://xmlns.oracle.com/adf/faces/rich))/@af:text">
     <customizationAllowedxmlns="http://xmlns.oracle.com/mds">false</customizationAllowed>
   </rdf:Description>
   

At runtime, these policies are read and the artifacts are enabled for customization accordingly.

5.8.2.1 How to Configure ADF Security

Before applying an instance-level customization restriction, you must secure your application using ADF security. For information, see Section 3.5.1, "How to Configure ADF Security."

5.8.2.2 How to Define Users and Grant Roles in the jazn-data.xml File

In a previous section, a customization restriction is applied to a Panel Customizable component so that, at runtime, only the user with admin privileges can access all the features of Panel Customizable, and therefore, can customize its attributes.

In this section, two users are created, admin and customer, and roles are granted. All permissions are granted to both users. The admin user can customize the Panel Customizable (panelCustomizable1) component. However, because of the customization restriction you applied in an earlier section, customer does not have the rights to customize panelCustomizable1, and this user cannot use all the features of panelCustomizable1.

To define users in the jazn-data.xml file:

1. In the Application Resources, right-click the jazn-data.xml file and select Properties.

   The Edit JPS Identity & Policy Store dialog box opens.

2. In Identity Store, under jazn.com, select Users.

3. Click Add.

   The Add User dialog box opens.

4. In the Name field, specify a user name, for example, admin.

5. In the Credentials field, specify the password, for example, password.

6. Click OK.

7. Repeat steps 3 through 6 to add another user, for example, customer.

8. To grant roles, double-click the jazn-data.xml file to open it.

9. Select the Web Pages tab.

10. Grant all the permissions (View, Customize, Edit, Grant, Personalize) to both, admin and customer users.

For more information about creating users, see the section on enforcing ADF Security in a Fusion Web application in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

5.8.2.3 How to Customize the SessionOptions Object to Include Customization Policy

To enable the expected runtime behavior of the Panel Customizable component, where only the user with admin role has access to all capabilities of the Panel Customizable, including the ability to customize it, the MDS session for this request must include the user roles in its customization policy. To achieve this, the following customization policy is included in the SessionOptions object:

SecurityContext stx = ADFContext.getCurrent().getSecurityContext();
  cPol = new CustomizationPolicy(stx.getUserRoles());

Then the MDS session is created with this customization policy.

To implement the ComposerSessionOptionsFactory class:

1. From the File menu, choose New.

2. In the New Gallery dialog, expand General, select Java, then Java Class, and click OK.

   The Create Java Class dialog box opens.

3. In the Name field, enter AppsSessionOptionsFactoryImpl.

4. Click OK.

   The AppsSessionOptionsFactoryImpl.java file is rendered in the Source view.

5. Import the following libraries:

   import oracle.adf.share.ADFContext;
   import oracle.adf.share.security.SecurityContext;
   import oracle.adf.view.page.editor.mds.ComposerSessionOptionsFactory;
   import oracle.adf.view.page.editor.mode.ModeContext;
   import oracle.mds.config.CustClassListMapping;
   import oracle.mds.config.CustConfig;
   import oracle.mds.core.SessionOptions;
   import oracle.mds.cust.CustClassList;
   import oracle.mds.cust.CustomizationClass;
   import oracle.mds.cust.CustomizationPolicy;
   

6. Add the following code to implement the ComposerSessionOptionsFactory class and provide SessionOptions:

   public class AppsSessionOptionsFactoryImpl 
   implements ComposerSessionOptionsFactory
   {
     public AppsSessionOptionsFactoryImpl()
     {
     }
     public SessionOptions createSessionOptions(SessionOptions sessionOptions,
                                                String mode)
     {    CustomizationClass[] custLayer;
       CustConfig custConfig = null;  
       CustomizationPolicy cPol = null;
           if (ModeContext.EDIT_MODE.equals(mode))
       {
         //Mode is Edit, change to SiteCC
         custLayer = EDIT_LAYER;
       }
       else
       {
         //Mode is View, change to UserCC + SiteCC
         custLayer = VIEW_LAYER;
       }
       try
       {
         CustClassList custClassList = new CustClassList(custLayer);
         CustClassListMapping custClassListMapping =
           new CustClassListMapping("/", null, null, custClassList);
         custConfig = new CustConfig(new CustClassListMapping[]
               { custClassListMapping });
         SecurityContext stx = ADFContext.getCurrent().getSecurityContext();
         cPol = new CustomizationPolicy(stx.getUserRoles());
       }
       catch (Exception e)
       {
         e.printStackTrace();
       }
       if(sessionOptions.getServletContextAsObject() != null)
       {
         return new SessionOptions(sessionOptions.getIsolationLevel(),
                                 sessionOptions.getLocale(), custConfig,
                                 sessionOptions.getVersionContext(),
                                 sessionOptions.getVersionCreatorName(),
                                 cPol == null ?
   sessionOptions.getCustomizationPolicy() : cPol,
                                 sessionOptions.getServletContextAsObject());
       }
       else
       {
         return new SessionOptions(sessionOptions.getIsolationLevel(),
                                 sessionOptions.getLocale(), custConfig,
                                 sessionOptions.getVersionContext(),
                                 sessionOptions.getVersionCreatorName(),
                                 cPol == null ?
   sessionOptions.getCustomizationPolicy() : cPol);
       }
     }
     //Edit mode SiteCC
     private static final CustomizationClass[] EDIT_LAYER =
       new CustomizationClass[]
       { new SiteCC() };
     //View mode SiteCC + USerCC
     private static final CustomizationClass[] VIEW_LAYER =
       new CustomizationClass[]
       { new SiteCC(), new UserCC() };
   }
   

5.8.2.4 How to Register the Implementation with Oracle Composer

To register the implementation with Oracle Composer, perform the steps described in Section 5.6.1.5, "How to Register the Implementation with Oracle Composer."

5.8.2.5 How to Configure WebCenterComposerFilter

To configure WebCenterComposerFilter, perform the steps described in Section 5.6.1.6, "How to Configure WebCenterComposerFilter."

5.8.2.6 How to Apply an Instance-Level Customization Restriction

In this section, you apply a customization restriction to a Panel Customizable component. At runtime, this restriction ensures that only the user with admin privileges can access all the features of the Panel Customizable, including customizing its attributes. Users who do not have admin privileges can use only a limited set of component features.

To apply an instance-level customization restriction:

1. In the JSPX page, add a Command Link.

2. In the Command Link (af:commandLink) component, add the #{appModeBean.edit} action listener you created in Section 5.6.1.7, "How to Redirect the Servlet to Enable Switch Between MDS Customization Layers."

3. Add a Page Customizable component.

4. Apply an instance-level customization restriction on the component panelCustomizable1 in the Page Customizable.

   This restriction is stored in the following directory: public_html/mdssys/mdx/<pagename>.jspx.rdf.

   The Source view should look like this:

   <af:commandLink text="Edit the Page" id="cl1"
                   actionListener="#{appModeBean.edit}">
     <af:clientListener method="togglePEPageMode" type="action"/>
     <af:navigationPane id="np1"/>
   </af:commandLink>
   <pe:pageCustomizable id="pageCustomizable1">
     <cust:panelCustomizable id="panelCustomizable1" layout="scroll"/>
       <f:facet name="editor">
         <pe:pageEditorPanel id="pep1"/>
       </f:facet>
   </pe:pageCustomizable>
   <trh:script text="
     function togglePEPageMode(event) { ComposerUtils.toggleMode(event); }
   ">
   </trh:script>
   

   The design view should look like Figure 5-5.

   Figure 5-5 Design View: Customization Allowed

   
   Description of "Figure 5-5 Design View: Customization Allowed"
   
   

5.8.2.7 What Happens at Runtime

What happens at runtime is influenced by which user is logged on. To see the difference, log in as one user and then the other. For example:

In the Application Navigator, right-click the JSPX page and select Run.

Log in to the page as admin, and switch to Edit mode. The Add Content button and the pencil icon are displayed on the outer panelCustomizable. As admin, you can switch to Source view and access the properties of the outer panelCustomizable, as shown in Figure 5-6. That is, the user admin can edit this component.

Figure 5-6 Edit Mode for admin

Description of "Figure 5-6 Edit Mode for admin"

Log in to the page as customer, and switch to Edit mode. The Add Content button and the pencil icon are not available on the outer Panel Customizable. That is, this component is not editable for customer, as shown in Figure 5-7.

Figure 5-7 Edit Mode for customer

Description of "Figure 5-7 Edit Mode for customer"

5.8.3.1 How to Define Change Persistence at the Component Level

You can use the persist-changes attribute in the adf-config.xml file to specify whether changes to a specific attribute must be persisted.

Example 5-14 shows a sample adf-config.xml file with persist-changes attributes defined for some attributes.

<adf-config xmlns="http://xmlns.oracle.com/adf/config">
  <adf-faces-config xmlns="http://xmlns.oracle.com/adf/faces/config">
    <persistent-change-manager>
      <persistent-change-manager-class>
       oracle.adf.view.rich.change.MDSDocumentChangeManager
      </persistent-change-manager-class>
    </persistent-change-manager>
    <taglib-config>
      <taglib uri="http://xmlns.oracle.com/adf/pageeditor">
        <tag name="imageLink">
          <attribute name="destination">
            <persist-changes>true</persist-changes>
          </attribute>
        </tag>
        <tag name="customAction">
          <attribute name="text">
            <persist-changes>true</persist-changes>
          </attribute>
          <attribute name="icon">
            <persist-changes>true</persist-changes>
          </attribute>
        </tag>
      </taglib>
    </taglib-config>
  </adf-faces-config>
</adf-config>

5.8.3.2 What Happens at Runtime

If you set persist-changes to true, then a change made to the component attribute is persisted in any instance of that component. If you set persist-changes to false, then even if you change the attribute value in the Component Properties dialog at runtime, the change is not saved.

5.8.4.1 How to Add an enableSecurity Section to adf-config.xml

The enableSecurity element is not available by default in adf-config.xml. To override or extend the page-level security inheritance for Show Detail Frame components, you must add the customizableComponentsSecurity section in the adf-config.xml file, as shown in Example 5-15, and set the enableSecurity element in that section to true.

<cust:customizableComponentsSecurity
xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">
  <cust:enableSecurity value="true"/>
    <cust:actionsCategory>
       ..........................................
</cust:customizableComponentsSecurity>

Restrictions on actions on Show Detail Frame components can be implemented at the following levels:

• Page level: You can define security for customizable components such that page-level privileges are inherited by these components. This is the default behavior.

  By default, customizable components inherit allowable actions from the defined page-level permissions, such as edit, personalize, or customize. That is, a user who has edit, personalize, or customize privileges on a page can perform View mode personalizations on that page. The enableSecurity element enables you to override the security inheritance behavior. It can take either of the following values:

  • true: If set to true (the default when not specified), then the ability of a user to modify a component is first determined from the page permissions and then adjusted according to the current set of actions defined for that type of permission. For example, if a user has customize permission, then the actions that constitute the customize category (move, customize, and so on) are available to the user, but they are overridden by the actions that are defined in the adf-config.xml file.

  • false: If set to false, then all actions are available to users. A user's page permissions and actions configured in adf-config.xml are ignored.

• Actions category level: You can define security on all actions for Show Detail Frame components.

  You can add an actionsCategory element in the adf-config.xml file to define security on multiple actions simultaneously. Depending on the actionCategory attributes that you enable, appropriate privileges are provided on the Show Detail Frame components.

• Actions level: You can define security on individual actions for Show Detail Frame components.

  You can use the actions element in the adf-config.xml file to enable or disable individual actions. Depending on the actions attributes that you enable, appropriate privileges are provided on the Show Detail Frame components.

You can define security for actions on Show Detail Frame components at the application level if enableSecurity is set to true in the adf-config.xml file. A value of true implies that permission checks are made in addition to the actionsCategory and actions values specified in the adf-config.xml.

5.8.4.2 Defining Security at the Actions Category Level

You can add an actionsCategory element in the customizable components actions security section in the adf-config.xml file to define security on multiple Show Detail Frame components actions. Depending on the actionsCategory attributes that you enable, appropriate privileges are provided on the Show Detail Frame components.

The actions and actionsCategory elements in the adf-config.xml file have certain default mappings. Table 5-2 describes the different actionsCategory attributes and the actions they support by default.

Example 5-16 shows the actionsCategory entry that you can add to the customizable components actions security section in the adf-config.xml file.

<cust:customizableComponentsSecurity 
xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">
  <cust:enableSecurity value="true"/>

  <cust:actionsCategory>
    <cust:actionCategory name="personalizeActionsCategory" value="false"/>
    <cust:actionCategory name="customizeActionsCategory" value="true"/>
  </cust:actionsCategory>

  <cust:actions>
  ..........................................
  </cust:actions>

</cust:customizableComponentsSecurity>

You can also use EL for these element values, as shown in Example 5-17.

<cust:actionsCategory>
  <cust:actionCategory name="personalizeActionsCategory" value="#{appBusinessRules.InsideCorpNetwork}"/>
</cust:actionsCategory>

For reference, the managed bean, appBusinessRules, is defined as shown in Example 24-7 in Section 24.10, "Overriding Inherited Security on Portlets and Customizable Components."

5.8.4.3 Defining Security at the Actions Level

You can use the actions element in the customizable components actions security section of the adf-config.xml file to enable or disable individual Show Detail Frame actions. Depending on the actions attributes that you enable, appropriate privileges are provided on the Show Detail Frame components.

Example 5-18 shows the actions entry that you can add to the customizable components actions section of the adf-config.xml file. You can use EL for element values.

<cust:customizableComponentsSecurity 
xmlns="http://xmlns.oracle.com/adf/faces/customizable/config">
  <cust:enableSecurity value="true"/>

  <cust:actionsCategory>
    ..........................................
  </cust:actionsCategory>

  <cust:actions>
    <cust:action name="showMinimizeAction" value="true"/> 
    <cust:action name="showMoveAction" value="false"/> 
  </cust:actions>

</cust:customizableComponentsSecurity>