12 Configuring the Resource Catalog for Oracle Composer

This chapter describes the default Resource Catalog in your application and explains how to customize the runtime Catalog to display different content to different users.

This chapter contains the following sections:

Section 12.1, "Overview of Resource Catalog"
Section 12.2, "Modifying the Content of the Default Resource Catalog"
Section 12.3, "Creating a Custom Resource Catalog"
Section 12.4, "Adding XML Content to the Resource Catalog"
Section 12.5, "Adding XML Content to the Resource Catalog: Examples"
Section 12.6, "Filtering Items in the Resource Catalog"
Section 12.7, "Configuring Multiple Resource Catalogs"

12.1 Overview of Resource Catalog

The Resource Catalog, also known as Oracle Business Dictionary, provides a consolidated view of the contents of one or more otherwise unrelated repositories in a unified search and browse user interface. Resources originate in their source repository and are then exposed to the developer through the Resource Catalog as shown in Figure 12-1.

Figure 12-1 Resource Catalog Overview

Description of "Figure 12-1 Resource Catalog Overview"

When using JDeveloper, you see two types of Resource Catalogs—design time catalogs and runtime catalogs.

Design time catalogs are created in the Resource Palette and are like favorites lists for developers. You can define connections and then create catalogs to organize resources exposed by those connections. Those resources can then be re-used in any application you are developing.

12.2 Modifying the Content of the Default Resource Catalog

You can determine the contents of your Resource Catalog by modifying the default catalog definition file or creating a new catalog definition file and configuring Oracle Composer to point to it.

This section provides an example that illustrates how to include items of your choice in the default catalog definition file. It contains the following sections:

Section 12.2.1, "How To Add Items to Your Resource Catalog"
Section 12.2.2, "What Happens at Runtime"
Section 12.2.3, "What You May Need to Know When Defining a Resource Catalog"
Section 12.2.4, "How to Define Task Flow Parameters and Attributes of the Enclosing Show Detail Frames for Task Flows"

12.2.1 How To Add Items to Your Resource Catalog

If you want to modify the contents of the default Resource Catalog, you must edit the default catalog definition file, default-catalog.xml and include the components of your choice. This section describes how to add more items to the default Resource Catalog. It contains the following subsections:

Section 12.2.1.1, "Adding Connections for Resources"
Section 12.2.1.2, "Defining the Catalog Contents"
Section 12.2.1.3, "Enabling Task Flows in the Resource Catalog"
Section 12.2.1.4, "Enabling Documents in the Resource Catalog"
Section 12.2.1.5, "Enabling Display of Saved Searches in the Resource Catalog"

12.2.1.1 Adding Connections for Resources

Many of the resources included in catalogs, such as Oracle WebCenter Services and portlets, are accessed through connections defined in your application's connections.xml file.

You can create connections to resources in different ways. This section describes how to create a connection from the Resource Palette. For information about additional ways to create connections, see Section 3.9, "Accessing Connection Wizards."

To create a connection from the Resource Palette:

From the Resource Palette, click the New icon in the upper left corner.
Choose New Connection and then the type of connection you want to create.

The wizard for your connection type appears.
Step through the wizard filling in the necessary information about the connection.

When you click Finish, the connection should appear in the Resource Palette under Connections.
Right click your connection in the Resource Palette and choose Add to Application from the context menu.

Alternatively, you can drag and drop the connection from the Resource Palette to the Application Resources panel of the Application Navigator.

12.2.1.2 Defining the Catalog Contents

If you modify the default catalog definition file, your modifications appear in the catalog at runtime. The default catalog definition file, default-catalog.xml, is available in the <Application_Root>\mds\oracle\adf\rc\metadata directory.

You can modify the catalog content according to the rules of catalog definitions. Refer to the following for assistance in modifying the definition:

The default catalog definition contains commented entries for displaying documents from the Documents service and out-of-the-box service task flows. If you want the Resource Catalog to display these components, you must enable relevant entries in the catalog definition file.

Example

This example describes the procedure for adding a Discussions folder to the Resource Catalog. The Discussions folder contains the Discussions service main view task flow as a resource.

To expose the new Discussions folder in the Resource Catalog, you must add the code shown in bold in Example 12-1 to the default-catalog.xml file.

Example 12-1 Modified Sample default-catalog.xml File

<?xml version = '1.0' encoding = 'UTF-8'?>
<catalogDefinition xmlns="http://xmlns.oracle.com/adf/rcs/catalog"
                   id="catalogDefinition"
                   name="Default Resource Catalog"
                   description="Default resource catalog definition containing sample entries">   
  <contents>

    <!-- **********************************************************************
    * Custom folder exposing ADF Faces components                             *
    * Comment out this element if you want to remove it from the catalog.     *
    *********************************************************************** -->
    <customFolder id="facesComponents" name="ADF Faces Components"
                  description="ADF Faces components you can add to application pages"
