Oracle9iAS Portal Developer Kit
Migrating PL/SQL Portlets from 3.0 Beta

Between Beta and Production, the Oracle Portal 3.0 architecture was enhanced with a distributed provider framework effectively allowing multiple physical machines to act as one Portal.  Because of this and other architectural enhancements, several minor changes were made to the implementation of portlets and portlet providers, as well as their APIs.

This document details those changes, the rationale behind them, and their impact.  Many of the changes are based on tips and feedback from Beta participants.

OVERVIEW OF MODIFICATIONS

Converting Beta portlets to work in the production environment is a relatively simple task which does not require any fundamental changes to the logic of the portlet.  For example, if your portlet makes extensive use of PL/SQL calls to the database, you do not need to change any of that logic. 

You will need to modify the way your Beta portlets are rendered.  The production version of Oracle Portal 3.0 provides a new balance of flexibility and consistency by taking advantage of Cascading Style Sheets (CSS).  You will also need to modify your implementation of PL/SQL portlet providers to include new functionality including provider registration, portlet security, and portlet categorization.

Each of the modifications is prioritized based on its impact on the developer and the portlet users.

·         You must make required changes to use your portlets and providers in the production version.

·         You should make recommended changes that dramatically affect your users and overall portal usability.

·         You could make optional enhancements that provide significant, but not critical, new functionality.


MIGRATING TO PRODUCTION

Use Cascading Style Sheets (CSS)

Required.  Portlets should use the CSS APIs provided with wwui_api_portlet to get the current page style.  This allows every portlet sharing a page to use the same font and color settings automatically. 

You should use the APIs, and not hardcode calls the CSS classes directly, so that you can take advantage of future enhancements without having to revisit hardcoded references.

Remove all references to p_style. 

Required.  In the production release, portlet providers will no longer use p_style and will instead rely on portlets to use the CSS APIs for their display settings.

Draw portlet title bars

Required.  To allow more flexibility in the presentation of portlets, the production version allows portlets to draw their own title bars.  The side-effect of this flexibility is that default title bars are no longer drawn automatically and will need to be created by each portlet.

To accommodate this change, the portlet_record returned by get_portlet_info has been changed.  The following fields are obsolete with production:

      has_show_about
has_show_help
has_show_details
has_title_region
execute_as

You can use the draw_portlet_header API in the wwui_api_portlet package to draw default portlet title bars. 

Since portlet title bars can be turned off at runtime, your portlets must check the has_title_region flag in portlet_runtime_record to see whether it should display a title bar using the following algorithm:

·         If has_title_region is true, show the banner only if user customization settings permit showing the banner.

·         If has_title_region is false, do not show the banner (overriding user customization, if necessary).

In addition you should set the following fields in your portlet_record:

            has_show_edit
            has_show_edit_defaults

These fields allow the page engine to provide an alternate means of customizing portlets that have their title bars (and their customization links) turned off.

You may want to use page_url and back_page_url parameters passed to the show_portlet call to assist with navigation from the portlet.  If you wish to redraw the page in which the portlet is currently resides then use page_url.  If you wish to go to the previous page then use back_page_url.

Remove all calls to page APIs

Required.  Calls to page APIs must be removed because they will fail in the distributed provider environment.  These calls may look something like wwpob_api_page.get_instance(p_back_url);

Implement portlet categorization security

Required.  get_portlet_list now has a flag called p_security_level which sets whether security is enabled in the portlet selector.  When p_security_level is set to true, user level security for the portlet selector is enabled and the selector must only return information about portlets that user is allowed to see.  When it is set to false, the API must return all portlets in the selector, but the user will only be able to use those he has permissions for.

Provide initialization and cleanup for your portlet providers

Required.  Procedures for registering and deregistering providers have been added. These methods must exist in the provider package.

·         register_provider allows provider level initializations to be performed.  The framework will call this procedure when a provider is registered using either the Portal user interface or the APIs.

·         deregister_provider allows provider level cleanup and is called when a provider is deregistered using either the Portal user interface or the APIs.

Add p_provider_id to API calls

Required.  This new parameter allows multiple providers to be created using the same implementation name.   Effectively, this allows for the same physical piece of code to be used for separate virtual providers.

Portal Applications are great examples of this.  For production, each Portal Application will have a separate provider so that it is easier to find specific portlets.  Instead of creating new code for the new provider, it uses the same provider code with a different p_provider_id.

Implement copy_portlet procedure

Required.  This procedure provides a way for portlet user and/or system level customizations to be copied.  This method must exist in the provider package.  This procedure is called when a page is copied and is called once for each portlet on that page.  

It is the responsibility of the API to copy appropriate portlet customizations.  Typically Edit Default (system level) customizations are copied in this API.   Note that register_portlet API is called prior to this one.

Implement portlet caching

Recommended.  Portlet caching is not required because it does not affect whether the portlet will successfully work or not.  However, it should definitely be implemented to improve the performance of the portal system. 

To implement portlet caching, you need to use the parameters p_caching_level and p_caching_key. Because portlet output can be customized by individual users, portlets can be cached for each user by setting p_caching_level.  p_caching_level can also be set to SYSTEM which will cause the same cache entry to be retrieved for all users.

Each p_caching_level has a p_caching_key associated with it.  The p_caching_key is used for signaling that portlet content for this p_caching_level has changed.  This is done by changing the value of p_caching_key.

Enable secure portlet categorization

Recommended.  Production portlets are easier for end users to find because they can be categorized.  As a security precaution, it is important to implement the is_portlet_runnable method to keep unauthorized users from seeing portlets they are not allowed to use while browsing through the portlet categories.

To implement this first level of security, you should implement the following:

·         If p_reference_path is null then check if the current user can see any instance of the portlet identified by portlet_id.

·         If p_reference_path is not null then check if the current user can see the instance of this portlet identified by p_reference_path.

Enable portlet preview support

Optional.  While users browse through the various categories in the portlet selector, they can also see previews of the portlets before inserting them onto a page.  Using the following fields in your portlet_record, you can provide preview information about your portlets:

            image_url                              URL to an image of your portlet (will be used in future release)
            thumbnail_image_url          URL to a small image of your portlet (will be used in future release)
            help_url                                URL to a detailed description of this portlet (will be used in future release)
            has_show_preview                flag, when set, allows preview link to be shown in portlet selector;
                                                            enables MODE_PREVIEW

Revision history: