34 Consuming Portlets

This chapter describes how to add portlets to the pages of your custom WebCenter application and the options that accompany this process.

This chapter includes the following sections:

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 custom WebCenter application pages. Therefore, you should familiarize yourself with the information covered in the Oracle Fusion Middleware Web User Interface Developer's Guide for Oracle Application Development Framework before reading this chapter.

For information about creating portlets, which can then be consumed by custom WebCenter application pages, see the following chapters:

34.1 Introduction to Consuming Portlets

Oracle WebCenter Framework enables you to consume a portlet by registering its producer either with an application or with the Resource Palette from where you can add it to any application. After you register the producer, its portlets appear under the registered producer's name under the Connections node in the Application Resources panel or in the Resource Palette.

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

There are many options associated with portlet consumption. For example, you can choose to place portlets straight onto a page or nest them in an Oracle Composer component, you can adjust many attributes of the portlet tag, and you can wire portlets to each other.

34.2 Registering Portlet Producers with a Custom WebCenter Application

Before you can add a portlet to a custom WebCenter application page, you must register the portlet's producer with the application. You can register portlet producers in two ways:

  • Register the portlet producer with a specific application. Use this option if you are not likely to want to register the producer with other applications.

  • Register the portlet producer using the Resource Palette. Use this option to use the producer's portlets in multiple applications.

A portlet that is available in the Resource Palette can be added to any of your custom WebCenter applications by dropping it on the page as you would any other component. When you add a portlet from the Resource Palette, its producer gets registered with the application if you have not done so. You can drag and drop a whole producer connection from the Resource Palette into the Application Resources panel of the Application Navigator. This registers the producer with the application. Alternatively, you can right-click a producer in the Resource Palette and choose Add to Application from the context menu to register the producer with the currently open application.

JDeveloper provides wizards for registering both WSRP producers and Oracle PDK-Java producers.

Note:

If your application is source controlled, you must manually create elements in the source control system for any new files created during producer registration. Any files that are already source controlled are checked out automatically by the producer registration process.

For more information about producers, see Section 29.2.3, "Deployment Type." For information about obtaining prebuilt portlets through Oracle, see Section 3.9, "Using Integrated WLS." For information about using JDeveloper's portlet creation wizards, see Chapter 31, "Creating Portlets with the Portlet Wizard." For more information about portlets, see Chapter 29, "Overview of Portlets."

This section includes the following subsections:

34.2.1 How to Register a WSRP Portlet Producer

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. The WSRP 2.0 standard, among others, provides support for inter-portlet communication and export and import of portlet customizations. 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.

The Register WSRP Portlet Producer 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 JDeveloper either in the Application Resources panel of the Application Navigator, or in the Resource Palette, depending on where you created the connection. You can then select portlets from the producer for placement on your application (.jspx) pages.

Note:

If you are registering the PeopleSoft portlet producer, you must set the require-iframe element to true in oracle-portlet.xml, for example:
<portlet-extension>
    <portlet-name>myPortlet</portlet-name>
    <portlet-id>18</portlet-id>
    <require-iframe>true</require-iframe>
    <minimum-wsrp-version>2</minimum-wsrp-version>
  </portlet-extension>

Note:

If you are registering a producer provided by Oracle WebLogic Portal, make sure you register the WSRP 2.0 WSDL URL.

You also use the Register WSRP Portlet Producer wizard to register JSF portlets, which are portletized JSF applications or portletized ADF task flows. Once you create a portlet from a JSF application, you can deploy the portlet to a WLS instance and register the JSF portlet producer as you would register any WSRP portlet producer. The Oracle Portlet Bridge exposes JSF applications and task flows as JSR 168 portlets. For more information, see Chapter 30, "Creating Portlets with the Oracle JSF Portlet Bridge."

Note:

In the Register WSRP Portlet Producer wizard, if you click Cancel after you have clicked Finish, the registration is not canceled.

To register a WSRP portlet producer:

  1. In the Application Resources panel of the Application Navigator, right-click Connections, choose New Connection and then choose WSRP Producer.

    For other methods of invoking the wizard, such as from the Resource Palette, see Section 3.10, "Accessing Connection Wizards."

  2. In the Specify Producer Name page (Figure 34-1) of the Register WSRP Portlet Producer wizard, the Create Connection in option is set depending on how you accessed the wizard. The default selection is Application Resources if you invoked the wizard from an application, and Resource Palette if you invoked the wizard from the Resource Palette. You can change this option at this point.

    Figure 34-1 The Specify Producer Name Page (WSRP Producer)

    Description of Figure 34-1 follows
    Description of "Figure 34-1 The Specify Producer Name Page (WSRP Producer)"

  3. From the Target Project dropdown list, select the project to be configured for the WSRP producer connection.

    This should be the same project as the one in which you intend to consume the portlets.

    You can change this option only if you invoked the wizard from the Application Navigator.

  4. In the Producer Registration Name field, enter a name for the producer registration that is unique among all connections and then click Next.

  5. In the Specify Connection Details page (Figure 34-2), in the WSDL URL field, enter the producer's URL.

    The syntax varies according to your WSRP implementation, for example, the sample WSRP producer uses the following syntax:

    • 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 port to which the server is listening for HTTP requests.

    • context-root is the Web application's 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.example.com:7101/portletapp/portlets/wsrp2?WSDL
    

    You can access the producer test page through the URL:

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

    Figure 34-2 The Specify Connection Details Page (WSRP Producer)

    Description of Figure 34-2 follows
    Description of "Figure 34-2 The Specify Connection Details Page (WSRP Producer)"

  6. If the application and the producer are separated by a firewall, an HTTP proxy is needed for communication between the application and the producer. If this is the case for your application, select Use Proxy for Contacting Producer and specify the URL and port number of the proxy.

    Note:

    The proxy fields in this step default to the proxy preferences set in JDeveloper Preferences (from the main menu, choose Tools > Preferences, and then select Web Browser and Proxy).
  7. Click Next.

    The connection to the producer is tested. If there are any problems, an error message displays. You must resolve any problems before you can continue.

  8. In the Specify Additional Registration Details page (Figure 34-3), in the Default Timeout Interval (Seconds) field, enter the number of seconds to wait for the producer to respond during design time operations.

    Some producers define additional registration properties. In such cases, the properties are displayed in a table on this page of the wizard. You 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.

    Figure 34-3 The Specify Additional Registration Details Page (WSRP Producer)

    Description of Figure 34-3 follows
    Description of "Figure 34-3 The Specify Additional Registration Details Page (WSRP Producer)"

  9. If you are registering the producer in the Resource Palette, click Finish to complete the registration.

    If you are registering the producer in the Application Resources panel, and plan to request authentication whenever the producer (and consequently, its portlet) is accessed, click Next and follow the remaining steps. If you do not want to configure security, click Finish.

    If the producer declares user categories, when you click Finish, the Register WSRP Portlet Producer dialog displays. Click Yes and see Section 34.2.2, "How to Map a Producer's Declared User Categories to an Application's Defined Java EE Security Roles." Click No to decline this opportunity and complete the registration process.

  10. In the Configure Security Attributes page (Figure 34-4), from the Token Profile dropdown list, select the type of token profile to use for authentication with the WSRP producer:

    • None—No token; no WS-Security header is attached to the SOAP message.

      If you select this option, you do not want to complete the rest of the wizard. Click Finish.

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

    • SAML Token with Message Protection—SAML (Security Assertion Markup Language) Token based identity propagation with certificate based message integrity and confidentiality.

    • User Name Token without Password—A Web service consumer can supply a user name token to identify the requester by user name only to authenticate that identity to the Web service producer.

    • User Name Token with Password—A Web service consumer can supply a user name token to identify the requester by user name and password to authenticate that identity to the Web service producer.

      This token profile is used when you want to consume WSRP producers that have a different identity store. For this token profile case, ensure that you define an external application pertaining to the producer and associate this external application with the producer being registered.

    Figure 34-4 The Configure Security Attributes Page (WSRP Producer)

    Description of Figure 34-4 follows
    Description of "Figure 34-4 The Configure Security Attributes Page (WSRP Producer)"

  11. Select the configuration type:

    • Default—If you choose default, then all the default keystore attributes, that is location, password, keystore type, signature key and alias, encryption key and alias are picked up from the JPS (Java Platform Security) configuration. The value for recipient alias is used from the policy being used. The WebLogic Server where the application is deployed must be configured for WS-Security. For more information, see "Securing a WSRP Producer with WS-Security" in Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter.

    • Custom—If you select this option, then you must enter the appropriate keystore attributes in the next page of the wizard.

  12. In the Default User field, enter a user name to assert to the remote producer when the user has not authenticated to the custom 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 custom WebCenter application has not authenticated the user so the default user you specify should be a low 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.

    Note:

    If you specify a Default User, the remote producer must be set up to accept this information. This is done by setting the <strict-authentication> flag in oracle-portlet.xml to true. For more information about this flag, see Section A.3.2, "oracle-portlet.xml."

    The Default User field does not appear if you selected User Name Token with Password.

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

    This field appears only if you selected an SAML Token option from the Token Profile dropdown list, and Custom from the Configuration options. The issuer name is the attesting entity that vouches for the verification of the subject.

  14. Select Associate Producer with External Application, then select the application, if this producer must provide authentication to an external application.

    For more information, see Section 37.2.3, "Managing External Applications."

    This option is available only if you selected User Name Token with Password.

  15. Click Next.

    If you selected Default as the configuration option, then the fields on the Specify Key Store page are disabled. Click Finish to complete the registration.

    If the producer declares user categories, when you click Finish, the Register WSRP Portlet Producer dialog displays. Click Yes and see Section 34.2.2, "How to Map a Producer's Declared User Categories to an Application's Defined Java EE Security Roles." Click No to decline this opportunity and complete the registration process.

  16. In the Specify Key Store page, in the Store Path field, provide the full path to the keystore 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.

    If you are not sure of the full path, click Browse to navigate to and select the file. The selected file should be a keystore created with the Java keytool.

    Figure 34-5 The Specify Key Store Page (WSRP Producer)

    Description of Figure 34-5 follows
    Description of "Figure 34-5 The Specify Key Store Page (WSRP Producer)"

  17. In the Store Password field, provide the password to the keystore that was set when the keystore was created.

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

    If an incorrect keystore path or password is entered, then an error message appears stating that the password is invalid and must be corrected. All fields on this screen except for Store Path and Store Password are disabled until you specify the correct values.

  18. After you provide the correct keystore path and 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 dropdown list are properly populated.

  19. The Store Type value is read from the keystore and is never editable. The store type is always JKS (Java Key Store).

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

    This 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 keystore 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. Optionally, from the Encryption Key Alias dropdown list, select the encryption key alias.

    This list populates automatically when the correct password is entered in the Store Password field. The key aliases found in the specified keystore are available in the list. Select the one to be used for encryption.

  23. Optionally, in the Encryption Key Password field, specify the password for accessing the key identified by the alias specified in Encryption Key Alias.

  24. From the Recipient Alias field, select the keystore alias that is associated with the producer's certificate and then click Finish.

    This certificate is used to encrypt the message to the producer.

    This field is not displayed if you selected SAML Token with Message Integrity as the Token Profile in the Configure Security Attributes page of the wizard.

    If the producer declares user categories, when you click Finish, a dialog displays asking whether you want to map the user categories to Java EE roles. Click Yes and see Section 34.2.2, "How to Map a Producer's Declared User Categories to an Application's Defined Java EE Security Roles." Click No to decline this opportunity and complete the registration process.

