14 Introduction to Pagelets

Learn about pagelets and how to create them suing WebCenter Portal's Pagelet Producer.

Topics:

14.1 About Creating Pagelets with 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:

14.1.1 Overview

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.

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), Oracle PDK-Java, 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, Oracle PDK-Java, 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

14.1.2 Pagelet Producer Architecture

This section describes the Pagelet Producer architecture and its key components.

This section includes the following topics:

14.1.2.1 Pagelet Producer Architecture and Components

Figure 14-1 shows a high-level view of the Pagelet Producer components and their interactions. Figure 14-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 back-end system. After the markup is received it is modified using any defined clippers, parsers, and so forth.

Figure 14-1 Pagelet Producer - High-Level Architecture

Description of "Figure 14-1 Pagelet Producer - High-Level Architecture"

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

Figure 14-2 Pagelet Producer - Interaction Flow

Description of "Figure 14-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: 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).

14.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. 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 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 WebCenter Portal, 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 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 WebCenter Portal or the managed server.

14.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 Configuring Pagelet Producer Settings and Creating Pagelet Producer Objects. For information about using the Pagelet Producer Console to register producers and migrate pagelet data, see Managing the Pagelet Producer in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

14.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:

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

14.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 14-1) can also be used by pagelets.

Table 14-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.

14.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 How to Configure 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 How to Configure 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 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.

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

14.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 Pagelet Producer Console.

The Settings pages are described in the following topics:

14.2.1 How to Configure 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 Configuring JDBC Data Sources in Oracle Fusion Middleware Administering JDBC Data Sources for Oracle WebLogic Server to configure the data source. Note that the data source must be named wcidb.

14.2.2 How to Configure Logging Settings

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

Figure 14-3 Pagelet Producer Console: Settings - Logging

Description of "Figure 14-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.

14.2.3 How to Configure 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:

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 14-4 Pagelet Producer Console: Settings - Proxy

Description of "Figure 14-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.

14.2.4 How to Configure 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 14-5 Pagelet Producer Console: Settings - Transform

Description of "Figure 14-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 is where you define a 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.

14.2.5 How to Configure 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.

14.2.6 How to Configure 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.

14.2.7 How to Configure OpenSocial Settings

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

Figure 14-6 Pagelet Producer Console: Settings - OpenSocial

Description of "Figure 14-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 Redeploying Pagelet Producer to a Different Context 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 How to Configure Transform Settings.