factoryClass="oracle.adfinternal.view.page.editor.componentcatalog.adapter.ComponentObjectFactory"/>

    <!-- **********************************************************************
    * Dynamically include the portlets custom folder into the catalog at      *
    * runtime. The custom folder is only included if the portlet runtime *
    * jar files are included in the application classpath.                    *
    *********************************************************************** -->
    <customContent id="portletContent"
 contentProviderClass="oracle.adf.rc.webcenter.WebCenterContentProvider"/>

    <!-- **********************************************************************
    * This entry is added to modify the default-catalog.xml                   *
    * In this entry  resource is publised within a folder.
        * 
    *********************************************************************** -->
   <folder name="Discussions" id="mydiscussions">
     <contents>
       <resource id="discussionsMainView"
                 name="Discussions"
                 description="Main view of the Discussions Service"
                 repository="application.classpath"
                 path="forum-view.jar/ADF_TaskFlow/oracle+webcenter+collab+forum+view+taskflows+main-task-flow.xml#forum-main"/>
     </contents>
 </folder>

    <!-- **********************************************************************
    * Uncomment the following <customFolder> element if you have configured   *
    * the Document Library service in your application and want to include    *
    * documents in the catalog.                                               *  
    *********************************************************************** -->    
<!--
    <customFolder id="doclibDocuments"
                  name="Documents"
                  description="Documents from the Document Library Service"
   factoryClass="oracle.webcenter.content.model.rc.CustomFolderContextFactory"/>
-->

    <!-- **********************************************************************
    * Uncomment the following <resource> element if you have configured the   *
    * Document Library service in your application and want to include the    *
    * Document Library main view in the catalog.                              *
    *                                                                         *    
    * NOTE: application.classpath is an implicitly defined "repository" for   *
    *       accessing ADF Libraries that are included in your classpath       *
    *********************************************************************** -->
<!--
    <resource id="doclibMainView"
              name="Document Library Task Flow"
              description="Main view of the Document Library Service"
              repository="application.classpath"
              path="doclib-service-view.jar/ADF_TaskFlow/oracle+webcenter+doclib+view+jsf+taskflows+mainView.xml#doclib-document-library"/>
-->          

    <!-- **********************************************************************
    * To create a link to a task flow in an ADF Library:                      *
    * 1) add a <resource> tag to your catalog definition & set the            *
    *    "repository" attribute to "application.classpath"                    *
    *    (see doclibMainView above)                                           *
    * 3) set the "repository" attribute to the name of your file system       *
    *    connection.                                                          *
    * 4) set the "path" attribute for the task flow you are interested in.    *
    *    The path is of the following form:                                   *
    *                                                                         *
    *    path_to_jar/ADF_TaskFlow/task_flow_path                              *
    *                                                                         *
    * To obtain the task_flow_path, use the file system connection from (1)   *
    * and navigate to the task flow in your ADF Library. Mouse-over your task *
    * flow so its tool-tip is displayed. The tooltip shows the fully qualified*
    * ID of the task flow. Take this value and replace all occurrances of "/" *
    * with "+". For example:                                                  *
    *                                                                         *
    * Tool-tip:       oracle/webcenter/collab/announcement/view/taskflows/main-view-definition.xml#announcement-main-view
    * Task_flow_path: oracle+webcenter+collab+announcement+view+taskflows+main-view-definition.xml#announcement-main-view 
    *********************************************************************** -->

    </contents>
</catalogDefinition>

After you add the specified code, the Discussions folder is displayed in the runtime Resource Catalog.

To run and test the page:

Run any editable JSPX page in your application.
Switch to page Edit mode.
Click an Add Content button on the page to view the Discussions folder in the Catalog dialog.

12.2.1.3 Enabling Task Flows in the Resource Catalog

If you want the Resource Catalog to display an out-of-the-box service task flow or custom task flow that you created in your application, you must add entries for the task flow in the default-catalog.xml file. Custom task flows must additionally be packaged in an ADF library, even if they are part of the same application.

This section describes how to package a custom task flow in an ADF library and how to enable the display of task flows in the Resource Catalog. It contains the following subsections:

Section 12.2.1.3.1, "How to Package a Custom Task Flow in an ADF Library"
Section 12.2.1.3.2, "How to Enable the Display of Task Flows in the Resource Catalog"

12.2.1.3.1 How to Package a Custom Task Flow in an ADF Library

To package a custom task flow in an ADF library:

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

12.2.1.3.2 How to Enable the Display of Task Flows in the Resource Catalog

To enable the display of task flows in the Resource Catalog:

Open the default-catalog.xml file in the <Application_Root>\mds\oracle\adf\rc\metadata directory.

Add a <resource> element to your catalog definition similar to the following example:

<resource id="doclibMainView"
         name="Document Library Task Flow"
         description="Main view of the Document Library Service"
         repository="application.classpath"
         path="doclib-service-view.jar/ADF_TaskFlow/oracle+webcenter+doclib+view+jsf+taskflows+mainView.xml#doclib-document-library"/>

Note:

Ensure that the task flow library is in the application class path.

Set the path attribute for the task flow you want to include in the catalog.

The path must be specified in the following format:

jar_file_name/ADF_TaskFlow/task_flow_path

where.

jar_file_name is the name of the task flow JAR file. This JAR is picked up from the application classpath.

task_flow_path is the path to the task flow within the JAR file.

To obtain the task flow path for any task flow exposed in the Resource Palette, including out-of-the-box service task flows, navigate to the task flow in your ADF Library and right-click the task flow. From the context menu, select Show Catalog Reference. A message dialog displays the values of the repository and path attributes for that task flow.
Save the default-catalog.xml file.

The task flows that you have defined in default-catalog.xml are now available in the Resource Catalog.

Note:

To enable users to view the task flow's content at runtime, ensure that the task flow you add to the Resource Catalog has a TaskFlowPermission grant in the application's jazn-data.xml file, with at least View action provisioned. Without this, the task flow appears blank when added to the page.

