Skip Headers
Oracle® Fusion Middleware Developing Portals with Oracle WebCenter Portal and Oracle JDeveloper
11g Release 1 (11.1.1.8.3)

Part Number E27739-05
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

57 Introduction to Portlets

This chapter provides an overview of portlets and describes their uses. It explains portlet anatomy and the resources you can use to create portlets. This chapter also explains the features, technologies, and tools to help you decide which portlet building technology best suits your needs.

This chapter includes the following topics:

57.1 Introduction to Portlets

A portlet is a reusable web component that can draw content from many different sources. Portlets can contain anything from static HTML content to Java controls to complex web services and process-heavy applications.

Figure 57-1 The Lottery Sample Portlet

Description of Figure 57-1 follows
Description of "Figure 57-1 The Lottery Sample Portlet"

Portlets provide a means of presenting data from multiple sources in a meaningful and related way. Portlets can display excerpts of other web sites, generate summaries of key information, perform searches, and access assembled collections of information from a variety of data sources. Because several different portlets can be placed on a single page, users benefit from a single-source experience even though, in reality, the content may be derived from multiple sources.

Portlets can communicate with each other using events and other techniques. A single portlet can also have multiple instances—in other words, it can appear on a variety of different pages within a single portal, or even across multiple portals. Page designers can customize portlets to meet the needs of their specific audience. With the correct privileges, individual end users can further personalize portlets for their own particular requirements.

Oracle WebCenter Portal supports the development of portlets using JSR 286, an industry standard. You can also create portlets from existing JSF applications using the Oracle JSF Portlet Bridge. For more information, see Section 57.3, "Portlet Resources."

57.2 Portlet Anatomy

Portlet anatomy is the visual representation of the portlet on a page. Figure 57-2 shows some aspects of portlet anatomy that you might expect to see in a typical portlet in a WebCenter Portal Framework application. Note that the same portlet displayed in a different application could look different.

Figure 57-2 A Sample Portlet Showing Typical Portlet Anatomy

Description of Figure 57-2 follows
Description of "Figure 57-2 A Sample Portlet Showing Typical Portlet Anatomy"

Aspects of portlet anatomy (some, but not all, of which are illustrated in Figure 57-2) include:

The portlet anatomy rendered on the page is controlled by two factors:

For example, when designing the portlet, the portlet developer may implement Help mode for the portlet. When an application developer adds the portlet to the page, he or she can determine, using the portlet tag attribute isHelpModeAvailable, whether or not to include the Help command in the portlet's Actions menu. If the application developer sets isHelpModeAvailable to false, the Help command is not included in the Actions menu even though it is provided in the portlet logic. Conversely, if the portlet developer has not implemented Help mode for a portlet, the Help command is not displayed in the Actions menu, even if isHelpModeAvailable is set to true.

For information about the different attributes available for the portlet tag, see Section 63.6, "Setting Attribute Values for the Portlet Tag."

57.3 Portlet Resources

The portlets in your applications can come from a variety of sources, including other Oracle products and third-party vendors. Portlet resources also include custom built Java portlets built using WebCenter Portal's Java portlet wizard for JSR 286. Each of these resources offers different product features and are targeted toward users with different levels of experience.

This section includes the following topics:

57.3.1 Prebuilt Portlets

What Are They?

Oracle provides integration with other Oracle applications by enabling you to expose functionality as portlets:

Other prebuilt portlets are available through Oracle's partnerships with leading system integrators, software vendors, and content providers.

Who Is the Intended User?

Fully developed, downloadable portlets are best suited for use by application developers who understand how to download, install, and register producers in WebCenter Portal. They are available for use by all levels of experience.

When Should They Be Used?

Use prebuilt portlets when your needs are met by the functions the portlets offer and the level of personalization readily available is sufficient to complete the desired task.

Consider alternatives when you want to extend or personalize the portlet, for example, when you need a different user interface or when the functionality you require is not available out of the box.

57.3.2 Java Server Faces (JSF) Portlets

What Are They?

JSF portlets are created from JSF applications using the Oracle JSF Portlet Bridge. The Oracle JSF Portlet Bridge enables application developers to expose their existing JSF applications and task flows as JSR 286 Java portlets. The Oracle JSF Portlet Bridge simplifies the integration of JSF applications with WSRP portlet consumers, such as WebCenter Portal.

JSF portlets do not require separate source code from that of the JSF application. Since these portlets are created using the Oracle JSF Portlet Bridge, you need only maintain one source for both your application and your portlets. Similarly, when you deploy your portletized JSF application, the JSF portlets are also deployed with it. Therefore, using the Oracle JSF Portlet Bridge eliminates the requirement to store, maintain, and deploy your portlets separately from your application.

For more information about creating JSF portlets, see Chapter 58, "Creating Portlets from JSF Applications Using the Oracle JSF Portlet Bridge."

Who Is the Intended User?

Application developers with knowledge of Faces.

When Should They Be Used?

JSF portlets are best suited when application developers intend to display content from a JSF application, or from individual task flows within the application, as a portlet without hosting the entire application, or without separately building a portlet for the same. When portletized, the consumption of the portlet is the same as registering any WSRP producer.

57.3.3 Custom Java Portlets

Custom Java portlets are portlets that you write yourself, in Java, using the Java Portlet Specification 2.0 (JSR 286). WebCenter Portal provides a declarative wizard in JDeveloper for simplifying the creation of standards-based JSR 286 Java portlets. This wizard assists in the construction of the framework within which you create the portlet.

