../E63259-01.epub /> ../E63259-01.mobi />

62 Creating Pagelets with Pagelet Producer

A pagelet is a reusable user interface component. Any HTML fragment can be a pagelet, but pagelet developers can also write pagelets that are parameterized and configurable, to dynamically interact with other pagelets, and respond to user input. Pagelets can be run on any Web page, including within a portal or other Web application. Pagelets can be used to expose platform-specific portlets in other Web environments. Oracle WebCenter Portal's Pagelet Producer (previously known as Oracle WebCenter Ensemble) provides a collection of useful tools and features that facilitate dynamic pagelet development.

This chapter includes the following sections:

62.1 About Pagelet Producer

This section provides an introduction to Pagelet Producer concepts and features. It describes how you can use Pagelet Producer, its underlying architecture and components, and introduces key concepts.

This section includes the following topics:

62.1.1 Overview

Pagelet Producer lets you leverage investments in existing Web infrastructure by making it usable in new ways. Pagelet Producer can be used to consume:

  • Web UI from applications that do not expose integration APIs or portlets out of the box

  • Standard portlets such as WSRP (JSR-168 or JSR-286), JPDK, CSP, and WebParts

It can also deliver Web UI to WebCenter Portal, Sites, or pretty much any HTML page with the added benefits of role-based access control to Pagelet Producer resources, and reverse proxying of Web resources with HTML markup parsing, clipping, injection and event handling (inter-pagelet communication).

Pagelet Producer provides:

  • Tools for consuming existing Web UI and re-using it as portable components called pagelets

  • Alternatives for integrating non-standard/non-compliant containers and components that do not support portlet standards. For example, you can:

    • Capture functionality from Web applications that do not expose portlets

    • Make existing WSRP, JPDK, or Content Syndication Protocol (CSP) portlets available for use in a non-portal setting

  • Injectors and parsers to modify HTML markup

  • A JavaScript framework for inter-pagelet communication and event handling

62.1.2 Pagelet Producer Architecture

This section describes the Pagelet Producer architecture and key components. This section includes the following subsections:

62.1.2.1 Pagelet Producer Architecture and Components

Figure 62-1 shows a high-level view of the Pagelet Producer components and their interactions. Figure 62-1 also reflects the way in which the pagelet request is being handled in Pagelet Producer. The request is received by the Proxy Servlet that maps incoming requests to the resource. Next, the request is authenticated. If the user can access the requested resource, pagelet processing starts by requesting HTML markup from the backend system. After the markup is received it is modified using any defined clippers, parsers, and so forth.

Figure 62-1 Pagelet Producer - High-Level Architecture

Description of Figure 62-1 follows
Description of "Figure 62-1 Pagelet Producer - High-Level Architecture"

Figure 62-2 provides a different view of component interaction:

Figure 62-2 Pagelet Producer - Interaction Flow

Description of Figure 62-2 follows
Description of "Figure 62-2 Pagelet Producer - Interaction Flow"

A: A Pagelet Producer application runs on a J2EE application server. Note that Pagelet Producer does not require the WebCenter schema, but it does require an MDS Instance (typically shared with WebCenter).

B: User calls a WebCenter Portal page that contains a pagelet.

C: WebCenter Portal returns the page, plus the JavaScript that will call Pagelet Producer to render the pagelet.

D: The JavaScript makes a render call to Pagelet Producer.

E: The Pagelet Producer can call external (E1) or internal (E2) Web applications as sources of HTML content. Pagelet Producer transforms the content (i.e., rewrites the URL) and returns it to the browser for insertion into the page. Pagelet Producer itself can be externally accessible (i.e., in the DMZ).

62.1.2.2 Pagelet Producer Key Concepts

The following key concepts are useful when working with Pagelet Producer:

  • Resources are core objects used to register applications within Pagelet Producer, including stand-alone Web applications, Pagelet Producers and OpenSocial containers. Creating a resource allows the proxy to map internal applications to external URLs, manage authentication, and transform applications. Registering a Web application as a Pagelet Producer resource allows you to do the following:

    • Proxy internal Web applications to external addresses

    • Manage authentication, both at the proxy level and at the resource level

    • Transform proxied Web applications, including URL rewriting

    For more information about creating resources, see Section 62.3.1, "Creating Resources."

  • Pagelets are sub-components of a Web page accessed through Pagelet Producer that can be injected into any proxied application. Any application on a Pagelet Producer resource that returns markup can be registered as a pagelet, which can then be displayed in a portal or Framework application, or any other Web application.

    Any HTML fragment can be a pagelet. Pagelet developers can create pagelets that are parameterized and configurable, dynamically interact with other pagelets, and respond to user input using Asynchronous Javascript and XML (AJAX) patterns.

    For more information about creating pagelets, see Section 62.3.2, "Creating Pagelets."

Pagelet Producer registration is dynamic. Additions and updates to existing producers are immediately available. In most cases, it is not necessary to restart the portal or Framework application or the managed server.

62.1.2.3 Pagelet Producer Console

The Pagelet Producer Console is a browser-based administration tool used to create and manage the various objects in your Pagelet Producer deployment. From the Console you can register Web applications as resources, create pagelets, manage proxy and transformation settings, and more.

The Pagelet Producer Console is accessible from any Web browser at the following URL:

http://<host>:<port>/pagelets/admin

The Pagelet Producer Console can also be launched in accessibility mode at:

http://<host>:<port>/pagelets/admin/accessible

During runtime, the Pagelet Producer Console is also accessible from the WebCenter Portal Shared Assets tab.

Note:

Pagelet Producer Console supports the standard administration languages and Dutch only. If you configure the browser language to something other than one of these languages, it will revert to the language defined for the current server.

For more information about using the Pagelet Producer Console to configure Pagelet Producer and create objects, see Section 62.2, "Configuring Pagelet Producer Settings" and Section 62.3, "Creating Pagelet Producer Objects." For information about using the Pagelet Producer Console to register producers and migrate pagelet data, see the "Managing the Pagelet Producer" chapter in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

62.1.2.4 Using HTTP and Content Syndication Protocol

HTTP is a protocol used mostly for transferring Web page content and XML between a server and a client. Content Syndication Protocol (CSP) is a platform-independent protocol based on the open standard of HTTP 1.1 that extends HTTP defining the syntax of communication between Pagelet Producer and external CSP resources.

Services on external resources communicate with Pagelet Producer using CSP. For example, when a browser requests a page, Pagelet Producer makes simultaneous requests to each external resource to retrieve the pagelet content for the page. The external resource reads the current user's preferences from the CSP headers sent by Pagelet Producer and sends back the appropriate HTML. Pagelet Producer inserts the HTML into the page markup. Any images stored in the Image Service are retrieved and displayed by the browser.

This section contains the following subsections:

62.1.2.4.1 HTTP

