Creating an Oracle Application Development Framework ADF Portlet

8 Creating PLSQL Portlets 8-1 8 Creating PLSQL Portlets The Oracle Portal PLSQL APIs are implemented as a set of PLSQL packages and objects. Database providers and portlets are deployed to a database schema as PLSQL packages. This chapter explains how to create PLSQL portlets based on the Oracle Portal Developer Kit-PLSQL PDK-PLSQL. To make effective use of this chapter, you should already know PLSQL and have some familiarity with the PLSQL Web Toolkit. This chapter contains the following sections: ■ Section 8.1, Guidelines for Creating PLSQL Portlets ■ Section 8.2, Building PLSQL Portlets with the PLSQL Generator ■ Section 8.3, Building PLSQL Portlets Manually ■ Section 8.4, Implementing Information Storage ■ Section 8.5, Using Parameters ■ Section 8.6, Accessing Context Information ■ Section 8.7, Implementing Portlet Security ■ Section 8.8, Improving Portlet Performance with Caching ■ Section 8.9, Implementing Error Handling ■ Section 8.10, Implementing Event Logging ■ Section 8.11, Writing Multilingual Portlets ■ Section 8.12, Enhancing Portlets for Mobile Devices ■ Section 8.13, Registering Providers Programmatically The source code for many of the examples referenced in this chapter is available as part of PDK-PLSQL. You can download PDK-PLSQL from the Oracle Portal Developer Kit PDK page on Oracle Technology Network OTN: http:www.oracle.comtechnologyproductsiasportalpdk.html When you unzip PDK-PLSQL, you will find the examples in: Note: In general, Oracle recommends that you build your portlets using Java rather than PLSQL. For more information on choosing a technology for building your portlets, refer to Chapter 2, Portlet Technologies Matrix . For more information on building your portlets using Java, refer to Chapter 6, Creating Java Portlets . 8-2 Oracle Fusion Middleware Developers Guide for Oracle Portal ..pdkplsqlstarter ..pdkplsqlsample ..pdkplsqlcache ..pdkplsqlsso ..pdkplsqlsvcex You can find the reference for PDK-PLSQL in: ..pdkplsqldoc

8.1 Guidelines for Creating PLSQL Portlets

When you write your portlets in PLSQL, you should follow the best practices described in this section: ■ Section 8.1.1, Portlet Show Modes ■ Section 8.1.2, Recommended Portlet Procedures and Functions ■ Section 8.1.3, Guidelines for Mobile Portlets

8.1.1 Portlet Show Modes

Just like a Java portlet, a PLSQL portlet has a variety of Show modes available to it. A Show mode is an area of functionality provided by a portlet. The following available Show modes are described more fully in Chapter 6, Creating Java Portlets : ■ Shared Screen mode is described in Section 6.1.1.1, Shared Screen Mode View Mode for JPS ■ Edit mode is described in Section 6.1.1.2, Edit Mode JPS and Pdk-Java . ■ Edit Defaults mode is described in Section 6.1.1.3, Edit Defaults Mode JPS and PDK-Java . ■ Preview mode is describe in Section 6.1.1.4, Preview Mode JPS and PDK-Java . ■ Full Screen mode is described in Section 6.1.1.5, Full Screen Mode PDK-Java . ■ Help mode is described in Section 6.1.1.6, Help Mode JPS and Oracle Portal . ■ About mode is described in Section 6.1.1.7, About Mode JPS and PDK-Java . ■ Link mode is described in Section 6.1.1.8, Link Mode PDK-Java . To check for the selected Show mode, you can use the constants in the wwpro_api_ provider package. These constants are listed with their corresponding Show mode in Table 8–1 . Table 8–1 Show Mode Constants in wwpro_api_provider Show mode Constant Shared Screen MODE_SHOW Edit MODE_SHOW_EDIT Edit Defaults MODE_SHOW_EDIT_DEFAULTS Preview MODE_SHOW_PREVIEW Full Screen MODE_SHOW_DETAILS Help MODE_SHOW_HELP About MODE_SHOW_ABOUT Creating PLSQL Portlets 8-3

8.1.2 Recommended Portlet Procedures and Functions

