Oracle® WebCenter Framework Developer's Guide 10g (10.1.3.2.0) Part Number B31074-05 |
|
|
View PDF |
This chapter explains how to add components to the pages of your WebCenter application. Note that this chapter does not cover Oracle JDeveloper or Oracle ADF page creation basics. It covers only those aspects of page creation that are specific to WebCenter application pages. Therefore, you must familiarize yourself with the information covered inOracle Application Development Framework Developer's Guide before reading this chapter.
Oracle WebCenter Framework provides functionality for placing a wide variety of content on an application page. Content types include portlets, customizable components, and content integration tools. Optionally, you can enable customization of these components to make the application more flexible. Oracle WebCenter Framework also provides for the linking of these components so that they operate cohesively, making the application easier to understand and use.
This section describes the Oracle WebCenter Framework components you can add to your WebCenter application pages. It includes the following subsections:
Note:
You are not limited to adding just these components to your WebCenter applications. You can add other components as well. This list encompasses only Oracle WebCenter Framework-specific components. For information about other useful components you might want to use, see Oracle Application Development Framework Developer's Guide.Oracle WebCenter Framework enables you to consume a portlet by registering its producer with an application. After you register the producer, its portlets appear on the Oracle JDeveloper Component Palette under the registered producer's name. You can drag portlets from the Component Palette and drop them onto a page as you would any other component.
Your application can consume portlets that you build as well as portlets that you receive from a third party, such as a packaged-application vendor.
Many options are associated with portlet consumption: you can choose to place portlets straight onto a page or nest them in a customizable component; you can adjust many attributes of the portlet tag (adfp:portlet
); you can wire portlets together.
This chapter provides information about consuming portlets and the options that accompany their consumption. It includes the following sections:
Note:
To learn more about creating portlets, see the following chapters:Customizable components provide the ability to control the design time at run time behavior of the application. These components enable users to manipulate their view of the content according to their requirements. For example, one user may choose to hide a certain piece of content altogether, while another moves it up to the top of the page. By adding customizable components to a page, you make the page customizable for users.
Oracle WebCenter Framework provides two core customizable components:
ShowDetailFrame
PanelCustomizable
A ShowDetailFrame
surrounds one Oracle ADF component and can provide a border and a chrome bar with menu actions, for example, to minimize the content. A ShowDetailFrame
component enables you to do the following:
Maximize or restore the display of the child component
Provide a chrome or border for the component
Provide an actions menu to perform specific actions on the child component
A PanelCustomizable
component offers horizontal and vertical layout capabilities to a group of Oracle ADF components, including customizable components. Similar to a ShowDetailFrame
component, a PanelCustomizable
component can also display a chrome to provide menu actions. A PanelCustomizable
component enables you to do the following:
Maximize or restore the display of child components
Show or hide child components
Move or rearrange child components within the PanelCustomizable
component
To leverage all features of customizable components, you can add ShowDetailFrame
and PanelCustomizable
components in the following manner:
Use a ShowDetailFrame
component to render a border or chrome around its child component and thereby provide User Interface (UI) controls to customize the display of the child component. For example, options to move, minimize, or maximize the display of content.
The placement hierarchy is as follows:
ShowDetailFrame ADF Faces component
Wrap a ShowDetailFrame
component within a PanelCustomizable
component to provide the ability to show or hide child components.
The placement hierarchy is as follows:
PanelCustomizable ShowDetailFrame Child1 ADF Faces component ShowDetailFrame Child2 ADF Faces component Portlet Portlet
Note:
Portlets provide the portlet chrome with display options similar toShowDetailFrame
components. Therefore, it is not necessary to include portlets within ShowDetailFrame
components.Use the ShowDetailFrame
tag to include a ShowDetailFrame
component on the page. A list of options, available as a list on the ShowDetailFrame
header as shown in Figure 4-1, enables users to control the display of a child component.
Figure 4-1 shows the following component placement hierarchy:
PanelCustomizable ShowDetailFrame Child1 ADF Faces component Portlet
Figure 4-1 Actions Available with a ShowDetailFrame Component
You can maximize and minimize content by using the options available under the Actions menu on the header. You can add your own UI controls to further customize the display by using facets of the cust:showDetailFrame
tag.
If you place ShowDetailFrame
components inside a PanelCustomizable
component, then in addition to maximizing and minimizing the display, you can also move the child components up and down or to the right and left.
Figure 4-2 shows the nesting of a PanelCustomizable
and a ShowDetailFrame
component with child components.
Figure 4-2 Nesting of Customizable Components
Placing Content and Portlets Inside of Customizable Components
You can include Oracle ADF Faces components as child components in your PanelCustomizable
and ShowDetailFrame
components. However, it is sufficient if you include portlets within PanelCustomizable
components only. It is not necessary to include portlets in ShowDetailFrame
components as portlets provide the portlet chrome with display options similar to ShowDetailFrame
components. You do not get any additional benefits by including portlets in ShowDetailFrame
components.
The procedure for adding child components in PanelCustomizable
and ShowDetailFrame
components is similar to adding Oracle ADF Faces components on a page. Before adding a child component, ensure that the PanelCustomizable
or ShowDetailFrame
component is selected in the Structure pane in Oracle JDeveloper. See Section 4.3.2, "Adding Portlets to a Page" for details.
Java Content Repository (JCR) data controls expose file and folder content on a page. In this way, they enable you to integrate content from a content repository into your WebCenter application. You create a data control that selects content from a particular content repository (for example, Oracle Content DB or a file system). Once the data control is created, you can drop it onto a JSP document in the desired format, for example, a table. For more information about JCR data controls and integrating content, see Chapter 5, "Integrating Content".
For detailed information about creating pages in Oracle JDeveloper with Oracle ADF, see Oracle Application Development Framework Developer's Guide. There you will find all of the information that you need on Oracle ADF Faces and building basic and complex pages. The section that follows describes some of the special requirements of WebCenter application pages.
Requirements for Pages
The following list provides rules and guidance to apply when you are creating your WebCenter application pages in Oracle JDeveloper with Oracle ADF:
Create WebCenter application pages as JSP documents (jspx
) rather than JSP pages (jsp
). In order for page customizations to be stored, the page must be represented in XML (jspx
). Hence, by choosing to create a JSP document, you ensure that customizations are always possible for the WebCenter application page.
If you are not planning to enable customization, then you could choose to create a JSP page, but this choice might cause problems if you later decide that you must enable customization.
Make sure that you have the following libraries in the Tag Libraries page of the Create JSF JSP Wizard.
ADF Portlet Components
This library is required when you plan to place portlets on application pages.
Customizable Components Core
This library is required when you plan to enable page customizations, such as the ability to move, hide, and show portlets, and to enable these customizations on any Oracle ADF component.
This section steps you through the processes of making portlets available to an application (that is, registering portlet producers), adding portlets to a page, and removing them from a page. It contains the following subsections:
For information about obtaining prebuilt portlets through Oracle, see Section 3.2, "Using the Preconfigured OC4J". For information about using Oracle JDeveloper's portlet creation wizards, see Chapter 18, "Creating Java Portlets". For more information about portlets, see Chapter 14, "Understanding Portlets".
Before you can add a portlet to a WebCenter application, you must register the portlet's producer with the application. Oracle JDeveloper provides two producer registration wizards: the WSRP Producer Registration Wizard and the PDK-Java Producer Registration Wizard. This section describes how to use these wizards. It contains the following subsections:
Note:
For additional information about producers, see Section 15.4, "Deployment Type".When you register a WSRP portlet producer, you provide basic information that describes the producer's operational parameters. This information is used by the portlet-consuming application to communicate with the producer and with the portlets through the producer.
Oracle WebCenter Framework supports both WSRP 1.0 and WSRP 2.0 producers. WSRP 2.0 support is for a preliminary (that is, preproduction) version of WSRP 2.0. Preliminary support is provided to accommodate the fact that the WSRP 2.0 standard was not finalized when Oracle WebCenter Framework was released.
This emerging standard, among others, provides support for inter-portlet communication and export or import of portlet customizations. This means that you can leverage the benefits of WSRP 2.0 while building standards-based JSR 168 portlets. To take advantage of more advanced features of WSRP 2.0, use the Oracle-specific oracle-portlet.xml
metadata extensions.
To take advantage of the benefits WSRP 2.0 provides, JSR 168 portlets exposed through WSRP 2.0 must be deployed to Oracle Container for J2EE (OC4J). Because the new version of the portlet application programming interface (API) (JSR 286) will support WSRP 2.0 capabilities, when JSR 286 becomes publicly available, vendor-specific extensions will no longer be required.
The Producer Registration Wizard is the entry point for registering both WSRP 1.0 and 2.0 producers. When registration is successful, the newly registered producer displays in Oracle JDeveloper on the Component Palette, from which you can select portlets for placement on your application (jspx
) page. Additionally, the producer is listed under the Portlet Producers node in the Applications Navigator.
To register a WSRP portlet producer, perform the following steps:
In the Applications Navigator, right-click the application under which to create the producer and select New from the context menu.
In New Gallery under Categories, expand the Web Tier node and select Portlets.
In New Gallery under Items, select WSRP Producer Registration.
Click OK.
On the Welcome page, click Next.
Optionally, before clicking Next, select Skip this Page Next Time to forgo display of the Welcome page on subsequent uses of this wizard. The Welcome page may not display if the option to skip was selected on earlier use of the wizard.
In the Name field, enter a name for the producer.
Give the producer a name that is unique among producers.
Note:
Producers given the same name display only once on the Component Palette. So, if you register two producers and give them each the name MyProducer, then the name MyProducer displays only once on the Component Palette, and both producers' portlets are listed under the one instance. This makes it difficult to determine which portlets come from which producer.If you find yourself in this situation, then consider editing one of these producers and giving it a unique name. See Section 4.3.1.3, "Editing Portlet Producer Registration Settings".
Click Next.
In the URL Endpoint field, enter the producer's URL.
The syntax will vary according to your WSRP implementation:
http://<host>:<port>/<context-root>/portlets/wsrp1?WSDL http://<host>:<port>/<context-root>/portlets/wsrp2?WSDL http://<host>:<port>/<context-root>/portlets?WSDL (WSRP 1.0 for backward compatibility)
Where:
host
is the server to which your producer has been deployed.
port
is the HTTP Listener port number.
context-root
is the context root.
portlets[/wsrp(1|2)]?WSDL
is static text. The text entered here depends on how the producer is deployed.
For example:
http://myhost:7778/MyPortletApp/porlets/wsrp2?WSDL
You can access the producer test page through the URL:
http://host:port/context-root/info
Note:
While the URL Endpoint is editable, use the edit feature only to update the host name, port, or IP address. Do not use the edit feature to point to a new producer. Switching from one producer to another (even when the portlets are identical) is not supported by the WSRP specification.If the application will use an HTTP proxy to connect to the producer, perform the following steps:
Note:
The proxy fields on this panel default to the proxy preferences set in Oracle JDeveloper Preferences (From the Tools menu, select Preferences, then select Web Browser and Proxy.)Select Use proxy for contacting the WSRP Portlet Producer.
Select this check box if the application will use an HTTP proxy in contacting the producer. The proxy is required in cases where the consumer application and the remote portlet producer are separated by a firewall and an HTTP proxy is needed for communication with the producer.
In the Proxy Host field, enter the URL of the proxy.
In the Proxy Port field, enter the port number of the proxy.
Click Next.
In the Default Execution Timeout (Seconds) field, enter the number of seconds to enable for a portlet to render in the WebCenter application before it times out.
Some producers can define additional registration properties. In such cases, the properties are displayed in a table on the wizard's Registration Details panel. Users can enter values for these additional properties in the table. These properties are producer-specific and are used only at registration time. That is, they collect information that consumer applications send to producers at registration time; the producers store this information against the consumers and use it subsequently.
At this point, you can click Finish to complete registration. Continue if you plan to require authentication whenever the producer (and consequently its portlet) is accessed, or if you plan to map user categories defined for the producer's portlets with J2EE security roles defined for the application.
Click Next.
From the Token Profile list, select the type of token profile to use for authentication with the WSRP Producer.
Choose from the following:
Username Token—A Web service consumer can supply a Username Token as a means of identifying the requestor by user name to authenticate that identity to the Web service producer.
SAML Token—SAML (Security Assertion Markup Language) is an XML-based approach for passing security tokens defining authentication and authorization rights. An attesting entity (that already has trust relationship with the receiver) vouches for the verification of the subject by method called sender-vouches.
None—No token. If None is selected, then no WS-Security header is attached to the SOAP message. In this case, the Finish button is enabled to complete producer registration.
In the Default User field, enter a user name to assert to the remote producer when the user has not authenticated to the WebCenter application.
When unauthenticated, the identity anonymous is associated with the application user. The value anonymous may be inappropriate for the remote producer, so you may need to specify an alternative identity here. Keep in mind though, that in this case, the WebCenter application has not authenticated the user so the default user you specify should be a lowly privileged user in the remote producer. If the user has authenticated to the application, then the user's identity is asserted rather than the default user.
In the Issuer Name field, enter the name of the issuer of the SAML Token, for example www.oracle.com
.
This field appears only when SAML Token is selected from the Token Profile list. The issuer name is the attesting entity vouches for the verification of the subject.
Under XML Signature, select the means by which the signing certificate is referenced within the WS-Security KeyInfo.
An XML Signature is used to digitally sign the security token and the SOAP message body to provide authenticity of the SOAP message. Use this panel to specify the means by which the signing certificate is referenced within the WS-Security KeyInfo.
Select either Binary Security Token or Subject Key Identifier.
Click Next.
In the Store Path field, provide the full path to the Key Store that contains the certificate and the private key that is used for signing some parts (security token and SOAP message body) of the SOAP message.
Optionally, click Browse to navigate to and select the file. The selected file could be a key store created with the Java keytool, or it could be an Oracle Wallet.
In the Store Password field, provide the password to the Key Store that was set when the Key Store was created.
The store password must be correct for the Store Type field and the Signature Key Alias list to populate.
If an incorrect password is entered, then an error message appears stating that the password is invalid and must be corrected. After you correct the password, press the Tab key to move to another active field (for example, the Store Path field). This ensures that the Store Type field and the Signature Key Alias list are properly populated.
The Store Type value is read from the Key Store and is never editable. Applicable values include JKS (Java Key Store) or Oracle Wallet.
From the Signature Key Alias list, select the signature key alias.
The Signature Key Alias list populates automatically when the correct password is entered in the Store Password field. The Signature Key Alias is the identifier for the certificate associated with the private key that is used for signing. The key aliases found in the specified key store are available in the list. Select the one to be used for signing.
In the Signature Key Password field, specify the password for accessing the key identified by the alias specified in Signature Key Alias.
Click Finish to complete registration of the WSRP portlet producer.
The next step depends on whether the producer being registered declares user categories:
If the producer does not declare user categories, then the registration process is complete.
If the producer declares user categories, then click Yes and see "Mapping a Producer's Declared User Categories to an Application's Defined J2EE Security Roles". Click No to decline this opportunity and complete producer registration.
Note:
Most registration settings can be edited. For example, if you decline to map the producer's user categories with J2EE security roles now, then you can reenter the wizard later and provide mapping information about the User Categories tab. For additional information, see Section 4.3.1.3, "Editing Portlet Producer Registration Settings".Mapping a Producer's Declared User Categories to an Application's Defined J2EE Security Roles
The user categories the producer declares come from the portlets it contains. For example, if the producer contains one or more JSR 168 portlets created with the Standards-based Java Portlet (JSR 168) Wizard, then any security roles added during portlet creation are included in the user categories the producer declares. J2EE Security Roles can be specified through the WebCenter application's web.xml
file properties.
This procedure continues forward from the previous procedure.
To map producer-declared user categories with application-defined J2EE security roles, perform the following steps:
In the mapping dialog box, click in the Application J2EE Security Role column.
This dialog box is accessed during producer registration, by completing registration and clicking Yes when given the option to continue with mapping (see Section 4.3.1.1). It is accessible as well when you edit producer registration settings (see Section 4.3.1.3).
From the resulting list, select the security role to map to the Producer User Category.
Repeat steps 1 and 2 for each user category.
Click OK when all user categories are mapped.
When you register an Oracle PDK-Java portlet producer, you provide basic information that describes the producer's operational parameters. This information is consumed by the WebCenter application for use in communicating with the producer and with portlets through the producer.
When registration is successful, the newly registered producer displays in Oracle JDeveloper on the Component Palette, from which you can now select portlets for placement on your application (jspx
) page. Additionally, the producer is listed under the Portlet Producers node in the Applications Navigator.
To register an Oracle PDK-Java Portlet Producer, perform the following steps:
In the Applications Navigator, right-click the application under which to create the producer and select New from the context menu.
In New Gallery under Categories, expand the Web Tier node and select Portlets.
In New Gallery under Items, select Oracle PDK-Java Producer Registration.
Click OK.
On the Welcome page, click Next.
Optionally, before clicking Next, select Skip this Page Next Time to forgo display of the Welcome page on subsequent uses of this wizard. The Welcome page may not display if the option to skip was selected on earlier use of the wizard.
In the Name field, enter a name for the producer.
Give the producer a name that is unique among producers.
Note:
Producers given the same name display only once on the Component Palette. So, if you register two producers and give them each the name MyProducer, then the name MyProducer displays only once on the Component Palette, and both producers' portlets are listed under the one instance. This makes it difficult to determine which portlets come from which producer.If you find yourself in this situation, then consider editing one of these producers and giving it a unique name. See Section 4.3.1.3, "Editing Portlet Producer Registration Settings".
Click Next.
In the URL Endpoint field, enter the producer's URL using the following syntax:
http://<host>:<port>/<context-root>/providers
Where:
host
is the server to which your producer has been deployed.
port
is the port to which the server is listening for HTTP requests.
context-root
is the Web application's context root.
providers
is static text. The text entered here depends on how the producer is deployed.
For example:
http://myHost:7778/myEnterprisePortlets/providers
In the Service ID field, enter a unique identifier for this producer.
PDK-Java enables you to deploy multiple producers under a single adapter servlet. The producers are identified by their unique service IDs. A service ID is required only when a service ID or producer name is not appended to the URL endpoint. For example the following URL endpoint requires the service ID, sample
:
http://domain.us.company.com:<port_number>/axyz/providers
However, the following URL endpoint, does not require a service ID:
http://domain.us.company.com:<port_number>/axyz/providers/sample
If the application will use an HTTP proxy to connect to the producer, perform the following steps:
Note:
The proxy fields on this panel default to the proxy preferences set in Oracle JDeveloper Preferences (From the Tools menu, select Preferences, then select Web Browser and Proxy.)Select Use proxy for contacting the PDK Portlet Producer.
Select this check box if the application will use an HTTP proxy in contacting the producer. The proxy is required in cases where the consumer application and the remote portlet producer are separated by a firewall and an HTTP proxy is needed for communication with the producer.
In the Proxy Host field, enter the URL of the proxy host.
In the Proxy Port field, enter the port number of the proxy host.
Select Associate producer with external application, then select the application, in the event this producer must provide authentication to an external application.
For more information, see Section 10.7, "Accessing External Applications Requiring Credentials".
Select Enable Producer Sessions to enable portlet producer sessions.
Use this option to enable sessions between the producer and the OC4J server. For sessionless communication between the producer and the server, do not select this option.
When sessions are enabled, the server maintains session-specific information, such as user name. Message authentication uses sessions, so if the shared key is set, then this option should also be selected.
Click Next.
In the Default Execution Timeout (Seconds) field, enter the number of seconds to enable for a portlet to render in the WebCenter application before it times out.
In the Subscriber ID field, enter a string to identify the consumer of the producer being registered.
When a producer is registered, a call is made to the producer. During the call, the consumer passes the value for Subscriber ID to the producer. If the producer does not see the expected value for Subscriber ID, then it might reject the registration call.
In the Shared Key field, enter a shared key to use for producers that are set up to handle encryption.
The shared key is used by the encryption algorithm to generate a message signature for message authentication. Note that producer registration will fail if the producer is set up with a shared key and you enter an incorrect shared key here. The shared key can contain between 10 and 20 alphanumeric characters.
Click Finish to complete registration of the PDK-Java portlet producer.
Click OK, to close the success message.
Both the WSRP and PDK-Java portlet producer registration wizards enable you to access and revise many of the values you entered when you registered the producer.
Note:
Once you have completed your edits, consider testing the producer connection to be sure connection information is valid. For more information, see Section 4.3.1.4, "Testing a Portlet Producer Connection".To edit a WSRP or Oracle PDK-Java Portlet Producer, perform the following steps:
In the Applications Navigator, navigate to the producer:
Applications <ApplicationName> Portlet Producers
Right-click the producer to be edited, and select Edit from the context menu.
Note:
You can also double-click the producer in the Applications Navigator to open the producer in edit mode.Click the tabs at the top of the wizard to bring different setting panels forward:
For information about WSRP Producer settings, see Section 4.3.1.1, "Registering WSRP Portlet Producers".
For information about PDK-Java Producer settings, see Section 4.3.1.2, "Registering PDK-Java Portlet Producers".
The connection testing feature provides a means of testing the validity of a portlet producer connection.
To test a portlet producer connection, perform the following steps:
In the Applications Navigator, navigate to the producer:
Applications <ApplicationName> Portlet Producers <ProducerName>
Right-click the producer to be edited, and select Test Producer Connection from the context menu.
A progress bar appears while the test is underway. A success or failure dialog box displays when the test is complete. Click OK to close this dialog box.
If the failure dialog box displays, then consider reediting producer registration details and retesting the producer connection. Additionally, make sure that the producer is available. For example, if the producer is provided through the preconfigured Oracle Containers for J2EE (OC4J), then make sure the preconfigured OC4J is running, and then retest the connection.
When you refresh a portlet producer, the portlets from that producer are also refreshed. This means that newly added portlets and any updates to existing portlets become available to any applications that are consuming portlets from this producer.
Note:
When a portlet is removed from a producer, be sure to manually delete the portlet from all application pages on which it has been placed. For more information, see Section 4.3.5, "Deleting Portlets from Application Pages".To refresh a WSRP or Oracle PDK-Java Portlet Producer, perform the following steps:
In the Applications Navigator, navigate to the producer:
Applications <ApplicationName> Portlet Producers
Right-click the producer to be edited, and select Refresh from the context menu.
In the Refresh Portlet Producer dialog box, click Yes.
Click OK to close the Success dialog box.
When you deregister a producer, registration data is removed on both the WebCenter application end and the remote producer end. On the application end the producer connection is deleted. On the producer end, portlet instances are deleted (though not the portlets themselves).
Though portlet instances are removed on the remote producer end, they are not also removed on the application end. Therefore, when you deregister a portlet producer, you must also remove any portlets the producer provides from your application pages. Additionally, if the portlet included parameters, then any associated page variables must be removed from any affected application page's Page Definition file.
Note:
For information about deleting portlets and relevant page variables, see Section 4.3.5, "Deleting Portlets from Application Pages".To deregister a portlet producer, perform the following steps:
In the Applications Navigator, navigate to the producer:
Applications <ApplicationName> Portlet Producers <producer_name>
Right-click the producer to be deregistered, and select Deregister from the context menu.
In the Portlet Producer Deregister dialog box, click Yes.
Instead of the Portlet Producer Deregister dialog box, you may see a Connection Error dialog box. This dialog displays when a connection cannot be made to the producer.
Connection failure can occur when the producer is not available or the producer's connection details are incorrectly specified in the WebCenter application. Your options are to click Yes or No:
Click Yes to continue with deregistration. When you click Yes, registration data is removed on the WebCenter application end but remains untouched on the remote producer end.
Click No to cancel deregistration. Should you cancel, you can try again after verifying that the producer is available and the connection details are valid in the Producer Registration wizard (see Section 4.3.1.3, "Editing Portlet Producer Registration Settings").
Click OK to close the resulting success message.
Placing a portlet on a WebCenter application page is a simple matter of dragging-and-dropping, though there are a few preparatory steps you must take before you can take this simple action. These include, creating a WebCenter application (see Section 3.1, "Creating a WebCenter Application"), creating an application page (see Section 4.2, "Building WebCenter Application-Enabled Pages in Oracle JDeveloper with Oracle ADF"), and registering the portlet's producer with the application (see Section 4.3.1, "Registering Portlet Producers").
Note:
For information about portlet parameters, see Section 4.5, "Contextually Linking Components".When you examine the source of the application page on which you have placed a portlet, you will see an adfp:portlet
tag. This is the tag that binds the portlet to the page. It carries with it a string of attributes you can revise to further control the behavior and appearance of the portlet. For more information, see Section 4.3.3, "Setting Attribute Values for the adfp:portlet Tag".
Note:
Some of the portlets you plan to consume may come from applications that handle their own authentication. In such cases, you must register the application as an external application and identify it to the portlet producer that will provide it. For more information, see Chapter 10, "Securing Your WebCenter Application".Some of the portlets you plan to consume may come from producers that are Secure Sockets Layer (SSL) enabled. When you try to access an SSL-enabled producer, a Security Alert dialog box may pop up, prompting you to view the producer's security certificate and add it to the list of trusted certificates. The Security Alert dialog box is displayed only if the producer uses a security certificate issued by a certificate authority that is not widely accepted. To consume portlets from such a producer, you must first add the producer's security certificate to the keystore. See Section 10.8, "Registering Custom Certificates with the Keystore" for the steps to be performed.
To add a portlet to a page, perform the following steps:
In the Applications Navigator, right-click the application page (jspx
file) to which you will add the portlet, and select Open from the context menu.
You can find the jspx
file at the following location in the Applications Navigator:
Applications <ApplicationName> <ProjectName> Web Content <ApplicationPage>.jspx
In the Component Palette, select the portlet producer that contains the portlet you will add to the application page.
Under the selected producer, the Component Palette lists all portlets contained by that producer.
Select a portlet, and drag it over the h:form
element in the Oracle JDeveloper Structure pane.
Alternatively, drag the portlet from the Component Palette directly onto the page in the editor.
The portlet should be nested somewhere in an h:form
element. It need not necessarily be directly wrapped in h:form
tags. If you add the component outside an h:form
element, then Oracle JDeveloper asks whether you want the form element to wrapped around it. Select this option.
If the application page includes one or more core customizable components, then this may influence where the portlet is placed. For example, in the Structure pane, a portlet placed on a page with a cust:panelCustomizable
tag, would be placed as illustrated in Example 4-1:
Example 4-1 Hierarchical Placement of the adfp:portlet Tag
h:form cust:panelCustomizable adfp:portlet
For information about the core customizable tags, cust:panelCustomizable
and cust:showDetailFrame
, see Section 4.4, "Using Customizable Components".
When you add a portlet to a page, an adfp:portlet
tag is added to the page source. The adfp:portlet
tag includes a number of attributes accessible through the Oracle JDeveloper Property Inspector. For information about attributes of the adfp:portlet
tag, see Section 4.3.3, "Setting Attribute Values for the adfp:portlet Tag".
Note:
When you drop an instance of OmniPortlet onto your page, open the Property Inspector and ensure that the AllModesSharedScreen, under the Display Mode category, is set tofalse
, the default value. Setting this property to true
may prevent you from editing certain sections of your OmniPortlet in the OmniPortlet wizard.Once you place a portlet on a page, right-click the page and select Run from the context menu. This displays the page and runs the portlet in your default browser using Oracle JDeveloper's embedded OC4J. Different portlets may require additional run time configuration. Notably, the content of an OmniPortlet or Web Clipping portlet instance is defined at run time. For more information about OmniPortlet, see Chapter 16, "Creating Portlets with OmniPortlet". For more information about the Web Clipping portlet, see Chapter 17, "Creating Content-Based Portlets with Web Clipping". For more information about portlets generally, see Chapter 14, "Understanding Portlets" and Chapter 15, "Portlet Technologies Matrix".
When running a portlet that has an Edit mode (in a WebCenter application, this renders as a Personalize command on the portlet's Actions menu), the Personalize option displays in the portlet's Actions menu only to authenticated users (that is, users who have logged in). Anonymous or public users do not see the option to personalize the portlet. Some form of security must be implemented for the portlet-consuming application before users can personalize their view of a portlet. If you are a developer creating portlets and pages, then you may want to test your portlet's Edit mode without creating a complete security model for your application. See Section 10.6, "Configuring Basic Authentication for Testing Portlet Personalization" for an explanation of how to add security to enable testing of portlet personalization (that is, for testing your portlet's Edit mode).
On application source pages, each portlet is represented by an adfp:portlet
tag, which includes a set of required and optional attributes. Required attributes, value
and portletType
, are provided automatically by the framework, and must not be altered. Optional attribute values are relevant when support for the attribute is built into the portlet. For example, you can set isAboutModeAvailable
to true
, but if no About mode has been defined for the portlet, then the attribute setting does not affect the portlet.
Portlets also support a set of style-related attributes, which are discussed more fully in Section 9.4, "Defining Styles Through the Property Inspector".
Set attribute values at design time either through the Oracle JDeveloper Property Inspector or in the source as attributes of the adfp:portlet
tag, shown in Example 4-2.
Example 4-2 adfp:portlet Tag
<adfp:portlet value="#{bindings.portlet1}" portletType="/oracle/adf/portlet/WsrpPortletProducer1/applicationPortlets/ E0default_b452f828_010a_1000_8002_82235f57eaa8" allModesSharedScreen="true" isMaximizable="true" isMinimizable="true"/>
The adfp:portlet
tag uses four types of attributes, which this section lists and describes. It contains the following subsections:
Section 4.3.3.1, "General Attributes of the adfp:portlet Tag"
Section 4.3.3.2, "Actions Attributes of the adfp:portlet Tag"
Section 4.3.3.5, "Display Mode Attributes of the adfp:portlet Tag"
Table 4-1 describes the general attributes of the adfp:portlet tag.
Table 4-1 General Attributes of the adfp:portlet Tag
Attribute | Value | Description |
---|---|---|
A number expressed in pixels or as a percentage of the available area:
|
The height of area to enable for portlet display. If the actual portlet height is larger than the |
|
The URI to an image. For example: icon="coffee.png" In Oracle JDeveloper, click the Edit icon in the value column to locate and select the required image. The URI provided in this example is stored at the document root; therefore, a full path is not required. An image that is not stored at the document root requires a full path, for example: icon="C:\portal\images\box_b.gif" Or: icon="http://source-pc/imgs/art.gif" |
A URI specifying the location of an icon to display to the left of the portlet title in the portlet header. |
|
A text string to use as the portlet's unique identifier. For example: id="newsBrief" |
The unique identifier of the component. |
|
A text string to use as the portlet's header title. For example: text="Announcements …" |
The portlet header title. Use this to supply a display title on the portlet. The attribute value specified in the If no value is specified, then the portlet extracts its title from the portlet mark-up (response). If neither the Note: Supplying a value to the |
|
A number expressed in pixels or as a percentage of available area:
|
The width of the portlet. If the actual portlet width is larger than the |
|
The name of the managed bean. For example: binding="#{frameActionsBean.Binding}" In Oracle JDeveloper, click the Edit icon in the value column to select a managed bean and specify the relevant managed bean property. |
A binding reference to store the component instance. The binding reference binds an instance of the portlet to a managed bean property. Managed beans are any JavaBeans used by the application that are registered in the JSF |
|
The ID of one or more components that trigger a partial update. For example: partialTriggers="_id1 componentID5" |
IDs of components that trigger a partial update. The portlet listens on the specified trigger components. If one of the trigger components receives a trigger event that causes it to update in some way, then the portlet also requests to be updated. In the |
|
This required attribute value is provided by the framework by default. |
|
|
A text string to use as a brief description of the portlet. For example: shortDesc="Portlet for entering display text in place." |
A short description of the portlet. |
|
This required attribute value is provided by default. |
The portlet gets its portlet container (producer) support from the reference to the portlet binding in the page definition. This attribute value is provided programmatically and should not be revised or removed. |
|
|
Portlet links that point to the page on which the portlet is situated force a page to submit itself rather than just reload with the link URL. By default, the parameters in this URL are not made available to the page. Rather, they are available only inside the portlet initiating the request. Setting |
Actions attributes control the rendering of mode-switching UI actions, such as entering edit mode. The ability to render a portlet in a particular mode depends on the modes supported by the portlet and the user authorization. For example, if the isCustomizeModeAvailable
attribute is set to true
, but the action is not supported in the portlet, then the attribute setting will not affect the portlet.
Actions attributes, described in Table 4-2, are value binding expressions that evaluates to true
or false
:
true
means the portlet is enabled to render in the named mode.
false
means the portlet is not enabled to render in the named mode.
Table 4-2 Actions Attributes of the adfp:portlet Tag
Attribute | Default | Description |
---|---|---|
|
In a WebCenter application, renders an About command on the portlet's Actions menu. Users select About to invoke the portlet's About mode. |
|
|
In a WebCenter application, renders a Configure command on a JSR 168 portlet's Actions menu. Users select Configure to open the portlet's Configuration settings. |
|
|
In a WebCenter application, renders a Customize command on the portlet's Actions menu. Customize mode enables site administrators to edit a portlet's default personalization data. |
|
|
In a WebCenter application, renders a Details command on the portlet's Actions menu. Users select Details to open the portlet's Details page. This attribute maps to the Show details page mode in Oracle PDK-Java portlets. It has no application in standards-based (JSR 168) Java portlets. |
|
|
In a WebCenter application, renders a Help command on the portlet's Actions menu. Users select Help to open the portlet's Help page. |
|
|
In a WebCenter application, renders a Maximize command on the portlets Actions menu. Users select Maximize to expand the portlet. When the component is maximized, the Restore command displays on the Actions menu to return the portlet to its default display mode. The Maximize option applies only to portlets placed inside a There is a difference in the way the Maximize and Restore actions work at design-time and at run time. For more information, see Section 4.3.3.3, "What You Should Know About Maximize, Minimize, Restore, and Move". |
|
|
In a WebCenter application, renders a Minimize icon on the portlet header. Users click the icon to collapse the portlet like a window shade. Users restore the portlet by clicking the icon again. There is a difference in the way the Minimize action behaves at design-time and at run time. For more information, see Section 4.3.3.3, "What You Should Know About Maximize, Minimize, Restore, and Move". |
|
|
In a WebCenter application, renders a Move command on the portlet's Actions menu. Users select the command, then the subcommand Move Up, Move Down, Move Left, or Move Right, depending on the portlet's current position related to the other portlets on the page. There is a difference in the way the Move action behaves at design-time and at run time. For more information, see Section 4.3.3.3, "What You Should Know About Maximize, Minimize, Restore, and Move". |
|
|
In a WebCenter application, renders a Refresh command on the portlet's Actions menu. Users select the Refresh command and the portlet refreshes (that is, redraws) independent of any other content on the page (also known as a partial-page refresh). |
|
|
In a WebCenter application, renders a Personalize command on the portlet's Actions menu. Users select Personalize to alter their personal view of the portlet. This mode is equivalent to the Edit mode selection in the Standards-based Java Portlet (JSR168) Wizard. The Personalize command displays on the Actions menu only to authenticated users (that is, users who are logged in). It does not display to Public or unauthenticated users. You must implement some form of application security for users to be able to personalize their portlet views. If you are a developer creating portlets, and you want to test the Personalize mode without creating a complete security model for your application, then see Section 10.6, "Configuring Basic Authentication for Testing Portlet Personalization". Note: A typical personalization setting is Portlet Title. You can set Portlet Title at design-time, by providing a value for the |
|
|
Provides a means of previewing portlet content. This mode has no particular application in WebCenter applications, but it is used in Oracle Application Server Portal's (OracleAS Portal) Portlet Repository, where it renders as a magnifying glass icon, which users click to preview a portlet. |
|
|
In a WebCenter application, renders a Print command on a JSR 168 portlet's Actions menu that displays a printer-friendly version of the portlet. |
|
|
Makes the portlet's seeded interactions, Maximize, Move, and Minimize, available for exposure to users. When the attribute is set to Custom interactions are not affected by this attribute setting. |
To accommodate the needs of the development environment, the behavior of the actions Minimize, Maximize, Restore, and Move for ShowDetailFrame
and portlet
components differs between design-time and run time. At design-time, these actions persist in a given OC4J session, but do not persist over sessions (session means the time between starting and stopping the OC4J). At run time, these actions persist both during a given OC4J session and across sessions.
This difference has been introduced to enable an automatic reset of an application page at design-time.
If persisting across sessions is not required at run time, then a simple modification to the application's web.xml
file can turn it off. Go to the following parameter setting in the application's web.xml
file (Example 4-3):
Example 4-3 Persistence Setting in the Application's web.xml File
<context-param>
<param-name>oracle.adf.view.faces.CHANGE_PERSISTENCE</param-name>
<param-value>oracle.adfinternal.view.faces.change.HybridChangeManager</param-value>
</context-param>
Replace it with the following (Example 4-4):
Example 4-4 Turning Run-Time Persistence Off in the Application's web.xml File
<context-param>
<param-name>oracle.adf.view.faces.CHANGE_PERSISTENCE</param-name>
<param-value>oracle.adf.view.faces.change.SessionChangeManager</param-value>
</context-param>
If security has been implemented on the application, then the Minimize, Maximize, Restore, and Move actions display only to users with Customize privileges. They do not display to users with Personalize privileges. Customize users can test the effect of these actions by following these steps at design-time:
Run the application page using Oracle JDeveloper's embedded OC4J.
Log-in as the administrator.
Maximize a portlet. Move portlets around. Make whatever changes you want using the relevant actions commands.
Log-out, then log-in as a user and check the effects of your actions.
Table 4-3 describes the core attributes of the adfp:portlet tag.
Table 4-3 Core Attributes of the adfp:portlet Tag
Attribute | Value | Description |
---|---|---|
The name of a CSS style For example, to turn off the portlet border, add the following to the contentInlineStyle="border-style:none;" |
The CSS style to apply to the portlet. Expand this node to specify styles for specific style elements on the specific portlet instance. Values entered here take precedence over styles included in a CSS or skin on the specific portlet instance. For more information, see Section 9.4, "Defining Styles Through the Property Inspector". |
|
The name of a CSS style |
The CSS style to apply to the portlet. Expand this node to specify styles for specific style elements on the specific portlet instance. Values entered here take precedence over styles included in a CSS or skin on the specific portlet instance. For more information, see Section 9.4, "Defining Styles Through the Property Inspector". |
|
|
Specifies whether the portlet is rendered. When set to The default value is |
Table 4-4 describes the display mode attributes of the adfp:portlet tag.
Table 4-4 Display Mode Attributes of the adfp:portlet Tag
Attribute | Value | Description |
---|---|---|
|
Determines whether a change in portlet mode renders the new mode on a new page, other than the page on which the portlet resides (
The default value is |
|
|
Provides a means of applying a different look and feel to each portlet on an application page. The default skins, Oracle, Minimal, and Simple, and custom skins include three versions of style selectors: light, medium, and dark. Depending on which value is specified for the background property, the skin will apply the relevant style or icon selector version. For more information, see Section 9.3.6, "Applying Color Schemes to Portlets and Core Customizable Components". |
|
|
Indicates whether the portlet's header is displayed.
The default value is |
|
|
The default state of the portlet. Select from:
|
|
|
Display a scrollbar if content does not fit the width and height specified ( A value of The default is |
|
|
A value binding expression that evaluates to
The default is For additional information, see Section 4.3.3.6, "iframes and form Tags". |
The HTML source generated by a JavaServer Faces page contains a form
tag. Because nested form
tags are not enabled in HTML, portlets cannot open new forms on the same page.
The best way to circumvent this issue is to render your portlets inside of an iframe
. You achieve this by setting the renderPortletInIFrame
attribute to true
or auto
. A value of true
always uses an iframe
. A value of auto
causes Oracle WebCenter Framework to detect whether the portlet contains a form
element and, if it does, then render it within an iframe
.
For example, the Upload Portlet that comes with the preconfigured OC4J's WSRP Sample Producer requires an iframe
to run correctly. If you do not place it in an iframe
by setting renderPortletInIFrame
to true
or auto
, then the portlet does not work.
Note:
If you render a portlet within aniframe
, then manipulating window.location
may give unexpected results. If your portlet uses window.location
, then you should ensure that your JavaScript is robust enough to handle the case where the portlet renders itself inside of an iframe
.Alternatively, you could rewrite your portlet such that you eliminate the form elements in the portlet's mark-up, but this approach is cumbersome and may not be feasible in all cases.
When you copy portlets, the portlets and their copies must reside within the same application. For example, you can copy a portlet from one page in an application to another page in the same application, from one place on a page to another place on the same page, or from one project to another project within the same application. The copies are references to the same portlet instance. This means customizations or personalizations made to any instance of the portlet (original or copy) affect all the other instances.
Copying a portlet is more than a matter of copying and pasting the portlet view tag. It involves copying portlet-related entries from the application page's source. It may also involve copying portlet-related entries from the page definition file as well as removing duplicate portlet binding information or creating a new method in the copied portlet's binding bean.
When a portlet is copied, the target page must be an Oracle ADF Faces page. Any preexisting code on the target page must reflect that. This is quite easy to accomplish. When Oracle JDeveloper creates a new JSF page, it contains pure JSF tags. The first time you drop an Oracle ADF Faces component onto the page, tags are automatically updated to be Oracle ADF Faces tags. For example, an <html>
tag becomes <afh:html>
, <head>
and <title="title">
tags become <afh:head title="title">
, and so on. Therefore, a simple way to ensure the conversion of the target page to an Oracle ADF Faces page is to place any Oracle ADF Faces component on the target page. This will perform any required code conversion for you automatically.
This section describes how to copy portlets from one application page to another as well as how to copy a portlet from one part of a page to another part of the same page. It includes the following subsections:
Section 4.3.4.1, "Copying and Placing a Portlet on the Same Page"
Section 4.3.4.2, "Copying Portlets from One Application Page to Another"
Because all of the page's resources are available to both portlet instances when you copy a portlet to the same page, there is no need to copy portlet-related information from the page's Page Definition file. It is just a matter of copying and pasting the portlet's view tag, and assigning a unique identifier to the copy.
To copy and place a portlet on the same page, perform the following steps:
In Oracle JDeveloper, go to the Source view of the page that hosts the portlet to be copied.
Copy the portlet tag (Example 4-5).
Example 4-5 Code Fragment to be Copied When Copying a Portlet
<f:view> <afh:html binding="#{backing_portlet_page.html1}" id="html1"> <afh:head title="portlet_page" binding="#{backing_portlet_page.head1}" id="head1"> <meta http-equiv="Content-Type" content="text/html;charset=windows-1252"/> </afh:head> <afh:body binding="#{backing_portlet_page.body1}" id="body1"> <h:form binding="#{backing_portlet_page.form1}" id="form1"> <adfp:portlet value="#{bindings.portlet1}" portletType="/oracle/adf/portlet/ pdksampleproducer_1153245807295/applicationPortlets/ Portlet2_82d49b79_010c_1000_8006_82235ffc4e2b" binding="#{backing_portlet_page.portlet1}" id="portlet1" isCustomModesAvailable="true"/> </h:form> </afh:body> </afh:html> </f:view>
Paste the copied code fragment into the page's Source view.
Provide a unique value for the copy's ID
attribute (Example 4-6).
Example 4-6 Changing the Portlet ID
<adfp:portlet value="#{bindings.portlet1}"
portletType="/oracle/adf/portlet/
pdksampleproducer_1153245807295/applicationPortlets/
Portlet2_82d49b79_010c_1000_8006_82235ffc4e2b"
binding="#{backing_portlet_page.portlet1}"
id="portlet2"
isCustomModesAvailable="true"/>
Note:
On a given page, each portlet must have a unique ID.In the page source, if the copied portlet's adfp:portlet
tag has a binding attribute, for example:
binding="#{backing_untitled2.portlet1}"
Then either remove this binding, or create a new method in the binding bean by opening the managed bean class for this managed bean and defining the new method in the faces-config.xml
file.
For example, if portlet1 is copied, and the pasted copy becomes portet2, in the faces-config.xml
file, as shown in Example 4-7.
When you copy a portlet from one page to another in an application, portlet-related code must also be copied from the source page's Page Definition file. This section describes the steps related to both copying from one application page to another and from one application project to another.
To copy a portlet from one application page or project to another, perform the following steps:
In Oracle JDeveloper, go to the Source view of the page that hosts the portlet to be copied.
Copy the portlet tag (Example 4-8).
If the target page does not contain Oracle ADF Faces components, then make sure the container objects—that is, any tags the portlet tag is nested in—use Oracle ADF tags:
Example 4-8 Source Page Code Fragment to Be Copied When Copying a Portlet
<f:view> <afh:html binding="#{backing_portlet_page.html1}" id="html1"> <afh:head title="portlet_page" binding="#{backing_portlet_page.head1}" id="head1"> <meta http-equiv="Content-Type" content="text/html;charset=windows-1252"/> </afh:head> <afh:body binding="#{backing_portlet_page.body1}" id="body1"> <h:form binding="#{backing_portlet_page.form1}" id="form1"> <adfp:portlet value="#{bindings.portlet1}" portletType="/oracle/adf/portlet/ pdksampleproducer_1153245807295/applicationPortlets/ Portlet2_82d49b79_010c_1000_8006_82235ffc4e2b" binding="#{backing_portlet_page.portlet1}" id="portlet1" isCustomModesAvailable="true"/> </h:form> </afh:body> </afh:html> </f:view>
Note:
Portlets can reside only on Oracle ADF Faces pages. See the introductory paragraph to this procedure for more information.Go to the application page to which to copy the portlet (the target page).
Paste the copied code into the target page's Source view.
Go to the page definition file of the page from which the portlet was copied (the source page).
Right-click the source page, and select Go to Page Definition from the context menu.
Copy the portlet binding from the source page's page definition file (Example 4-9).
Example 4-9 Code Fragment to Be Copied From a Page Definition File
<portlet id="portlet1" portletInstance="/oracle/adf/portlet/ pdksampleproducer_1153245807295/applicationPortlets/Portlet2_82d49b79_ 010c_1000_8006_82235ffc4e2b" class="oracle.adf.model.portlet.binding.PortletBinding" xmlns="http://xmlns.oracle.com/portlet/bindings"/>
Note:
When the portlet being copied includes parameters, be sure to include the copied portlet's portlet parameters as well as the page variables linked to the portlet parameters in the copy.Go the to page definition file of the target page.
Create a page definition file if necessary. Do this by right-clicking the target page and selecting Go to Page Definition. You will be prompted to create a page definition file if none exists.
Paste the portlet binding you copied from the source (as well as relevant portlet parameters and the page variables associated with those parameters).
When you delete a portlet from an application page, if the portlet had parameters, then you should also delete page variables associated with those parameters from the application page's Page Definition file.
To delete a portlet from a page and related page variables from a Page Definition file, perform the following steps:
In the Applications Navigator, navigate to the relevant application page (jspx
file), and open it:
Applications <ApplicationName> <ProjectName> WEB Content <ApplicationPage>.jspx
In Design view, right-click the portlet to delete and select Delete from the context menu.
This deletes the portlet from the page and the portlet binding from the page's Page Definition file.
If the portlet included variables, then right-click the jspx
file in the Editor and select Go to Page Definition from the context menu.
The page definition file opens in the Editor pane.
Locate the page variables associated with the deleted portlet, and delete them from the page definition file.
For example, if portlet1 is deleted you would delete the highlighted variables in Example 4-10:
Example 4-10 Deleting Portlet-Related Page Variables from a Page Definition File
<?xml version="1.0" encoding="UTF-8" ?> <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel" version="10.1.3.38.97" id="untitled1PageDef" Package="project1.pageDefs"> <parameters/> <executables> <variableIterator id="variables"> <variable Name="portlet1_param1" Type="java.lang.Object"/> <variable Name="portlet1_param2" Type="java.lang.Object"/> <variable Name="portlet2_param1" Type="java.lang.Object"/> <variable Name="portlet2_param2" Type="java.lang.Object"/> </variableIterator> <portlet id="portlet2" portletInstance="/oracle/adf/portlet/ PdkPortletProducer2_1154100666247/applicationPortlets/ Portlet1_b5e49696_010c_1000_8008_8c5707ef9c4f" class="oracle.adf.model.portlet.binding.PortletBinding" xmlns="http://xmlns.oracle.com/portlet/bindings"> <parameters> <parameter name="param1" pageVariable="portlet2_param1"/> <parameter name="param2" pageVariable="portlet2_param2"/> </parameters> </portlet> </executables> <bindings/> </pageDefinition>
From the File menu, select Save All.
Customizable components are JSF components that provide the ability to customize any JSF page. By using these components, you can minimize or maximize, hide or show, or move any component on the page. You add and modify customizable components in Oracle JDeveloper through the Component Palette and Property Inspector.
Section 4.4.2, "Dragging and Dropping Components onto a Page"
Section 4.4.3, "Changing the Look and Feel of Customizable Components"
Section 4.4.4, "Implementing Security for Customizable Components"
This section describes the steps involved in adding customizable components to the page, and including portlets and content within a PanelCustomizable
or ShowDetailFrame
component.
To add a PanelCustomizable
component to a JSF JSP (*.jspx
file), perform the following steps:
In the Oracle JDeveloper Applications Navigator, right-click the *.jspx
file, and select Open from the context menu.
The *.jspx
file is located in the Applications Navigator under:
Applications <ApplicationName> <ProjectName> Web Content
In the Structure pane, select the component inside which you want to add the PanelCustomizable
component.
In the Component Palette, select Customizable Components Core.
Click PanelCustomizable. The PanelCustomizable
component is displayed in the Page Editor. In the Structure pane, this component is placed under the component you had selected in step 2.
In the Property Inspector, set the attributes for this component as required.
Table 4-5 describes the attributes of a PanelCustomizable
component.
Table 4-5 Attributes of a PanelCustomizable Component
Attribute | Value | Description |
---|---|---|
General Attributes: |
||
Background |
default: |
Working in conjunction with the skin CSS, provides a means of applying a different look and feel for this |
DisplayHeader |
default: |
Indicates whether the header of the Note: One function of the header is to provide a place for users to interact with the customizations options a |
ExpansionMode |
default: |
The default state of the In the minimize mode, only the header is displayed. In the maximize mode, the component occupies the entire space allocated to its root parent (whichever occurs highest in the hierarchy). The root parent could be either a |
Height |
A number expressed in pixels (px) or as a percentage (%) of the available area. For example:
|
Specifies the height the This attribute setting is optional. If no value is specified for this attribute, then the layout wraps to the height of the child component. Note: If you have specified |
Icon |
Enter the URI to an image. For example: icon="coffee.png" The URI provided in this example is stored at the document root; therefore, a full path is not required. An image that is not stored at the document root requires a full path, for example: icon="c:\portal\images\box_b.gif" Or: icon="http://source-pc/images/accessability.gif" |
If you decide to add an icon on the header of the |
Id |
Enter a text string to use as the id="weather" |
The unique identifier for the component on the page. |
Layout |
default: |
Specifies whether the children of the If you specify If you choose |
Text |
Enter a text string to use as the text="Forecast for the Day" |
A title for the |
Width |
A number expressed in pixels (px) or as a percentage (%) of the available area. For example:
|
Specifies the width the Note: If you have specified |
DisclosureListener |
Specify a method reference of type javax.faces.el.MethodBinding. |
A method reference to a disclosure listener. |
DisplayScrollbar |
default: |
Specifies whether scrollbars should be rendered for the |
ShortDesc |
Enter a text string. |
A short description of this component. |
Core Attributes: |
||
ContentInlineStyle |
The name of a CSS style. |
The CSS style to apply to the |
InlineStyle |
The name of a CSS style. |
The CSS style to apply to the whole |
Rendered |
default: |
Specifies whether the component will be rendered or not. |
StyleClass |
The name of a CSS style class. |
The CSS style class for this component. |
Actions Attributes: |
||
IsEditable |
default: |
Specify whether an Edit command is rendered on the Actions menu for editing the child component. Note: If you specify |
IsHelpAvailable |
default: |
Specifies whether a Help command is rendered on the Actions menu for accessing Help on the child component. Note: If you specify true, then a corresponding |
IsMaximizable |
default: |
Renders a Maximize command on the |
IsMinimizable |
default: |
Renders a Minimize icon on the |
IsMovable |
default: |
Renders a Move command on the |
IsSeededInteractionAvailable |
default: |
Makes the Note: Display of each seeded interaction is controlled by its own attribute setting. |
IsShowContentEnabled |
default: |
Makes available a control in the Actions menu to users enabling them to show and hide the children of the |
The Bind option available when setting these attributes enables you to bind a PanelCustomizable
instance to a managed bean property.
Save your work.
Note:
To wrap an existing component in aPanelCustomizable
component, right-click the component in the Oracle JDeveloper Structure window, select Surround With from the context menu. Select Customizable Components Core from the list in the Surround With dialog box. Select PanelCustomizable
from the list of components.To add a ShowDetailFrame
component to a JSF JSP (*.jspx
file), perform the following steps:
In the Oracle JDeveloper Applications Navigator, right-click the *.jspx
file, and select Open from the context menu.
The *.jspx
file is located in the Applications Navigator under:
Applications <ApplicationName> <ProjectName> Web Content
In the Structure pane, select the component inside which you want to add the ShowDetailFrame
component.
In the Component Palette, select Customizable Components Core.
Click ShowDetailFrame. The ShowDetailFrame
component is displayed in the Page Editor. In the Structure pane, this component is placed under the component you had selected in step 2.
In the Property Inspector, set the attribute values for this component as required.
Table 4-6 describes the attributes of a ShowDetailFrame
component.
Table 4-6 Attributes of a ShowDetailFrame Component
Attribute | Type | Description |
---|---|---|
General Attributes: |
||
Background |
default: |
Working in conjunction with the skin CSS, provides a means of applying a different look and feel for this |
DisplayHeader |
default: |
Indicates whether the header of the Note: If you have exposed some actions on the component, and if the header display is turned off, then a toolbar is displayed when you move the mouse over the component area. The toolbar contains a drop down icon, which displays a menu of available options. This toolbar will appear only if there are actions available on the component. The toolbar display is also affected by the |
ExpansionMode |
default: |
The default state of the In the minimize mode, only the header is displayed. In the maximize mode, the component occupies the entire space allocated to its root parent, which occurs highest in the hierarchy. The root parent could be either a |
Icon |
Enter the URI to an image. For example: icon="coffee.png" The URI provided in this example is stored at the document root; therefore, a full path is not required. An image that is not stored at the document root requires a full path, for example: icon="c:\portal\images\box_b.gif" Or: icon="http://source-pc/images/accessability.gif" |
If you decide to add an icon on the header of the |
Id |
Enter a text string to use as the ShowDetailFrame's unique identifier. For example: id="weather" |
A unique identifier for the component on the page. |
Text |
Enter a text string to use as the ShowDetailFrame's header title. For example: text="Forecast for the Day" |
A title for the |
AttributeChangeListener |
Specify a method reference of type javax.faces.el.MethodBinding. |
A method reference to an attribute change listener. An event is fired when an attribute value changes. |
DisclosureListener |
Specify a method reference of type javax.faces.el.MethodBinding. |
A method reference to a disclosure listener. A disclosure event is fired when the disclosure state changes. |
ShortDesc |
Enter a text string. |
A short description of this component. |
Core Attributes: |
||
ContentInlineStyle |
The name of a CSS style. |
The CSS style to apply to the |
InlineStyle |
The name of a CSS style. |
The CSS style to apply to the whole Use the CCC styles in this attribute to set a width and height for the |
Rendered |
default: |
Specifies whether the component will be rendered or not. |
StyleClass |
The name of a CSS style class. |
The CSS style class for this component. |
Actions Attributes: |
||
IsEditable |
default: |
Specify whether an Edit command is rendered on the menu for editing the child component. Note: If you specify |
IsHelpAvailable |
default: |
Specify whether a Help command is rendered on the menu for accessing help on the child component. Note: If you specify |
IsMaximizable |
default: |
For |
IsMinimizable |
default: |
Renders a Minimize icon on the |
IsMovable |
default: |
For |
IsSeededInteractionAvailable |
default: |
Makes the Note: Display of each seeded interaction is controlled by its own attribute setting. |
The Bind option available when setting these attributes enables you to bind a ShowDetailFrame
instance to a managed bean property.
Save your work.
Note:
To wrap an existing component in aShowDetailFrame
component, right-click the component in the Oracle JDeveloper Structure window, select Surround With from the context menu. Select Customizable Components Core from the list in the Surround With dialog box. Select ShowDetailFrame
from the list of components.Use ShowDetailFrame
facets to define and display custom actions on the ShowDetailFrame
component. Table 4-7 describes the facets that provide additional hooks to display custom actions supported by the ShowDetailFrame
component.
Table 4-7 ShowDetailFrame Facets
Facet | Description |
---|---|
editAction |
Custom edit action facet. |
helpAction |
Custom help action facet. |
titleBarAction |
Used if an action is to be associated with title of the |
additionalActions |
Used if some additional actions are to be added to the list of actions available in the |
Oracle JDeveloper displays all facets available to the ShowDetailFrame
component in the Structure window. However, only those that contain UI components appear activated.
To add a ShowDetailFrame
facet, perform the following steps:
Right-click a ShowDetailFrame
component in the Structure window, and select Facets - Show Detail Frame.
Click the arrow to the right of this option.
From the list of supported facets, select the facet you want to add.
The f:facet
element for that facet is inserted in the page.
Note:
A checkmark next to a facet name means thef:facet
element for that facet is already inserted in the page, but it may or may not contain a child component.The Component Palette in the Oracle JDeveloper user interface lists all the available component tag libraries. You can select a library and drag and drop components from within that library onto a *.jspx
page.
See the Oracle Application Development Framework Developer's Guide for more information about dragging and dropping components onto a page.
You can change the look and feel of all customizable components by changing the Customizable Components selector CSS definition in the skin CSS file. Different Style selectors and Icon selectors are available for skinning customizable components. See Chapter 9, "Defining and Applying Styles to Core Customizable Components" for the list of available selectors, information about Oracle ADF Faces skins, creating custom skins, and configuring an application to use a skin.
You can use PanelCustomizable
and ShowDetailFrame
components to perform various actions on child components, such as minimize, maximize, move, and so on. Actions on customizable components are not secured by default. It is advisable not to expose all actions to all types of users, and therefore, recommended that you define security for these components appropriately.
To implement security for actions on customizable components at various levels, see Section 10.9.2, "Customizable Components Security".
One way to make your WebCenter application more interactive is by linking related components such that their contents are synchronized based upon the context. For example, suppose you have two stock portlets on a page, one provides data about a stock's price while the other provides headline news items for a stock. Both portlets are based upon the stock ticker symbol, hence it would make sense that, when the ticker symbol is changed in the stock price portlet, the stock headlines portlet picks up that change and refreshes itself with headlines pertaining to the same ticker symbol.
You can implement this kind of synchronization through parameters. Table 4-8 summarizes the types of components you may tie together with this type of contextual behavior.
Table 4-8 Components You Can Synchronize
Component Initiating Parameter | Component Reading Parameter Value | Comments |
---|---|---|
Oracle ADF Faces components |
Oracle ADF Faces components |
For more information about linking Faces components together, see Oracle Application Development Framework Developer's Guide. |
WSRP portlets |
Faces components, such as options or lists, can be used to change the displayed content of portlets. |
|
PDK-Java portlets |
Faces components, such as options or lists, can be used to change the displayed content of portlets. |
|
WSRP 2.0 portletsFoot 1 |
Oracle ADF Faces components |
Standards-based portlets can pass parameters to Faces components. |
WSRP 2.0 portlets |
You can pass parameters between standards-based portlets. |
|
PDK-Java portlets |
You can pass parameters from a standards-based portlet to a PDK-Java-based portlet. |
|
PDK-Java portlets |
Oracle ADF Faces components |
PDK-Java portlets can pass parameters to Faces components. |
WSRP portlets |
You can pass parameters from a PDK-Java portlet to a standards-based portlet. |
|
PDK-Java portlets |
You can pass parameters between PDK-Java-based portlets. |
|
Oracle ADF Faces page variable/parameter |
Oracle ADF Faces components |
You can set parameters at the page level and have them picked up by Faces components on the page. |
WSRP portlets |
Standards-based portlets can pick up page parameters. |
|
PDK-Java portlets |
PDK-Java portlets can pick up page parameters. |
Footnote 1 Note that support for navigational parameters exists only in WSRP 2.0. WSRP 1.0 does not have support for navigational parameters.
If you define page variables, then portlets on that page can then read the page variables at run time and change their behavior accordingly. By having page variables that can be linked to portlet parameters, you enable any portlets on the page to adapt to the context. For example, the page could contain a customer identifier variable. Any related portlets on the page could use this value to determine what they ought to display. A customer details portlet could take this value and determine which customer's information to display.
Figure 4-3 shows a portlet that gets a customer identifier number (320) from a page parameter.
Figure 4-3 Example of Portlet with Page Parameter
How to Link Portlets to Pages
If you defined public parameters when creating your portlet, then page variables are created for them when you drop the portlet onto a page.
To see how parameters are implemented when you drop a portlet onto a page, do the following:
Note:
The scenario that follows uses OmniPortlet, but the basic principles regarding parameters and page variables would be true for any portlet.Open the page by double-clicking it in the Applications Navigator. The page opens for editing and you should see its structure in the Structure pane.
Add an OmniPortlet portlet to the page. See Section 4.3.2, "Adding Portlets to a Page". Note that the OmniPortlet uses a PDK-Java producer and must be registered with the application. See Section 4.3.1.2, "Registering PDK-Java Portlet Producers" for more information about registering PDK-Java producers.
Right-click anywhere in the tree displayed in the Structure pane, and choose Go to Page Definition in the context menu. The page definition tree should now appear in the Structure pane and the page definition XML should open for editing.
In your page definition XML, you should see the five default OmniPortlet page variables inside the <variableIterator>
tag. You should then see references to the page variables from inside of the <portlet>
tag. Example 4-11 shows a sample page definition after an OmniPortlet was first dropped onto the page.
Example 4-11 PageDef.xml File with OmniPortlet
<?xml version="1.0" encoding="UTF-8" ?> <pageDefinition xmlns="http://xmlns.oracle.com/adfm/uimodel" version="10.1.3.39.0" id="SRDemoDashboardPageDef" Package="view.pageDefs"> <parameters/> <executables> <variableIterator id="variables"> <variable Name="portlet1_Param1" Type="java.lang.Object"/> <variable Name="portlet1_Param2" Type="java.lang.Object"/> <variable Name="portlet1_Param3" Type="java.lang.Object"/> <variable Name="portlet1_Param4" Type="java.lang.Object"/> <variable Name="portlet1_Param5" Type="java.lang.Object"/> </variableIterator> <portlet id="portlet1" portletInstance="/oracle/adf/portlet/OmniPortletProducer_1154018261057/ ap/Portlet100_b0da57c9_010c_1000_8003_82235f50a408" class="oracle.adf.model.portlet.binding.PortletBinding" xmlns="http://xmlns.oracle.com/portlet/bindings"> <parameters> <parameter name="Param1" pageVariable="portlet1_Param1"/> <parameter name="Param2" pageVariable="portlet1_Param2"/> <parameter name="Param3" pageVariable="portlet1_Param3"/> <parameter name="Param4" pageVariable="portlet1_Param4"/> <parameter name="Param5" pageVariable="portlet1_Param5"/> </parameters> </portlet> </executables> </pageDefinition>
In order for the page to take a parameter value through its URL, you must add a page level parameter. In the Structure pane, right-click the parameters node and select Insert inside parameters, parameter from the context menu. The Insert Parameter dialog box is displayed.
Enter an ID of custID
and a value of ${param.customerID}
. Click OK. You should now see something similar to the following in the XML of your page definition.
<parameters> <parameter id="custID" value="${param.customerID}"/> </parameters>
Right-click your page in the Applications Navigator and choose Run from the context menu.
When the page appears, click Define in OmniPortlet.
Choose SQL and click Next.
In the Statement area, enter the following SELECT statement. Note the reference to Param1
in the WHERE clause.
select * from USERS where USER_ID = ##Param1##
In the Connection section, choose or create a connection to a database that contains the SRDemo schema.
In Portlet Parameters, enter 320
as the Default Value for Param1
and select Personalizable.
Click Next.
You do not need a filter in this case, so click Next.
In Header Text, enter:
Select a customer from the Most Active Customers List to view the customer details.
Choose HTML for Layout Style and click Next.
Delete the default HTML in the Non-Repeating Heading Section.
Replace the default HTML in the Repeating Section with the following:
<TABLE BORDER='0' WIDTH="100%"> <TR CLASS='PortletText1'> <TD CLASS='PortletHeading1'>ID</TD> <TD>##USER_ID##</TD> </TR> <TR CLASS='PortletText1'> <TD CLASS='PortletHeading1'>Email</TD> <TD>##EMAIL##</TD> </TR> <TR CLASS='PortletText1'> <TD CLASS='PortletHeading1'>First Name</TD> <TD>##FIRST_NAME##</TD> </TR> <TR CLASS='PortletText1'> <TD CLASS='PortletHeading1'>Last Name</TD> <TD>##LAST_NAME##</TD> </TR> <TR CLASS='PortletText1'> <TD CLASS='PortletHeading1'>Street</TD> <TD>##STREET_ADDRESS##</TD> </TR> <TR CLASS='PortletText1'> <TD CLASS='PortletHeading1'>City</TD> <TD>##CITY##</TD> </TR> <TR CLASS='PortletText1'> <TD CLASS='PortletHeading1'>State</TD> <TD>##STATE_PROVINCE##</TD> </TR>
Leave the default Non-Repeating Footer Section as is and click Finish.
Return to Oracle JDeveloper and click the page variable, portlet1_Param1
, in the Structure pane. Its properties should now be displayed in the Property Inspector.
In the Property Inspector, click next to the DefaultValue property. A button for editing the value of the property should appear. Click this Edit button.
In the DefaultValue dialog box, expand the ADF Bindings node and then the bindings node beneath it. You should see a binding for portlet1_Param1
.
You can move variables into the Expression using the right arrow (>) and apply operators using the buttons. The expression you create should look something like the following:
${(bindings.custID == null || bindings.custID == '') ? 320 : bindings.custID }
Click OK. You should now see something similar to Example 4-12 in your page definition XML.
Now you must set the value of the parameter to test your portlet on the page. You can set the value through a page URL. For example:
http://pc1.com:8988/SRDemo/faces/app/management/SRDashboard.jspx?customerID=321
The passing of this URL causes the page to refresh with a value for customerID
of 321. The OmniPortlet on the page should be refreshed with data that reflects the changed value.
In many cases, it's useful to tie portlets together such that when a parameter in one portlet changes, it causes the other portlet to refresh with a new value as well. For example, Figure 4-4 illustrates two portlets. When a user clicks on the Last Name from the Most Active Customers portlet on the left, that customer's ID is provided to the Customer Details portlet on the right, which in turn refreshes with that customer's detailed data.
Figure 4-4 Example of Portlet to Portlet Communication
How to Link Portlets
Linking portlets works in much the same fashion as linking a portlet to a page. The example in "How to Link Portlets to Pages" illustrates how a value is passed from a page parameter in the URL to a page variable, and then the page variable's value is passed into a portlet's parameter. You could easily have multiple portlets on the page that read the page variable's value in this way. Furthermore, because the page parameter can be changed from the page URL, a portlet could set the value of the page parameter and in turn the page variable, which would then affect the other portlets on the page.
A very powerful pairing of components is a Faces component with a portlet. This kind of synchronization comes in handy if you envision an interactive Faces component, such as a list or option, that relates to one or more portlets on a page. For example, suppose you have some sort of a dashboard page and you want users to be able to pick from a predefined set of choices to determine what the portlets on the page display. The Faces component (list or option selection) could pass a value to one or more portlets on the page. The portlets in turn could use this value to determine what content to display.
In Figure 4-5, the list called Volume for last is a Faces component, and the pie chart is generated by OmniPortlet. The value from the list is passed to OmniPortlet, which in turn takes the new value and refreshes itself with the updated chart.
Figure 4-5 Example of Faces Component to Portlet Communication
How to Link Faces Components to Portlets
To link your Faces component to a portlet, do the following:
Open the page by double-clicking it in the Applications Navigator. The page opens for editing and you should see its structure in the Structure pane.
Add the desired Faces component to the page using the Oracle JDeveloper user interface gestures. Example 4-13 illustrates a selectOneChoice
created through the user interface within a ShowDetailFrame
within a PanelCustomizable
. The selectOneChoice
provides a list called dayPicker
from which a user can select the span of time (in days) over which an OmniPortlet (portlet1
) pie chart will graph data. Note that in this example, the get and set functionality of the day picker was automatically created in the backing class. Setting autoSubmit
to true
forces the value of the variable to change whenever an item is selected from the list. Notice also how the OmniPortlet specification, which appears just below the dayPicker
, references dayPicker
.
<cust:panelCustomizable text="Service Requests Volume" displayHeader="false" expansionMode="normal" isMovable="true" isSeededInteractionAvailable="true" id="panelCustomizable2" layout="horizontal"> <cust:showDetailFrame id="showDetailFrame1" text="Service Volume Distribution" displayHeader="true" isSeededInteractionAvailable="true"> <af:selectOneChoice id="dayPicker" label="Volume for last" value="360" binding="#{backing_app_management_SRDashboard.SelectOneChoice}" autoSubmit="true"> <af:selectItem label="1 day" value="1"/> <af:selectItem label="2 days" value="2"/> <af:selectItem label="3 days" value="3"/> <af:selectItem label="5 days" value="5"/> <af:selectItem label="10 days" value="10"/> <af:selectItem label="30 days" value="30"/> <af:selectItem label="60 days" value="60"/> <af:selectItem label="90 days" value="90"/> <af:selectItem label="180 days" value="180"/> <af:selectItem label="360 days" value="360"/> </af:selectOneChoice> <adfp:portlet value="#{bindings.portlet1}" portletType="/oracle/adf/portlet/OmniPortlet_Producer/applicationPortlets/ Portlet100_f20eef2c_010a_1000_8003_a9fe020295ca" partialTriggers="dayPicker" displayScrollBar="False" displayHeader="False" isMinimizable="True" renderPortletInIFrame="False"/> </cust:showDetailFrame> <adfp:portlet value="#{bindings.portlet3}" portletType="/oracle/adf/portlet/OmniPortlet_Producer/applicationPortlets/ Portlet100_f20f676b_010a_1000_8005_a9fe020295ca" renderPortletInIFrame="False"/> <adfp:portlet value="#{bindings.portlet2}" portletType="/oracle/adf/portlet/OmniPortlet_Producer/applicationPortlets/ Portlet100_f20f50cc_010a_1000_8004_a9fe020295ca" renderPortletInIFrame="False"/> </cust:panelCustomizable>
Once you have set up the Faces component and referenced it from the desired portlet on the page, you must add the parameter to the page definition. Right-click the JSP root in the Structure pane and choose Go to Page Definition in the context menu. The page definition XML opens for editing.
In the <executables>
section, you must specify the parameter to be passed from dayPicker
to portlet1
. Example 4-14 illustrates the default code in the page definition.
Example 4-14 portlet1 Parameters
<executables> <variableIterator id="variables"> <variable Name="OmniPortlet2_1_Param1" Type="java.lang.Object" DefaultValue="<parameter name="Param1" value="${(backing_app_management_ SRDashboard.dayPicker.value == null) ? 360 : backing_app_management_ SRDashboard.dayPicker.value}"/> <variable Name="OmniPortlet2_1_Param2" Type="java.lang.Object"/> <variable Name="OmniPortlet2_1_Param3" Type="java.lang.Object"/> <variable Name="OmniPortlet2_1_Param4" Type="java.lang.Object"/> <variable Name="OmniPortlet2_1_Param5" Type="java.lang.Object"/> </variableIterator>