4 Populating Pages

This chapter explains how to add components to the pages of your WebCenter application. Note that this chapter does not cover Oracle JDeveloper or Oracle ADF page creation basics. It covers only those aspects of page creation that are specific to WebCenter application pages. Therefore, you must familiarize yourself with the information covered inOracle Application Development Framework Developer's Guide before reading this chapter.

• Section 4.1, "Introduction to Page Content"

• Section 4.2, "Building WebCenter Application-Enabled Pages in Oracle JDeveloper with Oracle ADF"

• Section 4.3, "Consuming Portlets"

• Section 4.4, "Using Customizable Components"

• Section 4.5, "Contextually Linking Components"

4.1 Introduction to Page Content

Oracle WebCenter Framework provides functionality for placing a wide variety of content on an application page. Content types include portlets, customizable components, and content integration tools. Optionally, you can enable customization of these components to make the application more flexible. Oracle WebCenter Framework also provides for the linking of these components so that they operate cohesively, making the application easier to understand and use.

This section describes the Oracle WebCenter Framework components you can add to your WebCenter application pages. It includes the following subsections:

Note:

You are not limited to adding just these components to your WebCenter applications. You can add other components as well. This list encompasses only Oracle WebCenter Framework-specific components. For information about other useful components you might want to use, see Oracle Application Development Framework Developer's Guide.

• Section 4.1.1, "Portlet Overview"

• Section 4.1.2, "Customizable Components Overview"

• Section 4.1.3, "JCR Data Control Overview"

4.1.1 Portlet Overview

Oracle WebCenter Framework enables you to consume a portlet by registering its producer with an application. After you register the producer, its portlets appear on the Oracle JDeveloper Component Palette under the registered producer's name. You can drag portlets from the Component Palette and drop them onto a page as you would any other component.

Your application can consume portlets that you build as well as portlets that you receive from a third party, such as a packaged-application vendor.

Many options are associated with portlet consumption: you can choose to place portlets straight onto a page or nest them in a customizable component; you can adjust many attributes of the portlet tag (adfp:portlet); you can wire portlets together.

This chapter provides information about consuming portlets and the options that accompany their consumption. It includes the following sections:

• Section 4.3, "Consuming Portlets"

• Section 4.4, "Using Customizable Components"

• Section 4.5, "Contextually Linking Components"

Note:

To learn more about creating portlets, see the following chapters:

• Chapter 14, "Understanding Portlets"

• Chapter 15, "Portlet Technologies Matrix"

• Chapter 16, "Creating Portlets with OmniPortlet"

• Chapter 17, "Creating Content-Based Portlets with Web Clipping"

• Chapter 18, "Creating Java Portlets"

4.1.2 Customizable Components Overview

Customizable components provide the ability to control the design time at run time behavior of the application. These components enable users to manipulate their view of the content according to their requirements. For example, one user may choose to hide a certain piece of content altogether, while another moves it up to the top of the page. By adding customizable components to a page, you make the page customizable for users.

Oracle WebCenter Framework provides two core customizable components:

• ShowDetailFrame

• PanelCustomizable

A ShowDetailFrame surrounds one Oracle ADF component and can provide a border and a chrome bar with menu actions, for example, to minimize the content. A ShowDetailFrame component enables you to do the following:

• Maximize or restore the display of the child component

• Provide a chrome or border for the component

• Provide an actions menu to perform specific actions on the child component

A PanelCustomizable component offers horizontal and vertical layout capabilities to a group of Oracle ADF components, including customizable components. Similar to a ShowDetailFrame component, a PanelCustomizable component can also display a chrome to provide menu actions. A PanelCustomizable component enables you to do the following:

• Maximize or restore the display of child components

• Show or hide child components

• Move or rearrange child components within the PanelCustomizable component

To leverage all features of customizable components, you can add ShowDetailFrame and PanelCustomizable components in the following manner:

• Use a ShowDetailFrame component to render a border or chrome around its child component and thereby provide User Interface (UI) controls to customize the display of the child component. For example, options to move, minimize, or maximize the display of content.

  The placement hierarchy is as follows:

  ShowDetailFrame
      ADF Faces component
  

• Wrap a ShowDetailFrame component within a PanelCustomizable component to provide the ability to show or hide child components.

  The placement hierarchy is as follows:

  PanelCustomizable
     ShowDetailFrame Child1
            ADF Faces component
     ShowDetailFrame Child2 
            ADF Faces component
     Portlet
     Portlet
  

  Note:

  Portlets provide the portlet chrome with display options similar to ShowDetailFrame components. Therefore, it is not necessary to include portlets within ShowDetailFrame components.

4.1.2.1 Defining Appearance and Customization Characteristics

Use the ShowDetailFrame tag to include a ShowDetailFrame component on the page. A list of options, available as a list on the ShowDetailFrame header as shown in Figure 4-1, enables users to control the display of a child component.

Figure 4-1 shows the following component placement hierarchy:

PanelCustomizable
   ShowDetailFrame Child1
          ADF Faces component
   Portlet

Figure 4-1 Actions Available with a ShowDetailFrame Component

Description of "Figure 4-1 Actions Available with a ShowDetailFrame Component"

You can maximize and minimize content by using the options available under the Actions menu on the header. You can add your own UI controls to further customize the display by using facets of the cust:showDetailFrame tag.

4.1.2.2 Nesting Customizable Components

If you place ShowDetailFrame components inside a PanelCustomizable component, then in addition to maximizing and minimizing the display, you can also move the child components up and down or to the right and left.

Figure 4-2 shows the nesting of a PanelCustomizable and a ShowDetailFrame component with child components.

Figure 4-2 Nesting of Customizable Components

Description of "Figure 4-2 Nesting of Customizable Components"

Placing Content and Portlets Inside of Customizable Components

You can include Oracle ADF Faces components as child components in your PanelCustomizable and ShowDetailFrame components. However, it is sufficient if you include portlets within PanelCustomizable components only. It is not necessary to include portlets in ShowDetailFrame components as portlets provide the portlet chrome with display options similar to ShowDetailFrame components. You do not get any additional benefits by including portlets in ShowDetailFrame components.

The procedure for adding child components in PanelCustomizable and ShowDetailFrame components is similar to adding Oracle ADF Faces components on a page. Before adding a child component, ensure that the PanelCustomizable or ShowDetailFrame component is selected in the Structure pane in Oracle JDeveloper. See Section 4.3.2, "Adding Portlets to a Page" for details.

4.1.3 JCR Data Control Overview

Java Content Repository (JCR) data controls expose file and folder content on a page. In this way, they enable you to integrate content from a content repository into your WebCenter application. You create a data control that selects content from a particular content repository (for example, Oracle Content DB or a file system). Once the data control is created, you can drop it onto a JSP document in the desired format, for example, a table. For more information about JCR data controls and integrating content, see Chapter 5, "Integrating Content".

4.2 Building WebCenter Application-Enabled Pages in Oracle JDeveloper with Oracle ADF

For detailed information about creating pages in Oracle JDeveloper with Oracle ADF, see Oracle Application Development Framework Developer's Guide. There you will find all of the information that you need on Oracle ADF Faces and building basic and complex pages. The section that follows describes some of the special requirements of WebCenter application pages.

Requirements for Pages

The following list provides rules and guidance to apply when you are creating your WebCenter application pages in Oracle JDeveloper with Oracle ADF:

• Create WebCenter application pages as JSP documents (jspx) rather than JSP pages (jsp). In order for page customizations to be stored, the page must be represented in XML (jspx). Hence, by choosing to create a JSP document, you ensure that customizations are always possible for the WebCenter application page.

  If you are not planning to enable customization, then you could choose to create a JSP page, but this choice might cause problems if you later decide that you must enable customization.

• Make sure that you have the following libraries in the Tag Libraries page of the Create JSF JSP Wizard.

  • ADF Portlet Components

    This library is required when you plan to place portlets on application pages.

  • Customizable Components Core

    This library is required when you plan to enable page customizations, such as the ability to move, hide, and show portlets, and to enable these customizations on any Oracle ADF component.

4.3 Consuming Portlets

This section steps you through the processes of making portlets available to an application (that is, registering portlet producers), adding portlets to a page, and removing them from a page. It contains the following subsections:

• Section 4.3.1, "Registering Portlet Producers"

• Section 4.3.2, "Adding Portlets to a Page"

• Section 4.3.3, "Setting Attribute Values for the adfp:portlet Tag"

• Section 4.3.4, "Copying Portlets"

• Section 4.3.5, "Deleting Portlets from Application Pages"

For information about obtaining prebuilt portlets through Oracle, see Section 3.2, "Using the Preconfigured OC4J". For information about using Oracle JDeveloper's portlet creation wizards, see Chapter 18, "Creating Java Portlets". For more information about portlets, see Chapter 14, "Understanding Portlets".

4.3.1 Registering Portlet Producers

Before you can add a portlet to a WebCenter application, you must register the portlet's producer with the application. Oracle JDeveloper provides two producer registration wizards: the WSRP Producer Registration Wizard and the PDK-Java Producer Registration Wizard. This section describes how to use these wizards. It contains the following subsections:

• Section 4.3.1.1, "Registering WSRP Portlet Producers"

• Section 4.3.1.2, "Registering PDK-Java Portlet Producers"

• Section 4.3.1.3, "Editing Portlet Producer Registration Settings"

• Section 4.3.1.4, "Testing a Portlet Producer Connection"

• Section 4.3.1.5, "Refreshing a Portlet Producer"

• Section 4.3.1.6, "Deregistering a Portlet Producer"

Note:

For additional information about producers, see Section 15.4, "Deployment Type".

4.3.1.1 Registering WSRP Portlet Producers

When you register a WSRP portlet producer, you provide basic information that describes the producer's operational parameters. This information is used by the portlet-consuming application to communicate with the producer and with the portlets through the producer.

Oracle WebCenter Framework supports both WSRP 1.0 and WSRP 2.0 producers. WSRP 2.0 support is for a preliminary (that is, preproduction) version of WSRP 2.0. Preliminary support is provided to accommodate the fact that the WSRP 2.0 standard was not finalized when Oracle WebCenter Framework was released.

This emerging standard, among others, provides support for inter-portlet communication and export or import of portlet customizations. This means that you can leverage the benefits of WSRP 2.0 while building standards-based JSR 168 portlets. To take advantage of more advanced features of WSRP 2.0, use the Oracle-specific oracle-portlet.xml metadata extensions.

To take advantage of the benefits WSRP 2.0 provides, JSR 168 portlets exposed through WSRP 2.0 must be deployed to Oracle Container for J2EE (OC4J). Because the new version of the portlet application programming interface (API) (JSR 286) will support WSRP 2.0 capabilities, when JSR 286 becomes publicly available, vendor-specific extensions will no longer be required.