The primary goal of the portlets code is to generate the HTML output that displays on a page for all of the Show modes required by Oracle Portal. Although it is possible to implement the portlet as a set of separate PLSQL stored program units, organizing the portlets code into a PLSQL package is the best way of encapsulating related portlet code and data as a single unit in the database. You also achieve better database performance and ease of portlet maintenance. As you may recall from Section 2.4, Deployment Type , requests from Oracle Portal for a particular portlet go through the portlets provider. To communicate with its portlets, the provider contains a set of required methods that make calls to the portlet code. When implementing a portlet as a PLSQL package, it is a good idea to organize the portlet code in parallel with the provider code. For example, when the provider needs to retrieve information about one of its portlets, it uses its get_portlet function. Hence, it makes sense for the portlet to contain a get_portlet_info function that returns the requested information when called by the providers get_portlet function. Similarly, it is logical for the providers show_portlet procedure to call the portlets show procedure, which produces the HTML output for a requested Show mode and returns it to the provider. Table 8–2 describes the recommended procedures and functions for a PLSQL portlet to communicate effectively with the database provider.

8.1.3 Guidelines for Mobile Portlets

Oracle Portal is capable of rendering its pages for both HTML and non-HTML mobile devices. When designing a portlet for a mobile device, you must consider Link MODE_SHOW_LINK Table 8–2 Recommended Functions and Procedures for PLSQL Portlets ProcedureFunction Name Purpose get_portlet_info Returns the portlet record to the provider. show Produces HTML output for a requested Show mode and returns it to the provider. register Initializes the portlet at the instance level. The register procedure should not contain any transaction closing statements, such as COMMIT, ROLLBACK, or SAVEPOINT. OracleAS Portal handles the closing of the transactions itself. deregister Enables cleanups at the instance level. The deregister procedure should not contain any transaction closing statements, such as COMMIT, ROLLBACK, or SAVEPOINT. OracleAS Portal handles the closing of the transactions itself. is_runnable Determines whether the portlet can be run. Security checks can be performed in this function. copy Copies the personalized and default values of portlet preferences from one portlet instance to a new portlet instance when Oracle Portal makes a copy of the page. describe_parameters Returns a list of public portlet parameters. Table 8–1 Cont. Show Mode Constants in wwpro_api_provider Show mode Constant 8-4 Oracle Fusion Middleware Developers Guide for Oracle Portal some additional guidelines. The guidelines for mobile portlets are described fully in Section 6.1.4, Guidelines for Mobile Portlets . For information on how to build mobile-enabled portlets, refer to Section 8.12, Enhancing Portlets for Mobile Devices .

8.2 Building PLSQL Portlets with the PLSQL Generator

To facilitate the development of database providers and PLSQL portlets, you can use the PLSQL Generator, a utility that creates installable PLSQL code for a database provider and its portlets. The PLSQL Generator is a standalone Web application that receives the provider and portlet definitions in the form of an XML file similar in format to the provider.xml file. The XML tags used for the provider and portlet definition are a subset of the XML tags used for defining Web providers with PDK-Java. The output of the PLSQL Generator is a SQL script that can be run from SQLPlus. The script contains SQL commands for installing the provider and portlet packages in the correct order. You can download the PLSQL Generator along with its installation instructions from: http:www.oracle.comtechnologyproductsiasportalfilesplsqlgenerat or.zip The general model for working with the PLSQL Generator is as follows: 1. Create an XML file that defines the provider and portlets that you want to build, as described in Section 8.2.1, Creating the Input XML File . 2. Run the PLSQL Generator using the XML file as input, as described in Section 8.2.2, Running the PLSQL Generator . 3. Publish the generated PLSQL portlet, which includes the following steps: ■ Install the provider generated by the PLSQL Generator into the database, as described in Section 8.2.3.1, Installing the Packages in the Database . ■ Register the database provider with the Oracle Application Server, as described in Section 8.2.3.2, Registering the Database Provider . ■ Add the generated portlet to a page, as described in Section 8.2.3.3, Adding Your Portlet to a Page .

8.2.1 Creating the Input XML File

The source XML file starts and ends with the provider and provider tags, and can include one or more portlet definitions. Each portlet definition is bracketed by the portlet and portlet tags. A portlet definition includes the XML tags that specify values for the portlet record attributes and enable the links in the portlet header. For example, the name tag specifies the portlet name in the provider domain and the title tag specifies the portlet display name or title. When set to true, the showEdit tag enables the Edit mode for the portlet and the corresponding link in the portlet header. Table 8–3 lists the available XML tags for PLSQL Generator input. Table 8–3 XML Tags for PLSQL Generator Input XML Tag Definition Value Type provider Encloses provider definition tags. Not applicable portlet Encloses portlet definition tags. Not applicable