The Database Services example provides a detailed illustration of the services that a portlet can incorporate. The code is well commented.

This document explains:

• How the Services example is packaged and how to install it.

• The Services portlet included in the sample example.

CONTENTS

This section describes the files included in the Services example.  There are package specifications (*.pks), package bodies (*.pkb), and a bare-bones installation script.

Files

• services_portlet.pks: Contains detailed comments and headers for the Parameters Passing Portlet.

• services_portlet.pkb: Logic behind the Parameters Passing Portlet.

• services_provider.pks: Contains detailed comments and headers for the Sample Provider.

• services_provider.pkb: Logic behind the Sample Provider.

• install.sql: Main installation script that installs this sample. Prompts the user for 4 parameters - Oracle Portal schema, Oracle Portal password, Provider schema and Provider schema password.

• services_install.sql: Script that compiles the portlet and provider packages. Called internally by install.sql

• services_seed.sql: Script for seeding the NLS strings, called internally by install.sql

• services_register.sql: Registers the services provider, called internally by install.sql. This needs to be run in the Oracle Portal schema only.

Documentation

• installing.services.html:  This document.

SETUP

To give you a good understanding of what goes on behind the scenes, these instructions describe how to install the Database Services sample manually.

Installing the Packages

1. Find provsyns.sql and change to that directory (e.g. c:\portal30\webdb30\admin\plsql\wwc). Later, you will run this script to grant permission to call Oracle9iAS Portal APIs.
2. Create the schema where you will install the example:
   • Login to sqlplus (e.g. sqlplus sys/change_on_install)
   • Create a new schema (e.g. create user starter identified by starter)
   • Give it permissions (e.g. grant connect, resource to starter)
3. Grant your schema permission to call Oracle9iAS Portal APIs:
   • Login as the schema where your portal is installed (e.g. connect portal30/portal30)
   • Run provsyns.sql as the schema where your portal is installed (e.g. @provsyns.sql starter)
   • Exit sqlplus
4. Install the sample example:
   • Change to the directory where you unzipped this example
   • Login to sqlplus as your schema (e.g. sqlplus starter/starter)
   • Run install.sql (e.g. @install.sql)
   • Provide the inputs to this script when it asks for the following:
     • Portal schema username - Schema of Oracle Portal
     • Portal schema password 
     • Provider schema username - Schema where you want to install this Provider
     • Provider schema password

Registering Your Provider

The install script automatically registers your Provider. At the end of installation the Provider Registration information is printed out. Please verify that the Provider registered successfully.

1. Login to Oracle9iAS Portal as a Portal administrator.
2. Click the Administer tab.
3. Under the Administer tab, click Display Portlet Repository within the portlet called Provider.

   Note: If necessary, click Refresh , to refresh the portlet repository.

4. Scroll down to verify that the DatabaseServicesProvider is listed with the Database Services Portlet.

   You are now all set to add this portlet to your own pages.

PORTLETS

The portlet in the Database Services Provider serves as a guide for developing PL/SQL portlets that use different show modes and services provided by the framework.  They have been refined to reflect the best practices in PL/SQL portlet development.

Database Services Portlet

The Database Services Portlet is designed to illustrate how you can implement the different show modes and services.

Shared Screen Mode (MODE_SHOW)

This is the mode in which a portlet appears on a page. For guidelines on using this mode please refer to Guidelines for Shared Screen Mode.

Edit Mode (MODE_SHOW_EDIT)

This is the mode in which a portlet can be customized on your page.  You can invoke this mode by clicking the 'Customize' link on the Portlet banner.  For guidelines on using this mode please refer to Guidelines for Edit Mode. 

You can change the text and title of the portlet as you please in this particular example.

Edit Defaults Mode (MODE_SHOW_EDIT_DEFAULTS)

This is the mode in which an individual portlet can be customized for all users of that portlet. You can invoke this mode by clicking the 'Customize Page' link on the page. For guidelines on using this mode please refer to Guidelines for Edit Defaults Mode. 

Help Mode (MODE_SHOW_HELP)

This is the mode in which a portlet can provide help information on your page. You can invoke this mode by clicking the 'Help' link on the Portlet banner. For guidelines on using this mode please refer to Guidelines for Help Mode. 

About Mode (MODE_SHOW_ABOUT)

This is the mode in which a portlet can display information about the portlet's copyright, version, and author. You can invoke this mode by clicking the 'About' link on the Portlet banner. For guidelines on using this mode please refer to Guidelines for About Mode. 

Full Screen Mode (MODE_SHOW_DETAILS)

This is the mode in which a portlet can leverage a complete browser window for displaying more details that it needs to show. You can invoke this mode by clicking the link on the Portlet title. For guidelines on using this mode please refer to Guidelines for Full Screen Mode.

Preview Mode (MODE_PREVIEW)

This is the mode in which a portlet can be seen before adding it to a page.  You can invoke this mode by clicking the Portlet link while adding portlets to your page.  For guidelines on using this mode please refer to Guidelines for Preview Mode.

Apart from these seven show modes, this Services sample portlet also demonstrates the use of several different services.

Session Store

This service allows you to store temporary session related data that you find useful. In the shared screen mode shown above you can see how session storage has been used to keep track of  the number of times the portlet has been rendered.  For guidelines on using this mode please refer to Primer on Session Storage.

NLS

If you change the language settings of your browser from 'US' to 'German', you will see that the portlet title and texts displayed in the different modes acquire the '-d' tag. This is because we have seeded the NLS tables for the German language with equivalent strings of the US strings tagged with the '-d' marker, as an illustration of how Oracle9iAS Portal can have multiple language settings.

There are other services that these portlets use and we will provide detailed articles about these in the future. For more details please refer to the article A Primer on Database Portlet Services.

This sample provides well-commented code to help you with such functionality.

Revision history:

• December 26, 2000. Updated screenshots for Dec Release.

• March 14, 2000