12.2.1.4 Enabling Documents in the Resource Catalog

The default catalog definition file has entries for displaying documents from the Documents service, but these are commented out. Consequently, Documents service task flows (which include Document Manager, Document List Viewer, Recent Documents, and Content Presenter) are not available at runtime when using the default version of the Resource Catalog (see Section C.2, "Default Catalog Definition").

If you have configured the Documents service in your application (see Section 13.2, "Configuring Content Repository Connections") and want to expose its task flows in Oracle Composer at runtime, you can uncomment the Documents service entries in the default catalog definition file.

To enable display of Documents service task flows:

Open the default-catalog.xml file in JDeveloper.
Uncomment the <customFolder> element with an id value doclibDocuments (for the Document Manager, Document List Viewer, Recent Documents task flows).
Uncomment the <resource> element with an id value doclibContentPresenter (for the Content Presenter task flow).
Save the file.

Documents service task flows now display in a Documents folder in the Oracle Composer Catalog.

12.2.1.5 Enabling Display of Saved Searches in the Resource Catalog

Consider an example where your custom WebCenter Application page includes the Search task flow. At runtime, users can perform searches using this task flow and also save the results. To enable users to add such saved searches to their application pages, you must update the catalog definition file to include a saved searches folder. The Oracle Composer Catalog then displays this folder, which lists all saved searches.

Note:

As the Search service searches content created inside WebCenter applications by WebCenter services, ensure that you have configured other services that own resources, such as announcements, discussions, documents, tags, wikis/blogs, and pages. For more information, see Chapter 24, "Integrating the Search Service."

To display saved searches in the Resource Catalog so that users can add them to their application pages, you must add a customFolder entry in the catalog definition file, as shown in the following example:

<customFolder id="savedSearchesFolder"
              factoryClass="oracle.webcenter.search.view.rc.SearchServiceContextFactory">
  <attributes>
    <attribute value="Saved Searches" 
               attributeId="Title" isKey="true"/>
    <attribute value="Saved searches you can add to application pages"
               attributeId="Description" isKey="true"/>
    <attribute value="SAVED_SEARCHES.KEYWORDS"
               attributeId="Subject" isKey="true"/>
    <attribute value="oracle.webcenter.search"
               attributeId="WEBCENTER_SERVICE_ID" isKey="false"/>
    <attribute value="/adf/webcenter/foldersavedsearches_qualifier.png"
               attributeId="IconURI"/>
  </attributes>
</customFolder>

The Oracle Composer Catalog displays a saved searches folder, as shown in Figure 12-3. Users can open the folder, select a saved search, and add it to their page.

Figure 12-3 Saved Searches Folder in the Catalog

Description of "Figure 12-3 Saved Searches Folder in the Catalog"

12.2.2 What Happens at Runtime

After you enable Oracle Composer and define your catalog contents, you can run the page from Oracle JDeveloper. The Resource Catalog displays all elements that you defined in the catalog definition file.

To run and test the page:

In the Application Navigator, open your customizable MyPage.jspx and run it.
Switch to page Edit mode.
Click an Add Content button on the page to display the Catalog dialog.

In addition to the ADF Faces Components folder, the Resource Catalog displays all the elements you defined in the catalog definition file at design time.

For example, Figure 12-4 shows the Discussions folder that you enabled in Example 12-1.

Figure 12-4 Modified Resource Catalog with the Discussions Folder

Description of "Figure 12-4 Modified Resource Catalog with the Discussions Folder"

You can look at the sample application, ModifiedResourceCatalog.jws, containing a similar modified catalog definition, on the Oracle WebCenter Suite 11g Demonstrations and Samples page on the Oracle Technology Network (OTN) at:

http://webcenter.oracle.com

12.2.3 What You May Need to Know When Defining a Resource Catalog

To correctly implement resource catalogs, you must know where the application looks for the definitions and the XML schema upon which the definitions are based. See Appendix B, "Oracle Composer Component Properties and Files" for further information.

12.2.4 How to Define Task Flow Parameters and Attributes of the Enclosing Show Detail Frames for Task Flows

When you add a task flow from the Resource Catalog to your application page, the task flow is automatically enclosed in a Show Detail Frame component. To enable runtime editing of attributes associated with the enclosing Show Detail Frame, you must first define those attributes in the catalog definition file where the task flow is registered.

For example, if a user adds a task flow to a page with a dark background setting, the task flow continues to use the background setting of the enclosing Show Detail Frame component. This may not be the look the user wants. To enable the user to change the Show Detail Frame's background property, you must define this attribute in the catalog definition file. When a user selects the task flow for editing, the Component Properties dialog displays this Show Detail Frame attribute along with other task flow attributes.

Similarly, to prepopulate task flow parameters so that users do not have to set parameter values at runtime, you can define those parameters in the catalog definition file using an EL expression. When a user selects the task flow for editing, the Component Properties dialog displays these parameters with prepopulated values.

To define task flow parameters and Show Detail Frame attributes:

Open the catalog definition file that contains the task flow for which you want to set the parameters and Show Detail Frame attributes.

Within the task flow's <resource> element, add an <attribute> entry for each parameter and Show Detail Frame attribute you want to define.

The attributeId for a parameter must contain the parameter name prefixed with parameter.; the attributeId for a Show Detail Frame attribute must contain the attribute name prefixed with attr. as shown in the following example:

