Introduction to Portlets

11 Introduction to Portlets

Learn about portlets, their uses, and the resources you can use to create portlets that best suit your needs.

Topics:

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

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.

Figure 11-1 Lottery Sample Portlet

Description of "Figure 11-1 Lottery Sample Portlet"

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.

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 About Portlet Resources.

About Portlet Anatomy

Portlet anatomy is the visual representation of the portlet on a page.

Figure 11-2 shows some aspects of portlet anatomy that you might expect to see in a typical portlet in WebCenter Portal. Note that the same portlet displayed in a different application could look different.

Figure 11-2 Sample Portlet Showing Typical Portlet Anatomy

Description of "Figure 11-2 Sample Portlet Showing Typical Portlet Anatomy"

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

Portlet chrome—A collective term for the different types of decoration that surround the portlet, including the header, shadow, resize handle, Actions menu, and icons.
Portlet header—The area of the portlet that displays the portlet icon, title, Actions menu, and Customize and Personalize icons.
Portlet icon—A small image in the portlet header used to visually identify the portlet.
Portlet title—Text in the portlet header that indicates the purpose of the portlet. End users may be able to personalize this title at runtime to make it more meaningful to their particular usage.
Personalize icon—An icon in the portlet header that enables end users to make changes to the portlet that only they can see.

The Personalize icon is displayed only to authenticated users (that is, users who are logged in). It does not display to public users or unauthenticated users. You must implement some form of application security for users to be able to personalize their portlet views.
Customize icon—An icon in the portlet header that enables application administrators to make changes to the default settings of the portlet at runtime. These changes are visible to all users.

A typical customization setting is the portlet title. At runtime, the application administrator can determine what title should appear in the portlet header.
Actions icon—An icon in the portlet header that displays the Actions menu when clicked.
Actions menu—A menu that lists various actions that users can perform on the portlet. The actions listed depend on whether the user is logged in, what privileges that user has, the functionality provided by the portlet, and the options specified when the portlet was added to the page at design time. Actions include Move, Remove, Refresh, Move Up, and Move Down. The Actions menu also provides access to other portlet modes available for the portlet, such as About, Help, Configure, and Print.

If the user who added the portlet to the page chose to not display the portlet header, the Actions menu is displayed on a fade in/fade out toolbar that displays on mouse rollover.
Resize handle—An area at the bottom right of the portlet that enables users to change the size of the portlet.
Scroll bars—Display when the portlet content does not fit the width and height specified for the portlet, providing access the content that is not initially displayed.
Portlet content—The actual content of the portlet as determined by the portlet logic.

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

The portlet's own logic, as determined by the portlet developer. This includes which portlet modes are supported by the portlet.
The attributes of the portlet tag that binds the portlet to the page, as determined by the application developer who added the portlet to the page at design time.

For example, when designing the portlet, the portlet developer may implement Help mode for the portlet. When a page designer adds the portlet to the page, he or she can determine, using the portlet property isHelpModeAvailable, whether or not to include the Help command in the portlet's Actions menu. If the page designer 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.

About 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:

About Prebuilt Portlets

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

What Are They?

Supported applications include:

Peoplesoft—You can expose Peoplesoft applications as WSRP portlets. For more information, see Integrating PeopleSoft Applications in Administering Oracle WebCenter Portal.
JD Edwards—You can expose JD Edwards standalone regions as portlets. For more information, see Integrating JD Edwards Applications in Administering Oracle WebCenter Portal.
Oracle E-Business Suite—Oracle E-Business Suite provides several prebuilt portlets, such as Applications Navigator, Favorites, and Worklist, that you can add to WebCenter Portal. For more information, see Integrating E-Business Suite Applications in Administering Oracle WebCenter Portal.
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 portal 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.

About Java Server Faces (JSF) Portlets

JSF portlets are created from JSF applications using the Oracle JSF Portlet Bridge.

What Are They?

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 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 any WSRP producer.

About Custom Java Portlets

Custom Java portlets are portlets that you write yourself, in Java, using the Java Portlet Specification 2.0 (JSR 286).

What Are They?

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 portals, 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.

You can also consume legacy Oracle PDK-Java portlets in your portals.

Who Is the Intended Audience?

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 Building Standards-Based Java Portlets Using JSR 286.

About OmniPortlet

OmniPortlet is a declarative portlet-building tool that enables you to build portlets against a variety of data sources.

What Is It?

OmniPortlet data sources include XML files, character-separated value files (CSV, for example, spreadsheets), web services, and databases. 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 Working with OmniPortlet in Building Portals with Oracle WebCenter Portal

As an alternative to OmniPortlet, you should consider using data integration and presentation. For more information, see Working with Data Visualizations in Building Portals with Oracle WebCenter Portal.

If you want to include data from another web page, consider using a clipper pagelet using Oracle WebCenter Portal's Pagelet Producer's Pagelet Producer. For more information, see How to Configure the Clipper.

Portlet Technologies

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

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

Figure 11-3 Decision Tree for Portlet Technologies

Description of "Figure 11-3 Decision Tree for Portlet Technologies"

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 Creating ADF Task Flows in Developing Fusion Web Applications with 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.
Do you have existing Oracle ADF or JSF pages or task flows that you want to expose remotely?
- Yes—Use the Oracle JSF Portlet Bridge to expose your existing components. For more information, see Creating Portlets from JSF Applications Using the Oracle JSF Portlet Bridge.
- No—Go to Question 4.
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 11-1.
Do you have existing JSR 168 or JSR 286 portlets?
- Yes—Use your existing JSR 168 or JSR 286 portlets. For more information, see Registering WSRP Producers.
- No—Go to Question 5.
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.
Do you have existing Oracle PDK-Java portlets that will work correctly with the WebCenter Portal consumer?
- Yes—Use your existing PDK-Java portlets. For more information, see Registering an Oracle PDK-Java Portlet Producer
- No—Go to Question 6.
Do you have a requirement for your components to be rendered directly in the consumer page (that is, not in an inline frame)?
- Yes—Write JSR 286 portlets that do not use markup that requires them to be rendered in an inline frame. For more information, see Building Standards-Based Java Portlets Using JSR 286.
- No—Go to Question 7.
Do you want to use Oracle ADF to implement your component?
- Yes—Use the Oracle JSF Portlet Bridge to expose Oracle ADF pages or task flows as portlets. For more information, see Creating Portlets from JSF Applications Using the Oracle JSF Portlet Bridge.
- No—Write JSR 286 portlets. For more information, see Building Standards-Based Java Portlets Using JSR 286.
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 11-1 outlines the implications of choosing a particular portlet technology for implementing components for use with WebCenter Portal against various criteria.

Table 11-1 Portlet Building Technologies Comparison Matrix

Type	Local Oracle ADF Pages and Task Flows	JSR 286 Portlets	JSF Portlets
Distributed Architecture	No.	Yes, using WSRP SOAP/HTTP.	Yes, using WSRP SOAP/HTTP.
Navigation/Control Flow Support	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, 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. Authorization is implemented by Oracle ADF.
Inter-Component Communication (Events)	ADF contextual events enable task flows to communicate.	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 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. 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.
Geometry Management	Components are rendered directly in the containing page.	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.	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 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.	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.	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 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.

Portlets Versus Task Flows

A common question asked when creating portal is 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 page editor, 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, WebCenter Portal provides the Oracle JSF Portlet Bridge. For more information about the Oracle JSF Portlet Bridge, see 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 Getting Started with ADF Task Flows in the Developing Fusion Web Applications with Oracle Application Development Framework.

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

About Portlet Development

You can develop your portlet producers in Oracle JDeveloper.

This section includes the following topics:

Portlet Producer Applications

This section includes the following topics:

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

How to Create a Portlet Producer Application

To create portlets, you must first create a portlet producer application.

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

Access the New Gallery dialog in any of the following ways:
- From the File menu, choose New, then Application.
- From the Application menu, choose New.
- If you have an existing application open, in the Application Navigator, click the application name and choose New Application.
- If you have an existing application open, then in the Application Navigator, right-click the application name and choose New, then Application.
In the New Gallery dialog, select WebCenter Portlet Producer Application, and then click OK.
In the Name your application page of the Create WebCenter Portlet Producer Application wizard, in the Application Name field, enter a name for the application.
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.
If required, in the Application Package Prefix field, enter a prefix to use for packages to be created within the application.
Click Finish to create the portlet producer application with default project configurations.

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

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

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

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

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

Portlet Modes

This section includes the following topics:

About 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. Arbitrary custom modes that a third party or custom portlet producer offers are ignored and therefore are not supported.

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.

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.

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.

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 11-5).

Figure 11-5 Personalize Icon

Description of "Figure 11-5 Personalize Icon"

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.

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.

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.

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 choosing Customize from the component’s View Actions menu (Figure 11-6).

Figure 11-6 Customize Portlet

Description of "Figure 11-6 Customize Portlet"

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.

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.

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.

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.

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 Help from the Actions menu (Figure 11-7).

Figure 11-7 Help Option in the Portlet Actions Menu

Description of "Figure 11-7 Help Option in the Portlet Actions Menu"

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.

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 About from the Actions menu (Figure 11-8).

Figure 11-8 About Option in the Portlet Actions Menu

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

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.

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 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 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 interportlet communication guidelines specific to portlets created using the Oracle JSF Portlet Bridge, see Using Events to Link JSF Portlets with Other Portlets.

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 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 Migrating a WSRP Producer Persistence Store.

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 WebCenter Portal 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 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 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.

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

At the application level, WebCenter Portal uses Coherence for the establishment of application-level caching rules. The WebCenter Portal portlet client provides a default cache configuration file for portlets:

<?xml version="1.0"?>


<cache-config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
              xmlns="http://xmlns.oracle.com/coherence/coherence-cache-config"
              xsi:schemaLocation="http://xmlns.oracle.com/coherence/coherence-cache-config
coherence-cache-config.xsd">
   <defaults>
      <scope-name>portlets</scope-name>
   </defaults>
   <caching-scheme-mapping>
      <cache-mapping>
         <cache-name>portlet-consumer-content-cache-*</cache-name>
         <scheme-name>portlet-thin-direct</scheme-name>
      </cache-mapping>
   </caching-scheme-mapping>
   <caching-schemes>
      <distributed-scheme>
         <scheme-name>portlet-thin-direct</scheme-name>
         <local-storage>true</local-storage>
      </distributed-scheme>
   </caching-schemes>
</cache-config>

You can create your own cache configuration file to use for the portlet consumer cache and update the portlet client configuration information in adf-config.xml to point to your file. For more information, see Editing the Portlet Client Configuration in Administering Oracle WebCenter Portal. Base your file on the default cache configuration file to ensure that it defines a mapping for the cache name portlet-consumer-content-cache-*. For more information about Coherence, see Improving Data Caching Performance in Administering Oracle WebCenter Portal.

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.

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, 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 11-9 illustrates the basic architecture of WSRP producers.

Figure 11-9 WSRP Producer Architecture

Description of "Figure 11-9 WSRP Producer Architecture"

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

The end user requests a page from the web browser by entering a URL in the browser's Location field.
The browser transmits the request to the consumer application over HTTP.
The application contacts the portlet producers that provide the portlets that display on the requested page.

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.
The producers return the portlet content back to the consumer application using the WSRP 1.0 or 2.0 protocol:
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.