The Producer Registration Wizard is the entry point for registering both WSRP 1.0 and 2.0 producers. When registration is successful, the newly registered producer displays in Oracle JDeveloper on the Component Palette, from which you can select portlets for placement on your application (jspx) page. Additionally, the producer is listed under the Portlet Producers node in the Applications Navigator.

To register a WSRP portlet producer, perform the following steps:

1. In the Applications Navigator, right-click the application under which to create the producer and select New from the context menu.

2. In New Gallery under Categories, expand the Web Tier node and select Portlets.

3. In New Gallery under Items, select WSRP Producer Registration.

4. Click OK.

5. On the Welcome page, click Next.

   Optionally, before clicking Next, select Skip this Page Next Time to forgo display of the Welcome page on subsequent uses of this wizard. The Welcome page may not display if the option to skip was selected on earlier use of the wizard.

6. In the Name field, enter a name for the producer.

   Give the producer a name that is unique among producers.

   Note:

   Producers given the same name display only once on the Component Palette. So, if you register two producers and give them each the name MyProducer, then the name MyProducer displays only once on the Component Palette, and both producers' portlets are listed under the one instance. This makes it difficult to determine which portlets come from which producer.

   If you find yourself in this situation, then consider editing one of these producers and giving it a unique name. See Section 4.3.1.3, "Editing Portlet Producer Registration Settings".

7. Click Next.

8. In the URL Endpoint field, enter the producer's URL.

   The syntax will vary according to your WSRP implementation:

   http://<host>:<port>/<context-root>/portlets/wsrp1?WSDL
   http://<host>:<port>/<context-root>/portlets/wsrp2?WSDL
   http://<host>:<port>/<context-root>/portlets?WSDL (WSRP 1.0 for backward compatibility)
   

   Where:

   • host is the server to which your producer has been deployed.

   • port is the HTTP Listener port number.

   • context-root is the context root.

   • portlets[/wsrp(1|2)]?WSDL is static text. The text entered here depends on how the producer is deployed.

   For example:

   http://myhost:7778/MyPortletApp/porlets/wsrp2?WSDL
   

   You can access the producer test page through the URL:

   http://host:port/context-root/info
   

   Note:

   While the URL Endpoint is editable, use the edit feature only to update the host name, port, or IP address. Do not use the edit feature to point to a new producer. Switching from one producer to another (even when the portlets are identical) is not supported by the WSRP specification.

9. If the application will use an HTTP proxy to connect to the producer, perform the following steps:

   Note:

   The proxy fields on this panel default to the proxy preferences set in Oracle JDeveloper Preferences (From the Tools menu, select Preferences, then select Web Browser and Proxy.)

   1. Select Use proxy for contacting the WSRP Portlet Producer.

      Select this check box if the application will use an HTTP proxy in contacting the producer. The proxy is required in cases where the consumer application and the remote portlet producer are separated by a firewall and an HTTP proxy is needed for communication with the producer.

   2. In the Proxy Host field, enter the URL of the proxy.

   3. In the Proxy Port field, enter the port number of the proxy.

10. Click Next.

11. In the Default Execution Timeout (Seconds) field, enter the number of seconds to enable for a portlet to render in the WebCenter application before it times out.

    Some producers can define additional registration properties. In such cases, the properties are displayed in a table on the wizard's Registration Details panel. Users can enter values for these additional properties in the table. These properties are producer-specific and are used only at registration time. That is, they collect information that consumer applications send to producers at registration time; the producers store this information against the consumers and use it subsequently.

    At this point, you can click Finish to complete registration. Continue if you plan to require authentication whenever the producer (and consequently its portlet) is accessed, or if you plan to map user categories defined for the producer's portlets with J2EE security roles defined for the application.

12. Click Next.

13. From the Token Profile list, select the type of token profile to use for authentication with the WSRP Producer.

    Choose from the following:

    • Username Token—A Web service consumer can supply a Username Token as a means of identifying the requestor by user name to authenticate that identity to the Web service producer.

    • SAML Token—SAML (Security Assertion Markup Language) is an XML-based approach for passing security tokens defining authentication and authorization rights. An attesting entity (that already has trust relationship with the receiver) vouches for the verification of the subject by method called sender-vouches.

    • None—No token. If None is selected, then no WS-Security header is attached to the SOAP message. In this case, the Finish button is enabled to complete producer registration.

14. In the Default User field, enter a user name to assert to the remote producer when the user has not authenticated to the WebCenter application.

    When unauthenticated, the identity anonymous is associated with the application user. The value anonymous may be inappropriate for the remote producer, so you may need to specify an alternative identity here. Keep in mind though, that in this case, the WebCenter application has not authenticated the user so the default user you specify should be a lowly privileged user in the remote producer. If the user has authenticated to the application, then the user's identity is asserted rather than the default user.

15. In the Issuer Name field, enter the name of the issuer of the SAML Token, for example www.oracle.com.

    This field appears only when SAML Token is selected from the Token Profile list. The issuer name is the attesting entity vouches for the verification of the subject.

16. Under XML Signature, select the means by which the signing certificate is referenced within the WS-Security KeyInfo.

    An XML Signature is used to digitally sign the security token and the SOAP message body to provide authenticity of the SOAP message. Use this panel to specify the means by which the signing certificate is referenced within the WS-Security KeyInfo.

    Select either Binary Security Token or Subject Key Identifier.

17. Click Next.

18. In the Store Path field, provide the full path to the Key Store that contains the certificate and the private key that is used for signing some parts (security token and SOAP message body) of the SOAP message.

    Optionally, click Browse to navigate to and select the file. The selected file could be a key store created with the Java keytool, or it could be an Oracle Wallet.

19. In the Store Password field, provide the password to the Key Store that was set when the Key Store was created.

    The store password must be correct for the Store Type field and the Signature Key Alias list to populate.

    If an incorrect password is entered, then an error message appears stating that the password is invalid and must be corrected. After you correct the password, press the Tab key to move to another active field (for example, the Store Path field). This ensures that the Store Type field and the Signature Key Alias list are properly populated.

    The Store Type value is read from the Key Store and is never editable. Applicable values include JKS (Java Key Store) or Oracle Wallet.

20. From the Signature Key Alias list, select the signature key alias.

    The Signature Key Alias list populates automatically when the correct password is entered in the Store Password field. The Signature Key Alias is the identifier for the certificate associated with the private key that is used for signing. The key aliases found in the specified key store are available in the list. Select the one to be used for signing.

21. In the Signature Key Password field, specify the password for accessing the key identified by the alias specified in Signature Key Alias.

22. Click Finish to complete registration of the WSRP portlet producer.

The next step depends on whether the producer being registered declares user categories:

• If the producer does not declare user categories, then the registration process is complete.

• If the producer declares user categories, then click Yes and see "Mapping a Producer's Declared User Categories to an Application's Defined J2EE Security Roles". Click No to decline this opportunity and complete producer registration.

Note:

Most registration settings can be edited. For example, if you decline to map the producer's user categories with J2EE security roles now, then you can reenter the wizard later and provide mapping information about the User Categories tab. For additional information, see Section 4.3.1.3, "Editing Portlet Producer Registration Settings".

Mapping a Producer's Declared User Categories to an Application's Defined J2EE Security Roles

The user categories the producer declares come from the portlets it contains. For example, if the producer contains one or more JSR 168 portlets created with the Standards-based Java Portlet (JSR 168) Wizard, then any security roles added during portlet creation are included in the user categories the producer declares. J2EE Security Roles can be specified through the WebCenter application's web.xml file properties.

This procedure continues forward from the previous procedure.

To map producer-declared user categories with application-defined J2EE security roles, perform the following steps:

1. In the mapping dialog box, click in the Application J2EE Security Role column.

   This dialog box is accessed during producer registration, by completing registration and clicking Yes when given the option to continue with mapping (see Section 4.3.1.1). It is accessible as well when you edit producer registration settings (see Section 4.3.1.3).

2. From the resulting list, select the security role to map to the Producer User Category.

3. Repeat steps 1 and 2 for each user category.

4. Click OK when all user categories are mapped.

4.3.1.2 Registering PDK-Java Portlet Producers

When you register an Oracle PDK-Java portlet producer, you provide basic information that describes the producer's operational parameters. This information is consumed by the WebCenter application for use in communicating with the producer and with portlets through the producer.

When registration is successful, the newly registered producer displays in Oracle JDeveloper on the Component Palette, from which you can now select portlets for placement on your application (jspx) page. Additionally, the producer is listed under the Portlet Producers node in the Applications Navigator.

To register an Oracle PDK-Java Portlet Producer, perform the following steps:

1. In the Applications Navigator, right-click the application under which to create the producer and select New from the context menu.

2. In New Gallery under Categories, expand the Web Tier node and select Portlets.

3. In New Gallery under Items, select Oracle PDK-Java Producer Registration.

4. Click OK.

5. On the Welcome page, click Next.

   Optionally, before clicking Next, select Skip this Page Next Time to forgo display of the Welcome page on subsequent uses of this wizard. The Welcome page may not display if the option to skip was selected on earlier use of the wizard.

6. In the Name field, enter a name for the producer.

   Give the producer a name that is unique among producers.

   Note:

   Producers given the same name display only once on the Component Palette. So, if you register two producers and give them each the name MyProducer, then the name MyProducer displays only once on the Component Palette, and both producers' portlets are listed under the one instance. This makes it difficult to determine which portlets come from which producer.

   If you find yourself in this situation, then consider editing one of these producers and giving it a unique name. See Section 4.3.1.3, "Editing Portlet Producer Registration Settings".

7. Click Next.

8. In the URL Endpoint field, enter the producer's URL using the following syntax:

   http://<host>:<port>/<context-root>/providers
   

   Where:

   • host is the server to which your producer has been deployed.

   • port is the port to which the server is listening for HTTP requests.

   • context-root is the Web application's context root.

   • providers is static text. The text entered here depends on how the producer is deployed.

   For example:

   http://myHost:7778/myEnterprisePortlets/providers
   

9. In the Service ID field, enter a unique identifier for this producer.

   PDK-Java enables you to deploy multiple producers under a single adapter servlet. The producers are identified by their unique service IDs. A service ID is required only when a service ID or producer name is not appended to the URL endpoint. For example the following URL endpoint requires the service ID, sample:

   http://domain.us.company.com:<port_number>/axyz/providers
   

   However, the following URL endpoint, does not require a service ID:

   http://domain.us.company.com:<port_number>/axyz/providers/sample
   

10. If the application will use an HTTP proxy to connect to the producer, perform the following steps:

    Note:

    The proxy fields on this panel default to the proxy preferences set in Oracle JDeveloper Preferences (From the Tools menu, select Preferences, then select Web Browser and Proxy.)

    1. Select Use proxy for contacting the PDK Portlet Producer.

       Select this check box if the application will use an HTTP proxy in contacting the producer. The proxy is required in cases where the consumer application and the remote portlet producer are separated by a firewall and an HTTP proxy is needed for communication with the producer.

    2. In the Proxy Host field, enter the URL of the proxy host.

    3. In the Proxy Port field, enter the port number of the proxy host.