Note:

You can consume legacy JSR 168 and WSRP 1.0 portlets in your applications, for example from Oracle WebLogic Portal. There is no need to convert these portlets to JSR 286 first. However, when creating new Java portlets we recommend using JSR 286 to take advantage of features such as public render parameters and portlet events.

Who Is the Intended User?

Use of the wizard is easy, but creation of the portlet logic is best performed by experienced and knowledgeable Java developers who are comfortable with JSR 286 and who understand the configuration of producers.

When Should They Be Used?

Consider using custom Java portlets when you cannot find a prebuilt portlet or existing JSF application to address your requirements.

Use custom Java portlets when you have very specialized business rules or logic, or when you require personalized authentication, granular processing of dynamic results, or complete user interface control.

For more information about creating custom Java portlets, see Chapter 59, "Building Standards-Based Java Portlets Using JSR 286."

57.3.4 OmniPortlet

OmniPortlet is a declarative portlet-building tool that enables you to build portlets against a variety of data sources, including XML files, character-separated value files (CSV, for example, spreadsheets), web services, databases, and web pages. OmniPortlet users can also choose a prebuilt layout for the data. Prebuilt layouts include tabular, news, bullet, form, chart, or HTML. HTML layout enables OmniPortlet users to write their own HTML and inject the data into the HTML.

Who Is the Intended User?

Business users with a minimum knowledge of the URLs to their targeted data and limited programming skills may find OmniPortlet a valuable tool.

When Should It Be Used?

Use OmniPortlet when you want to build portlets rapidly against a variety of data sources with a variety of layouts. Consider alternatives when you want complete control of the design and functionality of the portlet.

For more information about OmniPortlet, see Chapter 64, "Creating Portlets with OmniPortlet."

As an alternative to OmniPortlet, if you want to expose data from a SQL database or web service, you should consider using Data Presenter. For more information, see the "Working with Data Presenter" chapter in Oracle Fusion Middleware Building Portals with Oracle WebCenter Portal.

57.3.5 Web Clipping Portlet

Note:

The Web Clipping portlet is deprecated in Release 11g (11.1.1.7.0). Consider using a clipper pagelet using Oracle WebCenter Portal's Pagelet Producer. For more information, see the "Managing the Pagelet Producer" chapter in Oracle Fusion Middleware Administering Oracle WebCenter Portal.

What Is It?

The Web Clipping portlet is a browser-based declarative tool that enables the integration of any web application with a Framework application. The Web Clipping portlet is designed to provide quick integration by leveraging the web application's existing user interface. The Web Clipping portlet has been implemented as an Oracle PDK-Java portlet.

To create a Web Clipping portlet, the Framework application developer uses a web browser to navigate to a web page that contains desired content. Through the Web Clipping Studio, the application developer can drill down through a visual rendering of the target page to choose the desired content.

Who Is the Intended User?

The Web Clipping portlet is best suited for use by application developers and component developers who want to leverage an existing web page for rapid portlet development. This portlet can be added to a page by any user with the appropriate privileges.

When Should It Be Used?

Use Web Clipping when you want to repurpose live content and functionality from an existing web page and expose it in your Framework application as a portlet. Consider alternatives to change the way information is presented in the clipped portlet. That is, you do not want to control the User Interface (UI) or application flow, and you are accessing web-based applications. For a greater level of control, use OmniPortlet's Web Page data source instead of the Web Clipping portlet. (For more information, see Section 57.3.4, "OmniPortlet.")

For more information about using the Web Clipping portlet, see Chapter 65, "Creating Content-Based Portlets with Web Clipping."

57.3.6 Portlet Technologies

When creating new portlets, there are several different technologies you can use. The technology you use depends on several factors.

Figure 57-3 provides a decision tree to enable you to determine which portlet implementation technology best fits your environment and requirements. The list below Figure 57-3 presents the same information in a non-graphical format and provides additional notes.

Figure 57-3 Decision Tree for Portlet Technologies

Description of Figure 57-3 follows
Description of "Figure 57-3 Decision Tree for Portlet Technologies"

  1. Do you need your components to be distributed?

    • Yes—Go to Question 2.

    • No—You don't need portlets. Use Oracle ADF task flows (or some other technology) that are local to your consuming application. For more information, see the "Creating ADF Task Flows" part in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

    Having a distributed environment results in a more complicated deployment and potentially makes it more difficult to track down issues. However, it also means that you can spread the processing load across multiple servers and enables your components to be used by several different consumers.

  2. Do you need to expose .NET components to the consuming application?

    The Oracle WebCenter WSRP Producer for .NET allows any .NET application to act as a WSRP producer.

  3. Do you have existing Oracle ADF or JSF pages or task flows that you want to expose remotely?

    Using existing Oracle ADF components in this way provides a very convenient way of developing portlets, but be aware of the implications of using Oracle ADF to implement portlets, as outlined in Table 57-1.

  4. Do you have existing JSR 168 or JSR 286 portlets?

    WebCenter Portal exposes JSR 168 and JSR 286 portlets over WSRP, which are fully compatible with the WebCenter consumer, assuming such portlets do not make assumptions that are specific to a particular consumer.

  5. Do you have existing Oracle PDK-Java portlets that will work correctly with the WebCenter Portal consumer?

  6. Do you have a requirement for your components to be rendered directly in the consumer page (that is, not in an inline frame)?

    See Section 63.5.4, "What You May Need to Know About Inline Frames" for considerations relating to the use of inline frames to render portlets.

  7. Do you want to use Oracle ADF to implement your component?

    The decision of whether to use Oracle ADF for implementing portlets is broadly the same as whether you would choose to use it for implementing a normal web application. However, the additional network hop (for markup, resource, and PPR) and consumer processing that is inherent when using remote portlets may make Oracle ADF a less attractive option than it is in the non-portlet case.

    Also, see the Oracle ADF Overview white paper on OTN for specific benefits of using Oracle ADF to develop Java EE applications. Another benefit of using an Oracle ADF task flow is that you can later run the same task flow locally if you encounter any issues running in an inline frame.