<?xml version = '1.0' encoding = 'UTF-8'?>
<catalogDefinition xmlns="http://xmlns.oracle.com/adf/rcs/catalog"
                   id="catalogDefinition" name="Default Resource Catalog"
                   description="Default resource catalog definition containing sample entries">
  <contents>
    <resource id="sampletaskflow" name="Sample Taskflow"
              path="sampletaskflow.jar/ADF_TaskFlow/WEB-INF+sample-task-flow-definition.xml#sample-task-flow-definition"
              repository="application.classpath">
      <attributes>
        <attribute value="dark" attributeId="attr.background"
                   isKey="false"/>
        <attribute value="#{myBean.myParam1}" attributeId="parameter.myParam1"
                   isKey="false"/>
      </attributes>
    </resource>
  </contents>
</catalogDefinition>

Note:

Retain the default value of false for the isKey attribute. Set it to true only if the value is coming from a resource bundle.

Save the catalog definition file.

12.3 Creating a Custom Resource Catalog

You can define the contents of your application's Resource Catalog either by modifying the existing, default catalog definition file, default-catalog.xml, or by creating a new catalog definition file. Create a custom Resource Catalog when you do not want to expose the ADF Faces components that are available in the default catalog, but instead want to include components or task flows that you specify.

This section describes how to create a custom Resource Catalog. It contains the following subsections:

Section 12.3.1, "How to Create a Custom Resource Catalog"
Section 12.3.2, "What Happens at Runtime"

12.3.1 How to Create a Custom Resource Catalog

To override default settings and display your custom Resource Catalog you must first create a new catalog definition file. Then you must specify the name of the new file in the application's adf-config.xml file.

To create a catalog definition:

Open your application in Oracle JDeveloper.
From File menu, choose New.
In the New Gallery dialog, expand General, select XML, then XML Document, and click OK.
In the Create XML File dialog, enter the file name, for example, users-catalog.xml, and the path of your catalog definition file.

Catalog definition files must be located in the Resource Catalog root directory (<JDEV_HOME>\jdev\mywork\<Application_Name>\mds\oracle\adf\rc\metadata) or a subdirectory of the root. For example, the Resource Catalog root might be:
```
C:\JDeveloper\mywork\RCSampleApp\mds\oracle\adf\rc\metadata
```
You could create your catalog here or create a subdirectory for it. For example:
```
C:\JDeveloper\mywork\RCSampleApp\mds\oracle\adf\rc\metadata\mycatalogs
```
Click OK.

You can now code your XML file according to the rules of catalog definitions.

Refer to the following to help you create the definition:

Section C.2, "Default Catalog Definition"
Section C.3, "XML Schema"
Section C.4, "Catalog Definition Attributes"

Tip:
If you do not want to write your catalog definition from the start, you could copy the contents of default-catalog.xml into your new catalog definition as a starting point.

Example 12-2 shows a sample catalog definition file containing the ADF Faces Components folder with its layout components, and a Discussions folder with the Discussions service task flows.

Example 12-2 The users-catalog.xml File

<?xml version="1.0" encoding="UTF-8" ?> 
  <catalogDefinition xmlns="http://xmlns.oracle.com/adf/rcs/catalog"
                     id="catalogDefinition"
                     name="Default Resource Catalog" 
                     description="Default resource catalog definition containing sample entries">
  <contents>
    <customFolder id="facesComponents" name="ADF Faces Components"
        description="ADF Faces components you can add to application pages"
         factoryClass="oracle.adfinternal.view.page.editor.componentcatalog.adapter.ComponentObjectFactory" /> 
    <folder id="forumsFolder">
      <attributes>
        <attribute value="Discussions" attributeId="Title" isKey="false" /> 
        <attribute value="Discussion Forum Taskflows" attributeId="Description" isKey="false" /> 
        <attribute value="" attributeId="Subject" isKey="false" /> 
        <attribute value="/adf/webcenter/folderdiscussions_qualifier.png" attributeId="IconURI" /> 
      </attributes>
      <contents>
      <!--  Forums Main View 
      --> 
        <resource path="forum-view.jar/ADF_TaskFlow/oracle+webcenter+collab+forum+view+taskflows+main-task-flow.xml#forum-main" 
          repository="application.classpath" id="forumMainView">
          <attributes>
            <attribute value="Main View" attributeId="Title" isKey="false" /> 
            <attribute value="Taskflow with complete view"
                       attributeId="Description" isKey="false" /> 
            <attribute value="/adf/webcenter/viewtopics_qualifier.png" attributeId="IconURI" /> 
            <attribute value="height:211px" attributeId="attr.contentStyle" isKey="false" /> 
          </attributes>
        </resource>
      <!--  Watched forum View 
      --> 
        <resource path="forum-view.jar/ADF_TaskFlow/oracle+webcenter+collab+forum+view+taskflows+watchedForum-task-flow.xml#forum-watchedForum" 
               repository="application.classpath" id="forumWatchedForumView">
          <attributes>
            <attribute value="Watched Forums" attributeId="Title" isKey="false" /> 
            <attribute value="All discussion forums you are watching" attributeId="Description" isKey="false" />
            <attribute value="/adf/webcenter/viewdiscussions_qualifier.png" attributeId="IconURI" /> 
            <attribute value="height:211px" attributeId="attr.contentStyle" isKey="false" /> 
          </attributes>
        </resource>
      </contents>
    </folder>
  </contents>
  </catalogDefinition>