HTTP communication is made up of requests and responses. Requests and responses are essentially lists of name-value pairs of metadata in headers, along with an optional body. The body is the data that is being transferred (an HTML page or XML file). The metadata in the headers is information about the request or response itself (for example, what language the content is in, or how long the browser should cache it). The request and response each contain specific information as described below. For more detailed information on HTTP, see RFC 2616 (http://www.faqs.org/rfcs/rfc2616.html).

The client sends the server an HTTP Request, asking for content. The request body is used only for requests that transfer data to the server, such as POST and PUT.

HTTP Request Format:

[METHOD] [REQUEST-URI] HTTP/[VERSION]
[fieldname1]: [field-value1]
[fieldname2]: [field-value2]
[request body, if any]

HTTP Request Example:

GET /index.html HTTP/1.1 
Host: www.xmlns.oracle.com 
User-Agent: Mozilla/3.0 (compatible; Opera/3.0; Windows 95/NT4) 
Accept: */* 
Cookie: username=JoeSmith

The server sends back an HTTP Response that contains page content and important details, such as the content type, when the document was last modified, and the server type. The response contains an error message if the requested content is not found.

HTTP Response Format:

HTTP/[VERSION] [CODE] [TEXT] 
[fieldname1]: [field-value1] 
[fieldname2]: [field-value2] 
[response body, if any (document content here)]

HTTP Response Example:

HTTP/1.0 200 Found 
Last-modified: Thursday, 20-Nov-97 10:44:53 
Content-length: 6372 
Content-type: text/html 
<!DOCTYPE HTML PUBLIC '-//W3C//DTD HTML 3.2 Final// EN'><HTML> 
...followed by document content...

Custom HTTP headers can be configured to include specialized information.

Note:

Header size limits are controlled by the server that hosts the code. The standard limit for IIS/ASP is 60K. Java Application Servers range from 2K to 10K. These limits are generally configurable; see your server documentation for more information.

Services can also access standard HTTP headers, such as the Set-Cookie header or HTTP 1.1 basic authentication header. If you want to investigate HTTP further, you can view all the headers being passed back and forth between your browser and Web server using logging (as described in Section 62.6.3, "Debugging Pagelets"). HTTP is used in conjunction with SSL to serve up secure content. Single sign-on (SSO) also uses HTTP headers for basic authentication.

62.1.2.4.2 Content Syndication Protocol

Content Syndication Protocol (CSP) extends HTTP and defines proprietary headers to pass settings between Pagelet Producer and external CSP resources (specifically, Oracle WebCenter Interaction portlets). CSP outlines how these services use HTTP to communicate and modify settings. The latest version of the CSP protocol is 1.4, and is available from:

http://docs.oracle.com/cd/E13158_01/alui/wci/docs103/devguide/references/CSP1.4.pdf

The custom CSP headers used to communicate system and user configuration variables (see Table 62-1) can also be used by pagelets.

Table 62-1 Pagelet Producer Headers

Header Name Description

User ID

The User ID of the currently logged in user. This value can be used to determine if the session has expired. If UserID=2, the default 'Guest' user is logged in; any other user's session has ended.

User Name

The name of the logged in user. The user's name can be used to personalize display or pre-fill form fields.

Image Service URL

The URL to the root virtual directory of the Image Service in the user's implementation of Pagelet Producer. This location should be used for all static images used in services.

Stylesheet URL

The URL to the current user's style sheet. In each implementation of Pagelet Producer, the UI is customized. In some portals, users can choose between a selection of stylesheets. Using these styles ensures that pagelets appear in the style of the current user's implementation of Pagelet Producer.

Pagelet ID

The ID for the current resource (pagelet), and the instance ID for the current pagelet. This value is useful for appending to the names of HTML forms and client-side JavaScript functions to ensure unique form and function names on the page to avoid name conflicts.

Host Page URL

The URL to the page that hosts the pagelet. Preference pages need this URL to return the user to the correct page after settings are configured. This value can also be used to allow a single pagelet to display different content on different pages.


62.1.2.5 Pagelet Producer Proxy

Pagelet Producer acts as a proxy server, brokering transactions between client computers and external resources. This configuration is typically used to serve content to clients that would otherwise be unable to access the external resource, but it can also be used to impose additional security restrictions on the client, including the use of policies. The proxy hides the external resource so that the content appears to come directly from the proxy server.

This architecture makes Pagelet Producer the single point of access for content, and allows external resources to reside on a private network or behind a firewall. As long as Pagelet Producer can connect to the external resource, users can view the content, even if they cannot access it directly. To the browser, Pagelet Producer appears to be the source of content on the external resource.

When a user interacts with a service, any request made to a URL in the proxy is automatically rerouted through Pagelet Producer. To the user, the content appears to come from Pagelet Producer; the external resource is an unknown back-end system.

There are many benefits to this configuration. The most useful to services are:

  • Dynamic functionality and personalization: Pagelet Producer intercepts request from pagelets, which allows the response to be modified dynamically, using information from MDS, the request, or the response"

  • Security: Services can allow users to access content that is not publicly available. Files stored on a secure server can be made available by including specific URLs in the configuration of the proxy.

    WARNING:

    The proxy is a powerful feature and can compromise security if incorrectly configured. Allowing direct access to a external resource that hosts unprotected private content could create a dangerous security gap.

  • Performance: Pagelet Producer caches proxied content, decreasing response time for end users and improving performance on the external resource. While proxying works efficiently for content like HTML, it is generally not appropriate for binary data like static images. Images do not need to be transformed, and proxying large images can adversely affect performance. This is one reason the Image Service should be used to prevent routing static images through the proxy.

Note that all URLs to other proxied CSP or Web resources will be proxied by default unless specified in the Do not proxy hosts field. For more information about configuring proxying, see Section 62.2.3, "Configuring Proxy Settings."

Keep the following warnings and best practices in mind when implementing services that use the proxy:

  • URL transformation: Pagelet Producer must transform code so that proxied URLs open correctly. Before Pagelet Producer sends a response, it parses the HTML and looks for URLs containing the HTTP Proxy Server URL field prefix (see Section 62.2.3, "Configuring Proxy Settings"). Pagelet Producer transforms any URLs that should be proxied before returning the response to the client. Relative URLs are transformed to point to the correct location.

  • Scripting limitations: JavaScript constructs that dynamically create URLs can cause problems, because they are run after content is already transformed. VBScript is not transformed by the proxy; you can continue to use dynamic scripts and VBScript as long as your code is proxy-aware. Parsers and Web injectors can be used to implement targeted control over URL rewriting. For details on parsers and Web injectors, see Section 62.6.2, "Modifying Pagelet Functionality at Runtime."

  • URL encoding: It is a best practice to encode all headers that are URLs to prevent unexpected transformation. In JSP, encode all URLs that are written. If the code writes URLs in the body of a page (for example, a link to a preferences page) it should be encoded. The standard Java servlet command response.encodeURL() is the preferred method, but you can also use URLEncoder.encode(url). In the .NET framework, the HttpUtility.URLEncode class provides the necessary functionality. Note that for .NET, there is no need to encode the redirect URL; this is handled automatically by the back end.

62.1.3 Requirements

Install WebCenter Portal following the instructions in the Oracle Fusion Middleware Installation Guide for Oracle WebCenter. Make sure that all dependent components are also installed and configured, including WebCenter Content Server, the discussions server, and Pagelet Producer.

By default the Services Producer is automatically deployed to the WC_Portlet managed server in the WebCenter Portal domain. If the WC_Portlet managed server was not created during installation or there is a requirement to run the Services Producer separately, there is a custom Services Producer template that can be used to create the WC_CustomServicesProducer managed server. This managed server contains the Oracle WebCenter Services Producer component as well as pre-configured JDBC data sources for accessing the WebCenter Portal, Activities, and MDS schemas. For more information, see the "Oracle WebCenter Portal: Custom Services Producer Template" section in the Oracle Fusion Middleware Domain Template Reference.

62.2 Configuring Pagelet Producer Settings

This section explains important configuration settings that affect all Pagelet Producer resources and how to set them using the Settings pages of the Pagelet Producer Console. For an introduction to the Pagelet Producer Console, see Section 62.1.2.3, "Pagelet Producer Console."

The following pages are included in the Settings section:

62.2.1 Configuring a WCI Data Source

A CSP login token is required to consume WCI resources, and a data source is required for that login token to be propagated from Pagelet Producer to CSP portlets. Pagelet Producer generates a login token that is sent to all remote portlets to propagate user identity and validate incoming requests. Follow the steps in the "Configuring JDBC Data Sources" section in Oracle Fusion Middleware Configuring and Managing JDBC Data Sources for Oracle WebLogic Server to configure the data source. Note that the data source must be named wcidb.

62.2.2 Configuring Logging Settings

The Logging page lets you set logging levels for Pagelet Producer components.

Figure 62-3 Pagelet Producer Console: Settings - Logging

Description of Figure 62-3 follows
Description of "Figure 62-3 Pagelet Producer Console: Settings - Logging"

To enable logging for any component, choose one of the following logging levels:

  • Severe

  • Warning

  • Info

  • Config

  • Fine

  • Finer

  • Finest

Logging messages can be viewed in the managed server log files. In Oracle WebLogic Server, this would be domain_home/servers/managed server name/managed server name.log and managed server name-diagnostic.log.

62.2.3 Configuring Proxy Settings

The Proxy page lets you define a list of URLs that will not be proxied, and set the URL, user name, and password for the HTTP proxy if required.

You must restart Pagelet Producer after changing the proxy settings.

Note:

If an HTTP proxy is required for external connections in the deployment environment, initial server startup will report connection errors. These errors are not an indication of problems with the environment; they indicate that some external OpenSocial libraries cannot be loaded remotely. The errors can be resolved by configuring the proxy settings as described above and restarting the server.

Note for Oracle WebLogic Server deployments:

The HTTP Proxy Server URL entered on the Proxy page is applied to all applications running on the server that hosts Pagelet Producer (on Oracle WebLogic Server, this setting is applied to all applications running on the WC_Portlet managed server). Oracle WebLogic Server users should pay particular attention to this setting and make sure that the WLS Administrative Server host and all clustered managed servers are included in the "Do not proxy hosts" list.

Figure 62-4 Pagelet Producer Console: Settings - Proxy

Description of Figure 62-4 follows
Description of "Figure 62-4 Pagelet Producer Console: Settings - Proxy "

The Proxy page contains the following settings:

  • The Do not proxy hosts field lets you define a list of semicolon-separated list of URLs that will not be proxied (wildcards are allowed). For Oracle WebLogic Server deployments, be sure to include the WLS Administrative Server host and all clustered managed servers in this list.

  • The HTTP Proxy Server Password field lets you set the password for the proxy server.

  • The HTTP Proxy Server URL field lets you define the proxy server URL.

  • The HTTP Proxy Server Username field lets you define the username with which to access the proxy server.

62.2.4 Configuring Transform Settings

The Transform page lets you enter the path to the credential vault provider and configure secure and insecure ports for Pagelet Producer. This page also lets you choose whether or not to log pre- and post- transformation content.

Figure 62-5 Pagelet Producer Console: Settings - Transform

Description of Figure 62-5 follows
Description of "Figure 62-5 Pagelet Producer Console: Settings - Transform"

The Transform page contains the following fields:

  • The Credential Vault Plugin Path field lets you define a path to the credential vault, where plug-ins are stored.

  • The Nonsecure Port field lets you define a non-secure port for Pagelet Producer.

    Note:

    The Nonsecure Port defaults to 8889. If Pagelet Producer is deployed on a different port, change this entry and restart the server.
  • The Secure Port field you define a non-secure port for Pagelet Producer.

  • The Trace Transformation option, when checked, turns on logging for pre- and post- transformation content. Note that this option, although useful for debugging, should not be turned on in production environments.

62.2.5 Configuring CSP Settings

CSP is a platform-independent protocol based on the open standard of HTTP 1.1. CSP defines the syntax of communication between Pagelet Producer and external resources. It also defines custom headers as well as outlines how services use HTTP to communicate and modify settings.

The CSP page lets you configure the Oracle WebCenter Interaction Credential Mapper, SOAP API service, and image service.

Note:

This page may be ignored if Oracle WebCenter Interaction is not present in your deployment. These settings are used for backwards compatibility with CSP portlets written for Oracle WebCenter Interaction.

62.2.6 Configuring Kerberos Settings

The Kerberos page is used to define the paths to the Kerberos configuration files (java.security.krb5.conf and java.security.auth.login.conf). These two configuration files are needed to configure the Kerberos realm and KDC to instruct HTTPClient where to retrieve the Kerberos Service ticket.

62.2.7 Configuring OpenSocial Settings

The OpenSocial page lets you configure Pagelet Producer for use with OpenSocial gadgets.

Figure 62-6 Pagelet Producer Console: Settings - OpenSocial

Description of Figure 62-6 follows
Description of "Figure 62-6 Pagelet Producer Console: Settings - OpenSocial"

The OpenSocial page includes the following settings:

  • The Cache option enables Pagelet Producer internal caching for OpenSocial gadgets.

  • The Context field defines the context to which Pagelet Producer is deployed. This value should be left at the default setting ("pagelets") unless a change is required by the OpenSocial container. For details on changing the context, see the "Redeploying Pagelet Producer to a Different Context" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

  • The Debug option enables debugging for OpenSocial gadgets (disables JavaScript obfuscation).

  • The Host field should contain the fully-qualified domain name of Pagelet Producer host. This value should be retrieved automatically from the environment; if it is not, restart the server to pick up the correct configuration settings. As with the Context setting, this value should be left at the default unless a change is required by the OpenSocial container.

  • The SSL option enables SSL for OpenSocial gadgets.

Note:

You must also configure the secure (HTTPS) and nonsecure (HTTP) ports before importing OpenSocial gadgets. For details on these settings, see Section 62.2.4, "Configuring Transform Settings."

62.3 Creating Pagelet Producer Objects

This section describes how to create and configure the various objects in a Pagelet Producer deployment, including resources, pagelets, Web injectors, parsers and hosted files.

As explained in Section 62.1.2.3, "Pagelet Producer Console," the Pagelet Producer Console is a browser-based administration tool used to create and manage the various objects in a Pagelet Producer deployment. This section describes the settings required for each type of object:

62.3.1 Creating Resources

Resources are applications registered with Pagelet Producer. Registering an application as a resource allows the proxy to map internal applications to external URLs, manage authentication, and transform application functionality.

To create a new resource, use the steps below:

  1. Select the Resources option from the dropdown list in the Pagelet Producer Console navigator.

  2. Click on any existing resource and click the Create icon in the navigator toolbar. (This button is only enabled when you have selected an object type that can be created.)

    Figure 62-7 Pagelet Producer Console - Create Resource

    Description of Figure 62-7 follows
    Description of "Figure 62-7 Pagelet Producer Console - Create Resource"

  3. In the Select Producer Type dialog box, choose the type of producer that the resource will be configured to proxy from the dropdown list:

    Figure 62-8 Select Producer Type Dialog

    Description of Figure 62-8 follows
    Description of "Figure 62-8 Select Producer Type Dialog"

  4. Click OK. An entry called "<new>" will be added to the list of resources. This new resource will include the necessary configuration pages for the producer type chosen.

  5. Configure the resource in the Pagelet Producer Console. The required configuration pages differ based on the type of producer. To save your changes at any time, click the Save icon in the navigator toolbar.

Once the resource is defined, create the pagelets and other objects within the resource. For more information, refer to the following sections:

62.3.1.1 Configuration Pages: Web and CSP Resources

This section describes how to configure Web and CSP resources.

This section includes the following subsections:

This section uses the welcome_resource created when Pagelet Producer is installed as an example.

62.3.1.1.1 Configuring General Settings

Use the General page (see Figure 62-9), to enter basic information about the resource.

Figure 62-9 Pagelet Producer Console: Resource - General Page

Description of Figure 62-9 follows
Description of "Figure 62-9 Pagelet Producer Console: Resource - General Page"

  • Enter a Name for the resource.

  • Enter a Description for the resource (optional).

  • In the Source URL field, type the URL to the location of the Web application resource to be proxied. For example, http://internalServer/foo/.

    Note:

    If you are configuring an ADF Web Application as a resource, the Source URL cannot be any more specific than http://hostname:portnumber/context-root/.
  • By default, Pagelet Producer attempts to connect to the resource for 30 seconds before returning an error message. To change this value, enter a new Source Timeout period in seconds.

  • In the Destination URL field, type the relative path to be used to access the resource. This path will be used to create an URL to the resource on the server that hosts Pagelet Producer.

  • To enable Dynamic HTML, choose DHTML Rewriting. This option supports URLs that are not in the original HTML returned from the server, but are added by DHTML. In most cases, this option should be enabled.

  • To enable rewriting of DHTML through asynchronous Ajax calls select Asynchronous Rewriting.

62.3.1.1.2 Configuring CSP settings

By default, the CSP login token is not passed to the proxied resource. To enable this feature, choose Send CSP Login Token. Note that the CSP page is only available for CSP resources.

62.3.1.1.3 Configuring Policy Settings

The Policy page (see Figure 62-10) lets you limit access to a resource to specific roles within WebCenter Portal.

Figure 62-10 Pagelet Producer Console: Resource - Policy Page

Description of Figure 62-10 follows
Description of "Figure 62-10 Pagelet Producer Console: Resource - Policy Page"

The J2EE container hosting Pagelet Producer (such as Oracle WebLogic Server) is responsible for establishing the role memberships associated with the current user. A resource can specify multiple roles on the Policy page, and users will be allowed access if they are a member of any of the specified roles; otherwise they will be directed to a suitable J2EE container delegated authentication page to establish the required credentials. If no roles are entered in the list, anonymous access is allowed, and the resource is termed as an "anonymous resource".

Note:

The role name(s) entered on this page must match those created in the J2EE container (such as Oracle WebLogic Server).
62.3.1.1.4 Configuring Autologin

The Autologin feature allows Pagelet Producer to supply credentials to applications automatically. The Autologin page (see Figure 62-11) lets you configure authentication information for all users who access the resource.

Figure 62-11 Pagelet Producer Console: Resource - Autologin Page

Description of Figure 62-11 follows
Description of "Figure 62-11 Pagelet Producer Console: Resource - Autologin Page"

The following sections describe how to configure credential mapping for authentication:

62.3.1.1.5 Configuring Autologin: Form Login

This section describes how to configure Autologin for a resource that prompts for authentication with an HTML form.

  1. On the Autologin page for the resource, expand the Form Login section (Figure 62-12).

    Figure 62-12 Autologin Page - Form Login

    Description of Figure 62-12 follows
    Description of "Figure 62-12 Autologin Page - Form Login"

  2. The login page can be identified by an URL or a regular expression. In the Login Form Identification section, choose one of the following options:

    • If the login form is located at a static URL, select URL and enter the URL in the Value field. You can choose to Automatically Detect Form Fields on the page or enter them manually as described in step 4 below.

    • If the login form is dynamic, select RegEx and type the regular expression pattern into the box.

  3. Set the login form action. In the Form Submit Location section, choose one of the following options:

    • If the login form action is a static URL, select URL and type the URL into the box. Choose the action for the form submission: POST or GET.

    • If the login form is dynamic, select RegEx and type the regular expression pattern into the box.

  4. To map fields from the form to authentication field sources, either click Automatically Detect Form Fields in the Login Form Identification section as described above or enter them manually using the process below:

    1. Click Create to add a new row to the Form Fields list.

    2. Enter the name of the HTML form input in the Field Name box.

    3. For details on how to configure the Source and Value properties, see Section 62.3.1.1.8, "Configuring Autologin: Authentication Sources."

      Note:

      Sensitive fields should be stored securely using the credential vault (User Vault or Secured).
    4. To delete field mappings, click Delete.

  5. The logout page and login error pages can also be identified by an URL or a regular expression. In the Logout Page Identification and Login Error Page Identification sections, choose one of the following options:

    • If the page is located at a static URL, select URL and type the URL into the field provided.

    • If the page is dynamic, select RegEx and type the regular expression pattern into the field provided.

62.3.1.1.6 Configuring Autologin: Basic Login and NTLM Login

This section describes how to configure autologin for a resource that prompts for authentication with basic authentication or NTLM.

  1. On the Autologin page for the resource, expand the Basic Login or NTLM Login section.

    Note:

    Basic authentication transmits passwords as plain text, and therefore, it must not be used in production systems. Further, it is strongly recommended that the underlying transport is HTTPS.
  2. In the Username and Password sections, choose the appropriate authentication source and enter a value as necessary. For details on how to configure these properties, see Section 62.3.1.1.8, "Configuring Autologin: Authentication Sources.".

62.3.1.1.7 Configuring Autologin: Kerberos Login

This section describes how to configure autologin for a resource that prompts for authentication using Kerberos. For information on defining basic Kerberos settings, see Section 62.2, "Configuring Pagelet Producer Settings."

  1. On the Autologin page for the resource, expand the Kerberos Login section.

  2. In the Username and Password sections, choose the appropriate authentication source and enter a value as necessary. For details on how to configure these properties, see the next section, Section 62.3.1.1.8, "Configuring Autologin: Authentication Sources."

  3. In the SPN field, enter the Service Principal Name (SPN) for the Kerberos account, in the format http://hostname_with_kerberos. (Before the Kerberos authentication service can use an SPN to authenticate a service, the SPN must be registered on the account object that the service instance uses to log on.)

62.3.1.1.8 Configuring Autologin: Authentication Sources

Authentication sources define the source for login fields. Table 62-2 describes each of the authentication field source values:

Table 62-2 Pagelet Producer Authentication Sources

Field Description

Unsecured

Uses the provided authentication information for all users accessing the resource. Type the static value in the field provided.

Secured

Uses the field value is entered by an administrator in the Pagelet Producer Administration Console. The value is stored in the Credential Vault and is shared among all users, including non-authenticated (anonymous) users. The field key is auto-generated and displayed as a read-only field in the Administration Console.

User Vault

Prompts the user for credentials the first time the resource is accessed. The supplied credentials are encrypted and stored in the credential vault, and each subsequent access to the resource is authenticated with the stored credentials. The field key is auto-generated and displayed as a read-only field in the Administration Console.In the second field, enter the name of the credential vault to use, or leave the entry as "default" to use the server vault.

Note: When you choose User Vault, the user will be presented with an error page that includes a link: "Click here to access pagelet directly." This link opens the authentication dialog. This is a known issue and occurs only the first time the resource is accessed by a user.

Generated

(Form Login only) The field value is taken from the backend server response markup.


62.3.1.1.9 Configuring Headers

The Headers page (see Figure 62-13) lets you choose request and response headers that should be dropped from the HTTP that is provided by Pagelet Producer.

Figure 62-13 Pagelet Producer Console: Resource - Headers Page

Description of Figure 62-13 follows
Description of "Figure 62-13 Pagelet Producer Console: Resource - Headers Page"

Some header elements should be blocked from being passed to back-end applications. For example, when using delegated (third-party SSO) authentication, the SSO system might insert some headers that need not be passed to the back-end applications. When passed, these headers might interfere with the back-end application functionality.

The following headers are dropped by default:

Request Headers Response Headers
- Cache-Control

- Connection

- Cookie

- Host

- Max-Forwards

- Pragma

- Proxy-Connection

- Proxy-Authorization

- TE

- Trailer

- Transfer-Encoding

- Upgrade

- Max-Forwards

- Proxy-Authenticate

- Proxy-Connection

- Set-Cookie

- Trailer

- Transfer-Encoding

- Upgrade


The Content-Length header is always implicitly dropped, because manipulating content during the proxying operation renders the content length invalid in almost all cases.

To add a header to the list, click Create and enter the header name in the field provided.

Once the Web or CSP resource is defined, you can create pagelets and other objects. For more information, see the following sections:

62.3.1.2 Configuring WSRP and JPDK Resources

This section describes how to configure WSRP/JPDK resources based on WSRP or Oracle JPDK portlet producers.

Note:

Before you can create a resource based on a WSRP or Oracle JPDK portlet producer, you must register the producer as described in the "Managing the Pagelet Producer" chapter in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

This section includes the following subsections:

62.3.1.2.1 Configuring General Settings

Use the General page to enter basic information about a WSRP or JPDK resource.

62.3.1.2.2 Configuring Policy Settings

The Policy page lets you limit access to a resource to specific roles within Oracle WebCenter Portal.

The J2EE container hosting Pagelet Producer (such as Oracle WebLogic Server) is responsible for establishing the role memberships associated with the current user. A resource can specify multiple roles on the Policy page, and users will be allowed access if they are a member of any of the specified roles; otherwise they will be directed to a suitable J2EE container delegated authentication page to establish the required credentials. If no roles are entered in the list, anonymous access is allowed, and the resource is termed as an "anonymous resource".

Note:

The role name(s) entered on this page must match those created in the J2EE container (such as Oracle WebLogic Server).

Once the WSRP or JPDK resource is defined, you can create pagelets and Web injectors. See the following sections for more information:

62.3.1.3 Configuring OpenSocial Resources (OpenSocial Gadget Producers)

This section describes how to configure OpenSocial resources based on OpenSocial gadget producers.

Note:

Configure Pagelet Producer for use with OpenSocial before creating an OpenSocial resource. For more information, see Section 62.2.7, "Configuring OpenSocial Settings."
62.3.1.3.1 Configuring General Settings

Use the General page to enter basic information about the resource.

  • Enter a Name for the resource.

  • Enter a Description for the resource (optional).

62.3.1.3.2 Configuring Policy Settings

The Policy page lets you limit access to a resource to specific roles within Oracle WebCenter Portal.

The J2EE container hosting Pagelet Producer (such as Oracle WebLogic Server) is responsible for establishing the role memberships associated with the current user. A resource can specify multiple roles on the Policy page, and users will be allowed access if they are a member of any of the specified roles; otherwise they will be directed to a suitable J2EE container delegated authentication page to establish the required credentials. If no roles are entered in the list, anonymous access is allowed, and the resource is termed as an "anonymous resource".

Note:

The role name(s) entered on this page must match those created in the J2EE container (such as Oracle WebLogic Server).

Once the OpenSocial resource is defined, you can create pagelets and files. Refer to the following sections for more information:

62.3.2 Creating Pagelets

The pagelets collection lists the pagelets associated with the resource. To create a new pagelet, select the Pagelets section under the resource you want to use in the Pagelet Producer Console and click the Create icon in the toolbar. A pagelet called "<new>" will be added to the list. To modify an existing pagelet, click the pagelet name.

This section contains the following subsections:

62.3.2.1 Configuring General Settings

Enter a Name for the pagelet and the Library name with which to associate the pagelet. (A pagelet library is a user-defined way to group related pagelets.) Enter a Description for the pagelet (optional).

  • For Web and CSP pagelets, type the relative path to the pagelet in the URL Suffix field (do not include the Source URL prefix you entered for the resource). If you leave the URL Suffix blank, then the entire resource will be considered the pagelet.

  • For pagelets based on WSRP or Oracle JPDK portlets, choose the portlet on which to base the pagelet from the Portlet dropdown list. This list is populated with the portlets on the WSRP or Oracle JPDK portlet producer associated with the parent resource. Any public parameters associated with the portlet will automatically be imported as pagelet parameters. For more information on support for WSRP and Oracle JPDK portlets, see Section 62.4, "Working with Pagelet Chrome for WSRP and Oracle JPDK Portlets."

  • For pagelets based on OpenSocial gadgets, enter the location of the gadget XML schema in the Gadget URL field. Click the Import Gadget Metadata button to import the following information from the XML schema:

    • Gadget name: This value will be imported into the Description field on the General page.

    • Gadget user preferences: The pagelet parameters on the Configuring Parameters page will be populated with the gadget's user preferences.

    For more information on support for OpenSocial gadgets, see Section 62.5, "Working with OpenSocial Gadgets."

To block access to the pagelet, choose Disabled. If the pagelet is included on any pages, it will display a simple error message.

62.3.2.2 Configuring Preferences

On the Preferences page (see Figure 62-14), enter the relative URLs to any preference pages required by the pagelet: Global, Customize, or Personalize. Do not include the Source URL prefix you entered for the resource. (As noted above, for OpenSocial gadgets with user preferences, a default entry will be created; this entry should not be modified.)

The Preferences page is not used by WSRP or Oracle JPDK-based pagelets.

Figure 62-14 Pagelet Producer Console: Pagelets - Preferences Page

Description of Figure 62-14 follows
Description of "Figure 62-14 Pagelet Producer Console: Pagelets - Preferences Page"

62.3.2.3 Configuring Parameters

Data can be passed to pagelets using pagelet parameters. Parameters pass name-value pairs to the pagelet application as described below.

On the Parameters page (see Figure 62-15), enter the Parameters that should be passed to the pagelet.

To add a parameter, click Create.

  • Enter the Name of the parameter.

  • If the parameter is required by the pagelet, select the Required checkbox.

  • Choose the appropriate data Type: string or numeric.

  • Enter a Description (optional).

Figure 62-15 Pagelet Producer Console: Pagelets - Parameters Page

Description of Figure 62-15 follows
Description of "Figure 62-15 Pagelet Producer Console: Pagelets - Parameters Page"

62.3.2.4 Configuring the Clipper

Clipping lets you create a pagelet by clipping a portion of a larger Web page in a proxied application. A news Web page, for example, may contain a box listing the latest headlines. By identifying the containing HTML for that box, you can clip only the headlines and serve that subset of the news Web page as a pagelet.

To create a clipper, select the Clipper section under the pagelet and click the Create icon in the toolbar. A new clipper will be created with two configuration pages:

  • On the General page, enter a name for the clipper.

  • On the Content page (see Figure 62-16), define the clipper content.

    Figure 62-16 Pagelet Producer Console: Clipper - Content Page

    Description of Figure 62-16 follows
    Description of "Figure 62-16 Pagelet Producer Console: Clipper - Content Page "

    • To use a graphical tool to select page content, click Launch Clipper.

    • To specify HTML tag attributes that describe the section to be clipped, expand the Advanced Clipper section and enter the tag name and associated attribute(s).

Keep the following in mind when using the clipper:

  • If the back-end resource is accessed over HTTPS, make sure the Pagelet Producer Console is also accessed over a secure port.

  • If the clip source is protected by a login form or other form of authentication, make sure to configure Autologin for the parent resource as described in Section 62.3.1.1.4, "Configuring Autologin." If you are using the vault to store credential values, make sure to capture the credentials prior to using the clipper.

  • If you are having problems with the clipper, make sure the configured pagelet URL can be loaded by the browser without redirects. If necessary, change the pagelet suffix to reflect the final URL loaded by the browser after following all the redirects.

  • Images and code overwritten using hosted files cannot be clipped. (For more information about hosted files, see Section 62.3.5, "Creating Hosted Files.")

62.3.2.5 Accessing the Pagelet and Preference Editor

Use the Documentation page (see Figure 62-17) to display sample code with which to access the pagelet and preference editor using either JavaScript or the REST API.

Figure 62-17 Pagelet Producer Console: Pagelets - Documentation Page

Description of Figure 62-17 follows
Description of "Figure 62-17 Pagelet Producer Console: Pagelets - Documentation Page "

62.3.3 Creating Web Injectors

A Web injector inserts content into a specified location in the proxied resource page. The content may be any text, including HTML, CSS, JavaScript, and pagelet declarations. An empty injector may also be used to remove unwanted content from a page. Injectors cannot be created for OpenSocial resources.

To create a Web injector, select the Injectors section under the resource you want to use and click the Create icon in the toolbar. A new injector called "<new>" will be added to the list. Injectors can then be configured using the General and Content configuration pages as described in the following sections:

62.3.3.1 Configuring General Settings

Use the General page (see Figure 62-18) to configure basic settings for the injector.

Enter a Name for the Web injector.

The injector can be applied to a subset of the resource by typing a URL pattern into the URL Filter box. The injector will be applied only to those URLs within the resource that begin with the text in the URL Filter box. If the box is empty or contains only a '/', the injector will be applied to the entire resource.

To restrict the injector to specific kinds of content, type a comma separated list of MIME types in the MIME Filter box. For example, text/html restricts the injector to HTML content, while text/css only restricts the injector to CSS content.

In the Inject Location section, define where in the resource's output the injection will be made in relation to a unique string. Enter the unique string in the field provided and choose Before, After or Replace to define where to put the content relative to the string. If you choose to replace the string, you can use the Enclose tag to replace both the string and the enclosing tag. You can choose to ignore the case of the string by selecting Ignore case.

Figure 62-18 Pagelet Producer Console: Injectors - General Page

Description of Figure 62-18 follows
Description of "Figure 62-18 Pagelet Producer Console: Injectors - General Page"

62.3.3.2 Injecting Content

Use the Content page to define content to be injected using the injector. Content to be injected may be any text, including HTML, CSS, JavaScript, and pagelet declarations.

For example, the following code could be injected at the beginning of a page. The example registers a handler function with the page load event and then uses the handler to modify the page markup (by finding and hiding the header and footer).

<script type="text/javascript">
if (window.addEventListener) {
  window.addEventListener('load', hideHeaderFooter, false);
} else if (document.attachEvent) {
  window.attachEvent('onload', hideHeaderFooter);
}
function hideHeaderFooter() {
  var header = null;
  // find the header table by class 
  if (document.getElementsByClassName) {
    header = document.getElementsByClassName('page_header')[0];
  } else {
    // for older versions of IE
    var tables = document.getElementsByTagName('table');
    for (var table in tables) {
      if (table.class == 'page_header') {
        header = table;
        break;
      }
    }
  }
  if (header != null) {
    header.style.display = 'none';
  }
  // now find and hide the footer (easier to find, since it has an id)
  var footer = document.getElementById('t23PageFooter');
  if (footer != null) {
    footer.style.display = 'none';
  }
}
</script>

62.3.4 Creating Custom Parsers

Custom parsers allow you to supplement or change built-in logic for parsing content and finding URLs. When the built-in parsers fail to identify URLs or identify sections that must not be rewritten as URLs, custom parsers can be used to change the default behavior. Note that parsers cannot be created for WSRP or Oracle JPDK portlet producers or OpenSocial gadget producers.

To create a custom parser, select the Parsers section under the resource you want to use and click the Create icon in the toolbar to display the Parser's General page (see Figure 62-19):

  • Enter a Name for the parser.

  • The parser can be applied to a subset of the resource by typing a URL pattern into the URL Filter box. The parser will be applied only to those URLs within the resource that begin with the text in the URL Filter box. If the box is empty or contains only a '/', the parser will be applied to the entire resource.

  • To add a new parsing rule, click Create to add a new row to the Fragment Locations section.

  • In the Regular Expressions column, enter the regular expression for identifying the URL fragment that should be transformed. The first grouping expression (in parentheses) identifies the fragment, and the rest of the expression provides the context for finding it.

  • Choose the Fragment Type to define how the selected location should be parsed:

    • Static URLs are transformed on the server.

    • Dynamic URLs are transformed using JavaScript on the client.

    • HTML Fragment and Javascript Fragment types are used for content that is embedded in another content type, such as XML.

    • No Rewriting specifies a location that should not be searched for URLs. This option is used to prevent rewriting of markup mistakenly identified as URLs.

  • Click the Save icon in the navigator toolbar.

Figure 62-19 Pagelet Producer Console: Parsers - General Page

Description of Figure 62-19 follows
Description of "Figure 62-19 Pagelet Producer Console: Parsers - General Page"

For example, the regular expression XMLFile=(.*?)" would identify URLs to XML files defined within a tag, as in <embed src="/i/flashchart/anychart_5/swf/OracleAnyChart.swf?>XMLFile=http://apexapps.oracle.com/pls/apex/apex_util.flash?p=53557:1:74175370346201:FLOW_FLASH_CHART5_R45192463162785599619_en".

62.3.5 Creating Hosted Files

Pagelet Producer can host all types of content (HTML, JavaScript, CSS, etc.) and present the file at a virtual URL location. Hosted files can be used for a range of purposes:

  • Overwrite content and functionality in a proxied application, by uploading files and configuring them to use the same URL as the original file.

  • Use hosted files in injectors to insert images or content into a proxied application.

  • Host pagelet files on the Pagelet Producer server.

To upload a file, select the Files section under the resource you want to use and click the Create icon in the toolbar.

  • On the General page (see Figure 62-20), enter the relative path to the file in the Name field. Do not use a leading forward-slash ("/"). The directory structure of the Files collection in the navigator is updated to match the path to the file.

    Enter the MIME type of the file.

    Figure 62-20 Pagelet Producer Console: Files - General Page

    Description of Figure 62-20 follows
    Description of "Figure 62-20 Pagelet Producer Console: Files - General Page"

  • On the Content page, enter the path to the file or click Browse to navigate to the file.

    Click Upload to upload the file to the Pagelet Producer server. If you entered text or html as the MIME type, you can also use the editor on the Content page to enter or edit file content. (The editor is only available for text and html files.) If you entered an image type as the MIME type, the uploaded image will be displayed on the Content page.

    Note:

    Text files (text/plain) uploaded to the Pagelet Producer must be saved as UTF-8.
  • Click the Save icon in the navigator toolbar.

After the file is uploaded, it will be available for use in injectors and pagelets at the following URL: http://<host_name>:<port_number>/pagelets/<resourcename>/<filepath>.

For example, if the file was uploaded under the "welcome_resource" resource and the name for the file was entered as "images/myimage.jpg" the path to the hosted file on the Pagelet Producer server would be: http://<host_name>:<port_number>/pagelets/welcome_resource/images/myimage.jpg

Keep the following in mind when working with hosted files:

  • The hosted file feature should not be used for bulky files.

  • If you choose to host OpenSocial gadget XML files, the files must be placed under an anonymous resource (with no security policy) or gadget functionality will not work correctly.

  • Hosted files cannot be created for WSRP or Oracle JPDK portlet producers.

62.4 Working with Pagelet Chrome for WSRP and Oracle JPDK Portlets

Pagelet Producer can be used to present WSRP and Oracle JPDK portlets for use in any Web application. This section explains how to use pagelet chrome to modify markup at runtime in WSRP or Oracle JPDK portlets. For details on configuring the Pagelet Producer to connect to a WSRP or Oracle JPDK portlet producer, see the "Managing the Pagelet Producer" chapter in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

A pagelet chrome template is an HTML file that specifies:

  • How portlet markup should be rendered stylistically

  • How to display the portlet title

  • How to render mode switching options

The default chrome template displays the portlet name and a dropdown menu that allows the user to switch into different modes. The dropdown menu is dynamically populated with all the standard modes supported by the underlying portlet. Templates use the following reserved tokens (see Table 62-3) to identify key portlet elements that Pagelet Producer then substitutes at runtime.

Table 62-3 Pagelet Chrome Template Tokens

Token Description
$$PORTLET TITLE$$

Portlet title

$$REPEAT MENU ITEM$$

Used to indicate the beginning of a repeating section for navigational items

$$END REPEAT MENU ITEM$$

Used to indicate the end of a repeating section for navigational items

$$MENU ITEM URL$$

Navigation URL (to switch portlet modes or window states)

$$MENU ITEM$$ 

Display name of navigational item (for example, Customize)

$$TOKEN$$

Unique identifier for pagelet instance on the page

$$PORTLET CONTENT$$

Portlet content

pt://images

Tag used to indicate the imageserver URL


The example below is a very simple pagelet chrome template:

<script type="text/javascript">
function goto(url)
{
  document.location = url;
  return false;
}
</script>
<div style="border: 1px solid">
<span><b><!-- $$PORTLET TITLE$$ --></b></span>
<span style="align: right">
  Switch Mode:
  <select size="1" name="mode">
    <!-- $$REPEAT MENU ITEM$$ -->
    <option onclick="goto('$$MENU ITEM URL$$')"><!-- $$MENU ITEM$$ --></option>
    <!-- $$END REPEAT MENU ITEM$$ -->
  </select>
 
</span>
</div>
<!-- $$PORTLET CONTENT$$ -->

Note:

The pagelet chrome template file must be hosted on the classpath of the Pagelet Producer Web application.

If you configured Pagelet Producer to use an external image server, copy the files from ensemblestatic.war/imageserver/yahoo to your image server to properly render the default chrome template.

To implement the chrome template, add it as a parameter to the pagelet inject URL (REST or JavaScript). For details on pagelet inject URLs, see Section 62.7.2, "Adding a Pagelet to a Web Page." For example:

  • REST: /inject/v2/pagelet/pagelet_lib/pagelet_name?chrome=mychrome.html

  • JavaScript: injectpagelet(library, name, iframe_options, payload, params, context_id, element_id, is_in_community, chrome)

The value of the chrome parameter can be the name of the file containing the chrome template or the special reserved value "none", which suppresses all chrome and sends back portlet markup only. If the chrome parameter is omitted, the default chrome is returned with the portlet markup. The default chrome template uses YUI menu control to display a gradient title bar and a DHTML dropdown menu for switching modes. (When ADF content is detected, a different chrome template is used by default. This template can be overridden with a custom template or with the standard default template by setting chrome=chrometemplate.html.)

62.5 Working with OpenSocial Gadgets

Any OpenSocial gadget reachable by the Pagelet Producer server can be registered as a pagelet and used in any Web application, including a portal. To support OpenSocial gadgets, you must first define an OpenSocial container as described in Section 62.2.7, "Configuring OpenSocial Settings."

Pagelet Producer supports most of the standard OpenSocial APIs excluding OAuth. The complete OpenSocial API reference documentation can be found here:

http://docs.opensocial.org/display/OSD/Specs

Pagelet Producer also allows gadgets to store preferences, retrieve WebCenter Portal profile and connection information, and access a user's activity stream using OpenSocial APIs.

This section contains the following subsections:

62.5.1 Configuring Authentication

In order for gadgets to request user-level data (preferences or people connections), the end user's identity must be established. If any OpenSocial gadgets need to access user-level data from the server, you must configure a security policy for the parent OpenSocial resource in the Pagelet Producer Console (see Section 62.3.1.3.2, "Configuring Policy Settings"). The first time a user accesses an OpenSocial gadget, a login page will be presented. After the initial login, subsequent requests for OpenSocial gadgets will use the established user identity.

62.5.2 Storing User Preferences

OpenSocial gadgets may use user preferences to store data at the container. User preferences are scoped to a particular user and may optionally be scoped to an appId (the gadget appId is the pagelet context ID). If you choose to use the OpenSocial gadget.Prefs API, the user preferences will be scoped to the user and pagelet instance. Alternatively, you may use the opensocial.DataRequest API to manage preferences at the user level that can be shared with other pagelets.

When registered as a pagelet, a gadget's user preferences are treated as pagelet preferences. In WebCenter Portal, for example, non-hidden user preferences can be edited by the end user using the Personalize button. Additionally, to simulate preferences shared between users, you may pass in user preferences via pagelet parameters. Note that a pagelet preference, if set, will always override the corresponding pagelet parameter (in other words, personalization takes precedence over customizations).

Outside of WebCenter Portal, gadget-backed pagelets are provided with a simple chrome that displays the gadget title and buttons for accessing the preference editor and minimizing/maximizing the gadget. The chrome may be suppressed by passing in the value of 'none' to the chrome parameter in the Pagelet Inject API. The preference editor UI supports all four types of user preferences:

  • string: rendered as a text field

  • bool: rendered as a checkbox

  • enum: rendered as a dropdown list

  • list: rendered as a text field (values must be separated with a pipe "|" character)

62.5.3 Accessing WebCenter Portal Profile Information

OpenSocial gadgets can query the current user's profile data and people connections via the standard OpenSocial API. To use this feature, you must manually target the WebCenterDS data source to the WC_Portlet server as described in the "Managing the Pagelet Producer" chapter in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

Note:

The OpenSocial API cannot be used to update profile or connection information.

The supported user profile fields are listed in Table 62-4.

Table 62-4 User Profile Fields

OpenSocial Field Type Description

aboutme

string

A general statement about the person.

addresses

Plural-Field <Address>

A physical mailing address for the person.

appData

Plural-Field <AppData>

A collection of AppData keys and values, used for preferences.

birthday

Date

The birthday of the person. The value MUST be a valid Date. The year may be set to 0000 when the age of the person is private or the year is not available.

emails

Plural-Field <string>

Email address for the person.

location

string

Physical address for the person.

name

Name

The broken-out components and formatted version of the person's real name.

organizations

Plural-Field <Organization>

Current or past organizational affiliation of the person.

phoneNumbers

Plural-Field <string>

Phone number for the person. In addition to the standard canonical values for type, this field defines the additional values mobile, fax, and pager.

photos

Plural-Field <string>

URL to a photo of the person. The value MUST point to an actual image file (e.g. a GIF, JPEG, or PNG image file) rather than to a Web page containing an image. Note that this field SHOULD NOT be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact suitable for display when describing the contact.

preferredUsername

string

The preferred username of this person on sites that ask for a username (e.g. jsmarr or daveman692).

status

string

The person's status, headline or shoutout.

thumbnailUrl

string

The person's photo thumbnail URL, specified as a string. This URL MUST be fully qualified.


62.5.4 Accessing a User's Activity Stream

OpenSocial gadgets can operate on a user's activity stream using OpenSocial APIs. The following operations are supported:

  • get activities

  • create activity

The following operations are not supported:

  • update activity

  • delete activity

The supported activity stream fields are listed in Table 62-5.

Table 62-5 Activity Stream Fields

OpenSocial Field Type Description

appId

Object-Id

The application with which the activity is associated.

body

string

An optional expanded version of the activity. Bodies may only have the following HTML tags: <b> <i>, <a>, <span>, but this formatting may be ignored.

externalId

Object-Id

An optional ID generated by the posting application.

id

Object-Id

An ID that is permanently associated with the activity.

postedTime

string

The time at which the activity took place in milliseconds since the epoch.

priority

number

A number between 0 and 1 representing the relative priority of the activity in relation to other activities from the same source.

title

string

The primary text of the activity. Titles may only have the following HTML tags: <b> <i>, <a>, <span>, but this formatting may be ignored.

userId

Object-Id

ID of the user for whom the activity is defined.


62.5.5 Using Gadget Eventing

Pagelet Producer supports the OpenSocial pubsub inter-gadget eventing model. A gadget may publish events over any number of arbitrary channels (defined by simple string names) in JavaScript. On the receiving end, a gadget may subscribe to receive events over any number of channels, again in JavaScript, and take appropriate actions based on the events.

function connSelected(element) {
  var connId = element.id;
  var connName = element.lastChild.textContent;
  gadgets.pubsub.publish(channel, {id: connId, name: connName});

For a complete JavaScript reference to the supported eventing API, see:

http://docs.opensocial.org/display/OSD/Specs

62.5.6 Example: Consuming an External OpenSocial Gadget

The example that follows is simplified for illustration. To support OpenSocial gadgets, you must first define an OpenSocial container as described in Section 62.2.7, "Configuring OpenSocial Settings."

  1. Using the Pagelet Producer Console, create a new Resource and choose OpenSocial as the type. Define URLs and policies as necessary. Save the new Resource.

  2. Using the Pagelet Producer Console, create a new pagelet and enter the location of the gadget XML schema in the Gadget URL field.

    • To import the gadget name and any user preferences defined for the gadget, click the Import Gadget Metadata button. If any of the preferences are editable, Pagelet Producer will create a preference editor using the imported preferences.

    • To configure or customize the generated preference editor, go to the Pagelet Parameters page.

  3. Go to the Documentation page to view sample code to access the pagelet and preference editor using either the JavaScript or REST API.

  4. Save the new pagelet.

62.5.7 Example: Consuming a Local OpenSocial Gadget

The example that follows is simplified for illustration. To support OpenSocial gadgets, you must first define an OpenSocial container as described in Section 62.2.7, "Configuring OpenSocial Settings."

  1. Using the Pagelet Producer Console, create a new Resource and choose OpenSocial as the type. Define URLs and policies as necessary. Save the new Resource.

  2. Create or upload the gadget file.

    Note:

    If you choose to host OpenSocial gadget XML files, the files must be placed under an anonymous resource (with no security policy) or gadget functionality will not work correctly.
    1. Select the Files section under the resource and click the Create icon in the toolbar.

    2. On the General page, enter the relative path to the file in the Name field. Do not use a leading forward-slash ("/"). For example, "gadgets/activities.xml". Any path and name can be used; the path is a 'virtual' URL that Pagelet Producer will use to serve the file. The visual directory structure of the Files collection in the navigator is updated to match the path to the file.

    3. Go to the Content page to upload or create the gadget file.

      To upload a gadget file, enter the path to the file or click the Browse button to navigate to the file, then click the Upload button to upload the file to the Pagelet Producer server.

      To create a gadget file, use the editor on the Content page to enter and edit content.

    4. Click the Save icon in the navigator toolbar.

  3. Create or upload any other files required by the gadget (JavaScript, images, etc.) in the Files section of the resource. Define paths for the files that match the paths in the gadget code. For example, if the gadget uses JavaScript files in a subfolder called "js", include that directory in the Name field when you upload the files, e.g., "gadgets/js/activities.js".)

  4. Using the Pagelet Producer Console, create a new pagelet and enter the relative path to the gadget XML schema (created or uploaded in step 2) in the Gadget URL field. For local files, this is the same path defined in the Name field for the file object; for example, "gadgets/activities.xml".

    • To import the gadget name and any user preferences defined for the gadget, click the Import Gadget Metadata button. If any of the preferences are editable, Pagelet Producer will create a preference editor using the imported preferences.

  5. Go to the Documentation page to view sample code to access the pagelet and preference editor using either the JavaScript or REST API.

  6. Save the new pagelet.

62.6 Building Custom Pagelets Using Pagelet Producer

This section provides detailed information about building pagelets using Pagelet Producer, including how to use the Adaptive Pagelet Scripting Framework, configure security settings for pagelets and resources to manage authentication for users, use custom Web injectors and parsers to modify pagelet functionality at runtime, and access advanced logging traces for debugging.

This section contains the following subsections:

62.6.1 Using the Adaptive Pagelet Scripting Framework

The Adaptive Pagelet Scripting Framework is a client-side JavaScript library that provides services to CSP pagelets and proxied pages. This section explains how to use the scripting framework to implement dynamic functionality in pagelets.

Note:

CSP (and the Adaptive Pagelet Scripting Framework) only applies to WCI and its predecessor, Plumtree Portal. WebCenter Portal does not support WebCenter Portal.

This section includes the following subsections:

For a full list of classes and methods, see the JSPortlet API documentation. For additional information about adaptive pagelets, see Section 62.6.1.5, "Adaptive Pagelet Development Tips."

62.6.1.1 Handling Structured HTTP Responses

This section describes how the adaptive pagelet scripting framework can be used as a client-side response handler for structured HTTP, typically encoded as XML.

In many cases it can be expensive and inefficient to send large amounts of HTML back in response to some HTTP request, if only a small part of the user interface needs to be changed. This is especially true with more complex user interfaces. In these cases, the response can be encoded in XML. The client-side response handler can then parse the XML, and update the user interface (or perform some other action) based on that response. Use the Structured Response design pattern to redraw a small area of the user interface after making an HTTP request, or to access a simple HTTP/URI type Web service from a pagelet. The example code below (structuredresponse_portlet.html) accesses an RSS feed from a selection of news sites.

<!-- jsxml includes -->
<a id="imgServerHref" href="/images/plumtree" style="display:none"></a>
<script type="text/javascript"
src="/images/plumtree/common/private/js/PTLoader.js"></script>
<script type="text/javascript">
var oImgServer = new Object();
oImgServer.location = document.getElementById('imgServerHref').href;
var imageServerURL = document.getElementById('imgServerHref').href;
var imageServerConnectionURL = oImgServer.location;
new PTLoader(imageServerURL, imageServerConnectionURL).include('jsxml','en');
</script>

<!-- jscontrols includes -->
<link rel="stylesheet" type="text/css" href="/portal-remote-server/js/jscontrols/styles/css/PTMenu.css"/>
<link rel="stylesheet" type="text/css" href="/portal-remote-server/js/jscontrols/styles/css/PTRichTextEditor.css"/>
<script type="text/javascript" src="/portal-remote-server/js/jscontrols/strings/PTControls-en.js"></script>
<script type="text/javascript" src="/portal-remote-server/js/jscontrols/PTControls.js"></script>

<!-- Inline JS helper functions -->
-->

<script defer type="text/javascript" id="structured-response-portlet-A-script">
// Function that gets the RSS XML feed found at the specified url
getRSSFeed = function(url)
  {
  // First clear out any existing rows in the table
  channelTable.clearRows();

  // Force the transformer to fix up the url
  var oURL = new Object();
  oURL.location = url;

  // Do the http get
  var get = new PTHTTPGETRequest(oURL.location, handleRSSResponse);
  get.invoke();
  }

// Function that handles the RSS XML response and updates the table based on the RSS items
handleRSSResponse = function(response)
  {
  // Get the rss xml
  var xml = response.responseText;
  if (!xml || xml.indexOf('<?xml') == -1) { return; }

  // Parse into a dom, and get the channel node
  var xmlDOM = new PTXMLParser(xml);
  var rssNode = xmlDOM.selectSingleNode('rss');
  var channelNode = rssNode.selectSingleNode('channel');

  // Get the channel title and set the status bar text in the table
  var channelTitle = channelNode.selectSingleNode('title').getNodeValue();
  channelTable.statusBarText = '<b>Loaded Channel</b>: ' + channelTitle;

  // Get channel item nodes
  var itemNodes = channelNode.selectNodes('item');
  
  // Build table rows
  channelTable.rows = new Array();
  for (var i=0; i<itemNodes.length; i++)
    {
    var itemNode = itemNodes[i];

    // Get channel item properties
    var itemTitle = itemNode.selectSingleNode('title').getNodeValue();
    var itemLink = itemNode.selectSingleNode('link').getNodeValue();
    var itemDescription = itemNode.selectSingleNode('description').getNodeValue();
    if (itemNode.selectSingleNode('author'))
      var itemAuthor = itemNode.selectSingleNode('author').getNodeValue();
    if (itemNode.selectSingleNode('category'))
      var itemCategory = itemNode.selectSingleNode('category').getNodeValue();
    if (itemNode.selectSingleNode('pubDate'))
      var itemPubDate = itemNode.selectSingleNode('pubDate').getNodeValue();

    // Create a row and add it to the table
    var row = new PTRow();
    row.parent = channelTable;
    row.id = i;
    row.uid = i;
    row.previewText = itemDescription;
    row.link = itemLink;
    row.columnValues[0] = new PTTextColumnValue(itemTitle);
    row.columnValues[1] = new PTTextColumnValue(itemCategory);
    row.columnValues[2] = new PTTextColumnValue(itemAuthor);
    row.columnValues[3] = new PTTextColumnValue(itemPubDate);
    channelTable.rows[channelTable.rows.length] = row;
    }

  // Redraw the table
  channelTable.draw();
  }
</script>

<b>Select RSS Feed:</b>
<a href="#" onclick="getRSSFeed('http://www.wired.com/news/feeds/rss2/0,2610,,00.xml'); return false;">Wired News</a>
<a href="#" onclick="getRSSFeed('http://news.com.com/2547-1_3-0-5.xml'); return false;">CNET News.com</a>
<a href="#" onclick="getRSSFeed('http://partners.userland.com/nytRss/nytHomepage.xml'); return false;">NY Times</a>
<br><br>

<!-- Set up a table control to display channel items -->
<div id="channelTableContainer"></div>
<script defer type="text/javascript">
  var channelTable = new PTTableControl();
  channelTable.locale = 'en_US';
  channelTable.objName = 'channelTable';
  channelTable.container = 'channelTableContainer';
  channelTable.baseURL = '/imageserver/plumtree/common/private/portal-remote-server/js/jscontrols/1/';
  channelTable.statusBarText = 'No RSS Feed Selected';
  channelTable.rowDetailAction = new PTJavaScriptAction('window.open(\'${ROW.link}\');');
  channelTable.columns[0] = new PTColumn();
  channelTable.columns[0].name = 'Title';
  channelTable.columns[0].width = '40%';
  channelTable.columns[1] = new PTColumn();
  channelTable.columns[1].name = 'Category';
  channelTable.columns[1].width = '20%';
  channelTable.columns[2] = new PTColumn();
  channelTable.columns[2].name = 'Author';
  channelTable.columns[2].width = '20%';
  channelTable.columns[3] = new PTColumn();
  channelTable.columns[3].name = 'Publication Date';
  channelTable.columns[3].width = '20%';
  channelTable.areColumnsResizable = true;
  channelTable.clientSortEnabled = true;
  channelTable.scrollHeight = 250;
  channelTable.init();
  channelTable.draw();
</script>
</div>

62.6.1.2 Using Event Notification

This section describes how the adaptive pagelet scripting framework allows pagelets to respond to both page-level events and custom events raised by other pagelets.

The registerForWindowEvent and registerOnceForWindowEvent methods in the scripting framework provide pagelets with access to page-level events. For a complete list, see Section 62.6.1.2.1, "Page-Level Events for Use with the Scripting Framework." To register for notification of these events, pass in the name of the event and the name of the method that should be called when it occurs. When a page-level event is raised, the JavaScript event object is passed to the event handler as an argument. The scripting framework also allows pagelets to raise and respond to custom events using raiseEvent and registerForEvent. The Broadcast-Listener design pattern illustrates an important example of using notification services with session preferences. Users can select an item or perform some other action in a "broadcast" pagelet, which causes the content in other related "listener" pagelets to be redrawn. In the following example, the broadcast pagelet displays a form that allows you to enter a number in a text box.

Figure 62-21 Broadcast Portlet

Description of Figure 62-21 follows
Description of "Figure 62-21 Broadcast Portlet"

When the user enters a number in the text box, the values in the listener pagelets change. The first listener pagelet displays the square root of the number entered in the broadcast pagelet.

Figure 62-22 Listener -1 Portlet

Description of Figure 62-22 follows
Description of "Figure 62-22 Listener -1 Portlet"

The second listener pagelet displays the cube root of the number entered in the broadcast pagelet.

Figure 62-23 Listener -2 Portlet

Description of Figure 62-23 follows
Description of "Figure 62-23 Listener -2 Portlet"

The following steps summarize how the pagelets work:

  • On load, each listener pagelet calls its own instance method (registerForEvent) to register for events of type 'onBroadcastUpdate'.

  • On each onkeyup event that occurs in the "Enter number" text box, the broadcast pagelet sets a session preference to the value entered in the text box, and calls its own instance method (raiseEvent) to raise an event of type 'onBroadcastUpdate'.

  • When the onBroadcastUpdate event is raised or the page is reloaded, each listener pagelet retrieves the session preference set by the broadcast pagelet and computes a new value to display based on the value of the preference.

Broadcast Pagelet

<div style="padding:10px;" align="center">
<p><b>Enter number:</b>
&nbsp;<input type="text" style="font-size:22px;font-weight:bold;text-align:center;"
id="broadcast_prefName" value="4" size="7" onkeyup="broadcast_setPrefs(this.value)"></p>
<br>
</div>

<script type="text/javascript">
function broadcast_setPrefs(val)
{
    var prefName = 'broadcastNumber';
    var prefValue = val;
    PTPortlet.setSessionPref(prefName,prefValue);
    var broadcastPortlet = PTPortlet.getPortletByGUID('{D9DFF3F4-EAE7-5478-0F4C-2DBD94444000}');

      if (!broadcastPortlet)
    {
        broadcast_debug('Could not locate PTPortlet object which corresponds to <b>Broadcast Portlet</b> on page.');
        return;
        }
      broadcast_debug('<b>Broadcast Portlet</b> raising onBroadcastUpdate event.');
    broadcastPortlet.raiseEvent('onBroadcastUpdate',false);
}
function broadcast_debug(str)
{
    if (window.PTDebugUtil) 
    { 
        PTDebugUtil.debug(str); 
    }
}
</script>

Listener Pagelet #1

<div style="padding:10px;" align="center">
<p><b>Square root:</b>
<div style="height:21px;border:2px solid black;padding:2px;overflow:visible;font-size:14px;"id="listener1-swatch">
</div>
</div>

<script>
function listener1_update()
{
    var broadcastNumber = parseFloat(PTPortlet.getSessionPref('broadcastNumber'));
    if (isNaN(broadcastNumber))
    {
        listener1_error('<b>Listener-1 Portlet</b> cannot parse number from session pref broadcastNumber');
        return;
    }

      listener1_debug('<b>Listener-1 Portlet</b> computing square root of ' + broadcastNumber);
      var swatch = document.getElementById('listener1-swatch');
    swatch.innerHTML = Math.sqrt(broadcastNumber);
}

function listener1_debug(str)
{
    if (window.PTDebugUtil) 
    { 
        PTDebugUtil.debug(str); 
    }
}

function listener1_error(str)
{
    if (window.PTDebugUtil) 
    { 
        PTDebugUtil.error(str); 
    }
}

function listener1_getPortlet()
{
    var portletGUID = '{D9DFF3F4-EAE7-5478-0F4C-2DBDB4F4A000}';
    var listener1Portlet = PTPortlet.getPortletByGUID(portletGUID);
    return listener1Portlet;
}

var listener1Portlet = listener1_getPortlet();
if (listener1Portlet)
{
    listener1Portlet.registerForEvent('onBroadcastUpdate','listener1_update');
    listener1_debug('<b>Listener-1 Portlet</b> registered refreshOnEvent for event onBroadcastUpdate');
    listener1Portlet.registerForEvent('onload','listener1_update');
}

</script>

Listener Pagelet #2

<div style="padding:10px;" align="center">
<p><b>Cube root:</b>
<div style="height:21px;border:2px solid black;padding:2px;overflow:visible;font-size:14px;"id="listener2-swatch">
</div>
</div>

<script>
var listener2_oneThird = (1/3);
function listener2_update()
{
    var broadcastNumber = parseFloat(PTPortlet.getSessionPref('broadcastNumber'));
    if (isNaN(broadcastNumber))
    {
        listener2_error('<b>Listener-2 Portlet</b> cannot parse number from session pref broadcastNumber');
        return;
    }

    listener2_debug('<b>Listener-2 Portlet</b> computing square root of ' + broadcastNumber);
    var swatch = document.getElementById('listener2-swatch');
    swatch.innerHTML = Math.pow(broadcastNumber,listener2_oneThird);
}

function listener2_debug(str)
{
    if (window.PTDebugUtil) 
    { 
        PTDebugUtil.debug(str); 
    }
}

function listener2_error(str)
{
    if (window.PTDebugUtil) 
    { 
        PTDebugUtil.error(str); 
    }
}

function listener2_getPortlet()
{
    var portletGUID = '{D9DFF3F4-EAE7-5478-0F4C-2DBDCA1C7000}';
    var listener2Portlet = PTPortlet.getPortletByGUID(portletGUID);
    return listener2Portlet;
}

var listener2Portlet = listener2_getPortlet();
if (listener2Portlet)
{
    listener2Portlet.registerForEvent('onBroadcastUpdate','listener2_update');
    listener2_debug('<b>Listener-2 Portlet</b> registered refreshOnEvent for event onBroadcastUpdate');
    listener2Portlet.registerForEvent('onload','listener2_update');
}

</script>
62.6.1.2.1 Page-Level Events for Use with the Scripting Framework

The scripting framework automatically has access to the following page-level events.

Table 62-6 Page-Level Events

Event Triggered:

onload

immediately after the browser loads the page

onbeforeunload

prior to a page being unloaded (browser window closes or navigates to different location)

onunload

immediately before the page is unloaded (browser window closes or navigates to different location)

onactivate

the page is set as the active element (receives focus)

onbeforeactivate

immediately before the page is set as the active element (receives focus)

ondeactivate

when the active element is changed from the current page to another page in the parent document

onfocus

when the page receives focus

onblur

when the page loses focus

oncontrolselect

when the user is about to make a control selection of the page

onresize

when the size of the page is about to change

onresizestart

when the user begins to change the dimensions of the page in a control selection

onresizeend

when the user finishes changing the dimensions of the page in a control selection

onhelp

when the user presses the F1 key while the browser is the active window

onerror

when an error occurs during page loading

onafterprint

immediately after an associated document prints or previews for printing


62.6.1.3 Using In-Place Refresh

This section describes how pagelets can reload their internal content without refreshing the page using the scripting framework to implement in-place refresh.

Many pagelets display data that is time sensitive. In some cases, users should be able to navigate across links within a pagelet without changing or refreshing the rest of the page. You can refresh pagelet content on command, associate the refresh action with an event (refreshOnEvent), or program the pagelet to refresh at a set interval (setRefreshInterval). The scripting framework also contains methods for expanding and collapsing pagelets. In the simplified example below, the refresh pagelet displays a "Refresh Portlet" button. Clicking the button updates the date and time displayed in the pagelet.

Figure 62-24 Refresh Portlet

Description of Figure 62-24 follows
Description of "Figure 62-24 Refresh Portlet"

The in-place refresh is executed by calling the refresh() method on the pagelet object instance. You can also set a new URL to be displayed within the pagelet upon refresh. (The title bar cannot be altered on refresh.)

<div style="padding:10px;" align="center">
<p><button onclick="refresh_portlet()">Refresh Portlet</button></p>
<p><b>Current time is:</b><br> <span id="refreshTimeSpan"></span></p>
</div>

<script type="text/javascript"> 
function refresh_portlet()
{
var refreshPortlet = PTPortlet.getPortletByID($PORTLET_ID$);
if (!refreshPortlet)
  {
  refresh_debug('Could not locate PTPortlet object which corresponds to <b>Refresh Portlet</b> on page.');
  return;
  }
refresh_debug('<b>Refresh Portlet</b> calling refresh() method.');
refreshPortlet.refresh();
}

function refresh_debug(str)
{
if (window.PTDebugUtil) 
  { 
  PTDebugUtil.debug(str); 
  }
}

var t = new Date();
document.getElementById('refreshTimeSpan').innerHTML = t;
</script>

62.6.1.4 Using Session Preferences

This section describes how browser-level variables can be stored and shared among pagelets, even if they are not on the same page. For example, a value entered by the user in one pagelet can be retrieved by another. The scripting framework acts as an intermediary, allowing all pagelets access to all values stored in a common session using session preferences.

Pagelets can use preferences to communicate with each other, but accessing preferences usually requires a round trip to a database. Session preferences provide a way to store and share settings in the user's session within the client browser. The Master-Detail design pattern illustrates the most basic usage of session preferences. This design pattern splits control and display between two pagelets. For example, the "master" pagelet could summarize data in list form, and the "detail" pagelet could display details on each data item in response to user selection. In the example below, the master pagelet displays a form that allows you to enter a color code in a text box.

When the user enters a color code in the text box, the color in the detail pagelet changes.

Figure 62-26 Color Swatch

Description of Figure 62-26 follows
Description of "Figure 62-26 Color Swatch"

For each onkeyup event that occurs in the "Enter color" text box in the master pagelet, the following steps are executed:

  1. The master pagelet sets the session preference using the current value of the text box.

  2. The master pagelet calls an update method on the detail pagelet.

  3. The detail pagelet retrieves the session preference to get the color value.

  4. The detail pagelet redraws its color swatch area to reflect the new color value.

Note:

Shared session preferences must be specified by name on the Preferences page for the pagelet in the Pagelet Producer Console or they will not be sent to the pagelet.

The adaptive pagelet scripting framework provides an easy way to detach the relationship between pagelets and use a common event interface for communication.

Note:

The example below is oversimplified; the master pagelet makes a direct call to a JavaScript method of the detail pagelet. Unless the master pagelet takes extra measures to ensure that the detail pagelet is actually present on the same page, calls from master to detail could generate errors.

Master Pagelet

<div style="padding:10px;" align="center">
<p><b>Enter color:</b> &nbsp;
<input type="text" style="font-size:22px;font-weight:bold;text-align:center;" id="master_prefName"
value="#FFFFFF" size="8" onkeyup="master_setPrefs(this.value)"></p><br>
</div>

<script type="text/javascript">
function master_setPrefs(val)
{
var prefName = 'masterColor';
var prefValue = val;
PTPortlet.setSessionPref(prefName,prefValue);

master_debug('<b>Master Portlet</b> called PTPortlet.setSessionPref(\'masterColor\',\'' + prefValue + '\').');

if (window.detail_update)
  {
  master_debug('<b>Master Portlet</b> calling detail_update().');
  detail_update();
  }
else
  {
  master_debug('Could not locate portlet <b>Detail Portlet</b> on page.');
  }
}
function master_debug(str)
{
if (window.PTDebugUtil) 
  { 
  PTDebugUtil.debug(str); 
  }
}
</script>

Detail Pagelet

<div style="padding:10px;" align="center">
<p><b>Color swatch</b> &nbsp;
<div style="width:100px;height:100px;border:2px solid black;padding:2px;"id="detail-swatch"></div>
<script>
function detail_update()
{
var color = PTPortlet.getSessionPref('masterColor');
detail_debug('<b>Detail Portlet</b> received value="' + color + '" for PTPortlet.getSessionPref(\'masterColor\')');

var swatch = document.getElementById('detail-swatch');
if (swatch)
  {
  swatch.innerHTML = '<div style="background-color:' + color + ';width:100%;height:100%;"></div>';
  }
else
  {
  detail_debug('<b>Detail Portlet</b> cannot find \'detail-swatch\' DIV element.');
  }
}

function detail_debug(str)
{
if (window.PTDebugUtil) 
  { 
  PTDebugUtil.debug(str); 
  }
}
</script>

62.6.1.5 Adaptive Pagelet Development Tips

These tips apply to most pagelets that use the adaptive pagelet scripting framework.

  • Use unique names for all forms and functions. Use the GUID of a pagelet to form unique names and values to avoid name collisions with other code on the page.

  • Proxy all URLs. You cannot make a request to a URL with a host/port that is different from that of the calling page. All URLs requested through JavaScript must be proxied.

  • If you are using the adaptive pagelet scripting framework, check for support. It is good practice to include code that determines whether or not the component is present. Ideally, your pagelet should be able to handle either situation. The simplest solution is to precede your code with an If statement that alerts the user if the scripting framework is not supported.

    <script>
    if (PTPortlet == null) 
      {
      if (document.PCC == null) 
        {
        alert("This pagelet only works in portals that support the JSPortlet API .
    The pagelet will be displayed with severely reduced
        functionality. Contact your Administrator.");
        }
      }
    else 
      {
      [scripting code here]
      }
    </script>
    
    
  • Close all popup windows opened by a pagelet when the window closes. The scripting framework can be used to close popup windows using the onunload event.

  • Add all required JavaScript to the page in advance. Browsers might not process script blocks/includes added to the page through the innerHTML property.

    • Microsoft Internet Explorer: Add the defer attribute to the script tag.

    • Netscape: Use RegExp to parse the response and look for the script, then eval it.

  • JavaScript HTTP and proxied HTTP must use the same authentication credentials. JavaScript brokered HTTP requests send the same authentication token (cookie) as when you make a normal gatewayed HTTP request.

62.6.2 Modifying Pagelet Functionality at Runtime

This section describes how to modify pagelet functionality at runtime using custom injectors and parsers.

This section includes the following subsections:

62.6.2.1 Using Web Injectors

A Web injector inserts content into a specified location in the proxied resource page. The content may be any text, including HTML, CSS, JavaScript, and pagelet declarations. An empty injector may also be used to remove unwanted content from a page. Injectors cannot be created for OpenSocial resources. While injecting simple HTML content has a limited use case, you can also inject JavaScript that directly modifies the pagelet's HTML markup. For details on creating a Web injector, see Section 62.3.3, "Creating Web Injectors."

62.6.2.2 Using Custom Parsers

Custom parsers allow you to supplement or change built-in logic for parsing content and finding URLs. When the built-in parsers fail to identify URLs or identify sections that must not be rewritten as URLs, custom parsers can be used to change the default behavior. Parsers cannot be created for WSRP or Oracle JPDK portlet producers or for OpenSocial gadget producers. For details on creating a custom parser, see Section 62.3.4, "Creating Custom Parsers."

62.6.3 Debugging Pagelets

This section describes how to use advanced logging traces for debugging pagelets. Logging is configured in the Settings section of the Pagelet Producer Console, where you can define different levels of logging for each Pagelet Producer component. For more information, see Section 62.2, "Configuring Pagelet Producer Settings."

This section includes the following subsections:

62.6.3.1 Viewing HTTP Requests and Responses

To view the HTTP requests and responses received and sent by Pagelet Producer, set the HTTP component on the Logging Settings page to Finest. The traces in Example 62-1, Example 62-2, Example 62-3, and Example 62-4 were captured from a test environment.

Example 62-1 HTTP Request Received By Pagelet Producer

URL: http://example.com:7001/pagelets/bidwiki/includes/js/ajax.js
METHOD: GET
SESSION ID: GdYGNJzMhxy1CJBMVTX8xTNq32GmLXYNY9VqFBcdprFnhcyQtzdp!1377086614!1305769149498
HEADERS: 
  Host: example.com
  Connection: keep-alive
  Referer: http://example.com:7001/pagelets/bidwiki/dashboard.action
  User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/534.16 (KHTML, like Gecko) Chrome/10.0.648.205 Safari/534.16
  Accept: */*
  Accept-Encoding: gzip,deflate,sdch
  Accept-Language: en-US,en;q=0.8,ru;q=0.6,it;q=0.4
  Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
  If-None-Match: W/"736-1124953206000"
  If-Modified-Since: Thu, 25 Aug 2012 07:00:06 GMT
COOKIES: 
  JSESSIONID: GdYGNJzMhxy1CJBMVTX8xTNq32GmLXYNY9VqFBcdprFnhcyQtzdp!1377086614

Example 62-2 HTTP Response Sent By Pagelet Producer

URL: http://example.com:7001/pagelets/bidwiki/styles/main-action.css
Response Code: 200
Reason: 
HEADERS: 
  Date: Thu, 19 May 2011 01:39:14 GMT
  Content-Type: text/css;charset=UTF-8
  Server: Apache-Coyote/1.1
BODY: 
.sidebar {
    /*background-image: url(http://example.com:7001/pagelets/bidwiki/download/ resources/leftnav_bg.jpg);*/
    /*background-repeat: repeat-y;*/
    background-color: #F0F0F0;
    /*border-bottom:1px solid #F0F0F0;*/
} ...

Example 62-3 HTTP Request Sent By Pagelet Producer

URL: http://xmlns.oracle.com/includes/js/ajax.js
METHOD: GET
HEADERS: 
  CSP-Ensemble-REST-API: http://example.com:7001/pagelets
  X-Client-IP: example.com
  User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/534.16 (KHTML, like Gecko) Chrome/10.0.648.205 Safari/534.16
  CSP-Session-Username: weblogic
  Accept-Language: en-US,en;q=0.8,ru;q=0.6,it;q=0.4
  CSP-Gateway-Type: Proxy
  PT-Proxy-Passes: 1
  If-Modified-Since: Thu, 25 Aug 2012 07:00:06 GMT
  CSP-Protocol-Version: 1.4
  Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
  Accept-Encoding: gzip,deflate,sdch
  Referer: http://example.com:7001/pagelets/bidwiki/dashboard.action
  If-None-Match: W/"736-1124953206000"
  Accept: */*
  CSP-Aggregation-Mode: Single
  PT-Proxy-instance0: {DECBB085-D891-72CF-2B75-005E7FE20000}
  CSP-Gateway-Specific-Config: PT-User-Name=weblogic,PT-Guest-User=0,...

Example 62-4 HTTP Response Received By Pagelet Producer

Original URI: http://xmlns.oracle.com/styles/main-action.css
Effective URI: http://xmlns.oracle.com/styles/main-action.css
Status Code: 200
Reason: OK
Version: HTTP/1.1
HEADERS: 
  Content-Type: text/css;charset=UTF-8
  Content-Length: 29178
  Server: Apache-Coyote/1.1
  Date: Thu, 19 May 2011 01:39:14 GMT
TRAILERS: 
BODY: 
body, p, td, table, tr, .bodytext, .stepfield {
  font-family: Verdana, arial, sans-serif;
  font-size: 11px;
  line-height: 16px;
  color: #000000;
  font-weight: normal;
}

62.6.3.2 Viewing Transformation Content

To view the content proxied by Pagelet Producer before and after transformation, set the Transform component on the Logging Settings page to Finest. The purpose of these traces is to log response content at different stages of transformation, allowing you to compare them and view the result of different transformers. The example traces in Example 62-5 and Example 62-6 were captured from a test environment.

Example 62-5 Untransformed Markup

Original request: URL: http://example.com:7001/pagelets/bidwiki/styles/main-action.css
METHOD: GET
SESSION ID: GdYGNJzMhxy1CJBMVTX8xTNq32GmLXYNY9VqFBcdprFnhcyQtzdp!1377086614!1305769149498
HEADERS: 
  Host: example.com:7001
  Connection: keep-alive
  Referer: http://example.com:7001/pagelets/bidwiki/dashboard.action
  User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/534.16 (KHTML, like Gecko) Chrome/10.0.648.205 Safari/534.16
  Accept: text/css,*/*;q=0.1
  Accept-Encoding: gzip,deflate,sdch
  Accept-Language: en-US,en;q=0.8,ru;q=0.6,it;q=0.4
  Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
COOKIES: 
  JSESSIONID: GdYGNJzMhxy1CJBMVTX8xTNq32GmLXYNY9VqFBcdprFnhcyQtzdp!1377086614
 
Untransformed content: 
body, p, td, table, tr, .bodytext, .stepfield {
  font-family: Verdana, arial, sans-serif;
  font-size: 11px;
  line-height: 16px;
  color: #000000;
  font-weight: normal;
}

Example 62-6 Transformed Markup (Transformed by Transformer Class)

Transformed by: class com.plumtree.server.impl.portlet.transformers.CSSTurboParser
  Original request: URL: http://example.com:7001/pagelets/bidwiki/styles/main-action.css
METHOD: GET
SESSION ID: GdYGNJzMhxy1CJBMVTX8xTNq32GmLXYNY9VqFBcdprFnhcyQtzdp!1377086614!1305769149498
HEADERS: 
  Host: 10.148.118.211:7001
  Connection: keep-alive
  Referer: http://example.com:7001/pagelets/bidwiki/dashboard.action
  User-Agent: Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/534.16 (KHTML, like Gecko) Chrome/10.0.648.205 Safari/534.16
  Accept: text/css,*/*;q=0.1
  Accept-Encoding: gzip,deflate,sdch
  Accept-Language: en-US,en;q=0.8,ru;q=0.6,it;q=0.4
  Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.3
COOKIES: 
  JSESSIONID: GdYGNJzMhxy1CJBMVTX8xTNq32GmLXYNY9VqFBcdprFnhcyQtzdp!1377086614
 
Transformed content: 
body, p, td, table, tr, .bodytext, .stepfield {
  font-family: Verdana, arial, sans-serif;
  font-size: 11px;
  line-height: 16px;
  color: #000000;
  font-weight: normal;
}

62.7 Using Pagelets in Web Applications

This section describes how to add pagelets to a JSF page in JDeveloper, to a Web page, and to a portal page. Before you can add a pagelet to any Web application, you must deploy and configure the resource and pagelet in Pagelet Producer as described in the "Deploying Portals, Templates, Assets, and Extensions" chapter in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

This section includes the following subsections:

62.7.1 Adding a Pagelet to a JSF Page in Oracle JDeveloper

Oracle JDeveloper allows you to drag and drop pagelets onto a JSF page. In this section, you will register Pagelet Producer with your Framework application, add a pagelet to a JSF page, and view the page in a browser to test the pagelet.

This section includes the following subsections:

62.7.1.1 Registering Pagelet Producer with a Framework Application

Before you can add a pagelet to a JSF page, you must register Pagelet Producer with your application. You can register a Pagelet Producer in two ways:

  • Register a producer with a specific application. By default, the IDE Connection option is selected in the New Pagelet Producer dialog that creates the connection under the Application Resources panel.

  • Register a producer using the Resource Palette. This option enables you to use the producer's pagelets in multiple applications. A pagelet that is available in the Resource Palette can be added to any of your Portal Framework applications by dropping it on the page. When you add a pagelet from the Resource Palette, its producer gets registered with the application if that producer is not already registered with the application. 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

To register a Pagelet Producer through Oracle JDeveloper:

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

  2. In the Name field of the New Pagelet Producer dialog, enter a meaningful name for your producer. For example, myPageletProducer.

  3. In the URL field, enter the URL of your Pagelet Producer in the format: http://hostname:portnumber/pagelets.

  4. Click OK. In the Application Resources panel, Pagelet Producer is created under the Pagelet Producer directory in the Connections directory, as shown in Figure 62-27.

    Figure 62-27 Pagelet Producer in the Application Resources Panel

    Description of Figure 62-27 follows
    Description of "Figure 62-27 Pagelet Producer in the Application Resources Panel"

62.7.1.2 Adding a Pagelet to a JSF Page

To add a pagelet to a page:

  1. In JDeveloper, open your JSF page in Design View, if it is not open already.

  2. Go to the Application Resources panel or the IDE Resources panel in the Resource Palette. Under Pagelet Producer, expand your producer to display its contents.

  3. From the producer's contents, drop a pagelet onto the JSF page.

  4. In the Add Pagelet to Page dialog, choose Yes in the Use IFrame section if you would like to enable IFRAME for this pagelet.

  5. In the IFrame Height field, specify the required height in pixels or leave it blank. You can also specify the height as "auto" to use automatic resizing. (To use this option, you must add the IFrame resizing page to the project. For details, see Section 62.7.2.3, "Using Automatic Resizing with IFrames.") Click OK.

  6. In the Edit Task Flow Binding dialog input parameters are specified by default. Change any parameters, if required, and then click OK.

  7. Save the page. In the Structure window, the page looks like Figure 62-28.

    Figure 62-28 Pagelet in the Structure Window

    Description of Figure 62-28 follows
    Description of "Figure 62-28 Pagelet in the Structure Window"

  8. In the Application Navigator, right-click your JSF page under Projects, and choose Run.

  9. If presented with a login page, enter user name and password so you can view the pagelet. Figure 62-29 shows a sample pagelet in a browser window.

    Figure 62-29 Sample Pagelet

    Description of Figure 62-29 follows
    Description of "Figure 62-29 Sample Pagelet"

62.7.1.3 Securing a Pagelet

For information about securing pagelets, see the "Configuring Oracle Single Sign-On (OSSO)" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

62.7.2 Adding a Pagelet to a Web Page

Once you have deployed a pagelet, you can insert it into a proxied or non-proxied page using JavaScript or REST.

This section includes the following subsections:

62.7.2.1 Inserting Pagelets Using Javascript

You can insert pagelets into non-proxied pages using a simple JavaScript function.

To activate this feature, add the following HTML snippet in the <HEAD> section of the page.

<script type="text/javascript" src="http://proxy:port/pagelets/inject/v2/csapi">
</script>

This script injects all CSAPI and pagelet inject functions into the page to display the pagelet. One of the sections injected is the following function:

function injectpagelet(library, name, iframe_options, params, context_id, element_id,  is_in_community, chrome, forward_params)
{
    ...
}

This function injects a pagelet as a widget into the parent page. The method interface uses the following parameters:

  • library: Required. A string representing the library name of the pagelet to inject. Accepts Unicode letters and numbers only; no spaces.

  • name: Required. A string representing the name of the pagelet to inject. Accepts Unicode letters and numbers only; no spaces.

  • iframe_options: Specifies whether to use IFRAME around the pagelet content. Sample IFRAME options: iframe width=100% height=auto frameborder=0. If omitted or left blank, the pagelet content is rendered inline.

  • params: The pagelet parameters in query string format. For example, 'param1=value1&param2=value2&param3=value3'.

  • context_id: The external identifier of the pagelet instance, used to scope preferences on the Pagelet Producer server. Must be an integer.

  • element_id: The HTML element ID in which the pagelet content is injected. If omitted or left blank, the pagelet content is injected using document.write() when the injectpagelet call is evaluated.

  • is_in_community: Specifies whether this pagelet is on a community or group page. If the value is set to true, it sends the context_id in the community ID header to the pagelet. Defaults to false.

  • chrome: Specifies the name of the chrome template to use for WSRP/JPDK pagelets. To suppress chrome, use a value of none.

  • forward_params: Specifies whether to forward query string arguments from the consuming page to the back-end server. To suppress this functionality, use a value of false.

Note:

These arguments are positional; they must be provided in the given order. If you do not want to specify a particular argument, but do want to specify an argument that follows it, you must pass in an empty value ('') for the former. All arguments are optional except for library and name.

The script also creates a new <div> with a unique name that includes a reference to the injectpagelet function. Several examples are shown below:

<div>
    <script type="text/javascript">
        injectpagelet('library', 'name');
    </script>
</div>
<div>
    <script type="text/javascript">
    injectpagelet('library', 'name', 'iframe', 'payload', 'param1=value1&param2=value2&param3=value3');
    </script>
</div>
<div>
    <script type="text/javascript">
    injectpagelet('library', 'name', 'iframe width=100% height=200', 'payload');
    </script>
</div>
62.7.2.1.1 Adding a Preference Editor Using Javascript

The injecteditor function lets you add preference editors that enable users to set personal and shared preferences for pagelets that support this capability. This functionality is analogous to personalization and customization functionality in WebCenter Portal.

injecteditor(library, name, type, iframe_options, context_id, element_id, is_in_community, chrome)

where:

  • library: Required. The library name of the pagelet to inject. Accepts Unicode letters and numbers only; no spaces.

  • name: Required. The name of the pagelet to inject. Accepts Unicode letters and numbers only; no spaces.

  • type: The editor type. This argument supports these values: 'admin', 'pagelet', 'community'. In case of the 'community' argument, context_id is sent to pagelet in the community ID CSP header.

  • iframe_options: Specifies whether to use IFRAME around the pagelet editor content. Sample IFRAME options: iframe width=100% height=auto frameborder=0. If omitted or left blank, the editor content is rendered inline.

  • context_id: The external identifier of the pagelet instance, used to scope preferences on the Pagelet Producer server. Must be an integer.

  • element_id: The HTML element ID in which the pagelet content is injected. If omitted or left blank, the pagelet content is injected using document.write() when the injecteditor call is evaluated.

  • is_in_community: Specifies whether this pagelet is on a community or group page. If the value is set to true, it sends the context_id in the community ID header to the pagelet. Defaults to false.

  • chrome: Specifies the name of the chrome template to use for WSRP/JPDK pagelets. To suppress chrome, use a value of none.

Note:

These arguments are positional; they must be provided in the given order. If you do not want to specify a particular argument, but do want to specify an argument that follows it, you must pass in an empty value ('') for the former. All arguments are optional except for library and name.

62.7.2.2 Accessing Pagelets Using REST

REST stands for Representational State Transfer and is a simple way of providing APIs over HTTP. The basic principles of REST are:

  • API URLs point to the resource rather than a generic method endpoint.

  • Requests use standard HTTP verbs for simplified CRUD methods. This is a read-only API and allows GET requests only.

  • Every request returns a full representation of the object retrieved (pagelet or resource).

Pagelet Producer REST APIs provide the following functionality:

62.7.2.2.1 Pagelet Inject API

The pagelet inject URL can be used in portals to specify the location of a remote portlet (this is how a pagelet can be used as a portlet). The inject URL can also be used as the source attribute of an IFrame tag in any HTML page.

The URL must use the following format:

http://host:port/pagelets/inject/v2/pagelet/libraryname/pageletname?content-type=html

where libraryname and pageletname refer to the library and pagelet configured in Pagelet Producer.

Note:

When using the pagelet inject API as the URL for a Portlet Web Service in Oracle WebCenter Interaction, you must switch "pagelet" to "portlet" in the URL. For example, the above URL would become:

http://host:port/pagelets/inject/v2/portlet/libraryname/pageletname?content-type=html

The query string arguments to the above call define how the pagelet is to be returned. The following parameters are defined:

  • instanceid: Optional. The instance ID of the pagelet, used to uniquely identify the pagelet on the page to facilitate inter-pagelet communication. Must be unique to the page.

  • context: Optional. The external identifier of the pagelet instance, used for scoping preferences on the Pagelet Producer server. Must be an integer.

  • content-type: The return type. Three types are supported:

    • javascript: Returns injectable code.

    • html: Returns the pagelet markup with its associated PTPortlet object.

    • iframe: Returns an IFrame that points back to the inject api, filling the IFrame with the pagelet content, instead of directly inline with the page. The IFrame can be styled by providing a set of query string parameters.

      Parameter Description Default
      ifwidth Sets the width of the IFrame; can be specified in percent '%' or pixels 'px', for example: ifwidth=500px. Can be set to 'auto' to automatically resize the IFrame to fit the content within. For details, see Section 62.7.2.3, "Using Automatic Resizing with IFrames". 100%
      ifheight Sets the height of the IFrame; can be specified in percent '%' or pixels 'px', for example: ifheight=500px. Can be set to 'auto' to automatically resize the IFrame to fit the content within. For details, see Section 62.7.2.3, "Using Automatic Resizing with IFrames". No default
      ifborder Sets the border of the IFrame. 'none'
      ifalign Sets the align rule within the IFrame, for example: ifalign=center. No default
      ifdesc Sets the description of the IFrame. No default
      ifmarginheight Sets the margin height; can be specified in percent '%' or pixels 'px', for example: ifmarginheight=500px. No default
      ifmarginwidth Sets the margin width; can be specified in percent '%' or pixels 'px', for example: ifmarginwidth=500px. No default
      ifscrolling Sets the scrollbars of the IFrame. Accepted values: yes/no/auto. auto
      ifstyle Sets the CSS style of the IFrame No default
      ifclass Sets the CSS class of the IFrame. No default

  • csapi: Optional. Sets whether the CSAPI will be included with the pagelet response (true or false). Including the CSAPI is optional, but the pagelet included in the response relies on the CSAPI libraries being present on the page where the pagelet is to be rendered. If csapi=false, then the CSAPI libraries must be included with the parent page (usually in the HEAD section).

  • onhtttperror: Optional. When a pagelet request results in a 403, 404 or any other error code, Pagelet Producer can forward the error code and the error page itself to the browser for display to the user. The onhttperror parameter accepts the following values:

    • comment (default): Pagelet Producer will create an HTML comment in place of the failing pagelet (the failing pagelet will simply not be displayed).

    • inline: The pagelet error along with the server error page will be displayed inline where the pagelet would normally be shown on the page.

    • fullpage: The http error will consume the whole page. This mode is only available if Pagelet Producer controls the parent page.

  • inline-refresh: Optional. Valid values are true or false (default). If the inline-refresh option is set to true, Pagelet Producer does not use an iFrame to embed pagelet markup onto the page. When the user interacts with the pagelet, markup updates are done inline, hence the term 'inline-refresh'. To achieve this, Pagelet Producer re-writes the URLs in the pagelet markup to use a JavaScript method call instead. That is, when the user clicks on a link or submits a form request to the backend, it's done by JavaScript on the browser and then the response is dynamically injected.

    The inline-refresh option works well for relatively simple HTML markup. If the pagelet exposes a very rich UI, such as an ADF task flow, inline-refresh may not work well or may simply break. Consequently, the inline-refresh option is set to false by default (that is, inject pagelet markup in an iFrame).

The following example URL points to the linkspagelet in the samples library:

http://host:port/pagelets/inject/v2/pagelet/samples/linkspagelet?content-type=iframe&csapi=true&ifheight=123px&ifclass=myclass

This URL should result in markup similar to the code below.

Note:

The IFrame source points back to the inject API, but this time the content-type parameter is set to html. This feature adds an additional step in the pagelet retrieval. The csapi parameter is set to true on the subsequent call to get the IFrame contents so that the required CSAPI content is included in the IFrame (if this was not the case, JavaScript resolve errors would be returned because the pagelet code cannot access any CSAPI script included outside the IFrame).
<html>
 <head>
 </head>
 <body>
  <iframe frameborder="none" class="myclass" width="100%" height="123px" scrolling="auto" src="http://proxy:port/inject/v2/pagelet/samples/linkspagelet?asdg=asdfgas&param=true&content-type=html&jswrap=false&csapi=true">
   <html>
    <head>
     <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsutil/LATEST/PTUtil.js" type="text/javascript"> </script>
     <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsutil/LATEST/PTDateFormats.js" type="text/javascript"></script>
     <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsxml/LATEST/PTXML.js" type="text/javascript"></script>
     <script src="http://proxy:loginserverport/loginserver/ensemblestatic/imageserver/plumtree/common/private/js/jsportlet/LATEST/PTPortletServices.js" type="text/javascript"></script>
    </head>
 
    <body>
     <div id="pt-pagelet-content-1" class="pagelet-container" style="display: inline;">
      <span xmlns:pt="http://www.xmlns.oracle.com/xmlschemas/ptui/">
      Pagelet links:
      <br/>
      <a href="http://proxy:port/inject/RP_PID393219_I1/headpagelet1.html">The first pagelet</a>
      <br/>
      <a href="http://proxy:port/inject/RP_PID393219_I1/headpagelet2.html">The second pagelet</a>
      <br/>
      <a href="http://proxy:port/inject/RP_PID393219_I1/csapipagelet.html">The csapi pagelet</a>
      <br/>
      <a href="http://proxy:port/inject/RP_PID393219_I1/linkspagelet.html">This pagelet</a>
      <br/>
      </span>
     </div>
    </body>
   </html>
  </iframe>
 </body>
</html>
62.7.2.2.2 Data Retrieval APIs

Two REST APIs are available to retrieve data from Pagelet Producer:

The base URL for all requests is http://host:port/pagelets/restservice/pageletproducer/.

Example 62-7 All Pagelets

http://host:port/pagelets/restservice/pageletproducer/pagelets/
http://host:port/pagelets/restservice/pageletproducer/pagelets/?format=xml

Example 62-8 Pagelets By Library and Name

http://host:port/pagelets/restservice/pageletproducer/pagelet/libraryname/pageletname/
http://host:port/pagelets/restservice/pageletproducer/pagelet/libraryname/pageletname/?format=xml

Example 62-9 All Resources

http://host:port/pagelets/restservice/pageletproducer/resources/
http://host:port/pagelets/restservice/pageletproducer/resources/

Example 62-10 Resource By Name

http://host:port/pagelets/restservice/pageletproducer/resource/name
http://host:port/pagelets/restservice/pageletproducer/resource/name/?format=xml

62.7.2.3 Using Automatic Resizing with IFrames

The Pagelet Producer pagelet inject API can automatically resize the IFrame that encapsulates pagelet content. The resizing is done so that the IFrame stretches to fit the content within. To use this feature, the ifwidth and ifheight parameters must be set to 'auto' as shown in the example below:

http://proxy:port/inject/v2/pagelet/samples/linkspagelet?content-type=iframe&csapi=true&ifheight=auto&ifwidth=auto&ifclass=myclass

In addition, this feature relies on an external page on the same domain as the consumer page. This page is included into the pagelet IFrame as an internal hidden IFrame. This page collects the sizing information and passes it on to the parent consumer page. This page must be deployed in the same directory as the consumer page.

The example below resizes the pagelet IFrame after it finishes loading. To add dynamic auto-resizing capabilities to user interaction activities after the initial load, simply add more event listeners for mouse and keyboard events.

<html>
  <head>
    <title>Resizing Page</title>
    <script type="text/javascript">
  function onLoad() {
    var params = window.location.search.substring( 1 ).split( '&' );
    var height;
    var width;
    var iframe;
 
    for( var i = 0, l = params.length; i < l; ++i ) {
      var parts = params[i].split( '=' );
      switch( parts[0] ) {
        case 'height':
          height = parseInt( parts[1] );
          break;
        case 'width':
          width = parseInt( parts[1] );
          break;
        case 'iframe':
          iframe = parts[1];
          break;
      }
    }
  window.top.updateIFrame( iframe, height, width );
  }
 
  if (window.addEventListener) {
    window.addEventListener("load", onLoad, false)
  } else if (window.attachEvent) {
     window.detachEvent("onload", onLoad)
     window.attachEvent("onload", onLoad)
  } else {
    window.onload=onLoad
  }
  </script>
 </head>
<body>
</body>
</html>

62.7.3 Adding a Pagelet to a Portal Page

Use Composer to add a pagelet to a portal page. By default, pagelets appear in the Mash-Ups folder in the Resource Catalog. To add a pagelet to a page, navigate to the pagelet in the Resource Catalog and select it.

For detailed information about how to add resources to pages in a portal, see the "Adding and Editing Resource Catalog Components on a Page" section in Oracle Fusion Middleware Using Oracle WebCenter Portal.

To configure a pagelet within a page, view the page in Edit mode and click the Edit icon (wrench) for the pagelet. The Pagelet Properties tab in the Component Properties dialog allows you to define pagelet parameters and IFrame options.

Figure 62-30 Component Properties Dialog: Pagelet Properties

Description of Figure 62-30 follows
Description of "Figure 62-30 Component Properties Dialog: Pagelet Properties"

62.8 Examples and Advanced Topics

This section contains several examples and advanced topics:

62.8.1 Creating a Simple Pagelet (an Example)

This section will give you a basic feel of how you can use Pagelet Producer to proxy a Web page. We will proxy a simple static "Hello World" Web page, cut one section out of that page, and present it as a pagelet that you can later insert in WebCenter Portal, WebCenter Interaction, on your own application page.

This section includes the following subsections:

62.8.1.1 Configuring the Initial Pagelet Producer Setup

For this example, let's assume that the Pagelet Producer server is running on http://pageletserver.company.com:8889/pagelets/.

  1. First, let's check that Pagelet Producer is up and running.

    To do that we just need to access its URL (http://pageletserver.company.com:8889/pagelets/). Figure 62-31 shows what should be returned:

    Figure 62-31 Pagelet Producer Welcome Page

    Description of Figure 62-31 follows
    Description of "Figure 62-31 Pagelet Producer Welcome Page"

  2. Access the Pagelet Producer administration screens using this URL:

    http://pageletserver.company.com:8889/pagelets/admin

    Figure 62-32 Pagelet Producer Administration Screen

    Description of Figure 62-32 follows
    Description of "Figure 62-32 Pagelet Producer Administration Screen"

  3. If you connect to the internet via a proxy server, you need to configure proxy in the Pagelet Producer settings:

    1. In the Navigator pane's Jump To drop down list, select Settings.

    2. Click Proxy.

    3. Enter your proxy server configuration as shown in Figure 62-33.

      Figure 62-33 Pagelet Producer Proxy Settings

      Description of Figure 62-33 follows
      Description of "Figure 62-33 Pagelet Producer Proxy Settings"

62.8.1.2 Creating a Resource

The first thing that you need to do is to create a resource for your Web page. This will tell Pagelet Producer that all sub-paths of the Web page should be proxied. It also will allow you to set up common rules for how your Web page should be proxied and will serve as a container for your pagelets.

  1. From the Navigator pane's Jump To drop down list select Resources.

  2. Click any existing resource (for example, welcome_resource).

  3. Click Create selected type.

  4. From the Select Producer Type dialog, select Web and click OK.

  5. After the resource is created, click the General node in the Navigation pane and specify the following values as shown in Figure 62-34:

    • Name: AppServer

    • Source URL: http://appserver.company.com:1234/

    • Destination URL: /appserver/

    Figure 62-34 Pagelet Producer's General Settings Page

    Description of Figure 62-34 follows
    Description of "Figure 62-34 Pagelet Producer's General Settings Page"

  6. Click Save.

    After the resource is created our Web page becomes accessible by the URL: http://pageletserver.company.com:8889/pagelets/appserver/helloworld/

    Figure 62-35 Hello World Pagelet

    Description of Figure 62-35 follows
    Description of "Figure 62-35 Hello World Pagelet"

    The original Web page address Source URL has now been replaced with the Pagelet Producer URL (http://pageletserver.company.com:8889/pagelets) + Destination URL.

62.8.1.3 Creating a Pagelet

Let's continue by creating our "Hello World" pagelet.

  1. Under the Resource node, open the Pagelets node.

  2. Click Create selected type.

  3. Click the General node of the newly created pagelet and specify the following values as shown in Figure 62-36:

    Name: Hello_World

    Library: MyLib

    Library is used for logical grouping. The portals use the Library value to group pagelets in their respective UIs. For example, when adding pagelets to a WebCenter Portal portal you would see the individual pagelets listed under "Library".

    URL Suffix: helloworld/index.html

    The URL Suffix is where the Hello World page HTML is served from.

    Figure 62-36 Pagelet Producer Settings for the Hello World Pagelet

    Description of Figure 62-36 follows
    Description of "Figure 62-36 Pagelet Producer Settings for the Hello World Pagelet"

  4. Click Save.

The Library name can be anything you want, it doesn't have to match the resource name at all. It is used as a logical grouping of pagelets, and you can include pagelets from multiple resources into the same library or create a new library for each pagelet.

After you save the pagelet you can access it here:

http://pageletserver.company.com:8889/pagelets/inject/v2/pagelet/MyLib/Hello_World

which is:

http://pageletserver.company.com:8889/pagelets/inject/v2/pagelet/ + [Library] + [Name]

Or to test the injection of a pagelet into iFrame you can click on the pagelet's Documentation node and use the Access Pagelet using REST URL.

Figure 62-37 Pagelet's Documentation Page

Description of Figure 62-37 follows
Description of "Figure 62-37 Pagelet's Documentation Page "

If you click the URL on the Documentation page you should see the following:

Figure 62-38 Hello World Pagelet

Description of Figure 62-38 follows
Description of "Figure 62-38 Hello World Pagelet"

62.8.1.4 Clipping the Pagelet

The pagelet that we just created would cover the whole Web page. Since we only want the "Hello World" segment of it we'll need to clip it as described in the following steps:

  1. Under the Hello_World pagelet node, click Clipper.

  2. Click Create selected type.

  3. Specify a Name for the newly created clipper (for example: c1).

  4. Click the clipper's Content node and click Launch Clipper.

    Figure 62-39 Pagelet Producer Clipper

    Description of Figure 62-39 follows
    Description of "Figure 62-39 Pagelet Producer Clipper"

  5. In the browser window, use the mouse to select the area you want to clip.

    When you click the mouse button the browser window disappears and a Clipping Path is automatically generated.

  6. Save the clipped pagelet and access the link from the Documentation page again.

  7. Our pagelet is now nicely clipped and ready to be used in a WebCenter Portal portal as shown in Figure 62-40:

    Figure 62-40 Clipped Hello World Pagelet

    Description of Figure 62-40 follows
    Description of "Figure 62-40 Clipped Hello World Pagelet"

62.8.2 Consuming a Pagelet in WebCenter Portal (an Example)

This section provides an example of how you can consume a simple "Hello World" pagelet in WebCenter Portal. Before continuing, first follow the instructions in Section 62.8.1, "Creating a Simple Pagelet (an Example)" to create the "Hello World" pagelet that will be used in this example.

This section includes the following subsections:

62.8.2.1 Registering the Pagelet Producer with WebCenter Portal

In order to use our newly created pagelet from WebCenter Portal, we first need to register Pagelet Producer:

  1. Log into WebCenter Portal as an administrator.

  2. Click Administration.

  3. Open the Configuration tab.

  4. Click Services.

  5. Click Portlet Producers.

  6. Click Register.

  7. Select Pagelet Producer and enter the values shown for the following fields:

    Producer Name: MyPageletProducer

    Server URL: http://pageletserver.company.com:8889/pagelets/

  8. Click Test to make sure that the connection was correctly configured.

    If everything is successful you should see the Test Status dialog display a message indicating that the test connection was successful.

  9. Click OK.

    The Pagelet Producer is now registered.

62.8.2.2 Inserting the Pagelet into a Portal

For our exercise we will need to create a portal. So let's start by logging into WebCenter Portal and creating a portal called "myportal" using "Portal Site" template.

  1. Log into WebCenter Portal as an administrator.

  2. Create a portal called myportal using the Portal Site template.

  3. On the myportal portal click on the Actions icon and select Edit Page.

  4. Click Add Content in one of the portal frames and select Mash-Ups.

  5. Select Pagelet Producers.

  6. Click the Pagelet Producer you previously registered.

    You will see the library MyLib containing the Hello_World pagelet.

  7. Click MyLib, select the Hello_World pagelet and click Add.

  8. Click Close.

  9. Click Save, and then click Close.

    The Hello World pagelet is now inserted into the myportal page.

62.8.3 Consuming a Pagelet in WebCenter Interaction (an Example)

This section provides an example of how you can consume a simple "Hello World" pagelet in WebCenter Interaction (WCI) 10.3.0 or later. Before continuing, first follow the instructions in Section 62.8.1, "Creating a Simple Pagelet (an Example)" to create the "Hello World" pagelet that will be used in this example.

This section includes the following subsections:

62.8.3.1 Registering the Pagelet Producer Remote Server

In order to use our newly created pagelet from WCI, we first need to register Pagelet Producer:

  1. Log into WCI as an administrator.

  2. Click Administration.

  3. Create the folder where we are going to keep all Pagelet Producer related objects by following the steps below:

    1. Open the Create Object... dropdown and select Administrative Folder.

    2. Enter PageletProducer as the Name and click OK.

      Figure 62-41 WCI - Create Administration Folder

      Description of Figure 62-41 follows
      Description of "Figure 62-41 WCI - Create Administration Folder"

  4. Click the newly created PageletProducer folder.

    Figure 62-42 WCI - Newly Created Folder

    Description of Figure 62-42 follows
    Description of "Figure 62-42 WCI - Newly Created Folder"

  5. Open the Create Object... dropdown and select Remote Server.

    Figure 62-43 WCI - Create Remote Server

    Description of Figure 62-43 follows
    Description of "Figure 62-43 WCI - Create Remote Server"

  6. In the Base URL field, enter http://pageletserver.company.com:8889/pagelets (this is the address of our Pagelet Producer server in this example).

  7. Click Finish.

  8. Select the PageletProducer folder and in the Save As field enter Pagelet Producer Remote Server.

    Figure 62-44 WCI - Saving the Pagelet Producer Remote Server Object

    Description of Figure 62-44 follows
    Description of "Figure 62-44 WCI - Saving the Pagelet Producer Remote Server Object"

  9. Click Save.

    You've now created a Pagelet Producer Remote Server connection in the PageletProducer folder.

    Figure 62-45 WCI - Pagelet Producer Remote Server Object

    Description of Figure 62-45 follows
    Description of "Figure 62-45 WCI - Pagelet Producer Remote Server Object"

62.8.3.2 Creating the "Hello World" Web Service

In this section we'll continue by creating the "Hello World" Web service.

  1. Open Create Object... dropdown and select Web Service - Remote Portlet.

  2. Click Browse and select Pagelet Producer Remote Server.

    Figure 62-46 WCI - Choose Remote Server Dialog

    Description of Figure 62-46 follows
    Description of "Figure 62-46 WCI - Choose Remote Server Dialog"

  3. Click OK.

  4. In the Portlet URL field enter:

    inject/v2/portlet/MyLib/Hello_World?content-type=iframe&csapi=true&ifheight=300px

    Where MyLib is a library that contains our "Hello World" pagelet and Hello_World is the name of our pagelet.

    Figure 62-47 WCI - Create Web Service - Remote Portlet Dialog

    Description of Figure 62-47 follows
    Description of "Figure 62-47 WCI - Create Web Service - Remote Portlet Dialog"

  5. Click Finish.

  6. Select the PageletProducer folder and in the Save As field enter Hello World Web Service.

  7. Click Save.

    You've now created the Hello World Web service.

62.8.3.3 Creating the "Hello World" Portlet

In this section we'll continue by creating a Hello World portlet.

  1. Open the Create Object... dropdown list and select Portlet.

    The Choose Template or Web Service dialog displays (Figure 62-48).

    Figure 62-48 WCI - Choose Template or Web Service

    Description of Figure 62-48 follows
    Description of "Figure 62-48 WCI - Choose Template or Web Service"

  2. From the list of templates or Web services select Hello World Web Service and click OK.

  3. Under Portlet Type/Size, select the portlet type and size you want to use and click Finish.

  4. Select the PageletProducer folder

  5. In the Save As field, enter Hello World Portlet and click Save.

    You've now created the Hello World portlet.

62.8.3.4 Using the Hello World Portlet on the WCI Home Page

Now that we've registered the Pagelet Producer, set up the Pagelet Producer Web service, and created the Hello World portlet, let's continue by using the portlet on a page in WCI. For the sake of simplicity, we'll use the WCI Home Page, but you could use any other WCI page.

  1. In WCI, navigate to My Pages > Home Page.

  2. Click Edit Page and open the PageletProducer folder.

  3. Click Hello World Portlet.

  4. Click Close Editor.

    Here's our Hello World pagelet inserted into the Home Page in WCI:

    Figure 62-49 WCI - Hello World Pagelet on Home Page

    Description of Figure 62-49 follows
    Description of "Figure 62-49 WCI - Hello World Pagelet on Home Page"

62.8.4 Consuming a Pagelet in Oracle WebCenter Sites (an Example)

This section is aimed at developers who need to integrate content into Oracle WebCenter Sites 11g pages, including existing WSRP portlets or elements of Web UI exposed by backend applications such as Oracle EBS. Developers should be familiar with Oracle WebCenter Sites and Oracle WebCenter Pagelet Producer and have a solid understanding of Web technologies.

This section includes the following subsections:

62.8.4.1 Adding Pagelets to Oracle WebCenter Sites

Once a pagelet and its related resources are configured, you can insert it into a Web page using JavaScript or REST. For more information, see Section 62.7.2, "Adding a Pagelet to a Web Page."

Here, we'll use an approach in which pagelets are added directly to a page template in Oracle WebCenter Sites using an iFrame with a REST URL for accessing pagelets as a content source. This requires an addition to the page template script tag to load the CSAPI JavaScript library (which adds necessary functions into the parent page), as well as the actual iFrame that loads pagelet content:

<script type="text/javascript" src="http://%PAGELET_PRD_HOST%/pagelets/inject/v2/csapi"/>
<iframe id="pt-pagelet-iframe-1" width="100%" frameborder="0" src="http://%PAGELET_PRD_HOST%/pagelets/inject/v2/pagelet/lib_name/pagelet_name?content-type=html&consumepage=true&ifheight=auto"></iframe>

Where lib_name and pagelet_name refer to the library and pagelet configured in Pagelet Producer. For more information about parameters, see Section 62.7.2.2, "Accessing Pagelets Using REST."

62.8.4.1.1 Enabling IFrame Auto-Resizing

To provide a more seamless integration of the pagelet into the consuming page, you can make the pagelet iFrame behave more like inline markup by dynamically resizing to accommodate its content. To enable this feature, some extra configuration is required in both Sites and Pagelet Producer.

This section uses the AviSports sample site shipped with WebCenter Sites. To add any new asset to this site, you must log in to the Sites Administration page and open the Dev section in the left hand navigation as shown in Figure 62-50:

Figure 62-50 Sites Administration Page

Description of Figure 62-50 follows
Description of "Figure 62-50 Sites Administration Page"

First, create a new template with the following settings:

  • Name

    • Name: iFrameResizeRelay (or name of your choice)

    • For Asset Type: Applicable to various asset types (typeless)

  • Element

    • Usage: Element defines a whole HTML page and can be called externally

    • Element Storage Path/Filename: iframe-resize.html (or name of your choice)

    • Element Logic:

      <html>
        <head>
          <title>Resizing Page</title>
          <script type="text/javascript">
      function onLoad() {
      var params = window.location.search.substring( 1 ).split( '&' );
      var height;
      var width;
      var iframe;
      for( var i = 0, l = params.length; i < l; ++i ) {
      var parts = params[i].split( '=' );
      switch( parts[0] ) {
      case 'height':
      height = parseInt( parts[1] );
      break;
      case 'width':
      width = parseInt( parts[1] );
      break;
      case 'iframe':
      iframe = parts[1];
      break;
      }
      }
      window.top.updateIFrame( iframe, height, width );
      }
      if (window.addEventListener) {
      window.addEventListener("load", onLoad, false);
      } else if (window.attachEvent) {
      window.detachEvent("onload", onLoad);
      window.attachEvent("onload", onLoad);
      } else {
      window.onload=onLoad;
      }
          </script>
        </head>
        <body>
        </body>
      </html>
      
  • Site Entry

    • Cache Rules: Cached (default)

  • Save

  • Record SiteCatalog Pagename as %PAGENAME% (if you used the default name, this would be <site_name>/iFrameResizeRelay)

The new template is addressable as follows:

http://%SITES_HOST%/cs/Satellite?pagename=%PAGENAME%

Make a note of this URL; it will be used to configure the Injector for the pagelet.

Next, apply the iFrame resizing feature by adding a new Injector to the pagelet using the Pagelet Producer Administration Console. Open the pagelet, select Injectors and create a new Injector with the following settings:

  • General

    • Name: auto_resizer (or name of your choice)

    • URL Filter: <none>

    • MIME Filter: text/html

    • Inject Location: Before </head>

  • Content: Select Text (default) and copy the JavaScript below into the text area

    Replace SITES_RESIZE_RELAY_PAGE in the JavaScript below with the URL to the template you created in the previous step.

    <script type="text/javascript">
    var SITES_RESIZE_RELAY_PAGE = "http://%SITES_HOST%/cs/Satellite?pagename=%PAGENAME%"; // CHANGE ME!
     
    if (window.addEventListener) {
        window.addEventListener("load", calculateSizeFixed, false);
    } else if (window.attachEvent) {
        window.attachEvent("onload", calculateSizeFixed);
    } else {
        window.onload=calculateSizeFixed;
    }
    function calculateSizeFixed() {
      var PTResizeIFrame = PTResizeIFrame || {};
      if (PTPortalPage && PTPortalPage.portlets) {
        for (var i in PTPortalPage.portlets) {
          if ( PTPortalPage.portlets[i].id != "page") {
            PTResizeIFrame.pageletInstanceID = PTPortalPage.portlets[i].id;
            break;
          }    
        }
      }
      else if (!PTResizeIFrame.pageletInstanceID) {
        PTResizeIFrame.pageletInstanceID = 1;
      }
      
      if (!PTResizeIFrame.pageletResizePage) {
        var match = window.location.search.match(/resizepage=[^&]*/);
        if (match != null && match.length > 0) PTResizeIFrame.pageletResizePage = unescape(match[0].substr("resizepage=".length));
        else PTResizeIFrame.pageletResizePage = SITES_RESIZE_RELAY_PAGE;
      }
      var agent = navigator.userAgent;
      var ffversion = agent.indexOf("Firefox") >= 0 ? agent.substring(agent.indexOf("Firefox")).split("/")[1] : -1;
      var FFextraHeight = parseFloat(ffversion)>=0.1? 25 : 0;
      var scrollHeightExtra = 15;
      if (agent.indexOf('MSIE') > 0) {
        scrollHeightExtra = 35;
      }
      if (FFextraHeight > 0) scrollHeightExtra = FFextraHeight;
      var wrapper = document.getElementById( 'pt-inner-iframe-wrapper-' + PTResizeIFrame.pageletInstanceID);
      if (wrapper == null) wrapper = createRelayIFrame(PTResizeIFrame.pageletInstanceID);
      var iframe = document.getElementById( 'pt-inner-iframe-' + PTResizeIFrame.pageletInstanceID);
      var height = 0;
      var width = 0;
      var iframename = '';
     
      if( (document.contentDocument) && (document.contentDocument.documentElement.offsetHeight) ) {
        height = document.contentDocument.documentElement.offsetHeight + FFextraHeight; 
      } else if( (document.contentDocument) && (document.contentDocument.body.offsetHeight) ) {
        height = document.contentDocument.body.offsetHeight+FFextraHeight; 
      } else if (document && document.documentElement.scrollHeight ) {
        height = document.documentElement.scrollHeight + scrollHeightExtra;
      } else if( document && document.body.scrollHeight ) {
        height = document.body.scrollHeight + scrollHeightExtra;
      } else {
        height = wrapper.offsetHeight;
      }
      width = wrapper.offsetWidth;
      iframename = 'pt-pagelet-iframe-' + PTResizeIFrame.pageletInstanceID;
      var qsSeparator = PTResizeIFrame.pageletResizePage.indexOf("?") >= 0 ? "&" : "?";
     
    iframe.setAttribute("src", PTResizeIFrame.pageletResizePage + qsSeparator + 'height=' + height + '&' + 'width=' + width + '&' + 'iframe=' + iframename);
    }
     
    function createRelayIFrame(pageletInstanceId) {
      var wrapper = document.createElement("div");
      wrapper.id = "pt-inner-iframe-wrapper-" + pageletInstanceId;
      var iframe = document.createElement("iframe");
      iframe.id =  "pt-inner-iframe-" + pageletInstanceId;
      iframe.setAttribute("height", 0);
      iframe.setAttribute("frameborder", 0);
      iframe.setAttribute("width", 0);
      wrapper.appendChild(iframe);
      document.body.appendChild(wrapper);
      return wrapper;
    }
    </script>
    