Table 57-1 outlines the implications of choosing a particular portlet technology for implementing components for use with WebCenter Portal against various criteria.

Table 57-1 Portlet Building Technologies Comparison Matrix

Local Oracle ADF Pages and Task Flows WebCenter WSRP Producer for .NET JSR 286 Portlets JSF Portlets

Distributed Architecture

No.

Yes, using WSRP SOAP/HTTP.

Yes, using WSRP SOAP/HTTP.

Yes, using WSRP SOAP/HTTP.

Data Access Support

Full support for working with databases, web services, and legacy systems.

No restrictions. This leverages the underlying .NET framework, which provides data access to a wide variety of data repositories.

No restrictions, but must be implemented by the portlet developer, possibly using a third party framework.

Full support for working with databases, web services, and legacy systems.

Navigation/Control Flow Support

Provides comprehensive support for declarative navigation.

Provides comprehensive support for declarative navigation.

No restrictions, but must be implemented by the portlet developer, possibly using a third party framework.

Provides comprehensive support for declarative navigation.

Richness of UI

Provides a rich, web-based UI with many AJAX-enabled components.

No restrictions. Supports both standard AJAX and ASP.NET AJAX toolkit.

No restrictions, but must be implemented by the portlet developer, possibly using a third party framework.

Provides a rich, web-based UI with many AJAX-enabled components.

Security

Fully integrated with the application

User identity propagated using WS-Security or asserted by consumer using WSRP.

Authorization checks must be implemented by the developer.

User profile information can be passed using WSRP user profile items.

User identity propagated using WS-Security or asserted by consumer using WSRP.

Authorization checks must be implemented by the developer.

User profile information can be passed using WSRP user profile items.

User identity propagated using WS-Security.

Authorization is implemented by Oracle ADF.

Inter-Component Communication (Events)

ADF contextual events enable task flows to communicate.

We provide samples to show how it can be accomplished client-side. Current version does not support WSRP server-side eventing model.

Full support for JSR 286 events, including automatic event delivery between portlets and event mapping between portlet events and ADF contextual events in the consumer.

As per JSR 286 portlets in addition to ADF contextual events allowing task flows to communicate as in the local case.

Consumer to Component Interaction (Parameters)

Task flow input parameters can take values from various sources.

Full support for WSRP portlet parameters. All parameters can be passed from the consumer application.

Full support for JSR 286 parameters, including passing public parameter values to and from the consumer and automatic sharing of parameter values between portlets.

As per JSR 286 portlets in addition to task flow input parameters taking values from various sources in the consumer application as in the local case.

Performance and Caching

No additional network hop since the component runs on the local server.

Remote component requires additional network hop.

Configuration parameters allow for resources (CSS, JavaScript, and .axd resource files) to be proxied via the consumer or direct access to reduce load and take advantage of browser caching.

Remote component requires additional network hop.

Resources should be proxied by the consumer.

Component performance depends on implementation.

Expires and validation based caching are supported and controlled by the portlet developer.

Remote component requires additional network hop.

Many resources are proxied via the consumer.

Heavyweight nature of framework means simple applications are likely to suffer performance-wise versus handcrafted JSR 286 equivalents. However, for applications offering more complex functionality, the performance benefits of using the framework (for example, partial page rendering) become more apparent.

JavaScript, CSS, and other resources are cached in the browser. Caching is controlled by the framework.

Concurrency

Multiple task flows are invoked sequentially.

Portlets are invoked in parallel.

Portlets are invoked in parallel.

Portlets are invoked in parallel.

Geometry Management

Components are rendered directly in the containing page.

Portlets are automatically rendered in a proxied inline frame and resized accordingly. The slider bars are hidden from view.

Portlet geometry and inline versus framed rendering is controlled by the portlet developer.

Complex UIs are more likely to require rendering in an inline frame.

Portlets must be rendered in an inline frame.

Use of JavaScript

JavaScript used heavily as a fundamental part of the framework to provide a rich user experience.

Developer does not generally need to write JavaScript.

JavaScript used heavily as a fundamental part of the framework to provide a rich user experience.

Developer does not generally need to write JavaScript, but samples are provided to show how JavaScript can be used.

All scripts can be proxied via the consumer.

Level of JavaScript use and packaging are controlled by the portlet developer.

Developers must be aware of special considerations regarding the use of JavaScript if portlets are to be rendered inline.

JavaScript used heavily as a fundamental part of the framework to provide a rich user experience.

Developer does not generally need to write JavaScript.

All scripts must be proxied via the consumer.

Skills Requirements/Ease of Development

Requires knowledge of ADF and possibly Java.

ADF provides an integrated framework across all layers.

JDeveloper provides a fully integrated environment for developing ADF applications. This includes declarative options for all layers of the framework.

Requires knowledge of .NET web parts development or ASP.NET web application development.

Requires knowledge of Java, Java portlets, and any other frameworks used to implement components.

Development time comparable with that required to develop a servlet-based component.

Requires knowledge of ADF and possibly Java. Development time is likely to be reduced (versus handcrafted portlets) for all but the most simple of applications due to the rich UI and control framework provided by ADF.

ADF provides an integrated framework across all layers.

JDeveloper provides a fully integrated environment for developing ADF applications. This includes declarative options for all layers of the framework.

Debugging

JDeveloper provides a comprehensive solution for debugging application code.

.NET framework provides a comprehensive solution for debugging application code and network trace for SOAP and HTTP traffic.

Log4net plug-in for WSRP consumer-producer debug messages.

Made more difficult by remote nature of deployment.

Producer provides tool for monitoring consumer-producer communication.

JDeveloper provides a comprehensive solution for debugging application code.

Made more difficult by remote nature of deployment.

Producer provides tool for monitoring consumer-producer communication.

JDeveloper provides a comprehensive solution for debugging application code.

Deployment

Components are deployed as part of the client application.

Entire application can be packaged into a single EAR file and deployed.

Deployment requires copying .NET applications under a particular folder hierarchy and filling out a configuration XML file.

Components can easily be run standalone under this folder hierarchy if required.

Made more complex by distributed nature of deployment and multiple applications.

Made more complex by distributed nature of deployment and multiple applications.

Components can easily be run standalone if required.

Level of Support

The ADF framework is an Oracle product and is supported as such.

The WebCenter WSRP Producer for .NET is an Oracle product and is supported as such.

The JSR 286 producer is an Oracle product and is supported as such.

The ADF framework, Oracle JSF Portlet Bridge, and JSR 286 producer are Oracle products and are supported as such.


57.3.7 When To Use Portlets Versus Task Flows?

Portlets are reusable Web components that can draw content from many different sources. Portlets can manage and display anything from static HTML to Java controls to complex web services and process-heavy applications.

A single portlet can also have multiple instances—in other words, it can appear on a variety of different pages within a single portal, or even across multiple portals if the portlet is enabled for Web Services for Remote Portlets (WSRP). You can customize portlets to meet the needs of specific users or groups.

Task flows let you build customizable applications with reusable units of business logic. They represent a modular approach for defining control flow in an application. Each task flow represents a reusable piece of business logic. With isolated memory and transaction scopes, task flows are decoupled from the surrounding application. This decoupling allows task flows to be included in Oracle WebCenter Portal's Composer, for instance.

A task flow encapsulates control flow rules, activities, and managed beans to implement business modules. Task flows are easily reusable within portals built with WebCenter Portal. You can drag and drop task flows onto any customizable WebCenter Portal portal page. In this sense, you can think of a task flow as a "local portlet" that can be reused and dropped into any ADF application.

While task flows are high-level implementations of business processes, they do not host data-access or business logic. Task flows must interact with data controls and declarative bindings for these purposes. These data controls and bindings in turn interact with the ADF Business Components framework.

Following the Oracle-submitted standard JSR 329, you can expose your task flows as standards based portlets. When you revise your application, the portlets are naturally and automatically updated right along with it, rather than requiring a separate development project. To support JSR 329, the Oracle WebCenter Portal Framework provides the Oracle JSF Portlet Bridge. For more information about the Oracle JSF Portlet Bridge, see Chapter 58, "Creating Portlets from JSF Applications Using the Oracle JSF Portlet Bridge."

In addition to consuming task flows as portlets, you can consume task flows as shared libraries in a JSF application to enable you to embed these JSF fragments directly. You can wrap the transactions around the task flows along with the other functionality in their application. For more information, see the "Getting Started with ADF Task Flows" chapter in the Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

For more information about when to use portlets versus task flows, see the "Oracle WebCenter & ADF Architecture Team" blog.

57.4 Portlet Development

This section includes the following topics:

57.4.1 Portlet Producer Applications

A portlet producer application is an application specifically configured for building and deploying Java portlets.

To readily find and use the appropriate components in your portlet producer application, you must ensure that the appropriate technology scopes are set, tag libraries added, and required Java classes are added to the class path. Once you do this, relevant components are included in the Component Palette and relevant context menus become available in JDeveloper.

JDeveloper provides an application template to ensure that scopes are set properly and the right tag and Java libraries are added to create portlet producer applications. The WebCenter Portlet Producer Application template provides a way of easily creating an application with a single project scoped for the creation of Java portlets.

To create an application using the WebCenter Portlet Producer Application template:

  1. Access the Create WebCenter Portlet Producer Application wizard in any of the following ways:

    • From the File menu, choose New. In the New Gallery dialog, expand General, select Applications then WebCenter Portlet Producer Application, and then click OK.

    • From the Application menu, choose New. In the Create Generic Application wizard, in the Application Template list select WebCenter Portlet Producer Application.

    • If you have an existing application open, in the Application Navigator, click the application name and choose New Application. In the Create Generic Application wizard, in the Application Template list select WebCenter Portlet Producer Application.

    • If you have an existing application open, then in the Application Navigator, right-click the application name and choose New. In the New Gallery dialog, expand General, select Applications then WebCenter Portlet Producer Application, and then click OK.

  2. In the Name your application page of the creation wizard, in the Application Name field, enter a name for the application.

  3. In the Directory field, accept the default path or enter a path to the directory where the application should be stored.

    For example:

    C:\JDeveloper\mywork\myApplication
    

    Optionally, click the Browse button to navigate to the desired directory.

  4. If required, in the Application Package Prefix field, enter a prefix to use for packages to be created within the application.

  5. Click Finish to create the portlet producer application with default project configurations.

Figure 57-4 shows a newly created portlet producer application, with its single Portlets project, in the Application Navigator.

Figure 57-4 New Portlet Producer Application in the Application Navigator

Description of Figure 57-4 follows
Description of "Figure 57-4 New Portlet Producer Application in the Application Navigator"

Options exposed in the JDeveloper user interface are limited to those appropriate for developing portlets.

When you right-click the Portlets project and choose New, options to create Java portlets are provided in the New Gallery (Figure 57-5).

Figure 57-5 Portlet Creation Options in the New Gallery

Description of Figure 57-5 follows
Description of "Figure 57-5 Portlet Creation Options in the New Gallery"

For information about how to create portlets within this application, see Chapter 59, "Building Standards-Based Java Portlets Using JSR 286."

57.4.2 Portlet Modes

Portlet modes exhibit the runtime functionality seen by users. WebCenter Portal supports the following standard portlet modes:

  • View mode

  • Edit mode

  • Edit Defaults mode

  • Help mode

  • About mode

WebCenter Portal defines an extended set of modes that it supports. Different modes are available to JSR 286 portlets. For example, the Create JSR 286 Java Portlet Wizard includes Print mode, which you can use to provide a printer-friendly version of the portlet.

If you are coding portlets to JSR 286, then you can also declare your own custom portlet modes in the portlet.xml file. You can use these to accommodate any other functionality you may want the portlet to provide.

Defining custom portlet modes is especially useful if the portlet must interoperate with portal implementations from other vendors. You can offer any of these modes to users. In fact, it is recommended that some modes like Edit Defaults are offered.

Note:

Third party portal products may have their own set of extended modes (JSR 286 custom modes) that producers can offer. In Portal Framework applications, the chrome UI for portlets shows only the custom modes that are defined in WebCenter Portal. Arbitrary custom modes that a third party or custom portlet producer offers are ignored and therefore are not supported.

This section includes the following topics:

57.4.2.1 View Mode

A portlet uses View mode to appear on a page with other portlets. This is the mode most people think about when they envision a portlet. A JSR 286 portlet must have a View mode, other modes are optional.

When developing portlets, you must consider all of the factors that may influence the portlet's appearance on the page, such as the portlet's containing object and the other portlets with which your portlet shares the page. For example, suppose you choose to place your portlet inside an HTML table cell. The portlet should display only content that can be rendered within a table cell. Furthermore, the actual size of the table cell may vary depending on end user settings, the browser width, and the amount and style of content in the portlet.

57.4.2.1.1 HTML Guidelines for Rendering Portlets

Plain HTML is the most basic way to render portlets and provides a great deal of flexibility to portlet developers. You can use almost any standard HTML paradigm, such as links, forms, images, and tables, if it can display within an HTML table cell. Improperly written HTML may appear inconsistently across different browsers and, in the worst case, could cause parts of your page to not appear at all. Ensure that you adhere to the following rules:

  • Use standard HTML—The official HTML specification is available from the W3C. For more information, see http://www.w3c.org/.

  • Avoid lengthy, complex HTML—The HTML you use affects the perceived performance of your site. Users judge performance based on how long it takes for them to see the page they requested, and browsers require time to interpret and display HTML. If portlets must render complex HTML or wait for external resources, such as third party applications, then it can greatly slow down the rendering of the page.

  • Avoid unterminated and extraneous tags—The behavior of pages with improperly terminated tags is unpredictable because it depends on what the browser chooses to do.

  • Consider restrictions imposed by container objects—If your portlet is contained inside an HTML element, such as a table cell, then you must ensure that your portlet can be rendered within that container. For example, if you place a portlet in a table cell, then you cannot use frames in the portlet because they do not appear when inserted in a table.

  • Keep portlet content concise—Do not try to take full screen content and expose it through a small portlet. You may end up with portlet content too small or cramped for smaller monitors.

  • Do not create fixed-width HTML tables in portlet—You have no way to tell how wide a column your portlet has on a user's page. If your portlet requires more room than given, then it might overlap with another portlet in some browsers.

  • Avoid long, unbroken lines of text—The result is similar to what happens with fixed-width tables. Your portlet might overlap other portlets in some browsers.

  • Check behavior when resizing the page—Test your portlet's behavior when the browser window is resized to ensure that it works in different browser window sizes.

  • Check behavior when the default browser font changes—End users may choose whatever font size they want and they can change it at any time. Your portlet should handle these situations gracefully.

57.4.2.1.2 CSS Guidelines for Rendering Portlets

The fonts and colors of every portlet on a page should match the style settings chosen by the user. To accomplish this goal, these style selections are embedded automatically using Cascading Style Sheets (CSS). The portlets access these settings for their fonts and colors, either directly or using the Application Programming Interface (API).

While different browsers have implemented varying levels of the full CSS specification, WebCenter Portal uses a very basic subset of this specification to allow for consistent fonts and colors. CSS implementation levels should not affect the consistency of your pages across browsers. Consider the following guidelines for using CSS:

  • Use CSS instead of hard coding—Hard coding fonts and colors is not advised. If you hard code fonts and colors, then your portlet may look out of place if the end user changes the page style settings. Since you have no way of knowing the end user's font and color preferences, you might also choose to hard code a font color that turns out to be the same as the user's chosen background color, in which case your portlet's content will not be visible to that user.

  • Avoid using CSS for absolute positioning—Since users may be able to personalize pages, you cannot guarantee that your portlet can appear in a particular spot on the page.

  • Follow accessibility standards—You should ensure that you code your style sheets according to existing accessibility standards. For more information, see http://www.w3c.org/TR/WCAG10-CSS-TECHS.

57.4.2.2 Edit Mode

A portlet uses Edit mode to enable users to personalize the behavior of the portlet. Personalizations are visible only to the user who performs them, not to other users. Edit mode provides a list of settings that the user can change. These settings may include the title, type of content, formatting, amount of information, defaults for form elements, and anything else that affects the appearance or content of the portlet.

Users typically access a portlet's Edit mode by clicking the Personalize icon in the portlet header (Figure 57-6).

Figure 57-6 The Personalize Icon for Accessing a Portlet's Edit Mode

Description of Figure 57-6 follows
Description of "Figure 57-6 The Personalize Icon for Accessing a Portlet's Edit Mode"

When users click Personalize, a new page appears in the same browser window. The portlet typically creates a web page representing a dialog to choose the portlet's settings. After applying the settings, users automatically return to the original page.

57.4.2.2.1 Guidelines for Edit Mode Operations

The following guidelines should govern what you expose to users in Edit mode:

  • Enable users to personalize the title of the portlet—The same portlet may be added to the same page several times. Enabling the end user to personalize the title helps alleviate confusion.

  • If using caching, invalidate the content—If personalizations cause a change in portlet display or content, then you must ensure that the portlet content is regenerated from the cache. If you do not do this, the user may see incorrect content.

  • Do not use Edit mode as an administrative tool—Edit mode is meant to give end users a way of changing the behavior of portlets. If you want to change producer settings or perform other administrative tasks, then you should create secured portlets specifically for these tasks.

57.4.2.2.2 Guidelines for Buttons in Edit Mode

For consistency and user convenience, Edit mode should implement the following buttons in the order listed:

  • OK—Saves the end user's personalizations and returns the portlet to View mode.

  • Apply—Saves the end user's personalizations and reloads the current page.

  • Cancel—Returns the portlet to View mode without saving changes.

57.4.2.3 Edit Defaults Mode

A portlet uses Edit Defaults mode to enable application administrators to customize the default behavior of a particular portlet instance at runtime. Edit Defaults mode provides a list of settings that the application administrator can change. These settings may include the title, type of content, formatting, amount of information, defaults for form elements, or anything that affects the appearance or content of the portlet.

Whereas personalizations affect a portlet instance for an individual user, customizations made in Edit Defaults mode affect the portlet instance for all users. Because Edit Defaults mode defines the system-level defaults for what a portlet displays and how it displays it, this mode should not be used as an administrative tool or for managing other portlets.

Application administrators access Edit Defaults mode, when editing a page, by clicking the Customize icon in the portlet header (Figure 57-7).

Figure 57-7 The Customize Icon for Accessing a Portlet's Edit Defaults Mode

Description of Figure 57-7 follows
Description of "Figure 57-7 The Customize Icon for Accessing a Portlet's Edit Defaults Mode"

When users click Customize, a new page appears in the same browser window. The portlet typically creates a web page representing a dialog to customize the portlet instance settings. After applying the settings, users are automatically returned to the original page.

57.4.2.3.1 Guidelines for Edit Defaults Mode Operation

The following guideline should govern what you expose to application administrators in Edit Defaults mode:

  • Do not use Edit Defaults mode as an administrative tool—Edit Defaults mode gives application administrators a way of changing the behavior of their portlets. If you want to change producer settings or do other administrative tasks, then you should create secured portlets specifically for those tasks.

57.4.2.3.2 Guidelines for Buttons in Edit Defaults Mode

For consistency and user convenience, Edit Defaults mode should implement the following buttons in the order listed:

  • OK—Saves the application administrator's customizations and returns the portlet to View mode.

  • Apply—Saves the application administrator's customizations and reloads the current page.

  • Cancel—Returns the portlet to View mode without saving changes.

57.4.2.3.3 Guidelines for Rendering Customization Values

When you show the forms used to change customization settings, you should default the values so that the application administrator does not have to constantly reenter settings. When rendering customization values, use the following sequence to provide consistent behavior:

  • Instance preferences—Query and display system defaults for the portlet instance.

  • Portlet defaults—If no system default customizations are found, then display general portlet defaults, which may be blank. General portlet defaults are sometimes hard coded into the portlet but should be overwritten by system defaults.

57.4.2.4 Help Mode

A portlet uses Help mode to display information about the functionality of the portlet and how to use it. The user should be able to find useful information about the portlet, its contents, and its capabilities with this mode.

Users access a portlet's Help mode by choosing the Help option in the Actions menu (Figure 57-8).

Figure 57-8 The Help Option in the Portlet Actions Menu

Description of Figure 57-8 follows
Description of "Figure 57-8 The Help Option in the Portlet Actions Menu"

57.4.2.4.1 Guidelines for Help Mode

The following guideline should govern what you expose in Help mode:

  • Describe how to use the portlet—Users may not be able to ascertain all the features your portlet offers just from its interface. Describe the features and how to get the most out of them.

57.4.2.5 About Mode

A portlet uses About mode to provide users with information such as the version of the portlet that is currently running, its publication and copyright information, and how to contact the portlet developer. Portlets that require registration could also use About mode to link to a web-based registration application or contact information.

Users access a portlet's About mode by choosing the About option in the Actions menu (Figure 57-9).

Figure 57-9 The About Option in the Portlet Actions Menu

Description of Figure 57-9 follows
Description of "Figure 57-9 The About Option in the Portlet Actions Menu"

A new page appears in the same browser window. The portlet can either generate the content for this page or take the user to an existing page or application.

57.4.2.5.1 Guidelines for About Mode

The following guideline should govern what you expose to users in About mode:

  • Display relevant copyright, version, and developer information—Users want to know what portlet they are using and where they can get more information. The About page may become important when supporting your portlets.

57.4.3 Interportlet Communication

Interportlet communication enables portlets to share data and react to events. WebCenter Portal supports interportlet communication through parameters and events:

  • Parameters—Public render parameters enable interportlet communication by sharing parameter values between portlets. For example, if a Map portlet and a Weather portlet are both configured to use a Zipcode parameter, entering a zip code in the Map portlet updates the same parameter value in the Weather portlet.

    For information about public render parameters, see Section 59.3.5, "How to Use Public Render Parameters in JSR 286 Portlets."

  • Events—Events enable interportlet communication by providing portlets with the ability to respond to actions that occur outside of the portlet itself, for example, an action performed on the page that contains the portlet or on another portlet on the same page. Portlet events can be cascaded so that a portlet may respond to an event by triggering an event of its own, which in turn affects other portlets on the page.

    For information about portlet events, see Section 59.3.6, "How to Use Portlet Events in JSR 286 Portlets."

In WebCenter Portal, interportlet communication happens automatically by default, as long as parameters and events share the same name or define an appropriate alias. You do not need to supply any extra code to enable this communication. For more information, see Section 63.5.3, "What You May Need to Know About Interportlet Communication."

For interportlet communication guidelines specific to portlets created using the Oracle JSF Portlet Bridge, see Section 58.7, "Using Events to Link JSF Portlets with Other Portlets."

57.4.4 Portlet Personalization and Customization

Portlet preferences enable end users to personalize or customize portlets at runtime. Personalizations are visible only to the user that performs them; not to other users. Customizations are visible to all users who have not personalized the portlet.

Portlet preferences greatly enhance the reusability of portlets. The same portlet can be instantiated on multiple pages, or multiple times on the same page. Using portlet preferences, each instance of the portlet can behave in a different way, but still use the same code and user interface.

For example, by default when you create a JSR 286 portlet using the JDeveloper wizard, a portlet preference is created to enable users to change the title of the portlet at runtime. You can create additional portlet preferences, either during portlet creation or by editing the portlet.xml file after portlet creation, to enable users to perform other modifications on the portlet at runtime.

Portlet preferences are stored in the persistence store, along with information about the registration and portlet instances, such as registration and portlet handles. Portlet producers can use one of three types of persistence store:

  • Consumer—A consumer persistence store ties the producer metadata to the consumer application. It is recommended that you should use a consumer persistence store in your production environment.

  • Database—A database persistence store persists data using a relational database.

  • File—A file-based persistence store persists data using the file system.

A file-based or consumer persistence store may be used for testing, since it removes the dependency on a database. But, for production configurations, it is recommended that you use a consumer persistence store.

By default, JSR 286 and JSF portlets use a consumer persistence store. For information about how to change this default setting, see Section 59.3.13.1, "Setting Up a Persistence Store for a WSRP Producer."

For information about migrating the persistence store, for example, when moving from a test to production environment, see Section 59.3.13.2, "Migrating a WSRP Producer Persistence Store."

57.4.5 Portlet Performance

Caching is a common technique for enhancing the performance of web sites that include a great deal of dynamic content. The overhead involved in retrieving data and generating the output for dynamic content can be significantly reduced by proxying requests through a local agent backed by a large, low-latency data store, known as a cache. The cache agent responds to a request in one of two ways:

  • If a valid version of the requested content exists in the cache, then the agent simply returns the existing cache copy, thus skipping the costly process of content retrieval and generation. This condition is known as a cache hit.

  • If a valid version of the requested content does not exist in the cache, then the agent forwards the request to its destination and awaits the return of the content. The agent returns the content to the requester and stores a local copy in its cache for reuse if a subsequent request for the same content arises. This condition is known as a cache miss.

Portlet producers generate dynamic content (that is, portlets) and they reside remotely from the Portal Framework application instance on which they are deployed. As such, caching might improve their performance. The architecture lends itself well to caching. You can cache the portlets rendered by your producer and reuse the cached copies to handle subsequent requests, minimizing the overhead your producer imposes on page assembly. Portlet caching is key to rapid response to user requests.

For JSR 286 portlets there are two different caching methods. The methods differ mainly in how they determine whether content is still valid:

  • Expiry-based caching—When a producer receives a render request, it stamps its response with an expiry time. The rendered response remains in the cache and fills all subsequent requests for the same content until its expiry time passes. This caching scheme is perhaps the simplest and most performant because the test for cache validity requires very little overhead and does not involve any network round trips. Expiry-based caching suits applications where the content has a well-defined life span. For content with a less certain life span however, expiry-based caching is less effective.

    Consider using expiry-based caching when the portlet content is static or when it is not critical that the most up-to-date content be displayed.

    For information about how to implement expiry-based caching for your portlets, see Section 59.3.9.1, "Implementing Expiry-Based Caching in JSR 286 Portlets."

  • Validation-based caching—When a producer receives a render request, it stamps a response with a version identifier (or ETag). The response goes into the cache, but before the consumer can reuse the cached content, it must determine whether the cached content is still valid. It sends the producer a render request that includes the version identifier of the cached content. The producer determines whether the version identifier remains valid. If the version identifier is still valid, then the producer immediately sends a lightweight response to the consumer without any content that indicates that the cached version can be used. Otherwise, the producer generates new content with a new version identifier, which replaces the previously cached version. In this form of caching, the consumer must always confirm with the producer whether the content is up to date. The validity of the cached copy is determined by some logic in the producer. The advantage of this approach is that the producer controls the use of cached content, rather than relying on a fixed period.

    Consider using validation-based caching for portlets with dynamic content that changes frequently or unpredictably.

    For information about how to implement validation-based caching for your portlets, see Section 59.3.9.2, "Implementing Validation-Based Caching in JSR 286 Portlets."

Caching rules can be specified at a portlet's container level, encoded in the portlet's own logic, or established through the portlet wizard. Provided it is specified, container-level caching takes over when caching is not part of the portlet code.

At the application level, WebCenter Portal Framework supports use of a Java cache for the establishment of application-level caching rules.

When you enable caching at the application level, you instruct the Java cache to maintain a copy of the portlet content. When data that was previously cached is requested, no time is lost in contacting the data source and regenerating its content. Instead, the previously cached portlet content is returned.

JSF portlets and custom Java portlets support expiry- and validation-based caching.

57.4.6 Multilanguage Portlets

There are three steps involved in making your portlets available in multiple languages:

  • Declare the locales supported by the portlet using the <supported-locale> element in the portlet.xml file. For example:

    <portlet id="1328624289503">
       ...
       <supported-locale>en</supported-locale>
       <supported-locale>fr</supported-locale>
       <supported-locale>es</supported-locale>
       ...
    </portlet>
    
  • Make the portlet metadata that is displayed in the portlet (for example, the portlet title, description, keywords, and so on) translatable.

    You can include the translations directly in the portlet.xml file, for example:

    <portlet id="1328624289503">
       <portlet-name>LotteryPortlet</portlet-name>
       <display-name xml:lang="en">Lottery Numbers</display-name>
       <display-name xml:lang="fr">Numéros de Loterie</display-name>
       <display-name xml:lang="es">Números de la Lotería</display-name>
       ...
       <supported-locale>en</supported-locale>
       <supported-locale>fr</supported-locale>
       <supported-locale>es</supported-locale>
       ...
    </portlet>
    

    Alternatively, you can provide translations in a separate resource bundle. You must declare the resource bundle in the portlet.xml file, for example:

    <portlet id="1328624289503">
       <portlet-name>LotteryPortlet</portlet-name>
       <display-name>Lottery Numbers</display-name>
       ...
       <supported-locale>en</supported-locale>
       <supported-locale>fr</supported-locale>
       <supported-locale>es</supported-locale>
       <resource-bundle>portlet.resource.LotteryPortletBundle</resource-bundle>
       ...
    

    Then, provide the translations in the resource bundle, for example:

    # English Resource Bundle
    #
    # filename: LotteryPortletBundle_en.properties
    javax.portlet.display-title=Lottery Numbers
    
    # French Resource Bundle
    #
    # filename: LotteryPortletBundle_fr.properties
    javax.portlet.display-title=Numéros de Loterie
    
    # Spanish Resource Bundle
    #
    # filename: LotteryPortletBundle_es.properties
    javax.portlet-title=Números de la Lotería
    
  • Make the portlet content translatable the same way as you would for any other web application.

57.4.7 Portlet Deployment

Before a portlet can be registered with and consumed by an application, you must first deploy it. JSR 286 portlets are deployed to a WSRP producer, which is remote and communicates with the consumer application through Web Services for Remote Portlets (WSRP). JSF portlets are deployed as JSR 286 portlets, that is, to a WSRP producer, either from JDeveloper or manually.

WebCenter Portal supports WSRP versions 1.0 and 2.0. This standard provides support for interportlet communication and export or import of portlet customizations.

WSRP is a communication protocol between portlet consumer applications and portlet containers. WSRP is a standard that enables the plug-and-play of visual, user-facing web services with intermediary web applications.

Being a standard, WSRP enables interoperability between a standards-enabled container based on a particular language (such as JSR 286, .NET, or Perl) and any WSRP portal. So, a portlet (regardless of language) deployed to a WSRP-enabled container can be rendered on any application that supports this standard.

Figure 57-10 illustrates the basic architecture of WSRP producers.

Figure 57-10 WSRP Producer Architecture

Description of Figure 57-10 follows
Description of "Figure 57-10 WSRP Producer Architecture"

When end users display a page in their web browsers, the flow of the request works as follows:

  1. The end user requests a page from the web browser by entering a URL in the browser's Location field.

  2. The browser transmits the request to the consumer application over HTTP.

  3. The application contacts the portlet producers that provide the portlets that display on the requested page.

  4. The producers make the necessary calls to their portlets so that the portlets generate the portlet content in the form of HTML or XML code.

  5. The producers return the portlet content back to the consumer application using the WSRP 1.0 or 2.0 protocol:

  6. The consumer application transmits the portlet content to the browser over HTTP.

To make standards-based portlets available to a consumer application in WebCenter Portal, you must package them in a Portlet Producer application and deploy them to a WSRP container. For more information, see Chapter 61, "Deploying Portlet Producers."