where:

<resource> elements are used to define resources that you can add to the page

<folder> elements are used to define folders in the catalog

Add an <rcv-config> element to register users-catalog in your adf-config.xml file as shown in the following example:
```
<rcv-config xmlns="http://xmlns.oracle.com/adf/rcs/viewer/adf-config">
  <default-catalog catalog-name="users-catalog"/>
</rcv:rcv-config>
```
The value for catalog-name specifies the name of the catalog definition file to use.

The name you specify is relative to the Resource Catalog root directory and should not include the file extension .xml. For example, if you saved your new catalog definition as C:\JDeveloper\mywork\RCSampleApp\mds\oracle\adf\rc\metadata\mycatalogs\users-catalog.xml, then the catalog name is mycatalogs/users-catalog. The name uses the / separator because it represents part of an MDS path.

These entries enable you to override the default Resource Catalog. You must add them specifically because they are not included in the adf-config.xml file by default.

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

12.3.2 What Happens at Runtime

When you run your application and edit a page, Oracle Composer now displays content based on your custom catalog.

To run and test the page:

Run any editable JSPX page in your application.
Switch to page Edit mode.
Click an Add Content button on the page.

The Catalog dialog displays your custom catalog.

Figure 12-5 shows the custom catalog, users-catalog, that was described in Example 12-2.

Figure 12-5 Custom Resource Catalog Displayed in the Resource Catalog

Description of "Figure 12-5 Custom Resource Catalog Displayed in the Resource Catalog"

The sample application, CustomResourceCatalog.jws, on the Oracle WebCenter Suite 11g Demonstrations and Samples page contains a similar custom catalog definition. You can find this page on the Oracle Technology Network (OTN) at:

http://webcenter.oracle.com

12.4 Adding XML Content to the Resource Catalog

You can add custom XML components to your Resource Catalog by including the XML code for such components in the catalog definition file. On adding such a component to the page from the Resource Catalog, the XML fragment is displayed on the page. You can add a variety of components, such as simple ADF Faces components, compound objects containing two or more components, and JSF Verbatim tags that let you add arbitrary HTML content inside them. An example for arbitrary HTML that you can add to your catalog is a YouTube video.

This section describes how to include custom components in the catalog definition file. It contains the following sections:

Section 12.4.1, "How to Add XML Content to the Resource Catalog"
Section 12.4.2, "What Happens at Runtime"

12.4.1 How to Add XML Content to the Resource Catalog

To add raw XML to your catalog definition file, you must include it in a component element within the contents section. Example 12-3 shows the code to add a Panel Customizable component to the Resource Catalog.

Example 12-3 Panel Customizable Component in the Catalog Definition File

<!-- panelCustomizable -->
<component id="pc" factoryClass="oracle.adf.rc.component.XmlComponentFactory">
  <attributes>
    <attribute attributeId="Title" value="Box"/>
    <attribute attributeId="Description" value="Container for other objects"/>
    <attribute attributeId="IconURI" value="/adf/webcenter/panelcustomizable_qualifier.png"/>
  </attributes>
  <parameters>
    <parameter id="xml">
      <![CDATA[
        <cust:panelCustomizable id="#" xmlns:cust="http://xmlns.oracle.com/adf/faces/customizable"/>
      ]]>
    </parameter>
  </parameters>
</component>

To add raw XML content to the Resource Catalog:

Open the catalog definition file in the <Application_Root>\mds\oracle\adf\rc\metadata directory.
Add a component element within the contents section, and set the factoryClass attribute to oracle.adf.rc.component.XmlComponentFactory.

factoryClass is the name of a Java class that implements the oracle.adf.rc.component.ComponentFactory interface and generates a resource catalog item based on a set of parameters. Each ComponentFactory implementation defines the set of parameters it requires. For example, XmlComponentFactory requires a single parameter named xml and the value of the parameter is a block of XML representing a component or components that can be inserted into a page.
Define attributes on the component element.

For more information, see Section C.4, "Catalog Definition Attributes."
Within the component element, add a parameters element with a nested parameter element.
Set the id on the parameter element to xml.

This indicates that the component contains raw XML.
Add a CDATA tag within the parameter element.
Include the XML fragment for your component within the CDATA tag. The CDATA tag indicates that the component contains character data.

Specify the namespace for the custom component you added, and set its id to #.

This ensures that an ADF faces ID is generated for the component when it is dropped on the page at runtime. This ID is useful while performing other configurations in your application. For example, while configuring a drop handler for the resource.
Save your catalog definition file.

12.4.2 What Happens at Runtime

The components you add to your catalog definition file are rendered in the runtime Resource Catalog. The code in Example 12-3 results in the Oracle Composer Catalog displaying the components shown in Figure 12-6.

Figure 12-6 Panel Customizable Component Titled Box in the Catalog

Description of "Figure 12-6 Panel Customizable Component Titled Box in the Catalog"

12.5 Adding XML Content to the Resource Catalog: Examples

This section provides examples of various custom components added to the catalog definition file.

12.5.1 Compound Object Containing Nested ADF Faces Components

Example 12-4 shows the code to add an ADF Faces component that has another ADF Faces component nested inside it.

Example 12-4 Nested ADF Faces Components in the Catalog Definition File