Add the pagelet to the page template in Sites using a REST URL within an IFrame. In the IFrame, the id parameter should use the unique number identifying the pagelet IFrame (for example, "pt-pagelet-iframe-1"). You must add the following query string parameters to the pagelet URL to support IFrame auto-resizing:

  • resizepage=http://%SITES_HOST%/cs/Satellite?pagename=%PAGENAME%

  • ifheight=auto

For example:

<script type="text/javascript" src="http://%PAGELET_PRD_HOST%/pagelets/inject/v2/csapi"/>
<iframe id="pt-pagelet-iframe-1" width="100%" frameborder="0" src="http://%PAGELET_PRD_HOST%/pagelets/inject/v2/pagelet/lib_name/pagelet_name?content-type=html& consumepage=true&resizepage=http://%SITES_HOST%/cs/Satellite?pagename=%PAGENAME%&ifheight=auto">
</iframe>

Note:

In certain situations automatic resizing may not work properly when multiple pagelets are present on a page. This is known to occur with pagelets that require form auto-login to external authentication servers. In this case, only one pagelet can be configured for auto-resizing, while the others should use static IFrame sizing.
62.8.4.1.2 Changing Pagelet Styling

To make a pagelet fit better visually in a consuming WebCenter Sites page, an Injector may be used to add styles that override the original CSS. In order for the override to work correctly, it is important that the style definitions supplied by the Injector come after the styles defined by the backend application. The following example does this by injecting replacement CSS into the end of the <HEAD> section.

To restyle a pagelet, add a new Injector to the pagelet using the Pagelet Producer Administration Console. Open the pagelet, select Injectors and create a new Injector with the following settings:

  • General:

    • Name: new_styles (or name of your choice)

    • URL Filter: <none>

    • MIME Filter: text/html

    • Injector Location: Before </head>

  • Content

    Injector Location: Before </head>
    

Section 62.8.7, "Consuming Applications as Pagelets Using EBS11i" includes a working example of an Injector used to re-style the EBS UI to match the sample AviSports site in WebCenter Sites.

62.8.4.2 Using Identity Propagation

The core purpose of Pagelet Producer is to proxy backend applications. Since Pagelet Producer acts as a "middle-man" between the browser and the backend application, identity propagation must be broken into two parts:

62.8.4.2.1 Establishing Identity in Pagelet Producer

Pagelet Producer typically injects Web content into WebCenter Sites using an IFrame as shown in Figure 62-51.

Figure 62-51 Pagelet Producer Content as IFrame in Sites

Description of Figure 62-51 follows
Description of "Figure 62-51 Pagelet Producer Content as IFrame in Sites"

Since the content is injected as an IFrame, user identity must be established in both the Sites container and the Pagelet Producer container as shown in Figure 62-52. Note that Figure 62-52 leaves out the user directory that is assumed to be shared between the two authentication schemes.

Figure 62-52 Different authentication schemes for Sites and Pagelet Producer

Description of Figure 62-52 follows
Description of "Figure 62-52 Different authentication schemes for Sites and Pagelet Producer"

The ideal way to manage identity between the browser and the two containers would be to use Oracle Access Manager (OAM) as shown in Figure 62-53. Note that Figure 62-53 leaves out the user directory that is assumed to be shared between the two authentication schemes, and excludes the OAM access server. Note also that this configuration is not supported for pre-11g versions.

Figure 62-53 Ideal Frontend Authentication Configuration Using OAM

Description of Figure 62-53 follows
Description of "Figure 62-53 Ideal Frontend Authentication Configuration Using OAM"

To set up OAM for WebCenter Sites 11g, refer to the chapter on "Oracle Access Manager Integration Setup" in Oracle WebCenter Sites Configuring Supporting Software.

62.8.4.2.2 Using a Login Page Supplied by Pagelet Producer

Before setting up OAM, it is sometimes useful to test the integration of Pagelet Producer in Sites. Without OAM, users must authenticate separately with Pagelet Producer and with Sites (see Figure 62-52). This section describes how to configure separate authentication with Pagelet Producer.

If OAM SSO is not present on either Pagelet Producer or Sites, the authentication scheme shown in Figure 62-54 must be supported by ensuring that Pagelet Producer provides a login form.

To force Pagelet Producer to display a login form:

  1. Identify a J2EE role to restrict access to the pagelet(s) or create a new role in the J2EE application server hosting Pagelet Producer.

    This example uses the global WebLogic Server (WLS) "Anonymous" J2EE role that is present in a default WLS installation.

  2. Log in to the Pagelet Producer Administration Console, navigate to the resource(s) containing the pagelet(s) that must be surfaced in Sites and add the role you chose in step 1.

    Roles are defined on the Policy page for the resource.

    Figure 62-54 Pagelet Producer Administration Console - Policy Page

    Description of Figure 62-54 follows
    Description of "Figure 62-54 Pagelet Producer Administration Console - Policy Page"

62.8.4.3 Propagating Identity from Pagelet Producer to the Backend Application

The way in which identity is established depends on the type of application, as described in the following sections:

62.8.4.3.1 WSRP/JPDK Portlets

WSRP portlets must use WSS tokens for identity propagation. For details on configuring security tokens, see the "Registering WSRP and Oracle JPDK Portlet Producers in the Pagelet Producer" section in the Oracle Fusion Middleware Administering Oracle WebCenter Portal, and Section 62.8.5, "Consuming WSRP Portlets as Pagelets."

Each Oracle JPDK portlet that requires an identity will be passed credentials based upon information supplied by the external application's login form. For details, see the "Managing External Applications" and "Registering Oracle JPDK Portlet Producers" sections in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