34.2.2 How to Map a Producer's Declared User Categories to an Application's Defined Java EE 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. Java EE Security Roles can be specified through the custom WebCenter application's web.xml file properties.

For more information about security roles in JSR 168 portlets, see Section 37.12, "Securing Identity Propagation Through WSRP Producers with WS-Security."

This procedure continues forward from Section 34.2.1, "How to Register a WSRP Portlet Producer."

To map producer-declared user categories with application-defined Java EE security roles:

  1. After clicking Finish in the Register WSRP Portlet Producer wizard, click Yes in the resulting dialog.

  2. In the User Categories dialog (Figure 34-6), for each User Category, click the corresponding field in the J2EE Security Role column.

    The User Categories dialog is also accessible when you edit producer registration settings. For more information see Section 34.2.4, "How to Edit Portlet Producer Registration Settings."

    Figure 34-6 The User Categories Dialog

    Description of Figure 34-6 follows
    Description of "Figure 34-6 The User Categories Dialog"

  3. From the resulting list, select the security role to map to the producer user category.

  4. Click OK when all user categories are mapped.

34.2.3 How to Register an Oracle PDK-Java Portlet Producer

When you register a PDK-Java 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.

When registration is successful, the newly registered producer is displayed in JDeveloper either in the Application Resources panel of the Application Navigator, or in the Resource Palette, depending on where you created the connection. You can then select portlets from the producer for placement on your application (.jspx) page.

Note:

In the Register Oracle PDK-Java Portlet Producer wizard, if you click Cancel after you have clicked Finish, the registration is not canceled.

To register a PDK-Java portlet producer:

  1. In the Application Resources panel of the Application Navigator, right-click Connections, choose New Connection and then choose Oracle PDK-Java Producer.

    For other methods of invoking the wizard, such as from the Resource Palette, see Section 3.10, "Accessing Connection Wizards."

  2. In the Specify Producer Name page (Figure 34-7) of the Register Oracle PDK-Java Portlet Producer wizard, the Create Connection in option is set depending on how you accessed the wizard. The default selection is Application Resources if you invoked the wizard from an application, and Resource Palette if you invoked the wizard from the Resource Palette. You can change this option at this point.

    Figure 34-7 The Specify Producer Name Page (PDK-Java Producer)

    Description of Figure 34-7 follows
    Description of "Figure 34-7 The Specify Producer Name Page (PDK-Java Producer)"

  3. From the Target Project dropdown list, select the project to be configured for the PDK-Java producer connection.

    This should be the same project as the one in which you intend to consume the portlets.

    You can change this option only if you invoked the wizard from the Application Navigator.

  4. In the Producer Registration Name field, enter a name for the producer registration that is unique among all connections and then click Next.

  5. In the Specify Connection Details page (Figure 34-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.example.com:7101/myEnterprisePortlets/providers
    

    Figure 34-8 The Specify Connection Details Page (PDK-Java Producer)

    Description of Figure 34-8 follows
    Description of "Figure 34-8 The Specify Connection Details Page (PDK-Java Producer)"

  6. In the Service ID field, enter the 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://myhost:7101/myEnterprisePortlets/providers
    

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

    http://myhost:7101/myEnterprisePortlets/providers/sample
    
  7. If the application and the producer are separated by a firewall, an HTTP proxy is needed for communication between the application and the producer. If this is the case for your application, select Use Proxy for Contacting Producer and specify the URL and port number of the proxy.

    Note:

    The proxy fields in this step default to the proxy preferences set in JDeveloper Preferences (from the main menu, choose Tools > Preferences, and then select Web Browser and Proxy.)
  8. Select Associate Producer with External Application, then select the application, if this producer must provide authentication to an external application.

    For more information, see Section 37.2.3, "Managing External Applications."

    This option is available only if you invoked the wizard from the Application Navigator, as external applications are scoped to individual applications.

  9. Select Enable Producer Sessions to enable sessions between the producer and the consuming application.

    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.

    For sessionless communication between the producer and the server, deselect this option.

  10. At this point in the wizard, you can click Finish to complete the registration, using the default values for all remaining steps.

    To provide additional details, click Next and follow the remaining steps.

  11. In the Specify Additional Details page (Figure 34-9), in the Default Timeout Interval (Seconds) field, enter the number of seconds to wait for the producer to respond during design time operations.

    Figure 34-9 The Specify Additional Registration Details Page (PDK-Java Producer)

    Description of Figure 34-9 follows
    Description of "Figure 34-9 The Specify Additional Registration Details Page (PDK-Java Producer)"

  12. 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. This value for Subscriber ID is also passed every time a portlet call is made. If the producer does not see the expected value for Subscriber ID, then it might reject the registration call.

    Note:

    Editing the producer registration to change the Subscriber ID after the initial registration has no effect. To specify a different Subscriber ID, you must reregister the producer.
  13. In the Shared Key field, enter a shared key to use for producers that are set up to handle encryption and then click Finish.

    The shared key is used by the encryption algorithm to generate a message signature for message authentication. Producer registration fails 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.

34.2.4 How to Edit 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.

To edit portlet producer registration settings:

  1. Navigate to the producer in the Application Resources panel of the Application Navigator or in the Resource Palette.

  2. Right-click the producer to edit, and choose Properties.

  3. Edit the producer registration properties as required, clicking Next to step through the pages of the wizard.

    You can also go directly to a specific step by clicking the links in the navigation panel on the left side of the wizard.

    You cannot edit the Producer Registration Name.

  4. When you have changed all the necessary settings, click Finish.

  5. Editing some properties, such as the WSDL URL or URL Endpoint, requires a producer refresh. When you make such a change, a dialog displays allowing you to refresh the producer immediately, save the changes but do not refresh the producer, or return to the edit producer registration wizard. Click Yes, No, or Cancel as appropriate.

    Note:

    While you can edit the value of the WSDL URL field, you can point to a different producer only if the new producer has access to the preference store of the old producer, or if the preference store of the old producer has been migrated to that of the new producer.
  6. Click OK when the producer has been successfully refreshed, if necessary.

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

34.2.5 How to Test 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:

  1. Navigate to the producer in the Application Resources panel of the Application Navigator or in the Resource Palette.

  2. Right-click the producer to test, and choose Test Producer Connection.

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

    If the failure dialog displays, consider editing the producer registration details and retesting the producer connection. Additionally, especially if the failure dialog takes a long time to display, ensure that the producer is available. For example, if the producer is provided through the Integrated WLS, ensure that the Integrated WLS is running, and then retest the connection.

34.2.6 How to Refresh a Portlet Producer

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

Tip:

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 34.6, "Deleting Portlets from Application Pages."

To refresh a portlet producer:

  1. Navigate to the producer in the Application Resources panel of the Application Navigator or in the Resource Palette.

  2. Right-click the producer to refresh, and choose Refresh Producer Registration.

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

34.2.7 How to Delete a Portlet Producer

If you no longer want to use a particular producer with your application, you can delete the producer. For information about deleting portlets and relevant page variables, see Section 34.6, "Deleting Portlets from Application Pages."

Note:

if you delete a producer, any pages that consume portlets from that producer display an error message that the portlet is unavailable. The portlets continue to be unavailable even if you re-register the producer using the same name.

To delete a portlet producer:

  1. Navigate to the producer in the Application Resources panel of the Application Navigator or in the Resource Palette.

  2. Right-click the producer to delete, and choose Delete.

  3. In the Delete Confirmation dialog, click Yes.

34.3 Adding Portlets to a Page

Placing a portlet on a custom WebCenter application page is a simple matter of dragging the portlet from the Application Resources panel or Resource Palette and dropping it on the page.

This section includes the following subsections:

Before You Begin

Before you can place a portlet on a page, there are a few preparatory steps you must perform before you can take this simple action. These include:

  1. Creating a custom WebCenter application. For more information, see Section 3.2, "Creating a WebCenter Application."

  2. Creating an application page. For more information, see Section 3.3, "Creating WebCenter Application-Enabled Pages."

  3. Registering the portlet's producer with the application. For more information, see Section 34.2, "Registering Portlet Producers with a Custom WebCenter Application."

  4. 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 provides it. For more information, see Chapter 37, "Securing Your WebCenter Application."

  5. 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, you may be presented with a Security Alert dialog, prompting you to view the producer's certificate and add it to the list of trusted certificates. The Security Alert dialog displays 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. For more information, see Section 37.9, "Registering Custom Certificates with the Keystore."

34.3.1 How to Add a Portlet to a Page

You can add a portlet to a page by dragging and dropping it from the Application Resources panel of the Application Navigator or from the Resource Palette.

To add a portlet to a page:

  1. In the Application Navigator, open the application that contains the page (.jspx file) to which you want to add the portlet.

  2. Expand the project that contains the page.

  3. Locate the page, right-click it, and then choose Open.

    Tip:

    You can also double-click the page to open it.
  4. Under the Connections node in the Application Resources panel of the Application Navigator, or in the Resource Palette:

    • If the producer is a WSRP producer, expand the WSRP Producer node.

    • If the producer is a PDK-Java producer, expand the Oracle PDK-Java Producer node.

  5. Expand the node for the portlet producer that contains the portlet to add to the page.

    Under the selected producer, all portlets contained by that producer are listed.

  6. Drag the portlet from the producer node directly onto the page.

    You should drag the portlet onto a form on the page. If you do not, a dialog displays prompting you to create a form to contain the portlet. Select:

    • ADF Faces - Form if the page contains rich client components. This adds an af:form component to the page.

    • JSF HTML - Form if the page contains HTML components (for example, if it is an upgraded 10.1.3.2 page). This adds an h:form or tr:form component to the page, depending on the surrounding document tag.

    Do not select HTML - Form as this is not valid for portlets.

34.3.2 What Happens When You Add a Portlet to a Page

When you add a portlet to a page, a portlet tag (adfp:portlet or adfph:portlet) is added to the page source. This is the tag that represents the portlet component. This tag includes attributes that you can edit using the Property Inspector, or in the page source, to further control the behavior and appearance of the portlet. For information about these attributes, see Section 34.4, "Setting Attribute Values for the Portlet Tag."

The type of portlet tag used is determined by the following:

  • If the project is configured for rich client components alone, the adfp:portlet tag is used.

  • If the project is configured for Trinidad components alone, the adfph:portlet tag is used.

  • If the project is configured for both rich client and Trinidad components, a dialog displays where you can choose which portlet tag to use.

  • If the project is not configured for rich client or Trinidad components, the adfp:portlet tag is used and the project is automatically configured for rich client components.

This is so that the look and feel of the portlet matches that of other components on the page. For example, if you created your page as described in Section 3.3, "Creating WebCenter Application-Enabled Pages," the page is a rich client page. In this case, the portlet is added using the adfp:portlet tag.

Example 34-1 A Rich Client Page Containing a Portlet

<?xml version='1.0' encoding='US-ASCII'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
          xmlns:adfp="http://xmlns.oracle.com/adf/faces/portlet">
  <jsp:directive.page contentType="text/html;charset=US-ASCII"/>
  <f:view>
    <af:document>
      <af:form>
        <adfp:portlet value="#{bindings.Portlet11_1}"
                      id="portlet1"
                      renderPortletInIFrame="true"
                      partialTriggers="com1"/>
      </af:form>
    </af:document>
  </f:view>
</jsp:root>

If you are working with an upgraded 10.1.3.2 application or an application that contains Trinidad components, the application uses HTML components, rather than rich client components. In this case, when you drag a portlet onto a page, the adfph:portlet tag is used.

Example 34-2 A Trinidad Page Containing a Portlet

<?xml version='1.0' encoding='US-ASCII'?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page" version="2.0"
          xmlns:h="http://java.sun.com/jsf/html"
          xmlns:f="http://java.sun.com/jsf/core"
          xmlns:af="http://xmlns.oracle.com/adf/faces/rich"
          xmlns:tr="http://myfaces.apache.org/trinidad"
          xmlns:adfph="http://xmlns.oracle.com/adf/faces/portlet/html">
  <jsp:directive.page contentType="text/html;charset=US-ASCII"/>
  <f:view>
    <tr:document title="Title 1">
      <tr:form>
        <adfph:portlet value="#{bindings.Portlet12_1}"
                       id="portlet1"/>
      </tr:form>
    </tr:document>
  </f:view>
</jsp:root>

If the application page includes one or more Oracle Composer components, this may influence where the portlet is placed. For example, in the Structure panel, a portlet placed on a page with a cust:panelCustomizable tag, would be placed as illustrated in Example 34-3:

Example 34-3 Hierarchical Placement of the Portlet Tag

af:document
  af:form
   cust:panelCustomizable
     adfp:portlet

Note:

We recommend that you do not mix ADF Faces rich client components with HTML or Trinidad components on the same page. Doing so may produce unexpected results at runtime. Therefore, do not place a rich client portlet inside an Oracle Composer HTML component or an HTML portlet inside an Oracle Composer rich client component.

For information about Composer tags, see Chapter 7, "Enabling Runtime Editing of Pages Using Oracle Composer."

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.

34.3.3 What Happens at Runtime

Once you place a portlet on a page, right-click the page and choose Run. This displays the page and runs the portlet in your default browser using JDeveloper's Integrated WLS. Different portlets may require additional runtime configuration. Notably, the content of an OmniPortlet or Web Clipping portlet instance is defined at runtime. For more information about OmniPortlet, see Chapter 35, "Creating Portlets with OmniPortlet." For more information about the Web Clipping portlet, see Chapter 36, "Creating Content-Based Portlets with Web Clipping." For more information about portlets generally, see Chapter 29, "Overview of Portlets."

When running a portlet that has an Edit mode (in a custom 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, you may want to test your portlet's Edit mode without creating a complete security model for your application. For information about how to add security to enable testing of a portlet's Edit mode, see Section 37.8, "Configuring Basic Authentication for Testing Portlet Personalization."

Note:

To be able to add portlets to your page at runtime, you must add at least one portlet to that page at design time. Adding a portlet at design time ensures that the following is added to the <definitionFactories> element of the DataBindings.cpx file:
<factory nameSpace="http://xmlns.oracle.com/portlet/bindings"
className="oracle.adf.model.portlet.binding.PortletBindingDefFactoryImpl"/>
<dtfactory className="oracle.adfdtinternal.view.faces.portlet.PortletDefinitionDTFactory"/>

This entry is required to enable consumption of portlets at runtime.

When running a portlet from a producer associated with an external application, a link to update login information is displayed. Clicking the link displays a credential provisioning page for entering external application credentials. After specifying valid credentials the portlet displays content appropriately. For more information about external applications, see Section 37.2, "Working with External Applications."

34.4 Setting Attribute Values for the Portlet Tag

In the source code view of a page, each portlet is represented by an adfp:portlet tag (or adfph: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.9, "Applying Styles to Components."

The portlet tag uses many attributes, which you can set at design time either through the JDeveloper Property Inspector or in the source code as attributes of the tag.

This section includes the following subsections:

34.4.1 How to Set Attribute Values for the Portlet Tag Using the Property Inspector

The Property Inspector provides a quick and easy way to set attribute values for the portlet tag without having to edit the source code yourself.

To set attribute values for the portlet tag using the Property Inspector:

  1. In the Application Navigator, open the application that contains the page on which the portlet appears.

  2. Expand the project that contains the page.

  3. Locate the page, right-click it, and then choose Open.

    Tip:

    You can also double-click the page to open it.
  4. In the design view, select the portlet whose attributes you want to set.

  5. In the Property Inspector, click the appropriate tab and set the desired attribute.

    Repeat this step as often as required.

  6. Save your changes.

  7. To test the changes you have made, right-click the page and choose Run.

34.4.2 How to Set Attribute Values for the Portlet Tag in Source Code

If you prefer working in source code, you can set attribute values for the portlet tag directly there.

To set attribute values for the portlet tag in source code:

  1. In the Application Navigator, open the application that contains the page on which the portlet appears.

  2. Expand the project that contains the page.

  3. Locate the page, right-click it, and then choose Open.

    Tip:

    You can also double-click the page to open it.
  4. In the design view, select the portlet whose attributes you want to set.

  5. Click the Source tab. The portlet that you selected is highlighted in the source code.

  6. Make your changes directly to the source code. Example 34-4 shows an edited portlet tag.

    Example 34-4 An Edited 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"/>
    
  7. Save your changes.

  8. To test the changes you have made, right-click the page and choose Run.

34.4.3 Common Attributes of the Portlet Tag

Table 34-1 describes the common attributes of the portlet tag.

Table 34-1 Common Attributes of the Portlet Tag

Attribute Value Description

id

Text string. For example:

id="newsBrief"

The value must follow a subset of the syntax allowed in HTML:

  • Must not be a zero-length String.

  • First character must be an ASCII letter (A-Z a-z) or an underscore (_).

  • Subsequent characters must be ASCII letter or digits (a-Z a-z 0-9), underscores (_), or dashes (-).

The unique identifier of the portlet. This attribute is populated with a unique value by default when you add the portlet to a page.

title

Text string. For example:

title="Announcements"

The portlet title, which is displayed in the portlet header.

The value specified here takes precedence over any title specified elsewhere (for example, in the portlet markup).

If no value is specified here, the portlet extracts its title from the portlet markup (response).

If no value is specified either here or in the portlet markup, the portlet extracts its title from the portlet definition.

Note: Supplying a value to the title attribute at design time means that any change made to the title at runtime in Edit or Edit Defaults mode is ignored.

width

Number expressed in pixels or as a percentage of available area:

  • For pixels, enter npx, for example:

    width = 300px
    
  • For percentage, enter n%, for example:

    width = 50%
    

The width of the area to allow for portlet display.

If the actual portlet width is larger than the width value entered here, a scrollbar appears, provided displayScrollBar is set to auto or true. If displayScrollBar is set to false, and the actual portlet width exceeds the value expressed for the width attribute, the width attribute value is considered and the portlet content is truncated.

height

Number expressed in pixels, for example:

height = 300px

The height of the area to allow for portlet display.

If the actual portlet height is larger than the height value entered here, a scrollbar appears, provided displayScrollBar is set to auto or true. If displayScrollBar is set to false, and the actual portlet height exceeds the value expressed for the height attribute, the height attribute value is considered and the portlet content is truncated.

icon

URI to an image. For example:

icon="coffee.png"

In the Property Inspector, click the Property Menu icon next to the field and then choose Edit to locate and select the required image.

The value must be an absolute URI or a URI that is resolvable relative to the current page or the application context root. The URI provided in the preceding example is stored at the application context root, therefore a full path is not required.

A URI specifying the location of an image to use as an icon, displayed to the left of the portlet title in the portlet header. You can use the icon to indicate the portlet's purpose, to reinforce branding, as a content indicator, or for some other reason.

partialTriggers

One or more component IDs. For example:

partialTriggers="_id1 _id2 componentID5"

Separate component IDs with spaces.

The IDs of the components that trigger a partial update. The portlet listens on the specified trigger components. If a trigger component receives a trigger event that causes it to update in some way, this portlet also requests to be updated.


34.4.4 Appearance Attributes of the Portlet Tag

Table 34-2 describes the appearance attributes of the portlet tag.

Table 34-2 Appearance Attributes of the Portlet Tag

Attribute Value Description

expansionMode

minimized
normal

Default: normal

The default state of the portlet:

  • minimized—The portlet's default display mode is collapsed (minimized).

  • normal—The portlet's default display made is neither collapsed nor expanded to the width of the page.

allModesSharedScreen

auto
false
true

Default: auto

Whether a change in portlet mode renders the new mode on a new page, rather than the page on which the portlet resides.

  • auto—All portlet modes are displayed inline if the remote portlet is configured, through its oracle-portlet.xml, to require an inline frame (IFRAME). This ensures that Oracle Bridge portlets are displayed inline.

  • false—All portlet modes, except View (JSR 168) or Show (PDK-Java), are rendered each on their own page. This is useful for portlets such 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.

  • true—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.

renderPortletInIFrame

auto
false
true

Default: auto

Whether the portlet is rendered in an IFRAME:

  • auto—The portlet is rendered in an IFRAME if:

    - parsing of the content fails

    - a form in the content contains an input of type file

    - the remote portlet is configured, through its oracle-portlet.xml, to require an IFRAME. This ensures that Oracle JSF Portlet Bridge portlets are displayed in an IFRAME.

    For more information, see Section 34.4.12, "What You May Need to Know About IFRAMEs."

  • false—The portlet is rendered inline. HTML markup from a portlet that is not rendered in an IFRAME may interfere with other components on the Oracle ADF page.

  • true—The portlet is rendered in an IFRAME.

displayScrollBar

auto
false
true

Default: auto

Whether a scroll bar is displayed:

  • auto—Render a scroll bar if the portlet content does not fit the width and height specified.

  • false—Never render a scroll bar. If the portlet content does not fit the height and width specified, the portlet renders in its actual size.

  • true—Always render a scroll bar.

displayHeader

false
true

Default: true

Whether the portlet header is displayed:

  • false—The portlet header is not displayed. Icons and links normally displayed in the header are hidden. If isSeededInteractionAvailable is set to true, users 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.

  • true—The portlet header is displayed. Consequently, header-based icons and links are displayed.

displayShadow

false
true

Default: true

Whether to display a shadow decoration around the portlet:

  • false—Do not display a shadow decoration.

  • true—Display a shadow decoration.

rendered

false
true

Default: true

Whether the portlet is rendered.

  • false—Do not render the portlet. No output is rendered.

  • true—Render the portlet. This is the recommended setting. Setting this attribute to false causes problems when you run the page.

background

dark
light
medium

Default: medium

The style selector to apply to the skin used by the portlet:

  • dark—Apply the dark style selector to the skin.

  • light—Apply the light style selector to the skin.

  • medium—Apply the medium style selector to the skin.

This provides a way for you to apply a different look and feel to each portlet on an page.

shortDesc

Text string. For example:

shortDesc="Portlet for entering display text in place."

A short description of the portlet.

displayActions

always
onHover

Default: always

Whether seeded interactions for the portlet are shown:

  • always—Always show seeded interactions.

  • onHover—Show seeded interactions when users move the mouse over the portlet.

showMoveAction

menu
none

Default: menu

Whether to display the Move command in the portlet's Action menu:

  • menu—Display the Move command on the portlet's Action menu.

  • none—Do not display the Move command.

There is a difference in the way that the Move command behaves at design time and at runtime. For more information, see Section 34.4.11, "What You May Need to Know About Maximize, Minimize, Restore, and Move."

showRemoveAction

menu
none

Default: menu

Whether to display the Remove icon on the portlet chrome:

  • menu—Display the Remove command on the portlet's Action menu.

  • none—Do not display the Remove icon.

There is a difference in the way that the Remove icon behaves at design time and at runtime. For more information, see Section 34.4.11, "What You May Need to Know About Maximize, Minimize, Restore, and Move."

Note: This attribute is available only for the adfp:portlet tag and not for the adfph:portlet tag.

showResizer

always
never

Default: always

Whether to display the resize handle at the bottom right corner of the portlet.

  • always—Always display the resize handle.

  • never—Never display the resize handle.

Note: This attribute is available only for the adfp:portlet tag and not for the adfph:portlet tag.

showMinimizeAction

chrome
none

Default: chrome

Whether to display the Minimize icon on the portlet chrome:

  • chrome—Display the Minimize icon on the portlet chrome.

  • none—Do not display the Minimize icon.

There is a difference in the way that the Minimize icon behaves at design time and at runtime. For more information, see Section 34.4.11, "What You May Need to Know About Maximize, Minimize, Restore, and Move."


34.4.5 Behavior Attributes of the Portlet Tag

Table 34-3 describes the behavior attributes of the portlet tag.

Table 34-3 Behavior Attributes of Portlet Tag

Attribute Value Description

partialTriggers

One or more component IDs. For example:

partialTriggers="_id1 _id2 componentID5"

Separate component IDs with spaces.

The IDs of the components that trigger a partial update. The portlet listens on the specified trigger components. If a trigger component receives a trigger event that causes it to update in some way, this portlet also requests to be updated.

submitUrlParamters

false
true

Default: false

Whether parameters in portlet links that point to the page on which the portlet is placed are made available to the page:

  • false—Parameters are not made available to the page. Rather, they are available only inside the portlet initiating the request.

  • true—Parameters available on the container page.


34.4.6 Portlet Modes Attributes of the Portlet Tag

Portlet Modes 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 does not affect the portlet.

Portlet Modes attributes, described in Table 34-4, are value binding expressions that evaluate to true or false:

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

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

Table 34-4 Portlet Modes Attributes of the Portlet Tag

Attribute Value Description

isAboutModeAvailable

false
true

Default: true

Whether to render an About command on the portlet's Actions menu.

Users choose About to invoke the portlet's About mode.

isConfigModeAvailable

false
true

Default: true

Whether to render a Configure command on a JSR 168 portlet's Actions menu.

Users choose Configure to open the portlet's Configuration settings.

isCustomizeModeAvailable

false
true

Default: true

Whether to render a Customize command on the portlet's Actions menu.

Site administrators choose Customize to edit a portlet's default personalization data.

isDetailModeAvailable

false
true

Default: true

Whether to render a Details command on a PDK-Java portlet's Actions menu.

Users choose Details to open the portlet in Full Screen mode.

isHelpModeAvailable

false
true

Default: true

Whether to render a Help command on the portlet's Actions menu.

Users choose Help to open the portlet's Help page.

isPrintModeAvailable

false
true

Default: true

Whether to render a Print command on a JSR 168 portlet's Actions menu.

Users choose Print to displays a printer-friendly version of the portlet.

isNormalModeAvailable

false
true

Default: true

Whether to render a Refresh command on the portlet's Actions menu.

Users choose Refresh to redraw the portlet independent of any other content on the page (also known as a partial-page refresh).

isPersonalizeModeAvailable

false
true

Default: true

Whether to render a Personalize command on the portlet's Actions menu.

Users choose 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 37.8, "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 title attribute. Consider however that supplying a value to the title attribute at design time prevents personalization and customization of the portlet title at runtime.

isPreviewModeAvailable

false
true

Default: false

Whether to enable previewing of portlet content.

This mode has no particular application in custom WebCenter applications, but it is used in Oracle Portal's Portlet Repository, where it renders as a magnifying glass icon, which users click to preview a portlet.


34.4.7 Style Attributes of the Portlet Tag

Table 34-5 describes the style attributes of the portlet tag.

Table 34-5 Style Attributes of the Portlet Tag

Attribute Value Description

contentStyle

One or more CSS styles.

These should be in compliance with, at least, CSS 2.0 and take the following format:

contentStyle="color:rgb(255,0,255); font-family:Arial Helvetica Geneva sans-serif;font-size:large;"

The CSS style to apply to the portlet content.

Values entered here take precedence over styles specified in the inlineStyle attribute and those included in a CSS or skin on the specific portlet instance. For more information, see Understanding contentStyle and inlineStyle Properties.

inlineStyle

One or more CSS styles.

These should be in compliance with, at least, CSS 2.0 and take the following format:

inlineStyle="color:rgb(255,0,255); font-family:Arial Helvetica Geneva sans-serif;font-size:large;"

The CSS style to apply to the whole portlet.

Values entered here take precedence over styles included in a CSS or skin on the specific portlet instance. For more information, see Understanding contentStyle and inlineStyle Properties.


34.4.8 Binding Attributes of the Portlet Tag

Table 34-6 describes the binding attributes of the portlet tag.

Table 34-6 Binding Attributes of the Portlet Tag

Attribute Value Description

binding

Name of a managed bean. For example:

binding="#{frameActionsBean.Binding}"

In the Property Inspector, click the Property Menu icon next to the field and then choose Edit 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.


34.4.9 Customization Attributes of the Portlet Tag

Table 34-7 describes the customization attributes of the portlet tag.

Table 34-7 Customization Attributes of the Portlet Tag

Attribute Value Description

customizationAllowed

false
true

Default: true

Whether design time customizations of the portlet tag are allowed on this portlet.

customizationAllowedBy

Text string

The roles for which design time customizations are allowed. This attribute enables you to allow customizations, but restrict who can actually perform them.


34.4.10 Other Attributes of the Portlet Tag

Table 34-8 describes the other attributes of the portlet tag.

Table 34-8 Other Attributes of the Portlet Tag

Attribute Value Description

iframeDtd

loose
none
strict

Default: loose

Which DTD, if any, is specified in the doctype declaration that is created when portlet content is rendered inside a IFRAME:

  • none—No DTD is specified. This relaxes the restrictions on the HTML content being technically conformant HTML. Browsers usually handle such HTML acceptably, however, because some CSS style sheet from the ADF Faces page consuming the portlet is also imported into the IFRAME document, for that style sheet to work correctly, it may be necessary to declare the content conformant to the loose or strict DTDs.

  • loose—The DTD http://www.w3.org/TR/html/loose.dtd is used.

  • strict—The DTD http://www.w3.org/TR/html/strict.dtd is used


34.4.11 What You May Need to 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 Show Detail Frame and portlet components differs between design time and runtime. At design time, these actions persist in a given WLS session, but do not persist over sessions (session means the time between starting and stopping WLS). At runtime, these actions persist both during a given WLS 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 runtime, 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 34-5):

Example 34-5 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 34-6):

Example 34-6 Turning Runtime 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:

  1. Run the application page using JDeveloper's Integrated WLS.

  2. Log in as the administrator.

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

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

34.4.12 What You May Need to Know About IFRAMEs

Placing a portlet inline on a page provides a better user experience as compared to placing it in an inline frame, or IFRAME. However, at times, it may be required to include the portlet markup inside an IFRAME. Setting the renderPortletInIFrame attribute to auto causes Oracle WebCenter Framework to render the portlet in an IFRAME if:

  • The portlet is a JSF Portlet.

    When you add a JSF Portlet to your page, renderPortletInIFrame is set to true by default as ADF pages within portlets are too complex to render inline due to Javascript issues.

  • The portlet contains a file upload element.

  • The parser throws an exception as it is not able to parse the markup.

  • You have specified that the portlet must be rendered in an IFRAME.

    To ensure that the portlet is always included in an IFRAME, open the oracle-portlet.xml file and in the <portlet> section, set the <prefer-iframe> element to true.

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.

Using IFRAMEs also has accessibility implications. For more information, see Section 1.3, "Accessibility Features."

34.5 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 project in that application, or from one place on a page to another place on the same page. You can also copy a portlet from one project to another project in the same application, if the target project is configured for consuming portlets. The copies are references to the same portlet instance, so 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 and 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 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 performs any required code conversion for you automatically.

This section includes the following subsections:

34.5.1 How to Copy a Portlet and Place it 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 requirement 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:

  1. In the Application Navigator, open the application that contains the page on which the portlet to copy appears.

  2. Expand the project that contains the page.

  3. Locate the page, right-click it, and then choose Open.

    Tip:

    You can also double-click the page to open it.
  4. In the design view, select the portlet to copy.

  5. Click the Source tab. The portlet that you selected is highlighted in the source code.

  6. Copy the portlet tag (Example 34-7).

    Example 34-7 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>
    
  7. Paste the copied code fragment into the desired location of the page source.

  8. Provide a unique value for the copy's id attribute (Example 34-8).

    Example 34-8 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.
  9. 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.

    For example, if portlet1 is copied, the pasted copy becomes portet2 in the managed bean class, as shown in Example 34-9.

    Example 34-9 Creating a New Method for a Managed Bean in the Managed Bean Class

    .
    private PortletBase portlet2;
    public void setPortlet2(PortletBase portet2) {
       this.portlet2 = portlet2;
    }
    .
    public PortletBase getPortlet2() {
       return portlet2;
    }
    
  10. From the main menu, choose File > Save All.

34.5.2 How to Copy a Portlet 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 to another:

  1. In the Application Navigator, open the application that contains the page on which the portlet to copy appears.

  2. Expand the project that contains the page.

  3. Locate the page, right-click it, and then choose Open.

    Tip:

    You can also double-click the page to open it.
  4. In the design view, select the portlet to copy.

  5. Click the Source tab. The portlet that you selected is highlighted in the source code.

  6. Copy the portlet tag (Example 34-10).

    Example 34-10 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>
    
  7. Go to the application page to which to copy the portlet (the target page).

    Portlets can reside only on Oracle ADF Faces pages. If the target page does not contain Oracle ADF Faces components, then ensure that the container objects—that is, any tags the portlet tag is nested in—use Oracle ADF tags.

    If you are copying the portlet to a page in a different project, the target project must be configured for consuming portlets. To configure the project, you must register a portlet producer with the project. For information, see Section 34.2, "Registering Portlet Producers with a Custom WebCenter Application."

  8. Click the Source tab and paste the copied code fragment into the desired location of the page source.

  9. In the Application Navigator, right-click the source page (the page from which the portlet was copied), and choose Go to Page Definition.

  10. Click the Source tab and copy the portlet binding from the source page's page definition file (Example 34-11).

    Example 34-11 Code Fragment to Be Copied From a Page Definition File

    <portlet id="portlet1"
      portletInstance="/oracle/adf/portlet/pdksampleproducer_1153245/applicationPortlets/Portlet2_82d49_010c_1000_8006_82235"
     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 and the page variables linked to the portlet parameters in the copy.
  11. In the Application Navigator, right-click the target page and choose Go to Page Definition.

    If a page definition does not exist for the page, you are asked if you want to create one. Click Yes.

  12. Click the Source tab and paste the portlet binding you copied from the source (along with relevant portlet parameters and the page variables associated with those parameters).

    Paste the code between the <executables> tags. You may need to add a closing </executables> tag and ensure that the opening tag does not contain a slash (/).

  13. From the main menu, choose File > Save All.

34.6 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 and its related page variables from a page:

  1. In the Application Navigator, open the application that contains the page on which the portlet to delete appears.

  2. Expand the project that contains the page.

  3. Locate the page, right-click it, and then choose Open.

    Tip:

    You can also double-click the page to open it.
  4. In the design view, right-click the portlet to delete and choose Delete.

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

  5. If the portlet included variables, in the Application Navigator, right-click the page and choose Go to Page Definition.

  6. Click the Source tab and locate the page variables associated with the deleted portlet, and delete them from the page definition file.

    For example, if you deleted portlet1, you would also delete the highlighted variables in Example 34-12:

    Example 34-12 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>
    
  7. From the main menu, choose, select File > Save All.

34.7 Contextually Linking WSRP 2.0 Portlets

One way to make your custom 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. Table 34-9 summarizes the types of components you may tie with this type of contextual behavior.

Table 34-9 Components You Can Synchronize

Component Initiating Parameter Can Initiate Partial Page Refresh Component Reading Parameter Value Comments

Oracle ADF Faces components

Yes

Oracle ADF Faces components

For more information about linking Faces components, see Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

 

Yes

WSRP portlets

You can use Faces components, such as options or lists, to change the displayed content of portlets.

 

Yes

PDK-Java portlets

You can use Faces components, such as options or lists, to change the displayed content of portlets.

WSRP 2.0 portletsFoot 1 

Yes

Oracle ADF Faces components

Standards-based portlets can pass parameters to Faces components.

 

Yes

WSRP 2.0 portlets

You can pass parameters between standards-based portlets.

 

Yes

PDK-Java portlets

You can pass parameters from a standards-based portlet to a PDK-Java-based portlet.

PDK-Java portlets

No

Oracle ADF Faces components

PDK-Java portlets can pass parameters to Faces components.

 

No

WSRP portlets

You can pass parameters from a PDK-Java portlet to a standards-based portlet.

 

No

PDK-Java portlets

You can pass parameters between PDK-Java-based portlets.

Oracle ADF Faces page variable/parameter

N/A

Oracle ADF Faces components

You can set parameters at the page level and have them picked up by Faces components on the page.

 

N/A

WSRP portlets

Standards-based portlets can pick up page parameters.

 

N/A

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.

WSRP 2.0 introduced navigational parameters, which can be used with page variables to link portlets on the page. When your goal is to link two components where at least one is a WSRP 2.0 portlet, you can use navigational parameters alone.

With navigational parameters, you publish to page variables, and individual components can subscribe to those page variables and reflect the changes made to those values. When you want to link more than two components, such as a task flow to two or more WSRP 2.0 portlets, you can use ADFm events instead of navigational parameters. The ADFm model enables one component to accept a value, process it, and then raise an event that another component can then process. This can continue until all events in the page are raised and consumed or discarded.

Note:

An example of how to use ADFm events and navigation parameters with JSF portlets is provided in Section 30.3, "Creating JSF Portlets: Example."

This section includes the following subsections:

Before You Begin

The following examples show how to link WSRP portlets in various ways. This is illustrated using the Parameter Form Portlet and Parameter Display Portlet provided by the sample WSRP producer. The Parameter Form Portlet has three output parameters that get set when values are submitted in the form inside the portlet. The Parameter Display Portlet has three input parameters, the values of which are displayed in the portlet when they are set.

Before you begin working through the examples, you must create an application and register the sample WSRP producer.

  1. Start JDeveloper.

  2. From the main menu, choose File > New.

  3. In the New Gallery, expand General, select Applications and then WebCenter Application, and click OK.

  4. In the Name your application page of the Create WebCenter Application wizard, in the Application Name field, enter ContextualWiringApplication and then click Finish.

  5. From the main menu, choose Run > Start Server Instance.

  6. From the main menu, choose Help > WebCenter Preconfigured Server Readme.

  7. Under Preconfigured Portlet Producers, click the Sample Portlets link under WSRP Portlet Producers.

  8. In your browser, note the URL of the WSRP V2 WSDL.

  9. In the Application Resources panel of the Application Navigator, right-click Connections and choose New Connection and then WSRP Producer.

  10. In the Specify Producer Name page of the Register WSRP Portlet Producer wizard, in the Producer Registration Name field, enter MyWsrpSampleProducer and then click Next.

  11. In the Specify Connection Details page, in the WSDL URL field, enter the URL of your sample WSRP producer (as noted in step 8), and then click Next.

    For example:

    http://127.0.0.1:7101/portletapp/portlets/wsrp2?WSDL
    
  12. In the Specify Additional Registration Details page, click Finish.

If you prefer to work through these examples using your own portlets, you must ensure that you have created portlets that support parameters. For information about how to create WSRP portlets, see Section 31.2.1, "How to Create a JSR 168 Java Portlet." For more specific information about how to implement parameters in your WSRP portlets, see Section 32.1.2, "How to Implement Navigational Parameters (WSRP 2.0)."

34.7.1 How to Link Portlets With Navigational Parameters

The simplest way to link WSRP 2.0 portlets, when you simply want to link two portlets, is to use navigational parameters.

To link your WSRP 2.0 portlets using navigational parameters:

  1. In the Application Navigator, right-click the ViewController project of the ContextualWiringApplication and choose New.

  2. In the New Gallery, expand Web Tier, select JSF and then JSF page, and click OK.

  3. In the Create JSF Page dialog, in the File Name field, enter PortletsWithNavParam.jspx.

  4. Select Create as XML Document (*.jspx) and click OK.

  5. In the Component Palette, select ADF Faces from the dropdown list.

  6. From the Layout panel, drag the Panel Splitter component onto the page you just created.

  7. In the Property Inspector, for the Panel Splitter component, click or expand the Style tab and then click the Box tab.

  8. In the Width field, enter 600 and select px - Pixel from the corresponding dropdown list.

  9. Click or expand the Appearance tab, and in the SplitterPosition field, enter 300.

  10. If the Integrated WLS is not running, from the main menu, choose Run > Start Server Instance.

  11. In the Application Resources panel of the Application Navigator, under the Connections node, expand WSRP Producer and then expand MyWSRPSampleProducer.

    You should have registered the sample WSRP producer. If you have registered the producer, see the "Before You Begin" section.

  12. Drag the Parameter Form Portlet onto the first facet of the PortletsWithNavParam page.

  13. Drag the Parameter Display Portlet onto the second facet of the page.

    Adding the portlets to the page creates six page variables: three page variables for the three portlet parameters of each portlet. To link the portlets, you must make the two portlets use the same page variables for their parameters. In this example, the Parameter Display Portlet sets three page variables to the values entered. The Parameter Display Portlet then uses the values from these same page variables to determine the values of its parameters.

  14. In the Projects panel of the Application Navigator, right-click PortletsWithNavParam.jspx and choose Go to Page Definition.

  15. In the Structure panel of the Application Navigator, expand the executables node, then ParameterFormPortlet1_1, then parameters.

  16. Select each parameter in turn and, from the Property Inspector, make a note of the page variable assigned to it. This should be the same as shown in Table 34-10:

    Table 34-10 Parameter Settings for the Parameter Form Portlet

    Portlet Parameter pageVariable

    ora_wsrp_navigparam_Parameter1

    ParameterFormPortlet1_1_ora_wsrp_navigparam_Parameter1

    ora_wsrp_navigparam_Parameter2

    ParameterFormPortlet1_1_ora_wsrp_navigparam_Parameter2

    ora_wsrp_navigparam_Parameter3

    ParameterFormPortlet1_1_ora_wsrp_navigparam_Parameter3


  17. Now to make the portlet parameters for the Parameter Display Portlet point to the same page variable as the Parameter Form Portlet so that the two portlets communicate correctly.

    In the Structure panel, expand ParameterDisplayPortlet1_1, then parameters.

  18. Select each parameter in turn and, in the Property Inspector, set the pageVariable property to the same page variables as used by the Parameter Form Portlet, instead of those created for the Parameter Display Portlet. Use Table 34-11 for guidance:

    Table 34-11 Parameter Settings for the Parameter Display Portlet

    Portlet Parameter pageVariable

    ora_wsrp_navigparam_Parameter1

    ParameterFormPortlet1_1_ora_wsrp_navigparam_Parameter1

    ora_wsrp_navigparam_Parameter2

    ParameterFormPortlet1_1_ora_wsrp_navigparam_Parameter2

    ora_wsrp_navigparam_Parameter3

    ParameterFormPortlet1_1_ora_wsrp_navigparam_Parameter3


  19. Next, you must ensure that the Parameter Display Portlet refreshes itself whenever the Parameter Form Portlet is updated to display the correct values.

    In the PortletsWithNavParam page, select the Parameter Form Portlet.

  20. In the Property Inspector, click or expand the Common tab and make a note of the value in the Id field (this should be portlet1).

  21. In the PortletsWithNavParam page, select the Parameter Display Portlet.

  22. In the Property Inspector, click or expand the Common tab and in the PartialTriggers field, enter the ID of the Parameter Form Portlet that you noted earlier (portlet1).

  23. From the main menu, choose File > Save All.

  24. In the Projects panel of the Application Navigator, right-click PortletsWithNavParam.jspx and choose Run.

34.7.2 What Happens at Runtime

When you run the page, you should see one portlet that enables you to change the value of the parameters (the Parameter Form Portlet) and another that displays the value of the parameters (the Parameter Display Portlet). When you change the value of a parameter in the Parameter Form Portlet and click OK, the corresponding parameter in the Parameter Display Portlet updates automatically to display the new value (see Figure 34-10).

Figure 34-10 Portlets Linked Using Navigational Parameters

Description of Figure 34-10 follows
Description of "Figure 34-10 Portlets Linked Using Navigational Parameters"

34.7.3 How To Associate Navigational Parameters with ADFm Events

ADFm events provide a powerful way of linking many components, including WSRP 2.0 portlets. When a portlet is placed on a page, an event is raised by the portlet if the portlet has parameters. By subscribing to that event, many components can be updated when the parameters change.

The following procedure provides a simple example that shows how to update the parameters of a single portlet using ADFm events. For an example that shows how to update the parameters of several portlets, see Section 34.7.5, "How To Cascade Events Across Multiple Components."

To associate parameters with an ADFm event:

  1. In the Application Navigator, right-click the ViewController project of the ContextualWiringApplication and choose New.

    You created this application in Section 34.7.1, "How to Link Portlets With Navigational Parameters."

  2. Create a JSPX page using the instructions provided in steps 1 through 13 in Section 34.7.1, "How to Link Portlets With Navigational Parameters," setting the File Name of the page to PortletsWithAdfmEvents.jspx.

  3. In the Projects panel of the Application Navigator, right-click PortletsWithAdfmEvents.jspx and choose Go to Page Definition.

  4. In the Structure panel of the Application Navigator, right-click PortletsWithAdfmEventsPageDef and choose Edit Event Map.

  5. In the Event Map Editor dialog, click the Add a New Event Entry icon.

  6. In the Add New EventMap Entry dialog, from the Producer dropdown list, select ParameterFormPortlet2_1.

    This identifies the Parameter Form Portlet as the component that triggers the event.

  7. The Event Name field is automatically populated with the value ParameterFormPortlet2_1_Event.

  8. From the Consumer dropdown list, select ParameterDisplayPortlet2_1.

    This identifies the Parameter Display Portlet as a component that receives values when the event is triggered.

  9. In the Consumer Params table, add the parameters listed in Table 34-12 by clicking the Add Consumer Parameter icon and specifying the name and value for each parameter.

    This maps the portlet parameters in the consumer (the Parameter Display Portlet) to the payload of the event triggered by the producer (the Parameter Form Portlet).

    Table 34-12 Parameter Values

    Param Name (Consumer) Param Value (Producer)

    ora_wsrp_navigparam_Parameter1

    ${payLoad.ora_wsrp_navigparam_Parameter1}

    ora_wsrp_navigparam_Parameter2

    ${payLoad.ora_wsrp_navigparam_Parameter2}

    ora_wsrp_navigparam_Parameter3

    ${payLoad.ora_wsrp_navigparam_Parameter3}


  10. Click OK to close the Add New EventMap Entry dialog, and then OK again to close the Event Map Editor dialog.

  11. Next, you must ensure that the Parameter Display Portlet refreshes itself whenever the Parameter Form Portlet is updated to display the correct values.

    In the PortletsWithAdfmEvents page, select the Parameter Form Portlet.

  12. In the Property Inspector, click or expand the Common tab and make a note of the value in the Id field (this should be portlet1).

  13. In the PortletsWithAdfmEvents page, select the Parameter Display Portlet.

  14. In the Property Inspector, click or expand the Common tab and in the PartialTriggers field, enter the ID of the Parameter Form Portlet that you noted earlier (portlet1).

  15. From the main menu, choose File > Save All.

  16. In the Application Navigator, right-click PortletsWithAdfmEvents.jspx and choose Run.

34.7.4 What Happens at Runtime

When you run the page, you should see one portlet that enables you to change the value of the parameters (the Parameter Form Portlet) and another that displays the value of the parameters (the Parameter Display Portlet). When you change the value of a parameter in the Parameter Form Portlet and click OK, the corresponding parameter in the Parameter Display Portlet updates automatically to display the new value (see Figure 34-10).

Figure 34-11 Portlets Linked Using ADFm Events

Description of Figure 34-11 follows
Description of "Figure 34-11 Portlets Linked Using ADFm Events"

When you run the page, you should see one portlet that enables you to change the value of the parameter and another that displays the value of the parameter. When you change the value of the parameter in one portlet and click OK, the other portlet should update automatically to display the new value.

34.7.5 How To Cascade Events Across Multiple Components

The main advantage of associating your navigational parameters with ADFm events is the capability to cascade the events across many components. In this way, you can link many more components than you could with just navigational parameters alone.

To cascade events across multiple components

  1. In the Application Navigator, right-click the ViewController project of the ContextualWiringApplication and choose New.

    You created this application in Section 34.7.1, "How to Link Portlets With Navigational Parameters."

  2. Create a JSPX page using the instructions provided in steps 1 through 8 in Section 34.7.1, "How to Link Portlets With Navigational Parameters," setting the File Name of the page to CascadingAdfmEvents.jspx and the SplitterPosition to 200.

  3. In the Layout panel of the Component Palette, drag a second Panel Splitter component onto the second facet of the page.

    Your page should now look something like Figure 34-12:

    Figure 34-12 Page Layout for Cascading ADFm Events Example

    Description of Figure 34-12 follows
    Description of "Figure 34-12 Page Layout for Cascading ADFm Events Example"

  4. If the Integrated WLS is not running, from the main menu, choose Run > Start Server Instance.

  5. In the Application Resources panel of the Application Navigator, under the Connections node, expand WSRP Producer and then expand MyWSRPSampleProducer.

    You should have registered the sample WSRP producer. If you have registered the producer, see the "Before You Begin" section.

  6. Drag the Parameter Form Portlet onto the leftmost first facet of the PortletsWithNavParam page.

  7. Drag the Parameter Display Portlet onto the other first facet of the page.

  8. Drag another Parameter Display Portlet onto the second facet of the page.

  9. In the Projects panel of the Application Navigator, right-click CascadingAdfmEvents.jspx and choose Go to Page Definition.

  10. In the Structure panel of the Application Navigator, right-click CascadingAdfmEventsPageDef and choose Edit Event Map.

  11. In the Event Map Editor dialog, click the Add a New Event Entry icon.

  12. In the Add New EventMap Entry dialog, from the Producer dropdown list, select ParameterFormPortlet3_1.

    This identifies the Parameter Form Portlet as the component that triggers the event.

  13. The Event Name field is automatically populated with the value ParameterFormPortlet3_1_Event.

  14. From the Consumer dropdown list, select ParameterDisplayPortlet3_1.

    This identifies the first Parameter Display Portlet as a component that receives values when the event is triggered.

  15. In the Consumer Params table, add the parameters listed in Table 34-13 by clicking the Add Consumer Parameter icon and specifying the name and value for each parameter.

    This maps the portlet parameters in the consumer (the Parameter Display Portlet) to the payload of the event triggered by the producer (the Parameter Form Portlet).

    Table 34-13 Parameter Values

    Param Name (Consumer) Param Value (Producer)

    ora_wsrp_navigparam_Parameter1

    ${payLoad.ora_wsrp_navigparam_Parameter1}

    ora_wsrp_navigparam_Parameter2

    ${payLoad.ora_wsrp_navigparam_Parameter2}

    ora_wsrp_navigparam_Parameter3

    ${payLoad.ora_wsrp_navigparam_Parameter3}


  16. Click OK to close the Add New EventMap Entry dialog.

  17. In the Event Map Editor dialog, click the Add a New Event Entry icon.

  18. In the Add New EventMap Entry dialog, from the Producer dropdown list, select ParameterDisplayPortlet3_1.

    This identifies the first Parameter Display Portlet as the component that triggers the event.

  19. The Event Name field is automatically populated with the value ParameterDisplayPortlet3_1_Event.

  20. From the Consumer dropdown list, select ParameterDisplayPortlet4_1.

    This identifies the second Parameter Display Portlet as a component that receives values when the event is triggered.

  21. In the Consumer Params table, add the parameters listed in Table 34-14 by clicking the Add Consumer Parameter icon and specifying the name and value for each parameter.

    This maps the portlet parameters in the consumer (the Parameter Display Portlet) to the payload of the event triggered by the producer (the Parameter Form Portlet).

    Table 34-14 Parameter Values

    Param Name (Consumer) Param Value (Producer)

    ora_wsrp_navigparam_Parameter1

    ${payLoad.ora_wsrp_navigparam_Parameter1}

    ora_wsrp_navigparam_Parameter2

    ${payLoad.ora_wsrp_navigparam_Parameter2}

    ora_wsrp_navigparam_Parameter3

    ${payLoad.ora_wsrp_navigparam_Parameter3}


  22. Click OK to close the Add New EventMap Entry dialog, and then OK again to close the Event Map Editor dialog.

  23. Next, you must ensure that the portlets refreshes themselves to display the correct values.

    In the CascadingAdfmEvents page, select the Parameter Form Portlet.

  24. In the Property Inspector, click or expand the Common tab and make a note of the value in the Id field (this should be portlet1).

  25. In the CascadingAdfmEvents page, select the first Parameter Display Portlet.

  26. In the Property Inspector, click or expand the Common tab and in the PartialTriggers field, enter the ID of the Parameter Form Portlet that you noted earlier (portlet1).

  27. Make a note of the value in the Id field (this should be portlet2).

  28. In the CascadingAdfmEvents page, select the second Parameter Display Portlet.

  29. In the Property Inspector, click or expand the Common tab and in the PartialTriggers field, enter the ID of the first Parameter Display Portlet that you noted earlier (portlet2).

  30. From the main menu, choose File > Save All.

  31. In the Application Navigator, right-click CascadingAdfmEvents.jspx and choose Run.

34.7.6 What Happens at Runtime

When you run the page, you should see one portlet that enables you to change the value of the parameters (the Parameter Form Portlet) and two that display the values of the parameters (the two Parameter Display Portlets). When you change the value of a parameter in the Parameter Form Portlet and click OK, an event is raised and the values from the parameters are sent as the payload to the first Parameter Display Portlet, which updates automatically to display the new value (see Figure 34-13). This then triggers an event in the first Parameter Display Portlet, which in turn provides a payload for the second Parameter Display Portlet.

In our example, the first Parameter Display Portlet does not perform any processing on the parameters, so the values in the second Parameter Display Portlet are the same. However, the advantage of using ADFm events over the simpler navigational parameters method is that the first Parameter Display Portlet could perform some processing on the parameter values and then pass the updated values to the second Parameter Display Portlet.

Figure 34-13 Cascading ADFm Events

Description of Figure 34-13 follows
Description of "Figure 34-13 Cascading ADFm Events"