<component id="sdf" factoryClass="oracle.adf.rc.component.XmlComponentFactory">
  <attributes>
    <attribute attributeId="Title" value="MOVABLE_BOX" isKey="true"/>
    <attribute attributeId="Description" value="MOVABLE_BOX.DESCRIPTION" isKey="true"/>
    <attribute attributeId="Subject" value="MOVABLE_BOX.KEYWORDS" isKey="true"/>
    <attribute attributeId="IconURI" value="/adf/webcenter/moveframe_qualifier.png"/>
  </attributes>
  <parameters>
    <parameter id="xml">
      <![CDATA[
        <cust:showDetailFrame xmlns:cust="http://xmlns.oracle.com/adf/faces/customizable"
                              id="#" text="#{componentExtensionBundle.MOVABLE_BOX}">
          <cust:panelCustomizable id="#" layout="scroll"/>
        </cust:showDetailFrame>
      ]]>
    </parameter>
  </parameters>
</component>

Figure 12-7 shows how the component appears in the Oracle Composer Catalog. When a user adds the Movable Box component to their page, a Box component (Panel Customizable component) is added automatically as a child component.

Figure 12-7 Show Detail Frame Component Titled Movable Box in the Catalog

Description of "Figure 12-7 Show Detail Frame Component Titled Movable Box in the Catalog"

12.5.2 YouTube Video Nested in a Verbatim Component

Example 12-5 shows the code to add a flash object showing a YouTube video to the Resource Catalog. The <object> element was copied directly from the YouTube site, available from the embed field or the Copy embed html context menu on the video, and pasted inside a Verbatim tag.

Example 12-5 Raw HTML Nested in a Verbatim Component in the Catalog Definition File

<!-- XML content - SDF around verbatim <object> -->
<component id="yt1" factoryClass="oracle.adf.rc.component.XmlComponentFactory">
  <attributes>
    <attribute attributeId="Title" value="Shuttle Launch 1"/>
    <attribute attributeId="Description" value="YouTube Video (Verbatim)"/>
    <attribute attributeId="IconURI" value="/adf/webcenter/videofile_qualifier.png"/>
  </attributes>
  <parameters>
    <parameter id="xml">
      <![CDATA[
        <cust:showDetailFrame id="#" stretchContent="false" text="Shuttle Launch (Verbatim)"
                              showResizer="never"
                              xmlns:cust="http://xmlns.oracle.com/adf/faces/customizable">
          <f:verbatim xmlns:f="http://java.sun.com/jsf/core">
            <object width="560" height="340">
              <param name="movie"
 value="http://www.youtube.com/v/27RTdNsYciE&amp;hl=en&amp;fs=1"></param>
              <param name="allowFullScreen" value="true"></param>
              <param name="allowscriptaccess" value="always"></param>
              <embed src="http://www.youtube.com/v/27RTdNsYciE&amp;hl=en&amp;fs=1"
                     type="application/x-shockwave-flash"
                     allowscriptaccess="always"
                     allowfullscreen="true" width="560" height="340"></embed>
            </object>
          </f:verbatim>
        </cust:showDetailFrame>
      ]]>
    </parameter>
  </parameters>
</component>

Figure 12-8 shows how the component appears in the Oracle Composer Catalog. When a user adds this component to their page, it displays as shown in Figure 12-9.

Figure 12-8 YouTube Video in a Verbatim Component in the Catalog

Description of "Figure 12-8 YouTube Video in a Verbatim Component in the Catalog"

Figure 12-9 YouTube Video on an Application Page

Description of "Figure 12-9 YouTube Video on an Application Page"

12.5.3 YouTube Video Nested in an Output Text Component

Example 12-6 shows the code to add a YouTube video within an ADF Faces Output Text component. The XML code available from the embed field on the YouTube site or Copy embed html context menu on the video was copied and pasted against the value parameter of the Output Text component. Consequently, users can select the Output Text component in Oracle Composer and edit the video object in Oracle Composer's Component Properties dialog.

The XML content here is the same as that used in Section 12.5.2, "YouTube Video Nested in a Verbatim Component," but in this case the XML is escaped, since it is being used as the value of an attribute.

Example 12-6 Raw HTML Nested In an Output Text Component in the Catalog Definition File

<!-- XML content - SDF around unescaped outputText -->
<component id="yt2" factoryClass="oracle.adf.rc.component.XmlComponentFactory">
  <attributes>
    <attribute attributeId="Title" value="Shuttle Launch 2"/>
    <attribute attributeId="Description" value="YouTube Video (Output Text)"/>
    <attribute attributeId="IconURI" value="/adf/webcenter/videofile_qualifier.png"/>
  </attributes>
  <parameters>
    <parameter id="xml">
      <![CDATA[
        <cust:showDetailFrame id="#" stretchContent="false" text="Shuttle Launch (Output Text)"
                              xmlns:cust="http://xmlns.oracle.com/adf/faces/customizable">
          <f:attribute xmlns:f="http://java.sun.com/jsf/core"
                       name="sdf_selection_rule" value="sdf_for_edit_mode_only"/>
          <af:outputText id="#" escape="false"
                         value="&lt;object width=&quot;560&quot;
                         height=&quot;340&quot;>&lt;param name=&quot;movie&quot;
 value=&quot;http://www.youtube.com/v/27RTdNsYciE&amp;hl=en&amp;fs=1&quot;>&lt;/param>&lt;param name=&quot;allowFullScreen&quot;
value=&quot;true&quot;>&lt;/param>&lt;param name=&quot;allowscriptaccess&quot;
value=&quot;always&quot;>&lt;/param>&lt;embed src=&quot;http://www.youtube.com/v/27RTdNsYciE&amp;hl=en&amp;fs=1&quot;
type=&quot;application/x-shockwave-flash&quot;
allowscriptaccess=&quot;always&quot; allowfullscreen=&quot;true&quot;
width=&quot;560&quot; height=&quot;340&quot;>&lt;/embed>&lt;/object>"
                         xmlns:af="http://xmlns.oracle.com/adf/faces/rich"/>
        </cust:showDetailFrame>
      ]]>
    </parameter>
  </parameters>