62.8.4.3.2 Stand-alone Backend Application Protected with Native Authentication (Non-SSO)

Pagelet Producer has a feature called Autologin that allows Pagelet Producer to interact with the "native" authentication mechanism established by a backend application.

62.8.4.3.3 Identity Propagation with Autologin

Since each backend application has its own means of authentication, a separate login prompt must be initiated by Pagelet Producer to collect any required credentials. Pagelet Producer resources can be configured to send credentials to backend applications as basic authentication headers, NTLM tokens, or Kerberos tokens, as well as manage forms-based authentication (typically via a session cookie). For information about configuring Autologin, see Section 62.3.1.1.4, "Configuring Autologin."

Note:

Set the Username and Password fields to use the User Vault so that each user will be prompted for his or her own unique credentials to access the backend application.
62.8.4.3.4 Stand-alone Backend Application Protected with SSO

Determining the proper Autologin settings for a backend application can be very challenging. Doing so requires looking at request headers, identifying redirects, and examining markup (sometimes dynamically generated). This inspection and configuration process can be daunting if there are multiple applications for which Autologin is required. Therefore, if Oracle Access Manager (OAM) or Oracle SSO (OSSO) is available, it is highly recommended that one of these single sign-on solutions be used to protect backend applications.

Once the backend application is protected with OAM, there are two ways that Pagelet Producer can supply credentials as described in the following subsections:

62.8.4.3.5 Using Direct Identity Propagation to OAM Protected Backend Application

An OAM 11g WebGate is an Apache module running on Oracle HTTP Server (OHS) that manages all validation of user credentials with the OAM server. Once it has established the validity of a user it sends the OAM_REMOTE_USER header to the Web application on the application server that OHS is proxying. The application server will have an OAM identity asserter running on it that will set the JAAS user principal name to the OAM_REMOTE_USER header value.

If Pagelet Producer is protected with an OAM 11g WebGate it will receive an OAM_REMOTE_USER header. All Web applications that it proxies will also receive this header. If the Web application it proxies is on an application server with the OAM Identity Asserter, then the OAM Identity Asserter will use the OAM_REMOTE_USER header value passed from Pagelet Producer to set the user principal. This will all work as long as Pagelet Producer is not trying to proxy the URL to the WebGate for the protected Web application. The rest of this section describes in details how this can be achieved in the context of Sites integration.

Example Setup

This example assumes that both WebCenter Sites and Pagelet Producer are protected by OAM WebGate as illustrated in Figure 62-53 above, and the following hosts and ports are used by the applications:

  • OAM SSO WebGate: www.example.com:80

  • WebCenter Sites: sites_host:8080

  • WebCenter Pagelet Producer: pp_host:8889

  • Backend application: backendhost:8001

  • Full URL to backend application as viewed from browser (via WebGate)

    http://www.example.com/backend/console

  • Full URL to backend application if accessed directly through application server (available only in internal network) http://backendhost:8001/console