11. Select Associate producer with external application, then select the application, in the event this producer must provide authentication to an external application.

    For more information, see Section 10.7, "Accessing External Applications Requiring Credentials".

12. Select Enable Producer Sessions to enable portlet producer sessions.

    Use this option to enable sessions between the producer and the OC4J server. For sessionless communication between the producer and the server, do not select this option.

    When sessions are enabled, the server maintains session-specific information, such as user name. Message authentication uses sessions, so if the shared key is set, then this option should also be selected.

13. Click Next.

14. In the Default Execution Timeout (Seconds) field, enter the number of seconds to enable for a portlet to render in the WebCenter application before it times out.

15. In the Subscriber ID field, enter a string to identify the consumer of the producer being registered.

    When a producer is registered, a call is made to the producer. During the call, the consumer passes the value for Subscriber ID to the producer. If the producer does not see the expected value for Subscriber ID, then it might reject the registration call.

16. In the Shared Key field, enter a shared key to use for producers that are set up to handle encryption.

    The shared key is used by the encryption algorithm to generate a message signature for message authentication. Note that producer registration will fail if the producer is set up with a shared key and you enter an incorrect shared key here. The shared key can contain between 10 and 20 alphanumeric characters.

17. Click Finish to complete registration of the PDK-Java portlet producer.

18. Click OK, to close the success message.

4.3.1.3 Editing Portlet Producer Registration Settings

Both the WSRP and PDK-Java portlet producer registration wizards enable you to access and revise many of the values you entered when you registered the producer.

Note:

Once you have completed your edits, consider testing the producer connection to be sure connection information is valid. For more information, see Section 4.3.1.4, "Testing a Portlet Producer Connection".

To edit a WSRP or Oracle PDK-Java Portlet Producer, perform the following steps:

1. In the Applications Navigator, navigate to the producer:

   Applications
     <ApplicationName>
       Portlet Producers
   

2. Right-click the producer to be edited, and select Edit from the context menu.

   Note:

   You can also double-click the producer in the Applications Navigator to open the producer in edit mode.

3. Click the tabs at the top of the wizard to bring different setting panels forward:

   • For information about WSRP Producer settings, see Section 4.3.1.1, "Registering WSRP Portlet Producers".

   • For information about PDK-Java Producer settings, see Section 4.3.1.2, "Registering PDK-Java Portlet Producers".

4.3.1.4 Testing a Portlet Producer Connection

The connection testing feature provides a means of testing the validity of a portlet producer connection.

To test a portlet producer connection, perform the following steps:

1. In the Applications Navigator, navigate to the producer:

   Applications
     <ApplicationName>
       Portlet Producers
         <ProducerName>
   

2. Right-click the producer to be edited, and select Test Producer Connection from the context menu.

   A progress bar appears while the test is underway. A success or failure dialog box displays when the test is complete. Click OK to close this dialog box.

   If the failure dialog box displays, then consider reediting producer registration details and retesting the producer connection. Additionally, make sure that the producer is available. For example, if the producer is provided through the preconfigured Oracle Containers for J2EE (OC4J), then make sure the preconfigured OC4J is running, and then retest the connection.

4.3.1.5 Refreshing a Portlet Producer

When you refresh a portlet producer, the portlets from that producer are also refreshed. This means that newly added portlets and any updates to existing portlets become available to any applications that are consuming portlets from this producer.

Note:

When a portlet is removed from a producer, be sure to manually delete the portlet from all application pages on which it has been placed. For more information, see Section 4.3.5, "Deleting Portlets from Application Pages".

To refresh a WSRP or Oracle PDK-Java Portlet Producer, perform the following steps:

1. In the Applications Navigator, navigate to the producer:

   Applications
     <ApplicationName>
       Portlet Producers
   

2. Right-click the producer to be edited, and select Refresh from the context menu.

3. In the Refresh Portlet Producer dialog box, click Yes.

4. Click OK to close the Success dialog box.

4.3.1.6 Deregistering a Portlet Producer

When you deregister a producer, registration data is removed on both the WebCenter application end and the remote producer end. On the application end the producer connection is deleted. On the producer end, portlet instances are deleted (though not the portlets themselves).

Though portlet instances are removed on the remote producer end, they are not also removed on the application end. Therefore, when you deregister a portlet producer, you must also remove any portlets the producer provides from your application pages. Additionally, if the portlet included parameters, then any associated page variables must be removed from any affected application page's Page Definition file.

Note:

For information about deleting portlets and relevant page variables, see Section 4.3.5, "Deleting Portlets from Application Pages".

To deregister a portlet producer, perform the following steps:

1. In the Applications Navigator, navigate to the producer:

   Applications
     <ApplicationName>
       Portlet Producers
         <producer_name>
   

2. Right-click the producer to be deregistered, and select Deregister from the context menu.

3. In the Portlet Producer Deregister dialog box, click Yes.

   Instead of the Portlet Producer Deregister dialog box, you may see a Connection Error dialog box. This dialog displays when a connection cannot be made to the producer.

   Connection failure can occur when the producer is not available or the producer's connection details are incorrectly specified in the WebCenter application. Your options are to click Yes or No:

   • Click Yes to continue with deregistration. When you click Yes, registration data is removed on the WebCenter application end but remains untouched on the remote producer end.

   • Click No to cancel deregistration. Should you cancel, you can try again after verifying that the producer is available and the connection details are valid in the Producer Registration wizard (see Section 4.3.1.3, "Editing Portlet Producer Registration Settings").

4. Click OK to close the resulting success message.

4.3.2 Adding Portlets to a Page

Placing a portlet on a WebCenter application page is a simple matter of dragging-and-dropping, though there are a few preparatory steps you must take before you can take this simple action. These include, creating a WebCenter application (see Section 3.1, "Creating a WebCenter Application"), creating an application page (see Section 4.2, "Building WebCenter Application-Enabled Pages in Oracle JDeveloper with Oracle ADF"), and registering the portlet's producer with the application (see Section 4.3.1, "Registering Portlet Producers").

Note:

For information about portlet parameters, see Section 4.5, "Contextually Linking Components".

When you examine the source of the application page on which you have placed a portlet, you will see an adfp:portlet tag. This is the tag that binds the portlet to the page. It carries with it a string of attributes you can revise to further control the behavior and appearance of the portlet. For more information, see Section 4.3.3, "Setting Attribute Values for the adfp:portlet Tag".

Note:

Some of the portlets you plan to consume may come from applications that handle their own authentication. In such cases, you must register the application as an external application and identify it to the portlet producer that will provide it. For more information, see Chapter 10, "Securing Your WebCenter Application".

Some of the portlets you plan to consume may come from producers that are Secure Sockets Layer (SSL) enabled. When you try to access an SSL-enabled producer, a Security Alert dialog box may pop up, prompting you to view the producer's security certificate and add it to the list of trusted certificates. The Security Alert dialog box is displayed only if the producer uses a security certificate issued by a certificate authority that is not widely accepted. To consume portlets from such a producer, you must first add the producer's security certificate to the keystore. See Section 10.8, "Registering Custom Certificates with the Keystore" for the steps to be performed.

To add a portlet to a page, perform the following steps:

1. In the Applications Navigator, right-click the application page (jspx file) to which you will add the portlet, and select Open from the context menu.

   You can find the jspx file at the following location in the Applications Navigator:

   Applications
     <ApplicationName>
       <ProjectName>
         Web Content
          <ApplicationPage>.jspx
   

2. In the Component Palette, select the portlet producer that contains the portlet you will add to the application page.

   Under the selected producer, the Component Palette lists all portlets contained by that producer.

3. Select a portlet, and drag it over the h:form element in the Oracle JDeveloper Structure pane.

   Alternatively, drag the portlet from the Component Palette directly onto the page in the editor.

   The portlet should be nested somewhere in an h:form element. It need not necessarily be directly wrapped in h:form tags. If you add the component outside an h:form element, then Oracle JDeveloper asks whether you want the form element to wrapped around it. Select this option.

   If the application page includes one or more core customizable components, then this may influence where the portlet is placed. For example, in the Structure pane, a portlet placed on a page with a cust:panelCustomizable tag, would be placed as illustrated in Example 4-1:

   Example 4-1 Hierarchical Placement of the adfp:portlet Tag

   h:form
     cust:panelCustomizable
       adfp:portlet
   

   For information about the core customizable tags, cust:panelCustomizable and cust:showDetailFrame, see Section 4.4, "Using Customizable Components".

When you add a portlet to a page, an adfp:portlet tag is added to the page source. The adfp:portlet tag includes a number of attributes accessible through the Oracle JDeveloper Property Inspector. For information about attributes of the adfp:portlet tag, see Section 4.3.3, "Setting Attribute Values for the adfp:portlet Tag".

Note:

When you drop an instance of OmniPortlet onto your page, open the Property Inspector and ensure that the AllModesSharedScreen, under the Display Mode category, is set to false, the default value. Setting this property to true may prevent you from editing certain sections of your OmniPortlet in the OmniPortlet wizard.

Once you place a portlet on a page, right-click the page and select Run from the context menu. This displays the page and runs the portlet in your default browser using Oracle JDeveloper's embedded OC4J. Different portlets may require additional run time configuration. Notably, the content of an OmniPortlet or Web Clipping portlet instance is defined at run time. For more information about OmniPortlet, see Chapter 16, "Creating Portlets with OmniPortlet". For more information about the Web Clipping portlet, see Chapter 17, "Creating Content-Based Portlets with Web Clipping". For more information about portlets generally, see Chapter 14, "Understanding Portlets" and Chapter 15, "Portlet Technologies Matrix".

When running a portlet that has an Edit mode (in a WebCenter application, this renders as a Personalize command on the portlet's Actions menu), the Personalize option displays in the portlet's Actions menu only to authenticated users (that is, users who have logged in). Anonymous or public users do not see the option to personalize the portlet. Some form of security must be implemented for the portlet-consuming application before users can personalize their view of a portlet. If you are a developer creating portlets and pages, then you may want to test your portlet's Edit mode without creating a complete security model for your application. See Section 10.6, "Configuring Basic Authentication for Testing Portlet Personalization" for an explanation of how to add security to enable testing of portlet personalization (that is, for testing your portlet's Edit mode).

4.3.3 Setting Attribute Values for the adfp:portlet Tag

On application source pages, each portlet is represented by an adfp:portlet tag, which includes a set of required and optional attributes. Required attributes, value and portletType, are provided automatically by the framework, and must not be altered. Optional attribute values are relevant when support for the attribute is built into the portlet. For example, you can set isAboutModeAvailable to true, but if no About mode has been defined for the portlet, then the attribute setting does not affect the portlet.

Portlets also support a set of style-related attributes, which are discussed more fully in Section 9.4, "Defining Styles Through the Property Inspector".

Set attribute values at design time either through the Oracle JDeveloper Property Inspector or in the source as attributes of the adfp:portlet tag, shown in Example 4-2.

Example 4-2 adfp:portlet Tag

<adfp:portlet value="#{bindings.portlet1}"
  portletType="/oracle/adf/portlet/WsrpPortletProducer1/applicationPortlets/
    E0default_b452f828_010a_1000_8002_82235f57eaa8"
  allModesSharedScreen="true"
  isMaximizable="true"
  isMinimizable="true"/>

The adfp:portlet tag uses four types of attributes, which this section lists and describes. It contains the following subsections:

• Section 4.3.3.1, "General Attributes of the adfp:portlet Tag"

• Section 4.3.3.2, "Actions Attributes of the adfp:portlet Tag"

• Section 4.3.3.4, "Core Attributes of the adfp:portlet Tag"

• Section 4.3.3.5, "Display Mode Attributes of the adfp:portlet Tag"

4.3.3.1 General Attributes of the adfp:portlet Tag

Table 4-1 describes the general attributes of the adfp:portlet tag.

Table 4-1 General Attributes of the adfp:portlet Tag

Attribute	Value	Description
height	A number expressed in pixels or as a percentage of the available area: For pixels, enter npx, for example, 300px. For percentage, enter n%, for example, 50%.	The height of area to enable for portlet display. If the actual portlet height is larger than the height value entered here, then a scrollbar appears, provided displayScrollBar is set to auto or true. If displayScrollBar is set to false, and actual portlet height exceeds the value expressed for the height attribute, then the height attribute value is considered and the portlet content is truncated.
icon	The URI to an image. For example: icon="coffee.png" In Oracle JDeveloper, click the Edit icon in the value column to locate and select the required image. The URI provided in this example is stored at the document root; therefore, a full path is not required. An image that is not stored at the document root requires a full path, for example: icon="C:\portal\images\box_b.gif" Or: icon="http://source-pc/imgs/art.gif"	A URI specifying the location of an icon to display to the left of the portlet title in the portlet header.
id	A text string to use as the portlet's unique identifier. For example: id="newsBrief"	The unique identifier of the component.
text	A text string to use as the portlet's header title. For example: text="Announcements …"	The portlet header title. Use this to supply a display title on the portlet. The attribute value specified in the <adfp:portlet> tag takes precedence over any title specified elsewhere (for example, in the portlet mark-up). If no value is specified, then the portlet extracts its title from the portlet mark-up (response). If neither the text attribute nor the portlet mark-up is available, then the title is extracted from the portlet definition. Note: Supplying a value to the text attribute at design-time prevents customization and personalization of the portlet title at run time.
width	A number expressed in pixels or as a percentage of available area: For pixels, enter npx, for example, 300px. For percentage, enter n%, for example, 50%.	The width of the portlet. If the actual portlet width is larger than the width value entered here, then a scrollbar appears, provided displayScrollBar is set to auto or true. If displayScrollBar is set to false, and actual portlet width exceeds the value expressed for the width attribute, then the width attribute value is considered and the portlet content is truncated.
binding	The name of the managed bean. For example: binding="#{frameActionsBean.Binding}" In Oracle JDeveloper, click the Edit icon in the value column to select a managed bean and specify the relevant managed bean property.	A binding reference to store the component instance. The binding reference binds an instance of the portlet to a managed bean property. Managed beans are any JavaBeans used by the application that are registered in the JSF faces-config.xml file.
partialTriggers	The ID of one or more components that trigger a partial update. For example: partialTriggers="_id1 componentID5"	IDs of components that trigger a partial update. The portlet listens on the specified trigger components. If one of the trigger components receives a trigger event that causes it to update in some way, then the portlet also requests to be updated. In the partialTriggers tag, components are separated from each other by a space.
portletType	This required attribute value is provided by the framework by default.	portletType is used to differentiate between different portlets in the design-time environment. The value is provided programmatically by the framework and should not be revised or removed.
shortDesc	A text string to use as a brief description of the portlet. For example: shortDesc="Portlet for entering display text in place."	A short description of the portlet.
value	This required attribute value is provided by default.	The portlet gets its portlet container (producer) support from the reference to the portlet binding in the page definition. This attribute value is provided programmatically and should not be revised or removed.
submitUrlParamters	false	Portlet links that point to the page on which the portlet is situated force a page to submit itself rather than just reload with the link URL. By default, the parameters in this URL are not made available to the page. Rather, they are available only inside the portlet initiating the request. Setting submitUrlParameters to true makes these URL parameters available on the container page as well.

4.3.3.2 Actions Attributes of the adfp:portlet Tag

Actions attributes control the rendering of mode-switching UI actions, such as entering edit mode. The ability to render a portlet in a particular mode depends on the modes supported by the portlet and the user authorization. For example, if the isCustomizeModeAvailable attribute is set to true, but the action is not supported in the portlet, then the attribute setting will not affect the portlet.

Actions attributes, described in Table 4-2, are value binding expressions that evaluates to true or false:

• true means the portlet is enabled to render in the named mode.

• false means the portlet is not enabled to render in the named mode.

Table 4-2 Actions Attributes of the adfp:portlet Tag

Attribute	Default	Description
isAboutModeAvailable	true	In a WebCenter application, renders an About command on the portlet's Actions menu. Users select About to invoke the portlet's About mode.
isConfigModeAvailable	true	In a WebCenter application, renders a Configure command on a JSR 168 portlet's Actions menu. Users select Configure to open the portlet's Configuration settings.
isCustomizeModeAvailable	true	In a WebCenter application, renders a Customize command on the portlet's Actions menu. Customize mode enables site administrators to edit a portlet's default personalization data.
isDetailModeAvailable	true	In a WebCenter application, renders a Details command on the portlet's Actions menu. Users select Details to open the portlet's Details page. This attribute maps to the Show details page mode in Oracle PDK-Java portlets. It has no application in standards-based (JSR 168) Java portlets.
isHelpModeAvailable	true	In a WebCenter application, renders a Help command on the portlet's Actions menu. Users select Help to open the portlet's Help page.
isMaximizable	true	In a WebCenter application, renders a Maximize command on the portlets Actions menu. Users select Maximize to expand the portlet. When the component is maximized, the Restore command displays on the Actions menu to return the portlet to its default display mode. The Maximize option applies only to portlets placed inside a PanelCustomizable component. When users select Maximize, the portlet expands to the width of its parent PanelCustomizable, displacing all other components placed in the PanelCustomizable. There is a difference in the way the Maximize and Restore actions work at design-time and at run time. For more information, see Section 4.3.3.3, "What You Should Know About Maximize, Minimize, Restore, and Move".
isMinimizable	true	In a WebCenter application, renders a Minimize icon on the portlet header. Users click the icon to collapse the portlet like a window shade. Users restore the portlet by clicking the icon again. There is a difference in the way the Minimize action behaves at design-time and at run time. For more information, see Section 4.3.3.3, "What You Should Know About Maximize, Minimize, Restore, and Move".
isMovable	true	In a WebCenter application, renders a Move command on the portlet's Actions menu. Users select the command, then the subcommand Move Up, Move Down, Move Left, or Move Right, depending on the portlet's current position related to the other portlets on the page. There is a difference in the way the Move action behaves at design-time and at run time. For more information, see Section 4.3.3.3, "What You Should Know About Maximize, Minimize, Restore, and Move".
isNormalModeAvailable	true	In a WebCenter application, renders a Refresh command on the portlet's Actions menu. Users select the Refresh command and the portlet refreshes (that is, redraws) independent of any other content on the page (also known as a partial-page refresh).
isPersonalizeModeAvailable	true	In a WebCenter application, renders a Personalize command on the portlet's Actions menu. Users select Personalize to alter their personal view of the portlet. This mode is equivalent to the Edit mode selection in the Standards-based Java Portlet (JSR168) Wizard. The Personalize command displays on the Actions menu only to authenticated users (that is, users who are logged in). It does not display to Public or unauthenticated users. You must implement some form of application security for users to be able to personalize their portlet views. If you are a developer creating portlets, and you want to test the Personalize mode without creating a complete security model for your application, then see Section 10.6, "Configuring Basic Authentication for Testing Portlet Personalization". Note: A typical personalization setting is Portlet Title. You can set Portlet Title at design-time, by providing a value for the text attribute of the adfp:portlet tag. Consider however that supplying a value to the text attribute at design-time prevents personalization and customization of the portlet title at run time.
isPreviewModeAvailable	false	Provides a means of previewing portlet content. This mode has no particular application in WebCenter applications, but it is used in Oracle Application Server Portal's (OracleAS Portal) Portlet Repository, where it renders as a magnifying glass icon, which users click to preview a portlet.
isPrintModeAvailable	true	In a WebCenter application, renders a Print command on a JSR 168 portlet's Actions menu that displays a printer-friendly version of the portlet.
isSeededInteractionAvailable	true	Makes the portlet's seeded interactions, Maximize, Move, and Minimize, available for exposure to users. When the attribute is set to true, seeded interactions are available for display (note, however, that display of each seeded interaction is controlled by its own attribute setting). When the attribute is set to false, seeded interactions are not available for display. Custom interactions are not affected by this attribute setting.

4.3.3.3 What You Should Know About Maximize, Minimize, Restore, and Move

To accommodate the needs of the development environment, the behavior of the actions Minimize, Maximize, Restore, and Move for ShowDetailFrame and portlet components differs between design-time and run time. At design-time, these actions persist in a given OC4J session, but do not persist over sessions (session means the time between starting and stopping the OC4J). At run time, these actions persist both during a given OC4J session and across sessions.

This difference has been introduced to enable an automatic reset of an application page at design-time.

If persisting across sessions is not required at run time, then a simple modification to the application's web.xml file can turn it off. Go to the following parameter setting in the application's web.xml file (Example 4-3):

Example 4-3 Persistence Setting in the Application's web.xml File

<context-param>
  <param-name>oracle.adf.view.faces.CHANGE_PERSISTENCE</param-name>
  <param-value>oracle.adfinternal.view.faces.change.HybridChangeManager</param-value>
</context-param>

Replace it with the following (Example 4-4):

Example 4-4 Turning Run-Time Persistence Off in the Application's web.xml File

<context-param>
  <param-name>oracle.adf.view.faces.CHANGE_PERSISTENCE</param-name>
  <param-value>oracle.adf.view.faces.change.SessionChangeManager</param-value>
</context-param>

If security has been implemented on the application, then the Minimize, Maximize, Restore, and Move actions display only to users with Customize privileges. They do not display to users with Personalize privileges. Customize users can test the effect of these actions by following these steps at design-time:

• Run the application page using Oracle JDeveloper's embedded OC4J.

• Log-in as the administrator.

• Maximize a portlet. Move portlets around. Make whatever changes you want using the relevant actions commands.

• Log-out, then log-in as a user and check the effects of your actions.

4.3.3.4 Core Attributes of the adfp:portlet Tag

Table 4-3 describes the core attributes of the adfp:portlet tag.

Table 4-3 Core Attributes of the adfp:portlet Tag

Attribute	Value	Description
contentInlineStyle	The name of a CSS style For example, to turn off the portlet border, add the following to the adfp:portlet tag: contentInlineStyle="border-style:none;"	The CSS style to apply to the portlet. Expand this node to specify styles for specific style elements on the specific portlet instance. Values entered here take precedence over styles included in a CSS or skin on the specific portlet instance. For more information, see Section 9.4, "Defining Styles Through the Property Inspector".
inlineStyle	The name of a CSS style	The CSS style to apply to the portlet. Expand this node to specify styles for specific style elements on the specific portlet instance. Values entered here take precedence over styles included in a CSS or skin on the specific portlet instance. For more information, see Section 9.4, "Defining Styles Through the Property Inspector".
rendered	true/false	Specifies whether the portlet is rendered. When set to false, no output is rendered. The default value is true.

4.3.3.5 Display Mode Attributes of the adfp:portlet Tag

Table 4-4 describes the display mode attributes of the adfp:portlet tag.

Table 4-4 Display Mode Attributes of the adfp:portlet Tag

Attribute	Value	Description
allModesSharedScreen	true/false	Determines whether a change in portlet mode renders the new mode on a new page, other than the page on which the portlet resides (false). true means all portlet modes are displayed inline. One mode is swapped out for another on the same page. In other words, this attribute enables all portlet modes to display without leaving the context of a given page. false means all portlet modes, except View (JSR 168) or Show (PDK-Java), are rendered each on their own page. The default mode is useful for such portlets as OmniPortlet and the Web Clipping portlet, which require that modes other than Show mode display on pages other than the page on which the portlet resides. The default value is false.
background	light/medium/dark	Provides a means of applying a different look and feel to each portlet on an application page. The default skins, Oracle, Minimal, and Simple, and custom skins include three versions of style selectors: light, medium, and dark. Depending on which value is specified for the background property, the skin will apply the relevant style or icon selector version. For more information, see Section 9.3.6, "Applying Color Schemes to Portlets and Core Customizable Components".
displayHeader	true/false	Indicates whether the portlet's header is displayed. true means the header is displayed. Consequently, header-based icons and links are displayed. false means the header is not displayed, and icons and links normally displayed in the header are hidden. If isSeededInteractionAvailable is set to true, then the user can access portlet menus and icons by rolling the mouse over the portlet. A fade-in/fade-out toolbar appears, from which users can select Actions menu options. The default value is true.
expansionMode	maximized/minimized/normal	The default state of the portlet. Select from: minimized—Portlet's default display mode is collapsed (minimized). maximized—This option applies only to portlets placed inside a PanelCustomizable component. Portlet's default display mode is expanded to the width of its parent PanelCustomizable, displacing all other components placed in the PanelCustomizable. normal—This is the default value for the expansionMode attribute. Portlet's default display mode is normal. That is, it is neither collapsed nor expanded to the width of the page.
displayScrollBar	true/false/auto	Display a scrollbar if content does not fit the width and height specified (auto). A value of true always renders a scroll bar. A value of false never renders a scroll bar. If the portlet exceeds the values expressed for width or height, then these values are ignored and the portlet renders in its actual size. The default is auto.
renderPortletInIFrame	true/false/auto	A value binding expression that evaluates to true/false/auto: true means the portlet is rendered in an iframe. auto means the portlet tag checks the portlet response and decides if an iframe is required. It bases its decision on the existence of FORM or any links inside the portlet response. false Although this value is available for selection, it is not supported. HTML mark-up from a portlet that is not rendered in an iframe may interfere with other components on the Oracle ADF page. The default is auto. For additional information, see Section 4.3.3.6, "iframes and form Tags".

4.3.3.6 iframes and form Tags

The HTML source generated by a JavaServer Faces page contains a form tag. Because nested form tags are not enabled in HTML, portlets cannot open new forms on the same page.

The best way to circumvent this issue is to render your portlets inside of an iframe. You achieve this by setting the renderPortletInIFrame attribute to true or auto. A value of true always uses an iframe. A value of auto causes Oracle WebCenter Framework to detect whether the portlet contains a form element and, if it does, then render it within an iframe.

For example, the Upload Portlet that comes with the preconfigured OC4J's WSRP Sample Producer requires an iframe to run correctly. If you do not place it in an iframe by setting renderPortletInIFrame to true or auto, then the portlet does not work.

Note:

If you render a portlet within an iframe, then manipulating window.location may give unexpected results. If your portlet uses window.location, then you should ensure that your JavaScript is robust enough to handle the case where the portlet renders itself inside of an iframe.

Alternatively, you could rewrite your portlet such that you eliminate the form elements in the portlet's mark-up, but this approach is cumbersome and may not be feasible in all cases.

4.3.4 Copying Portlets

When you copy portlets, the portlets and their copies must reside within the same application. For example, you can copy a portlet from one page in an application to another page in the same application, from one place on a page to another place on the same page, or from one project to another project within the same application. The copies are references to the same portlet instance. This means customizations or personalizations made to any instance of the portlet (original or copy) affect all the other instances.

Copying a portlet is more than a matter of copying and pasting the portlet view tag. It involves copying portlet-related entries from the application page's source. It may also involve copying portlet-related entries from the page definition file as well as removing duplicate portlet binding information or creating a new method in the copied portlet's binding bean.

When a portlet is copied, the target page must be an Oracle ADF Faces page. Any preexisting code on the target page must reflect that. This is quite easy to accomplish. When Oracle JDeveloper creates a new JSF page, it contains pure JSF tags. The first time you drop an Oracle ADF Faces component onto the page, tags are automatically updated to be Oracle ADF Faces tags. For example, an <html> tag becomes <afh:html>, <head> and <title="title"> tags become <afh:head title="title">, and so on. Therefore, a simple way to ensure the conversion of the target page to an Oracle ADF Faces page is to place any Oracle ADF Faces component on the target page. This will perform any required code conversion for you automatically.

This section describes how to copy portlets from one application page to another as well as how to copy a portlet from one part of a page to another part of the same page. It includes the following subsections:

• Section 4.3.4.1, "Copying and Placing a Portlet on the Same Page"

• Section 4.3.4.2, "Copying Portlets from One Application Page to Another"

4.3.4.1 Copying and Placing a Portlet on the Same Page

Because all of the page's resources are available to both portlet instances when you copy a portlet to the same page, there is no need to copy portlet-related information from the page's Page Definition file. It is just a matter of copying and pasting the portlet's view tag, and assigning a unique identifier to the copy.

To copy and place a portlet on the same page, perform the following steps:

1. In Oracle JDeveloper, go to the Source view of the page that hosts the portlet to be copied.

2. Copy the portlet tag (Example 4-5).

   Example 4-5 Code Fragment to be Copied When Copying a Portlet

   <f:view>
     <afh:html binding="#{backing_portlet_page.html1}" id="html1">
       <afh:head title="portlet_page" binding="#{backing_portlet_page.head1}"
         id="head1">
         <meta http-equiv="Content-Type"
           content="text/html;charset=windows-1252"/>
       </afh:head>
       <afh:body binding="#{backing_portlet_page.body1}" id="body1">
         <h:form binding="#{backing_portlet_page.form1}" id="form1">
           <adfp:portlet value="#{bindings.portlet1}"
             portletType="/oracle/adf/portlet/
             pdksampleproducer_1153245807295/applicationPortlets/
             Portlet2_82d49b79_010c_1000_8006_82235ffc4e2b"
             binding="#{backing_portlet_page.portlet1}"
             id="portlet1"
             isCustomModesAvailable="true"/>
         </h:form>
       </afh:body>
     </afh:html>
   </f:view>
   

3. Paste the copied code fragment into the page's Source view.

4. Provide a unique value for the copy's ID attribute (Example 4-6).

   Example 4-6 Changing the Portlet ID

   <adfp:portlet value="#{bindings.portlet1}"
     portletType="/oracle/adf/portlet/
     pdksampleproducer_1153245807295/applicationPortlets/
     Portlet2_82d49b79_010c_1000_8006_82235ffc4e2b"
     binding="#{backing_portlet_page.portlet1}"
     id="portlet2"
     isCustomModesAvailable="true"/>
   

   Note:

   On a given page, each portlet must have a unique ID.

5. In the page source, if the copied portlet's adfp:portlet tag has a binding attribute, for example:

   binding="#{backing_untitled2.portlet1}"
   

   Then either remove this binding, or create a new method in the binding bean by opening the managed bean class for this managed bean and defining the new method in the faces-config.xml file.

   For example, if portlet1 is copied, and the pasted copy becomes portet2, in the faces-config.xml file, as shown in Example 4-7.

   Example 4-7 Creating a New Method for a Managed Bean in faces-config.xml

   .
   private PortletBase portlet2;
   public void setPortlet2(PortletBase portet2) {
      this.portlet2 = portlet2;
   }
   .
   public PortletBase getPortlet2() {
      return portlet2;
   }
   

4.3.4.2 Copying Portlets from One Application Page to Another

When you copy a portlet from one page to another in an application, portlet-related code must also be copied from the source page's Page Definition file. This section describes the steps related to both copying from one application page to another and from one application project to another.

To copy a portlet from one application page or project to another, perform the following steps:

1. In Oracle JDeveloper, go to the Source view of the page that hosts the portlet to be copied.

2. Copy the portlet tag (Example 4-8).

   If the target page does not contain Oracle ADF Faces components, then make sure the container objects—that is, any tags the portlet tag is nested in—use Oracle ADF tags:

   Example 4-8 Source Page Code Fragment to Be Copied When Copying a Portlet

   <f:view>
     <afh:html binding="#{backing_portlet_page.html1}" id="html1">
       <afh:head title="portlet_page" binding="#{backing_portlet_page.head1}"
         id="head1">
         <meta http-equiv="Content-Type"
           content="text/html;charset=windows-1252"/>
       </afh:head>
       <afh:body binding="#{backing_portlet_page.body1}" id="body1">
         <h:form binding="#{backing_portlet_page.form1}" id="form1">
           <adfp:portlet value="#{bindings.portlet1}"
             portletType="/oracle/adf/portlet/
             pdksampleproducer_1153245807295/applicationPortlets/
             Portlet2_82d49b79_010c_1000_8006_82235ffc4e2b"
             binding="#{backing_portlet_page.portlet1}"
             id="portlet1"
             isCustomModesAvailable="true"/>
         </h:form>
       </afh:body>
     </afh:html>
   </f:view>
   

   Note:

   Portlets can reside only on Oracle ADF Faces pages. See the introductory paragraph to this procedure for more information.

3. Go to the application page to which to copy the portlet (the target page).

4. Paste the copied code into the target page's Source view.

5. Go to the page definition file of the page from which the portlet was copied (the source page).

   Right-click the source page, and select Go to Page Definition from the context menu.

6. Copy the portlet binding from the source page's page definition file (Example 4-9).

   Example 4-9 Code Fragment to Be Copied From a Page Definition File

   <portlet id="portlet1"
       portletInstance="/oracle/adf/portlet/
       pdksampleproducer_1153245807295/applicationPortlets/Portlet2_82d49b79_    010c_1000_8006_82235ffc4e2b"
       class="oracle.adf.model.portlet.binding.PortletBinding"
       xmlns="http://xmlns.oracle.com/portlet/bindings"/>
   

   Note:

   When the portlet being copied includes parameters, be sure to include the copied portlet's portlet parameters as well as the page variables linked to the portlet parameters in the copy.

7. Go the to page definition file of the target page.

   Create a page definition file if necessary. Do this by right-clicking the target page and selecting Go to Page Definition. You will be prompted to create a page definition file if none exists.

8. Paste the portlet binding you copied from the source (as well as relevant portlet parameters and the page variables associated with those parameters).

4.3.5 Deleting Portlets from Application Pages

When you delete a portlet from an application page, if the portlet had parameters, then you should also delete page variables associated with those parameters from the application page's Page Definition file.

To delete a portlet from a page and related page variables from a Page Definition file, perform the following steps:

1. In the Applications Navigator, navigate to the relevant application page (jspx file), and open it:

   Applications
     <ApplicationName>
       <ProjectName>
         WEB Content
          <ApplicationPage>.jspx
   

2. In Design view, right-click the portlet to delete and select Delete from the context menu.

   This deletes the portlet from the page and the portlet binding from the page's Page Definition file.

3. If the portlet included variables, then right-click the jspx file in the Editor and select Go to Page Definition from the context menu.

   The page definition file opens in the Editor pane.

4. Locate the page variables associated with the deleted portlet, and delete them from the page definition file.

   For example, if portlet1 is deleted you would delete the highlighted variables in Example 4-10:

   Example 4-10 Deleting Portlet-Related Page Variables from a Page Definition File

   <?xml version="1.0" encoding="UTF-8" ?>
   <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
       version="10.1.3.38.97" id="untitled1PageDef"
       Package="project1.pageDefs">
     <parameters/>
     <executables>
       <variableIterator id="variables">
           <variable Name="portlet1_param1" Type="java.lang.Object"/>
           <variable Name="portlet1_param2" Type="java.lang.Object"/>
           <variable Name="portlet2_param1" Type="java.lang.Object"/>
           <variable Name="portlet2_param2" Type="java.lang.Object"/>
       </variableIterator>
       <portlet id="portlet2" portletInstance="/oracle/adf/portlet/
           PdkPortletProducer2_1154100666247/applicationPortlets/
           Portlet1_b5e49696_010c_1000_8008_8c5707ef9c4f"
           class="oracle.adf.model.portlet.binding.PortletBinding"
           xmlns="http://xmlns.oracle.com/portlet/bindings">
         <parameters>
            <parameter name="param1" pageVariable="portlet2_param1"/>
            <parameter name="param2" pageVariable="portlet2_param2"/>
         </parameters>
       </portlet>
     </executables>
     <bindings/>
   </pageDefinition>
   

5. From the File menu, select Save All.

4.4 Using Customizable Components

Customizable components are JSF components that provide the ability to customize any JSF page. By using these components, you can minimize or maximize, hide or show, or move any component on the page. You add and modify customizable components in Oracle JDeveloper through the Component Palette and Property Inspector.

• Section 4.4.1, "Adding Customizable Components"

• Section 4.4.2, "Dragging and Dropping Components onto a Page"

• Section 4.4.3, "Changing the Look and Feel of Customizable Components"

• Section 4.4.4, "Implementing Security for Customizable Components"

4.4.1 Adding Customizable Components

This section describes the steps involved in adding customizable components to the page, and including portlets and content within a PanelCustomizable or ShowDetailFrame component.

4.4.1.1 Adding a PanelCustomizable Component

To add a PanelCustomizable component to a JSF JSP (*.jspx file), perform the following steps:

1. In the Oracle JDeveloper Applications Navigator, right-click the *.jspx file, and select Open from the context menu.

   The *.jspx file is located in the Applications Navigator under:

   Applications
     <ApplicationName>
       <ProjectName>
         Web Content
   

2. In the Structure pane, select the component inside which you want to add the PanelCustomizable component.

3. In the Component Palette, select Customizable Components Core.

4. Click PanelCustomizable. The PanelCustomizable component is displayed in the Page Editor. In the Structure pane, this component is placed under the component you had selected in step 2.

5. In the Property Inspector, set the attributes for this component as required.

   Table 4-5 describes the attributes of a PanelCustomizable component.

   Table 4-5 Attributes of a PanelCustomizable Component

   Attribute	Value	Description
   General Attributes:
   Background	light/medium/dark default: light	Working in conjunction with the skin CSS, provides a means of applying a different look and feel for this PanelCustomizable instance.
   DisplayHeader	true/false default: false	Indicates whether the header of the PanelCustomizable is displayed. Note: One function of the header is to provide a place for users to interact with the customizations options a PanelCustomizable enables through the Actions menu. You can still enable these interactions when DisplayHeader is set to False by setting the isSeededInteractionAvailable property to True. This will cause the Actions menu, usually displayed on the header, to appear when the mouse moves over the component.
   ExpansionMode	maximized/minimized/normal default: normal	The default state of the PanelCustomizable. In the minimize mode, only the header is displayed. In the maximize mode, the component occupies the entire space allocated to its root parent (whichever occurs highest in the hierarchy). The root parent could be either a ShowDetailFrame or a PanelCustomizable component.
   Height	A number expressed in pixels (px) or as a percentage (%) of the available area. For example: 500px 50%	Specifies the height the PanelCustomizable should have. This attribute setting is optional. If no value is specified for this attribute, then the layout wraps to the height of the child component. Note: If you have specified DisplayHeader to be false, then it is recommended that you specify a fixed height for the component, for example 500px. If you do not set the Height attribute, then you may not be able to access the toolbar containing the Actions menu when all child components are hidden.
   Icon	Enter the URI to an image. For example: icon="coffee.png" The URI provided in this example is stored at the document root; therefore, a full path is not required. An image that is not stored at the document root requires a full path, for example: icon="c:\portal\images\box_b.gif" Or: icon="http://source-pc/images/accessability.gif"	If you decide to add an icon on the header of the PanelCustomizable component, then this specifies the path where the image for the icon is stored.
   Id	Enter a text string to use as the PanelCustomizable's unique identifier. For example: id="weather"	The unique identifier for the component on the page.
   Layout	horizontal/vertical default: vertical	Specifies whether the children of the PanelCustomizable must be laid out vertically or horizontally. If you specify vertical, then the child components are displayed one below the other and can be moved either up or down within the layout. If you choose horizontal, then the child components are displayed adjacent to each other and can be moved either to the left or right within the layout.
   Text	Enter a text string to use as the PanelCustomizable's header title. For example: text="Forecast for the Day"	A title for the PanelCustomizable component.
   Width	A number expressed in pixels (px) or as a percentage (%) of the available area. For example: 500px 50%	Specifies the width the PanelCustomizable should have. Note: If you have specified DisplayHeader to be false, then it is recommended that you specify a fixed width for the component, for example 500px. If you do not set the Width attribute, then you may not be able to access the toolbar containing the Actions menu when all child components are hidden.
   DisclosureListener	Specify a method reference of type javax.faces.el.MethodBinding.	A method reference to a disclosure listener.
   DisplayScrollbar	true/false/auto default: auto	Specifies whether scrollbars should be rendered for the PanelCustomizable content area always (true), never (false), or only when the PanelCustomizable content is larger that specified width and height (auto).
   ShortDesc	Enter a text string.	A short description of this component.
   Core Attributes:
   ContentInlineStyle	The name of a CSS style.	The CSS style to apply to the PanelCustomizable content area. Manually enter any style in compliance with CSS version 2.0 or later.
   InlineStyle	The name of a CSS style.	The CSS style to apply to the whole PanelCustomizable. Manually enter any style in compliance with CSS version 2.0 or later, or expand this node to specify style elements.
   Rendered	true/false default: true	Specifies whether the component will be rendered or not.
   StyleClass	The name of a CSS style class.	The CSS style class for this component.
   Actions Attributes:
   IsEditable	true/false default: false	Specify whether an Edit command is rendered on the Actions menu for editing the child component. Note: If you specify true, then a corresponding editAction facet must also be specified.
   IsHelpAvailable	true/false default: false	Specifies whether a Help command is rendered on the Actions menu for accessing Help on the child component. Note: If you specify true, then a corresponding helpAction facet must also be specified.
   IsMaximizable	true/false default: true	Renders a Maximize command on the PanelCustomizable's Actions menu so that the child component can take advantage of the entire PanelCustomizable area for display.
   IsMinimizable	true/false default: true	Renders a Minimize icon on the PanelCustomizable header that collapses and restores the PanelCustomizable.
   IsMovable	true/false default: true	Renders a Move command on the PanelCustomizable Actions menu.
   IsSeededInteractionAvailable	true/false default: false	Makes the PanelCustomizable's seeded interactions, Maximize, Minimize, and Move, available for exposure to users. Note: Display of each seeded interaction is controlled by its own attribute setting.
   IsShowContentEnabled	true/false default: true	Makes available a control in the Actions menu to users enabling them to show and hide the children of the PanelCustomizable.

   
   

   The Bind option available when setting these attributes enables you to bind a PanelCustomizable instance to a managed bean property.

6. Save your work.

Note:

To wrap an existing component in a PanelCustomizable component, right-click the component in the Oracle JDeveloper Structure window, select Surround With from the context menu. Select Customizable Components Core from the list in the Surround With dialog box. Select PanelCustomizable from the list of components.

4.4.1.2 Adding a ShowDetailFrame Component

To add a ShowDetailFrame component to a JSF JSP (*.jspx file), perform the following steps:

1. In the Oracle JDeveloper Applications Navigator, right-click the *.jspx file, and select Open from the context menu.

   The *.jspx file is located in the Applications Navigator under:

   Applications
     <ApplicationName>
       <ProjectName>
         Web Content
   

2. In the Structure pane, select the component inside which you want to add the ShowDetailFrame component.

3. In the Component Palette, select Customizable Components Core.

4. Click ShowDetailFrame. The ShowDetailFrame component is displayed in the Page Editor. In the Structure pane, this component is placed under the component you had selected in step 2.

5. In the Property Inspector, set the attribute values for this component as required.

   Table 4-6 describes the attributes of a ShowDetailFrame component.

   Table 4-6 Attributes of a ShowDetailFrame Component

   Attribute	Type	Description
   General Attributes:
   Background	light/medium/dark default: light	Working in conjunction with the skin CSS, provides a means of applying a different look and feel for this ShowDetailFrame instance.
   DisplayHeader	true/false default: true	Indicates whether the header of the ShowDetailFrame is displayed. Note: If you have exposed some actions on the component, and if the header display is turned off, then a toolbar is displayed when you move the mouse over the component area. The toolbar contains a drop down icon, which displays a menu of available options. This toolbar will appear only if there are actions available on the component. The toolbar display is also affected by the isSeededInteractionAvailable attribute. As the default value for isSeededInteractionAvailable is false, the toolbar is not displayed. It can be displayed by setting isSeededInteractionAvailable to true.
   ExpansionMode	maximized/minimized/normal default: normal	The default state of the ShowDetailFrame. In the minimize mode, only the header is displayed. In the maximize mode, the component occupies the entire space allocated to its root parent, which occurs highest in the hierarchy. The root parent could be either a ShowDetailFrame or a PanelCustomizable component.
   Icon	Enter the URI to an image. For example: icon="coffee.png" The URI provided in this example is stored at the document root; therefore, a full path is not required. An image that is not stored at the document root requires a full path, for example: icon="c:\portal\images\box_b.gif" Or: icon="http://source-pc/images/accessability.gif"	If you decide to add an icon on the header of the ShowDetailFrame component, then this specifies the path where the image for the icon is stored.
   Id	Enter a text string to use as the ShowDetailFrame's unique identifier. For example: id="weather"	A unique identifier for the component on the page.
   Text	Enter a text string to use as the ShowDetailFrame's header title. For example: text="Forecast for the Day"	A title for the ShowDetailFrame component.
   AttributeChangeListener	Specify a method reference of type javax.faces.el.MethodBinding.	A method reference to an attribute change listener. An event is fired when an attribute value changes.
   DisclosureListener	Specify a method reference of type javax.faces.el.MethodBinding.	A method reference to a disclosure listener. A disclosure event is fired when the disclosure state changes.
   ShortDesc	Enter a text string.	A short description of this component.
   Core Attributes:
   ContentInlineStyle	The name of a CSS style.	The CSS style to apply to the ShowDetailFrame content area. Manually enter any style in compliance with CSS version 2.0 or later.
   InlineStyle	The name of a CSS style.	The CSS style to apply to the whole ShowDetailFrame. Manually enter any style in compliance with CSS version 2.0 or later, or expand this node to specify style elements. Use the CCC styles in this attribute to set a width and height for the ShowDetailFrame, or to enable scrollbars on the ShowDetailFrame.
   Rendered	true/false default: true	Specifies whether the component will be rendered or not.
   StyleClass	The name of a CSS style class.	The CSS style class for this component.
   Actions Attributes:
   IsEditable	true/false default: false	Specify whether an Edit command is rendered on the menu for editing the child component. Note: If you specify true, then a corresponding editAction facet must also be specified.
   IsHelpAvailable	true/false default: false	Specify whether a Help command is rendered on the menu for accessing help on the child component. Note: If you specify true, then a corresponding helpAction facet must also be specified.
   IsMaximizable	true/false default: true	For ShowDetailFrame components placed inside a PanelCustomizable component, renders a Maximize command on the ShowDetailFrame's Actions menu so that the child component can take advantage of the entire PanelCustomizable area for display.
   IsMinimizable	true/false default: true	Renders a Minimize icon on the ShowDetailFrame header that collapses and restores the ShowDetailFrame.
   IsMovable	true/false default: true	For ShowDetailFrame components placed inside a PanelCustomizable component, renders a Move command on the ShowDetailFrame Actions menu.
   IsSeededInteractionAvailable	true/false default: true	Makes the ShowDetailFrame's seeded interactions, Maximize, Minimize, and Move, available for exposure to users. Note: Display of each seeded interaction is controlled by its own attribute setting.

   
   

   The Bind option available when setting these attributes enables you to bind a ShowDetailFrame instance to a managed bean property.

6. Save your work.

Note:

To wrap an existing component in a ShowDetailFrame component, right-click the component in the Oracle JDeveloper Structure window, select Surround With from the context menu. Select Customizable Components Core from the list in the Surround With dialog box. Select ShowDetailFrame from the list of components.

4.4.1.3 Adding ShowDetailFrame Facets

Use ShowDetailFrame facets to define and display custom actions on the ShowDetailFrame component. Table 4-7 describes the facets that provide additional hooks to display custom actions supported by the ShowDetailFrame component.

Table 4-7 ShowDetailFrame Facets

Facet	Description
editAction	Custom edit action facet.
helpAction	Custom help action facet.
titleBarAction	Used if an action is to be associated with title of the ShowDetailFrame component.
additionalActions	Used if some additional actions are to be added to the list of actions available in the ShowDetailFrame component.

Oracle JDeveloper displays all facets available to the ShowDetailFrame component in the Structure window. However, only those that contain UI components appear activated.

To add a ShowDetailFrame facet, perform the following steps:

1. Right-click a ShowDetailFrame component in the Structure window, and select Facets - Show Detail Frame.

2. Click the arrow to the right of this option.

3. From the list of supported facets, select the facet you want to add.

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

Note:

A checkmark next to a facet name means the f:facet element for that facet is already inserted in the page, but it may or may not contain a child component.

4.4.2 Dragging and Dropping Components onto a Page

The Component Palette in the Oracle JDeveloper user interface lists all the available component tag libraries. You can select a library and drag and drop components from within that library onto a *.jspx page.

See the Oracle Application Development Framework Developer's Guide for more information about dragging and dropping components onto a page.

4.4.3 Changing the Look and Feel of Customizable Components

You can change the look and feel of all customizable components by changing the Customizable Components selector CSS definition in the skin CSS file. Different Style selectors and Icon selectors are available for skinning customizable components. See Chapter 9, "Defining and Applying Styles to Core Customizable Components" for the list of available selectors, information about Oracle ADF Faces skins, creating custom skins, and configuring an application to use a skin.

4.4.4 Implementing Security for Customizable Components

You can use PanelCustomizable and ShowDetailFrame components to perform various actions on child components, such as minimize, maximize, move, and so on. Actions on customizable components are not secured by default. It is advisable not to expose all actions to all types of users, and therefore, recommended that you define security for these components appropriately.

To implement security for actions on customizable components at various levels, see Section 10.9.2, "Customizable Components Security".

4.5 Contextually Linking Components

One way to make your WebCenter application more interactive is by linking related components such that their contents are synchronized based upon the context. For example, suppose you have two stock portlets on a page, one provides data about a stock's price while the other provides headline news items for a stock. Both portlets are based upon the stock ticker symbol, hence it would make sense that, when the ticker symbol is changed in the stock price portlet, the stock headlines portlet picks up that change and refreshes itself with headlines pertaining to the same ticker symbol.

You can implement this kind of synchronization through parameters. Table 4-8 summarizes the types of components you may tie together with this type of contextual behavior.

Table 4-8 Components You Can Synchronize

Component Initiating Parameter	Component Reading Parameter Value	Comments
Oracle ADF Faces components	Oracle ADF Faces components	For more information about linking Faces components together, see Oracle Application Development Framework Developer's Guide.
	WSRP portlets	Faces components, such as options or lists, can be used to change the displayed content of portlets.
	PDK-Java portlets	Faces components, such as options or lists, can be used to change the displayed content of portlets.
WSRP 2.0 portletsFoot 1	Oracle ADF Faces components	Standards-based portlets can pass parameters to Faces components.
	WSRP 2.0 portlets	You can pass parameters between standards-based portlets.
	PDK-Java portlets	You can pass parameters from a standards-based portlet to a PDK-Java-based portlet.
PDK-Java portlets	Oracle ADF Faces components	PDK-Java portlets can pass parameters to Faces components.
	WSRP portlets	You can pass parameters from a PDK-Java portlet to a standards-based portlet.
	PDK-Java portlets	You can pass parameters between PDK-Java-based portlets.
Oracle ADF Faces page variable/parameter	Oracle ADF Faces components	You can set parameters at the page level and have them picked up by Faces components on the page.
	WSRP portlets	Standards-based portlets can pick up page parameters.
	PDK-Java portlets	PDK-Java portlets can pick up page parameters.

^Footnote 1 Note that support for navigational parameters exists only in WSRP 2.0. WSRP 1.0 does not have support for navigational parameters.

4.5.1 Linking Portlets to Pages

If you define page variables, then portlets on that page can then read the page variables at run time and change their behavior accordingly. By having page variables that can be linked to portlet parameters, you enable any portlets on the page to adapt to the context. For example, the page could contain a customer identifier variable. Any related portlets on the page could use this value to determine what they ought to display. A customer details portlet could take this value and determine which customer's information to display.

Figure 4-3 shows a portlet that gets a customer identifier number (320) from a page parameter.

Figure 4-3 Example of Portlet with Page Parameter

Description of "Figure 4-3 Example of Portlet with Page Parameter"

How to Link Portlets to Pages

If you defined public parameters when creating your portlet, then page variables are created for them when you drop the portlet onto a page.

To see how parameters are implemented when you drop a portlet onto a page, do the following:

Note:

The scenario that follows uses OmniPortlet, but the basic principles regarding parameters and page variables would be true for any portlet.

1. Open the page by double-clicking it in the Applications Navigator. The page opens for editing and you should see its structure in the Structure pane.

2. Add an OmniPortlet portlet to the page. See Section 4.3.2, "Adding Portlets to a Page". Note that the OmniPortlet uses a PDK-Java producer and must be registered with the application. See Section 4.3.1.2, "Registering PDK-Java Portlet Producers" for more information about registering PDK-Java producers.

3. Right-click anywhere in the tree displayed in the Structure pane, and choose Go to Page Definition in the context menu. The page definition tree should now appear in the Structure pane and the page definition XML should open for editing.

4. In your page definition XML, you should see the five default OmniPortlet page variables inside the <variableIterator> tag. You should then see references to the page variables from inside of the <portlet> tag. Example 4-11 shows a sample page definition after an OmniPortlet was first dropped onto the page.

   Example 4-11 PageDef.xml File with OmniPortlet

   <?xml version="1.0" encoding="UTF-8" ?>
   <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel"
                   version="10.1.3.39.0" id="SRDemoDashboardPageDef"
                   Package="view.pageDefs">
     <parameters/>
     <executables>
       <variableIterator id="variables">
         <variable Name="portlet1_Param1" Type="java.lang.Object"/>
         <variable Name="portlet1_Param2" Type="java.lang.Object"/>
         <variable Name="portlet1_Param3" Type="java.lang.Object"/>
         <variable Name="portlet1_Param4" Type="java.lang.Object"/>
         <variable Name="portlet1_Param5" Type="java.lang.Object"/>
       </variableIterator>
       <portlet id="portlet1"
         portletInstance="/oracle/adf/portlet/OmniPortletProducer_1154018261057/
           ap/Portlet100_b0da57c9_010c_1000_8003_82235f50a408"
         class="oracle.adf.model.portlet.binding.PortletBinding"
                xmlns="http://xmlns.oracle.com/portlet/bindings">
         <parameters>
           <parameter name="Param1" pageVariable="portlet1_Param1"/>
           <parameter name="Param2" pageVariable="portlet1_Param2"/>
           <parameter name="Param3" pageVariable="portlet1_Param3"/>
           <parameter name="Param4" pageVariable="portlet1_Param4"/>
           <parameter name="Param5" pageVariable="portlet1_Param5"/>
         </parameters>
       </portlet>
     </executables>
   </pageDefinition>
   

5. In order for the page to take a parameter value through its URL, you must add a page level parameter. In the Structure pane, right-click the parameters node and select Insert inside parameters, parameter from the context menu. The Insert Parameter dialog box is displayed.

6. Enter an ID of custID and a value of ${param.customerID}. Click OK. You should now see something similar to the following in the XML of your page definition.

   <parameters>
       <parameter id="custID" value="${param.customerID}"/>
   </parameters>
   

7. Right-click your page in the Applications Navigator and choose Run from the context menu.

8. When the page appears, click Define in OmniPortlet.

9. Choose SQL and click Next.

10. In the Statement area, enter the following SELECT statement. Note the reference to Param1 in the WHERE clause.

    select * from USERS 
    where USER_ID = ##Param1##
    

11. In the Connection section, choose or create a connection to a database that contains the SRDemo schema.

12. In Portlet Parameters, enter 320 as the Default Value for Param1 and select Personalizable.

13. Click Next.

14. You do not need a filter in this case, so click Next.

15. In Header Text, enter:

    Select a customer from the Most Active Customers List to view the customer details.
    

16. Choose HTML for Layout Style and click Next.

17. Delete the default HTML in the Non-Repeating Heading Section.

18. Replace the default HTML in the Repeating Section with the following:

    <TABLE BORDER='0' WIDTH="100%">
    <TR CLASS='PortletText1'>
      <TD CLASS='PortletHeading1'>ID</TD>
      <TD>##USER_ID##</TD>
    </TR>
    <TR CLASS='PortletText1'>
      <TD CLASS='PortletHeading1'>Email</TD>
      <TD>##EMAIL##</TD>
    </TR>
    <TR CLASS='PortletText1'>
      <TD CLASS='PortletHeading1'>First Name</TD>
      <TD>##FIRST_NAME##</TD>
    </TR>
    <TR CLASS='PortletText1'>
      <TD CLASS='PortletHeading1'>Last Name</TD>
      <TD>##LAST_NAME##</TD>
    </TR>
    <TR CLASS='PortletText1'>
      <TD CLASS='PortletHeading1'>Street</TD>
      <TD>##STREET_ADDRESS##</TD>
    </TR>
    <TR CLASS='PortletText1'>
      <TD CLASS='PortletHeading1'>City</TD>
      <TD>##CITY##</TD>
    </TR>
    <TR CLASS='PortletText1'>
      <TD CLASS='PortletHeading1'>State</TD>
      <TD>##STATE_PROVINCE##</TD>
    </TR>
    

19. Leave the default Non-Repeating Footer Section as is and click Finish.

20. Return to Oracle JDeveloper and click the page variable, portlet1_Param1, in the Structure pane. Its properties should now be displayed in the Property Inspector.

21. In the Property Inspector, click next to the DefaultValue property. A button for editing the value of the property should appear. Click this Edit button.

22. In the DefaultValue dialog box, expand the ADF Bindings node and then the bindings node beneath it. You should see a binding for portlet1_Param1.

23. You can move variables into the Expression using the right arrow (>) and apply operators using the buttons. The expression you create should look something like the following:

    ${(bindings.custID == null || bindings.custID == '') ? 320 : bindings.custID }
    

24. Click OK. You should now see something similar to Example 4-12 in your page definition XML.

    Example 4-12 <variable>

    <executables>
      <variableIterator id="variables">
        <variable Name="portlet1_Param1" Type="java.lang.Object"
            DefaultValue="${(bindings.custID == null || 
            bindings.custID == '') ? 320 : bindings.custID }"/>
      </variableIterator>
    ...
    

25. Now you must set the value of the parameter to test your portlet on the page. You can set the value through a page URL. For example:

    http://pc1.com:8988/SRDemo/faces/app/management/SRDashboard.jspx?customerID=321
    

    The passing of this URL causes the page to refresh with a value for customerID of 321. The OmniPortlet on the page should be refreshed with data that reflects the changed value.

4.5.2 Linking Portlets

In many cases, it's useful to tie portlets together such that when a parameter in one portlet changes, it causes the other portlet to refresh with a new value as well. For example, Figure 4-4 illustrates two portlets. When a user clicks on the Last Name from the Most Active Customers portlet on the left, that customer's ID is provided to the Customer Details portlet on the right, which in turn refreshes with that customer's detailed data.

Figure 4-4 Example of Portlet to Portlet Communication

Description of "Figure 4-4 Example of Portlet to Portlet Communication"

How to Link Portlets

Linking portlets works in much the same fashion as linking a portlet to a page. The example in "How to Link Portlets to Pages" illustrates how a value is passed from a page parameter in the URL to a page variable, and then the page variable's value is passed into a portlet's parameter. You could easily have multiple portlets on the page that read the page variable's value in this way. Furthermore, because the page parameter can be changed from the page URL, a portlet could set the value of the page parameter and in turn the page variable, which would then affect the other portlets on the page.

4.5.3 Linking Faces Component to Portlets

A very powerful pairing of components is a Faces component with a portlet. This kind of synchronization comes in handy if you envision an interactive Faces component, such as a list or option, that relates to one or more portlets on a page. For example, suppose you have some sort of a dashboard page and you want users to be able to pick from a predefined set of choices to determine what the portlets on the page display. The Faces component (list or option selection) could pass a value to one or more portlets on the page. The portlets in turn could use this value to determine what content to display.

In Figure 4-5, the list called Volume for last is a Faces component, and the pie chart is generated by OmniPortlet. The value from the list is passed to OmniPortlet, which in turn takes the new value and refreshes itself with the updated chart.

Figure 4-5 Example of Faces Component to Portlet Communication

Description of "Figure 4-5 Example of Faces Component to Portlet Communication"

How to Link Faces Components to Portlets

To link your Faces component to a portlet, do the following:

1. Open the page by double-clicking it in the Applications Navigator. The page opens for editing and you should see its structure in the Structure pane.

2. Add the desired Faces component to the page using the Oracle JDeveloper user interface gestures. Example 4-13 illustrates a selectOneChoice created through the user interface within a ShowDetailFrame within a PanelCustomizable. The selectOneChoice provides a list called dayPicker from which a user can select the span of time (in days) over which an OmniPortlet (portlet1) pie chart will graph data. Note that in this example, the get and set functionality of the day picker was automatically created in the backing class. Setting autoSubmit to true forces the value of the variable to change whenever an item is selected from the list. Notice also how the OmniPortlet specification, which appears just below the dayPicker, references dayPicker.

   Example 4-13 selectOneChoice

   <cust:panelCustomizable text="Service Requests Volume"
                           displayHeader="false"
                           expansionMode="normal" isMovable="true"
                           isSeededInteractionAvailable="true"
                           id="panelCustomizable2" layout="horizontal">
     <cust:showDetailFrame id="showDetailFrame1"
                           text="Service Volume Distribution"
                           displayHeader="true"
                           isSeededInteractionAvailable="true">
       <af:selectOneChoice id="dayPicker" label="Volume for last"
         value="360"
         binding="#{backing_app_management_SRDashboard.SelectOneChoice}"
          autoSubmit="true">
          <af:selectItem label="1 day" value="1"/>
          <af:selectItem label="2 days" value="2"/>
          <af:selectItem label="3 days" value="3"/>
          <af:selectItem label="5 days" value="5"/>
          <af:selectItem label="10 days" value="10"/>
          <af:selectItem label="30 days" value="30"/>
          <af:selectItem label="60 days" value="60"/>
          <af:selectItem label="90 days" value="90"/>
          <af:selectItem label="180 days" value="180"/>
          <af:selectItem label="360 days" value="360"/>
       </af:selectOneChoice>
       <adfp:portlet value="#{bindings.portlet1}"
          portletType="/oracle/adf/portlet/OmniPortlet_Producer/applicationPortlets/
            Portlet100_f20eef2c_010a_1000_8003_a9fe020295ca"
          partialTriggers="dayPicker"
          displayScrollBar="False" displayHeader="False"
          isMinimizable="True"
          renderPortletInIFrame="False"/>
     </cust:showDetailFrame>
     <adfp:portlet value="#{bindings.portlet3}"
        portletType="/oracle/adf/portlet/OmniPortlet_Producer/applicationPortlets/
          Portlet100_f20f676b_010a_1000_8005_a9fe020295ca"
        renderPortletInIFrame="False"/>
     <adfp:portlet value="#{bindings.portlet2}"
        portletType="/oracle/adf/portlet/OmniPortlet_Producer/applicationPortlets/
          Portlet100_f20f50cc_010a_1000_8004_a9fe020295ca"
        renderPortletInIFrame="False"/>
   </cust:panelCustomizable>
   

3. Once you have set up the Faces component and referenced it from the desired portlet on the page, you must add the parameter to the page definition. Right-click the JSP root in the Structure pane and choose Go to Page Definition in the context menu. The page definition XML opens for editing.

4. In the <executables> section, you must specify the parameter to be passed from dayPicker to portlet1. Example 4-14 illustrates the default code in the page definition.

   Example 4-14 portlet1 Parameters

   <executables>
   <variableIterator id="variables">
      <variable Name="OmniPortlet2_1_Param1" Type="java.lang.Object"
      DefaultValue="<parameter name="Param1" value="${(backing_app_management_
      SRDashboard.dayPicker.value == null) ? 360 : backing_app_management_
      SRDashboard.dayPicker.value}"/>
      <variable Name="OmniPortlet2_1_Param2" Type="java.lang.Object"/>
      <variable Name="OmniPortlet2_1_Param3" Type="java.lang.Object"/>
      <variable Name="OmniPortlet2_1_Param4" Type="java.lang.Object"/>
      <variable Name="OmniPortlet2_1_Param5" Type="java.lang.Object"/>
   </variableIterator>