</component>

Figure 12-10 shows the video object in the Catalog.

Figure 12-10 YouTube Video in an Output Text Component in the Catalog

Description of "Figure 12-10 YouTube Video in an Output Text Component in the Catalog"

Figure 12-11 shows how the object is rendered on the page.

Figure 12-11 YouTube Video on an Application Page

Description of "Figure 12-11 YouTube Video on an Application Page"

Figure 12-12 shows the object in the Edit dialog, which is invoked when you click Expression Builder next to the Value property field for the Output Text component in the Component Properties dialog.

Figure 12-12 XML for the YouTube Video Object in the Edit dialog for the Output Text's Value Property

Description of "Figure 12-12 XML for the YouTube Video Object in the Edit dialog for the Output Text's Value Property "

12.6 Filtering Items in the Resource Catalog

If you want to arrange catalog content so that it is essentially the same for all users, but displays different subsets of the content to different users, then you can configure your Resource Catalog to filter out selected items based on specific criteria.

For example, if two users A and B have different privileges on a page, you can configure your application to display the entire catalog to user A and only a subset of items in the catalog to user B.

This section describes how to filter items in the Resource Catalog. It contains the following subsections:

Section 12.6.1, "How to Filter Items in the Resource Catalog"
Section 12.6.2, "What Happens at Runtime"

12.6.1 How to Filter Items in the Resource Catalog

To display subsets of Resource Catalog items to different users, you must implement the oracle.adf.rc.spi.plugin.catalog.CatalogDefinitionFilter interface. Additionally, you must associate this filter with the Resource Catalog.

To implement the CatalogDefinitionFilter:

From the File menu, choose New.
In the New Gallery dialog, expand General, select Java, and then Java Class, and click OK.
In the Create Java Class dialog, specify a name for the class, for example, CatalogFilter.
Under the Optional Attributes section, add the oracle.adf.rc.spi.plugin.catalog.CatalogDefinitionFilter interface.
Click OK.

Specify the logic for filtering items.

Note:

When implementing the filter logic it is common to want information about the current user and current page. This information can be obtained from the FacesContext.

Example 12-7 shows a sample CatalogDefinitionFilter implementation. It is configured to hide the Discussions folder (forumsFolder) for user ngreenbe from the custom catalog, users-catalog.xml, described in Section 12.3, "Creating a Custom Resource Catalog." The entire catalog, with the ADF Faces Components and Discussions folders, is shown to all other users.

Example 12-7 Sample Showing CatalogDefinitionFilter Implementation

package webcenter;

import oracle.adf.rc.catalog.CatalogElement;
import oracle.adf.rc.spi.plugin.catalog.CatalogDefinitionFilter;

import java.util.Hashtable;

import javax.faces.context.ExternalContext;
import javax.faces.context.FacesContext;

public class CatalogFilter implements CatalogDefinitionFilter {

  public boolean includeInCatalog(CatalogElement element, Hashtable env) {

    try {

      FacesContext fctx = FacesContext.getCurrentInstance();
      ExternalContext ectx = fctx.getExternalContext();
      String user = ectx.getRemoteUser();
      String resourceId = element.getId();
      if ((user != null && user.equals("ngreenbe")) &&
        resourceId != null && (resourceId.equals("forumsFolder"))) {
        
          return false;
        }

    }
    catch (Exception e) {
      System.out.println(e);
    }
    return true;
    }

}

Edit the application's catalog definition file to add the definitionFilter entry inside the <catalogDefinition> element:

<catalogDefinition xmlns="http://xmlns.oracle.com/adf/rcs/catalog"
                   id="catalogDefinition"
                   name="Default Resource Catalog"
                   description="Default resource catalog definition containing sample entries"
                   definitionFilter="java.class.name">

The value for java_class_name is the name of the Java class you created, for example, webcenter.CatalogFilter.

Save the catalog definition file.

12.6.2 What Happens at Runtime

When your catalog definition is opened, each entry in the catalog is passed through the CatalogDefinitionFilter to determine which entries should be displayed and which should be excluded. Depending on your implementation in the Java class, different subsets of items are displayed to different users.

Figure 12-14 and Figure 12-13 show the catalogs that are rendered for ngreenbe and any other user, for example, sking, on implementing the CatalogDefinitionFilter interface using the logic in Example 12-7.

Figure 12-13 Resource Catalog Displayed to ngreenbe

Description of "Figure 12-13 Resource Catalog Displayed to ngreenbe"

Figure 12-14 Resource Catalog Displayed to sking

Description of "Figure 12-14 Resource Catalog Displayed to sking "

The sample application, CustomResourceCatalog.jws, contains a similar implementation of CatalogDefinitionFilter. You can access it from the Oracle WebCenter Suite 11g Demonstrations and Samples page on the Oracle Technology Network (OTN) at:

http://webcenter.oracle.com

12.7 Configuring Multiple Resource Catalogs

To expose different items to different users based on specific criteria, such as the page being edited, the user, or the user role, you can associate multiple Resource Catalogs with your application. This section describes how. It contains the following subsections:

Section 12.7.1, "How to Configure Multiple Resource Catalogs"
Section 12.7.2, "What Happens at Runtime"

12.7.1 How to Configure Multiple Resource Catalogs

The main difference between using multiple catalogs and a single catalog is that, in addition to creating custom catalogs, you must implement the ResourceCatalogSelector API to select the appropriate catalog for the user and the page being edited. You must include the catalog-selector entry in your application's adf-config.xml file to specify the name of your ResourceCatalogSelector class. If you do not specify a catalog-selector, the default catalog is used for all editable pages and all users see the same content. If you specify a catalog-selector, the default catalog is used only when the specified selector returns null.

To implement multiple resource catalogs:

Create your custom catalogs by performing the steps outlined in Section 12.3, "Creating a Custom Resource Catalog."

Implement the oracle.adf.rc.model.config.ResourceCatalogSelector interface in your own resource catalog selector class, for example, CatalogSelector.java.

Example 12-8 shows a catalog selector implementation where a custom Resource Catalog, admin-catalog.xml, is shown to ahunold who has administrator privileges, and users-catalog.xml is shown to users sking and ngreenbe. If there is a problem with rendering either of these catalogs, then the default catalog is shown to users.

Example 12-8 Sample ResourceCatalogSelector Showing Entries for Multiple Resource Catalogs

package webcenter;


import javax.faces.context.FacesContext;

import java.util.Map;

import javax.faces.component.UIViewRoot;
import javax.faces.context.FacesContext;
import javax.faces.context.ExternalContext;

import oracle.adf.rc.model.config.ResourceCatalogSelector;
import oracle.adf.rc.model.dc.RCVContext;

import oracle.adf.rc.model.config.ResourceCatalogSelector;

/**
 * CatalogSelector is a sample implementation of the ResourceCatalogSelector
 * interface.
 *
 * This implementation is based on the authenticated user
 */
public class CatalogSelector implements ResourceCatalogSelector {
  public CatalogSelector() {
  }

  /**
   * Returns the Id of the catalog that must be used for the current
   * user.
   *
   * @param context a Map cont
   * @return id of the catalog to be used for the current user or
   *         null if the default catalog must be used.
   */
  public String getCatalogName(Map context) {
    // if no catalog is selected, return null & the composer uses the
    // default catalog defined in the rcv-config
    String retval = null;

    // get information about the current user.
    FacesContext fctx = FacesContext.getCurrentInstance();
    ExternalContext ectx = fctx.getExternalContext();
    String user = ectx.getRemoteUser();
    
    if (user == null || user.length() == 0) {
      // user name is not available so use the default catalog
      retval = null;

    } 
    else if (user.equals("ngreenbe") || user.equals("sking")  ) {
      // return users-catalog for users ngreenbe and sking
      retval = "users-catalog";
      
      
    } 
    else if (user.equals("ahunold")) {
      // return admin-catalog for user ahunold
      retval = "admin-catalog";
      
    } 
    
    return retval;

    }
}

In your adf-config.xml file, enter the name of the class you created for selecting a resource catalog with the <catalog-selector> tag as show in the following example:
```
<rcv-config xmlns="http://xmlns.oracle.com/adf/rcs/viewer/adf-config">
  <catalog-selector class-name="webcenter.CatalogSelector"/>
  <default-catalog catalog-name="default-catalog"/>
</rcv-config>
```
The value for catalog-name corresponds to the default catalog definition file stored in the Resource Catalog root within MDS.

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

12.7.2 What Happens at Runtime

Different catalogs are displayed to users based on the criteria you specified.

Based on the ResourceCatalogSelector implementation in Example 12-8, Figure 12-15 and Figure 12-16 show the two catalogs that are shown to user sking or ngreenbe and to administrator ahunold respectively.

Figure 12-15 Catalog Displayed to sking and ngreenbe

Description of "Figure 12-15 Catalog Displayed to sking and ngreenbe"

Figure 12-16 Resource Catalog Displayed to the ahunold

Description of "Figure 12-16 Resource Catalog Displayed to the ahunold"

You can look at these catalog definitions in the StoreFrontModule in FOD. For information about FOD, see Chapter 2, "Introduction to the WebCenter Sample Application."

12.8 Troubleshooting Problems with the Resource Catalog

This section provides information to assist you in troubleshooting problems you may encounter while using the Resource Catalog.

For information about configuring logging, see "Configuring ADF Logging for Oracle Composer".

Problem

Resource Catalog is empty.

Solution

The default catalog is not available to MDS. Ensure that the deployment profile contains the necessary entries to copy the default catalog file. Also, ensure that in the MDS section of adf-config.xml, a namespace entry points to the default catalog file.

Problem

A project task flow does not appear in the Resource Catalog.

Solution

The task flow must be packaged as an ADF Library (JAR file) and added to the project. You must also ensure that the task flow ID is given in the following format:

path_to_jar/ADF_TaskFlow/task_flow_path
Ex. doclib-service-view.jar/ADF_TaskFlow/oracle+webcenter+doclib+view+jsf+taskflows+mainView.xml#doclib-document-library