Set up the Pagelet Producer resource to use the direct URL to the backend application, thus bypassing the WebGate (i.e., http://backendhost:8001/console).

Figure 62-55 Pagelet Producer Administration Console - General Properties Page

Description of Figure 62-55 follows
Description of "Figure 62-55 Pagelet Producer Administration Console - General Properties Page"

By setting up Pagelet Producer to call directly into the backend application (bypassing the WebGate) all the OAM secure headers that Pagelet Producer receives are passed to the OAM Identity Asserter on the application server hosting the backend application. Once the OAM Identity Asserter on the application server hosting the backend application receives the OAM headers it will set the proper user principal (see Figure 62-56). Note that Figure 62-56 leaves out the user directory that is assumed to be shared between the two authentication schemes. It also excludes the OAM access server.

Figure 62-56 Pagelet Producer Calling the Backend Application Directly

Description of Figure 62-56 follows
Description of "Figure 62-56 Pagelet Producer Calling the Backend Application Directly"

Note:

Although setting up Pagelet Producer to bypass the WebGate will achieve single sign-on, this solution should not always be applied. In cases where the OHS server hosting the WebGate is also managing load balancing for the backend application, bypassing the WebGate will also bypass load-balancing. All traffic to the application will be routed to one server. In this case we recommend configuring Pagelet Producer for Autologin as described in Section 62.8.4.3.6, "Using Identity Propagation with Autologin and SSO."
62.8.4.3.6 Using Identity Propagation with Autologin and SSO

If bypassing the OAM WebGate (as described in Section 62.8.4.3.5, "Using Direct Identity Propagation to OAM Protected Backend Application") is not a feasible option then credentials can still be supplied using Pagelet Producer's Autologin feature. The advantage of using Autologin with an Oracle SSO solution (OAM or OSSO) login page as opposed to individual login forms for each backend application (see Section 62.8.4.3.3, "Identity Propagation with Autologin") is that Autologin only has to be set up once and the configuration steps are the same for every implementation.

The steps for setting up Autologin with OSSO are described in Section 62.8.7.2, "Configuring Autologin." In a production environment, these steps can be followed as is with one exception: the ssousername and password form fields should be linked to the "User Vault".

Backend applications protected with OAM can also be set up following the steps described for OSSO in the Configure Autologin section in this document with the following exceptions:

  • The login form URL will be a set location (e.g., http://oam11g.mycompany.com:14100/oam/server/obrareq.cgi).

    Be sure to remove the query string after the fixed location argument when setting the Autologin form identification URL.

  • The form action URL will be a different value, but it should be a static value. Inspect the OAM form to determine the form action URL.

  • The username and password fields may be different values. Inspect the OAM form fields to determine these values.

  • Include the following two generated values: "request_id" and "OAM_REQ".

62.8.4.3.7 Reference: Common Autologin Configurations

This section provides a quick reference of Autologin settings in Pagelet Producer for common backend SSO scenarios.

This section contains the following subsections:

62.8.4.3.8 Autologin Settings for Oracle Access Manager (OAM)

Login Form Identification:

  • URL: http://%OAM_ROOT%/server/obrareq.cgi

Form Submit Location:

  • URL: /oam/server/auth_cred_submit

Form Fields:

  • actionURL: static: /oam/server/auth_cred_submit

  • requested: Generated

  • username: Unsecured or Credential Vault

  • OAM_REQ: Generated

  • password : Unsecured or Credential Vault

62.8.4.3.9 Autologin Settings for Oracle SSO (OSSO)

Login Form Identification:

  • URL: %OSSO_HOST%/sso/jsp/login.jsp

Form Submit Location:

  • URL: %OSSO_HOST/sso/auth - POST

Form Fields:

  • appctx: Generated

  • locale: Generated

  • password : Unsecured or Credential Vault

  • site2pstoretoken: Generated

  • ssousername: Unsecured or Credential Vault

  • v: Generated

62.8.5 Consuming WSRP Portlets as Pagelets

Pagelet Producer incorporates the WebCenter Common Consumer and therefore can expose WSRP and Oracle JPDK portlets as pagelets for use in WebCenter Sites or any other Web container that does not include a WSRP consumer.

The WSRP Portlet Producer can be registered with Pagelet Producer using Fusion Middleware Control, WLST, or the Pagelet Producer Administrative Console. For more information, see the "Registering WSRP and Oracle JPDK Portlet Producers in Pagelet Producer" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal. Once registration is complete, the WSRP producer will appear as a resource in the Pagelet Producer Administrative Console, and the portlets associated with the WSRP endpoint will be listed in the pagelets collection for the resource.

Note:

Auto-generated WSRP resources and pagelets cannot be modified. To create a version that can be modified, choose the resource in the Pagelet Producer Administrative Console and click Copy. The cloned version of the resource can be edited and various elements such as Injectors can be added to customize pagelet functionality. For example, a custom Injector could be used to inject CSS classes to modify portlet markup to make it look and feel like the Sites that will host the pagelet.

If the WSRP Producer that you are registering with Pagelet Producer requires authentication, the following steps are required:

  • Configure WS-Security between Pagelet Producer and the WSRP Producer as described in Configuring WS-Security in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal. You must ensure that the Java Key Store (JKS) is properly configured between the WSRP producer and Pagelet Producer; for details, see the "Setting Up the WebCenter Portal Domain Keystore" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

  • During the WSRP Producer registration, select the appropriate Token Profile in the Security section and enter the necessary configuration information. The path to the keystore must be absolute.

62.8.5.1 Exposing Custom ADF Task Flows as WSRP Portlets

Although it is possible to consume an ADF task flow in Pagelet Producer by 'clipping' it out of the page on which it is hosted, this is not the recommended approach. Considering the complexity of the markup generated by an ADF page and potential dependencies on other task flows or ADF page parameters, the recommended approach is to create a WSRP portlet based on the task flow and then consume the portlet in Pagelet Producer. One advantage of this approach is that ADF task flow parameters become portlet parameters that can be mapped to pagelet parameters, allowing information to be passed from the Sites page to the tasteful. For step-by-step instructions on how to make a portlet from an ADF tasteful, see Section 58.2.3, "How to Create a JSF Portlet Based on a Task Flow."

After the ADF tasteful is exposed as a portlet, deploy a new WSRP Producer to a managed server in your WLS domain (for example, the WC_Portlet server on your WebCenter domain). Obtain the WSDL URL from the info page (http://%PRODUCER_HOST%/%APP_CONTEXT%/info) and make note of it. To register the new WSRP Producer with Pagelet Producer, see the "Registering WSRP and Oracle JPDK Portlet Producers in Pagelet Producer" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

62.8.5.1.1 Exposing WSRP Portlets Developed for Oracle WebLogic Portal

Oracle WebLogic Portal (WLP) supports a variety of portlet types, including Java Portlets, Java Server Faces Portlets, Java Server Page and HTML Portlets (for a complete list see the "Portlet Types" section in Oracle Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal). Remote (Proxy) Portlets are WSRP portlets and can be directly exposed as pagelets by registering the WSRP Producer with Pagelet Producer. This section describes how to expose local WLP portlets such as JSF, JSP or Java Portlets as pagelets for use in Sites.

62.8.5.1.2 Exposing WLP Portlets Using WLP as WSRP Producer

WLP can expose Java, Page Flow, JSP, JSF, and Struts Portlets as a "complex producer" that includes the required WSRP interfaces, optional interfaces and some extended interfaces (for details see "WebLogic Portal Producers" in the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal). Consequently, native WLP portlets can be consumed by Pagelet Producer as any other WSRP portlets. Configuration and best practices for WSRP interoperability between WLP and the WebCenter Common Consumer are described in the "WSRP Interoperability with Oracle WebCenter Portal and Oracle Portal" section in Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.

Note:

WLP portlets are WSRP-enabled by default since version 9.2. In earlier versions, you must edit the portlet properties and set the "Offer as Remote" property to true.
62.8.5.1.3 Configuring WS Security between WLP WSRP Producer and WebCenter Consumer

To consume WSRP portlets exposed by WLP in the WebCenter Common Consumer (Pagelet Producer), configuration is required on both the producer and consumer sides.

Typically it is impossible to consume WSRP portlets exposed by WebLogic Portal as an anonymous user, so it is necessary to configure SAML security on WLP for the producer and the WebCenter Common Consumer. Step-by-step instructions can be found in the "SAML Security Between a WebCenter Portal: Framework Application Consumer and a WebLogic Portal Producer" section in Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal. These instructions are comprehensive, with the following adjustments:

  • In section 5 of "Configuring the Producer", the steps for configuring keystore information on the WSRP consumer are executed in JDeveloper. You must complete this step in the WebCenter Common Consumer (Pagelet Producer). You can specify the signing alias and keystore password using WLST or Fusion Middleware Control. For details, see "Configuring the Keystore Using WLST" or "Configuring the Keystore Using Fusion Middleware Control" in the Oracle Fusion Middleware Administrator's Guide for Oracle WebCenter Portal.

    Note:

    Once you have configured the keystore values you must restart both the managed server hosting Pagelet Producer (by default WC_Portlet) and the WLS Admin Server for the JPS configuration changes to be picked up.
  • In section 4 of "Configuring the Producer", the instructions do not emphasize the importance of the issuer name. The name placed here must match that sent by the consumer. For Oracle JPS, the default issuer ID sent is www.oracle.com.

62.8.5.1.4 Registering the WLP WSRP Producer in Pagelet Producer

To register the WLP WSRP Producer in Pagelet Producer, follow the standard steps for creating and configuring a new WSRP Producer described in the "Registering WSRP and Oracle JPDK Portlet Producers in Pagelet Producer" section in Oracle Fusion Middleware Administering Oracle WebCenter Portal. Make sure to include the following settings:

  • WSDL URL:

    http://%WLP_HOST%/%PORTAL_APP_NAME%/producer/wsrp-1.0/markup?WSDL

  • Security:

    Token Profile: Select "WSS 1.0 Token with Message Integrity"

After registration, a new Pagelet Producer resource is automatically created and populated with pagelets to represent the WLP portlets associated with this WSRP endpoint.

Note:

To allow user identity propagation to the portlets, both WLP and Pagelet Producer should be configured as described in Section 62.8.4.3, "Propagating Identity from Pagelet Producer to the Backend Application." (For testing purposes or for portlet content that can be accessed without authentication, you can specify a valid username in the Default User field under Security.)
62.8.5.1.5 Adding WLP WSRP Portlets to Sites

To add WLP WSRP portlets to a page in Sites, follow the steps in Section 62.8.4.1, "Adding Pagelets to Oracle WebCenter Sites." The URL to use for the src attribute in the IFrame tag that loads pagelet content can be found under "Documentation" in Section 62.7.2.2, "Accessing Pagelets Using REST."

Auto-generated WSRP resources and pagelets cannot be modified. To use Pagelet Producer features to alter the markup of the WLP portlet such as modify look and feel of the portlet UI by injecting custom CSS styles, you must create a new version of the resource. Choose the resource that was created for your WLP WSRP Producer in the Pagelet Producer Administrative Console and click Copy. The cloned version can be modified, including adding elements such as Injectors to customize pagelet functionality.

62.8.6 Consuming WebCenter Portal Services as Pagelets in Sites

WebCenter Portal includes services and tools, such as announcements and documents, that can be used to facilitate user collaboration in WebCenter Sites. For an overview of these tools, see the "Part IV Staying Informed" and "Part V Staying Organized" parts in Oracle Fusion Middleware Using Oracle WebCenter Portal.

The recommended approach for exposing these services and tools in Sites is to consume the associated WSRP portlets in Pagelet Producer by leveraging the Services Producer component included with Oracle WebCenter Portal (11.1.1.6 and later).

The following portal tools are exposed as WSRP portlets by default:

  • Activity Stream

  • Discussion Forums

  • Mail

  • Polls Manager

  • Document Manager

  • Lists

  • Tag Cloud

  • Blogs

  • Work list

  • Polls

  • Announcements

Note:

Additional tools can be exposed by extending the Services Producer to a new JSPX page and then adding the taskflow to the page.

62.8.6.1 Requirements

Install WebCenter Portal following the instructions in the Oracle Fusion Middleware Installation Guide for Oracle WebCenter. Make sure that all dependent components are also installed and configured, including WebCenter Content Server, the discussions server, and Pagelet Producer. For more information, see Section 62.1.3, "Requirements."

62.8.6.2 Configuring Security and Single Sign-On

There are two prerequisites to allow access to WebCenter Portal services from a Sites-driven Web site:

  • Create a common user base between the Web site and WebCenter Portal

  • Establish user identity propagation from the Web site to WebCenter Portal

These are described in the following subsections:

62.8.6.2.1 Creating a Common User Base: LDAP Integration

Creating a common user base requires configuring a common LDAP repository to be used by WebCenter Sites and all WebCenter Portal components. When selecting an LDAP server, make sure it is compliant with the WebLogic Server that runs WebCenter Portal components.

Things to remember when configuring security on WLS:

  • Set the priority of the Authenticators to SUFFICIENT

  • Set the Control Flag (in parenthesis) and order of authentication providers as follows:

    • OAM Identity Asserter (REQUIRED)

    • LDAP Authenticator (SUFFICIENT)

    • Default Authenticator (SUFFICIENT)

    • Default Identity Asserter (SUFFICIENT)

62.8.6.2.2 Establishing User Identity Propagation: OAM Configuration

To establish user identity propagation, we recommend configuring the SSO solution for WebCenter Sites and WebCenter Portal using Oracle Access Manager (OAM).

If you are using OAM, make sure it is configured to pass the user principal name in the ORACLE_REMOTE_USER header. Both ObSSOCookie and OAM_REMOTE_USER must be set to active on the OAM Identity Asserter on the WebLogic Server.

62.8.6.2.3 Configuring the GUID Attribute in the Identity Store

Specify the GUID attribute value to ensure that the value that is used in the identity store matches the value configured in the LDAP authentication provider. This value is configured in the jps-config.xml file.

Set the GUID for your LDAP authenticator in the jps-config.xml file.

<serviceInstance provider="idstore.ldap.provider" name="idstore.ldap">
<property value="oracle.security.jps.wls.internal.idstore.WlsLdapIdStoreConfigProvider" name="idstore.config.provider"/>
<property value="oracle.security.idm.providers.stdldap.JNDIPool" name="CONNECTION_POOL_CLASS"/>
<property value="GUID=uuid" name="PROPERTY_ATTRIBUTE_MAPPING"/>
</serviceInstance>
62.8.6.2.4 Configuring SSO for Discussions Server

To use discussions, configure the discussions server for SSO before ordering the Authenticators in WebLogic Server (using the Default Authenticator and Default Identity Asserter). It is also possible to use WLST to configure SSO for the discussions server. For details, see the "Configuring the Discussions Server for SSO" chapter in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

62.8.6.3 Registering WebCenter Services Exposed as WSRP Portlets

To import the WSRP portlets that expose WebCenter Services into Pagelet Producer, simply register the Services Producer as a WSRP Producer in Pagelet Producer using Enterprise Manager, WLST or the Pagelet Producer Administrative Console.

Figure 62-57 shows an example of WSRP endpoint registration in the Pagelet Producer Administrative Console. For details, see the "Registering WSRP and Oracle JPDK Portlet Producers in Pagelet Producer" sections in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

Figure 62-57 Pagelet Producer Administrative Console - Registering WSRP Endpoint

Description of Figure 62-57 follows
Description of "Figure 62-57 Pagelet Producer Administrative Console - Registering WSRP Endpoint"

The Token Profile in the Security section of this page must be set to WSS 1.0 SAML Token to support the Services Producer. You should also enter a suitable execution timeout for requests made by Pagelet Producer to the Services Producer (the default is 30 seconds).

Once registration is complete, the Services Producer will appear as a resource in the Pagelet Producer Administrative Console and all WSRP portlets exposed by the Producer will be listed in the pagelets collection for the resource:

Description of jpsdg_sites10.gif follows
Description of the illustration jpsdg_sites10.gif

62.8.6.3.1 Adding Pagelets to Sites Pages

Any pagelet exposing WebCenter Services can be added to a WebCenter Sites page following the steps described in Adding Pagelets to Oracle WebCenter Sites. Figure 62-58 shows the Document Manager Service embedded into a page of the AviSports sample site in WebCenter Sites.

Note:

Auto-generated WSRP resources and pagelets such as the ones associated with the Services Producer cannot be modified. To add an Injector or make other modifications, you must create a version that can be edited. Choose the resource in the Pagelet Producer Administrative Console and click Copy. The cloned version of the resource can be edited and various elements such as Injectors can be added to customize pagelet functionality.

Figure 62-58 AviSports Sample Site with Document Embedded

Description of Figure 62-58 follows
Description of "Figure 62-58 AviSports Sample Site with Document Embedded"

62.8.7 Consuming Applications as Pagelets Using EBS11i

This section provides detailed instructions for consuming the Oracle E-Business Suite 11i Order Information module UI as a pagelet. It covers autologin, navigation suppression, restyling, and URL rewriting.

This example was created using an EBS 11i instance that is protected with Oracle SSO. The following common terms and variables are used in the example:

  • %EBS_HOST%: root URL of the EBS host (for example, http://my-ebs.company.com:port/)

  • %OSSO_HOST%: root URL of the OSSO host (for example, http://sso.company.com:port/)

This section contains the following subsections:

62.8.7.1 Creating a Resource for Basic URL Mapping (Proxy)

The following steps set up the basic URL mapping for a new EBS resource in Pagelet Producer:

  1. Create new "Web" resource with the following settings:

    • Name: EBS 11 (or your choice)

    • Source URL: %EBS_HOST%

      Make sure the URL is not more specific to avoid missing URLs used in the UI

    • Destination URL: /ebs11/ (or your choice)

    • URL Rewriting: on

    • DHTML Rewriting: on

  2. Click Save.

62.8.7.2 Configuring Autologin

This step assumes that the EBS System is protected by OSSO and that Pagelet Producer will be configured to provide form Autologin rather than participate in SSO (a common scenario if the Web site is not protected by SSO). EBS credentials may be shared for all users (useful for testing) or stored in the Pagelet Producer credential vault for each user.

  1. Create a new "Web" resource with the following settings:

    • Name: OSSO (or your choice)

    • Source URL: %OSSO_HOST%

    • Destination URL: /osso/ (or your choice)

    • URL Rewriting: on

    • DHTML Rewriting: off

  2. Click Save.

  3. Under the newly created OSSO resource, configure Autologin using the Form Login option as follows:

    • Login Form Identification: URL - %OSSO_HOST%/sso/jsp/login.jsp

    • Form Submit Location: URL - %OSSO_HOST/sso/auth - POST

    • Form Fields:

      appctx: Generated

      locale: Generated

      password: Unsecured or User Vault

      site2pstoretoken: Generated

      ssousername: Unsecured or User Vault

    • v: Generated

  4. Click Save.

Note:

The names of login form fields are usually obtained by investigating the HTML source for the login page that protects the backend resource.

62.8.7.3 Creating a Pagelet

This step associates a pagelet with the Order Status page in the EBS Order Information module. To create a new pagelet, select the Pagelets section under the EBS resource you created and click the Create icon. Create the new pagelet with the following settings:

  • Name: order_status (or your choice)

  • Library: ebs11 (or your choice)

  • URL Suffix: OA_HTML/RF.jsp?function_id=1005664&resp_id=22480&resp_appl_id=660&security_group_id=0&lang_code=US

  • Refresh Inline: off

You can test the configured pagelet by accessing it via the REST link on the Documentation page. You should be taken to the Sales Order page without logging in (unless the pagelet uses the User Vault to store credentials and you are accessing it for the first time). From this page, you can use Simple Search to locate orders, using '%' as a wildcard character.

62.8.7.4 Making Corrective Configurations

After a pagelet has been created, it often requires additional features (Parser, Injector and/or Clipper) to either address issues with URL re-writing in the proxied markup, or simply to modify the markup for style or to hide unnecessary elements. This section describes corrective configurations that were applied to the sample pagelet that exposes the Order Information UI in EBS.

This section includes the following subsections:

62.8.7.4.1 Creating a Pluggable Parser for Popup URL Rewriting

Parsers allow you to supplement or change the built-in logic for parsing content and finding URLs that need to be rewritten. When built-in parsers fail to identify URLs, custom parsers can be used to correct this failure. In the case of the EBS 11i UI, this step is required to fix popup handling in Advanced Search.

Under the EBS Resource, create a new Parser with the following settings:

  • Name: popupRewriter (or your choice)

  • URL Filter: *.jsp*

  • Use Base Parser: on

  • Fragment Locations

    • var _jspDir='(.*?)'; (type Static URL)

    • <frame .? src="(.?) (type Static URL)

Figure 62-59 shows the settings for the popupRewriter.

Figure 62-59 popupRewriter

Description of Figure 62-59 follows
Description of "Figure 62-59 popupRewriter"

62.8.7.4.2 Creating an Injector to Disable Frame-busting

Injectors insert content into a specified location in the proxied resource page. The content can be any text, including HTML, CSS, JavaScript, and pagelet declarations. An empty injector may also be used to remove unwanted content from the page. The following injector was created for the EBS pagelet to prevent it from taking over the page, which was happening on the first displayed page where the user is asked to choose responsibility.

Under the EBS resource create a new Injector with the following settings:

  • General

    • Name: frameBustDisabler

    • URL Filter: <none>

    • MIME Filter: text/html

    • Inject Location: Replace target=_top

  • Content: (Text) alt=''

Figure 62-60 shows the parameter settings for the new Injector.

Figure 62-60 frameBustDisabler Injector

Description of Figure 62-60 follows
Description of "Figure 62-60 frameBustDisabler Injector"

62.8.7.4.3 Creating an Injector to Auto-Resize the iFrame

In order to provide a more seamless integration into the consuming page, the pagelet iFrame can be configured to behave more like inline content by dynamically resizing to accommodate its contents. For details, see Enabling IFrame Auto-Resizing in this document.

62.8.7.4.4 Setting Up Clipping by JavaScript Injection

One option for suppressing page elements exposed as a pagelet is to create a clipper using graphical or Regular Expression-based clipping, available in Pagelet Producer. However, the recommended approach is to use custom JavaScript that is injected into the proxied page. This approach is often more flexible as it can easily accommodate the need to dynamically adjust rules that identify the element(s) to suppress or accommodate rules for suppressing multiple elements on the page.

Custom JavaScript can be added to the proxied resource page using an injector. To suppress EBS 11i standard header and navigation elements, use the following injector definition to insert a snippet of JavaScript that hides the unnecessary elements at page load time. (The standard Clipper feature in Pagelet Producer is not used due to the complexity of the EBS Web UI.)

Under the EBS Resource, create a new Injector with the following settings:

  • General:

    • Name: nav_suppressor (or your choice)

    • URL Filter: <none>

    • MIME Filter: text/html

    • Inject Location: Before </body>

  • Content: (Text - copy and paste the content below)

    <script type="text/javascript">
    // this script is injected into the page by ensemble
    // it hides header and footer tables at page load
     
    // register handler function to the page load event
    if (window.addEventListener) {
      window.addEventListener('load', hideHeaderFooter, false);
    } else if (document.attachEvent) {
      window.attachEvent('onload', hideHeaderFooter);
    }
     
    // this function does the actual hiding
    function hideHeaderFooter() {
      var form = document.forms[0];
      if (typeof(form) == 'undefined') return;
      // main span is form's second child span
      var spansFound = 0;
      var mainSpan = null;
      for (var i = 0; i < form.childNodes.length; i++) {
        var child = form.childNodes[i];
        if (child.tagName && child.tagName.toLowerCase() == 'span') {
          if (++spansFound == 2) {
           mainSpan = child;
           break;
          }
        }
      }
      if (typeof(mainSpan) != "undefined" && mainSpan != null) {
        for (var i = 0; i < mainSpan.childNodes.length; i++) {
          var child = mainSpan.childNodes[i];
           if (child.tagName && child.tagName.toLowerCase() == 'table') {
             child.style.display = 'none';
           }
        }
      }
    }
    // call this function directly
    hideHeaderFooter();
    </script>
    
62.8.7.4.5 Creating an Injector for Pagelet Restyling

To make the EBS pagelet fit better visually in the consuming page, an injector can be used to add styles to override the original CSS.

The example injector definition below shows how to implement restyling for the AviSports sample Web site in WebCenter Sites.

Note:

In order for the override to work correctly, it is important that the style definitions supplied by the injector come after the styles defined by the backend application. In the example below, the content is injected into the end of the <HEAD> section on the page.

Under the EBS Resource, create a new Injector with the following settings:

  • General:

    • Name: avisports_styles

    • URL Filter: <none>

    • MIME Filter: text/html

    • Inject Location: Before </head>

  • Content: (Text - copy and paste the content below)

    <style>
    * { 
      font: 11px Arial,Helvetica,sans-serif; 
    }
    body {
      background: url("http://sites-host:port/cs/avisports/images/BlueSliver.png") repeat-x scroll center bottom transparent;
    }
    .OraTableCellText, .x1l, .OraTableCellNumber, .x1n, .OraTableCellIconButton, .x1p, .OraTableCellSelect, .x55, 
    .OraTableControlBarTop, .x1i, .OraTableControlBarBottom, .x1j {
        background-color: #eceef1;
        border-color: #0b2a55;
    }
    .OraTableColumnHeader, .x1r, .OraTableSortableColumnHeader, .x20, .OraTableSortableHeaderLink, .x23 {
        background-color: #0b2a55;
        border-color: #F7F7E7;
        color: #336699;
    }
    .OraTableHeaderLink, .x24, .OraTableColumnHeaderNumber, .x1s, .OraTableColumnHeaderIconButton, .x1t {
        background-color: #0b2a55;
        color: #ffffff;
    }
    .p_InContextBrandingText, .x2l, .OraHGridNavRowInactiveLink, .x3v, .OraNavBarInactiveLink, .x42, 
    .OraBINavBarInactiveLink, .x7n, .OraBINavBarInactiveLink_small, .x7o {
        color: #000000;
    }
    .OraLink:link, .xd:link, .OraBreadCrumbs, .xh, .OraBulletedList a, .xj a, .OraLinkText, .x2v, 
    .OraHGridNavRowActiveLink, .x3u, .OraNavBarActiveLink, .x41, .OraBINavBarActiveLink, .x7l, .OraBINavBarActiveLink_small, .x7m {
        color: #0b2a55;
    }
    .OraBreadCrumbs a, .xh a {
        color: #0b2a55;
    }
    </style>
    
62.8.7.4.6 Testing the Pagelets

The EBS11 resource now includes the pagelet, the custom injectors, and the custom parser as shown in Figure 62-61.

Figure 62-61 EBS11 Project Resources

Description of Figure 62-61 follows
Description of "Figure 62-61 EBS11 Project Resources"

Test the pagelet by browsing to the Documentation page and using the URL shown below, substituting the local host ID for "example.com."

http://example.com:8889/pagelets/inject/v2/pagelet/ebs11/order_status?content-type=iframe&csapi=true&ifheight=300px
62.8.7.4.7 Final Result

The following screenshots show the EBS 11i Order Information screens embedded into a page of the AviSports sample site in WebCenter Sites using a REST URL for pagelet access in an iFrame:

Description of jpsdg_sites14.gif follows
Description of the illustration jpsdg_sites14.gif

Description of jpsdg_sites15.gif follows
Description of the illustration jpsdg_sites15.gif

Description of jpsdg_sites16.gif follows
Description of the illustration jpsdg_sites16.gif

62.8.7.4.8 Troubleshooting

If some images are not rendered properly, make sure DHTML rewriting is enabled. (The DHTML Rewriting setting is on the General page for the resource.)

62.8.8 Consuming OpenSocial Gadgets Using Pagelet Producer

Pagelet Producer is an OpenSocial container that exposes the following features:

  • People (exposes People Connections)

  • Activities (exposes Activity Stream)

  • Appdata (supports gadget personalization)

  • Pub-Sub mechanism

Note that the People and Activities features require WebCenter Portal. To use the People or Activities features, target the WebCenterDS at the WC_Portlet managed server (i.e., at Pagelet Producer). For Appdata, Pagelet Producer supports user, instance and pagelet -scoped preferences.

To follow the example:

  1. Open Pagelet Producer and create a new OpenSocial resource.

  2. Define the URLs and policies as required.

  3. Create a new pagelet specifying the URL for an external gadget.

    For example:

    http://bayareacoder.com/gogo/localweather/localweather.xml

  4. If the gadget supports Preferences, configure the required parameters (see Figure 62-62 and Figure 62-63).

    Figure 62-62 Preferences Editor

    Description of Figure 62-62 follows
    Description of "Figure 62-62 Preferences Editor"

    Figure 62-63 Pagelet Parameters Dialog

    Description of Figure 62-63 follows
    Description of "Figure 62-63 Pagelet Parameters Dialog"

  5. Create or upload the gadget XML file (see Figure 62-64).

    Figure 62-64 Pagelet Producer with Activities JavaScript and XML Options

    Description of Figure 62-64 follows
    Description of "Figure 62-64 Pagelet Producer with Activities JavaScript and XML Options"

    Note that the path supplied in the Name field is a 'virtual' URL that Pagelet Producer will use to serve the file and any path or name can be used.

  6. Create or upload any other files that the new gadget requires (for example, any JavaScript files, images, and so forth), and you're done.

62.8.9 Manipulating HTML Markup

This section discusses how you can inject JavaScript to modify HTML markup, and use an injector with SSL.

This section includes the following subsections:

62.8.9.1 Using an Injector with JavaScript

Injecting and/or replacing just HTML markup has limited potential. A more useful approach to consider is injecting JavaScript that directly modifies HTML markup. To do so:

  • Register a handler function on the page load event as shown in the following code snippet:

    if (window.addEventListener) {
      window.addEventListener('load', hideHeaderFooter, false);
    } else if (document.attachEvent) {
      window.attachEvent('onload', hideHeaderFooter);
    }
    
  • Use the handler to do the markup manipulation as shown in the rest of the code sample:

    function hideHeaderFooter() {
      var header = null;
      // find the header table by class 
      if (document.getElementsByClassName) {
        header = document.getElementsByClassName('page_header')[0];
      } else {
        // for older versions of IE
        var tables = document.getElementsByTagName('table');
        for (var table in tables) {
          if (table.class == 'page_header') {
            header = table;
            break;
          }
        }
      }
      if (header != null) {
        header.style.display = 'none';
      }
      // now find and hide the footer (easier to find, since it has an id)
      var footer = document.getElementById('t23PageFooter');
      if (footer != null) {
        footer.style.display = 'none';
      }
    }
    </script>
    

62.8.9.2 Using an Injector with SSL

Consuming an SSL resource requires a Pagelet Producer connection over HTTPS, including:

  • Secure port mapping between WLS and Pagelet Producer

  • Container should also be accessed via HTTPS

The injector can modify HTML markup that Pagelet Producer proxies:

  • Based on URL pattern (resource scope)

  • Based on MIME type

  • Based on location (top or bottom) or exact text match (before, after, replace)

  • Content page defines what gets injected

62.8.10 Advanced URL Rewriting

This section describes how to use Pagelet Producer's auto-login feature, and how to design a custom parser.

This section contains the following sub-sections:

62.8.10.1 Using Auto-Login

Auto-login lets you pass username/password credentials to a back-end resource. These can be passed as either:

  • Static credentials – one set for all users

  • Dynamically acquired from user at first resource access and then stored in secure Credential Vault

  • User Profile (capture and pass username)

The supported authentication mechanisms for auto-login are:

  • Basic login

  • Form login (used in the following example)

  • NTLM login

  • Kerberos login

The example in Figure 62-65 and the code snippet below shows how you can use auto-login to redirect to a login page:

Figure 62-65 Pagelet Producer - Auto-Login Example

Description of Figure 62-65 follows
Description of "Figure 62-65 Pagelet Producer - Auto-Login Example"

The following code reflects the settings in Figure 62-65:

<form action="wwv_flow.accept" method="post" name="wwv_flow" id="wwvFlowForm" autocomplete="off">
 <input type="hidden" name="p_flow_id" value="53557" id="pFlowId" />
<input type="hidden" name="p_flow_step_id" value="101" id="pFlowStepId" />
<input type="hidden" name="p_instance" value="724836084846701" id="pInstance" />
<input type="hidden" name="p_page_submission_id" value="1431956852758801" id="pPageSubmissionId" />
<input type="hidden" name="p_request" value="" id="pRequest" /> 
<div id="login"> <div id="messages"></div> <div id="login-main">
<table id="myapp_layout_45149677586857064102" border="0" class="formlayout" summary="" role="presentation" datatable=0 >
<tr><td align="right"><label for="P101_USERNAME" tabindex="999"><a class="optional-w-help" href="javascript:popupFieldHelp('45149677686365064111','724836084846701')"
tabindex="999">
User Name</a></label></td> <td colspan="1" rowspan="1" align="left"><input
type="hidden" name="p_arg_names" value="45149677686365064111" /><input type="text"
id="P101_USERNAME" name="p_t01" value="" size="20" maxlength="100" class="text_
field" /></td></tr><tr><td align="right"><label for="P101_PASSWORD"
tabindex="999"><a class="optional-w-help" href="javascript:popupFieldHelp('45149677888869064121','724836084846701')"
tabindex="999">Password</a></label></td> <td colspan="1" rowspan="1"
align="left"><input type="hidden" name="p_arg_names" value="45149677888869064121"/>
<input type="password" name="p_t02" size="20" maxlength="100" value="" id="P101_
PASSWORD" class="password" onkeypress="return submitEnter(this,event)" />
<input type="button" value="Login"onclick="myapp.submit('LOGIN');" id="P101_LOGIN" />
</td></tr> </table> Please refer to "Using Myapp" in the Myapp User's Guide for more information.</div>
</div> <input type="hidden" name="p_md5_checksum" value="" /><input type="hidden"
 name="p_page_checksum" value="D95DBE8607E971820E98E93FC0EC064E" /></form>

62.8.10.2 Using a Custom Parser

Parsers let you extend or change built-in logic for URL parsing. Using a URL Filter and regular expressions, you can narrow down the part of the page that the parser should modify (Figure 62-66).

Figure 62-66 Pagelet Producer - Custom Parser Example

Description of Figure 62-66 follows
Description of "Figure 62-66 Pagelet Producer - Custom Parser Example"

Using regular expressions lets you specify the HTML fragment to parse. The first grouping expression, denoted by parentheses, identifies the fragment itself, while the rest of the expression provides the context for finding it. A pluggable parser framework lets you fine-tune how the proxy recognizes different types of content based on MIME type, HTTP headers or URL.

In this example, there are three URLs in two places within the page markup that need to be modified to make Flash work:

<embed src=" /i/flashchart/anychart_5/swf/OracleAnyChart.swf?
XMLFile=http://example.com/pls/myapp/myapp_
util.flash?p=53557:1:74175370346201:FLOW_FLASH_CHART5_R45192463162785599619_en"
      <param name="movie" value="/i/flashchart/anychart_5/swf/AnyChart.swf?
        XMLFile=http://example.com/pls/myapp/myapp_
util.flash?p=53557:1:74175370346201:FLOW_FLASH_CHART5_R45192463162785599619_en"

The following three regular expressions (shown under Regular Expressions in Figure 62-66) are used to achieve this:

  • XMLFile=(.*?)"

  • param name="movie" value="(.*?\.swf)

  • embed src="(.*?\.swf)

62.9 Troubleshooting Pagelets

Keep the following common configuration errors in mind when troubleshooting resources and pagelets. For details on configuring Pagelet Producer settings, see Section 62.2, "Configuring Pagelet Producer Settings."

  • If you are using SSL, make sure both HTTP (nonsecure) and HTTPS (secure) ports are configured properly on the Transform page of the Pagelet Producer settings.

  • If you are proxying external sites on a network that requires an HTTP proxy, you must configure the proxy URL on the Proxy page of the Pagelet Producer settings.

  • Confirm that the login_resource and pagelet_api resources, created by default, are present and correctly configured.

  • If you are proxying KD Browser or other CSP pagelets, make sure the image service URL is absolute and the CSP SOAP API URL is set correctly in the CSP page of the Pagelet Producer settings.

  • Due to restrictions in the Sun Java Virtual Machine (JVM), pagelets cannot use HTTPS content where the underlying certificate uses MD2 signing algorithm.

For additional troubleshooting information, use logging. Pagelet Producer logs messages to the standard Oracle Diagnostic Logging facility. In Oracle WebLogic Server, that location is: user-projects/domains/<domain>/servers/ <server>/logs/<server>-diagnostic.log. For details on configuring logging, see Section 62.2.2, "Configuring Logging Settings." For more information on debugging pagelets, see the "Creating Pagelets with Oracle WebCenter Portal's Pagelet Producer" chapter in Oracle Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper.