| Last Updated: | March 20, 2003 |
| Status: | Production |
| Version: | Any PDK Release |
As described in An Overview of Portlets, a portlet is a reusable component located within a contained region on an Oracle9iAS Portal web page. Oracle9iAS Portal provides many solutions for constructing portlets. While all these portlets will look the same to your users, they are implemented differently and are typically used in different situations. This article describes some of the implementation strategies and guidelines for writing portlets.
There are two types of portlets available when constructing portlets: built-in and custom.
Out of the box, Oracle9iAS Portal provides a considerable amount of built-in functionality for constructing portlets, all without writing code. This functionality falls into three main categories, web application development, web publishing, and external site integration.
Oracle9iAS Portal web applications allow information to be captured, acted upon, and displayed dynamically using portal components. These components include forms, reports, charts, calendars, hierarchies, and menus. Here are some examples of how you might create Oracle9iAS Portal components for your own enterprise portal:
Mailing list registration. You can use a simple Oracle9iAS Portal form to sign up readers for a mailing list. This form can even use the built-in client-side JavaScript validation to verify that the email address is formatted correctly before sending this information to the database.
Gathering user feedback. A more detailed form can be used as a rating card for finding out what your users think about a certain page on a web site. It could include static lists of ratings to choose from (e.g. excellent, good, fair, and poor) as well as free text boxes and dynamically generated lists. You can then quickly create Oracle9iAS Portal reports to see what people are saying. They could even use these reports to generate links back to the page being rated and highlight any poor ratings in red.
Displaying an interactive list of events. Oracle9iAS Portal components make it easy to create a powerful events calendar which shows a calendar view of upcoming events. Users could then click on an event to see its details, or even use a form to submit more information about that event.
Building an organization chart. The hierarchy component is useful for creating a visual representation of a parent-child relationship similar in structure to an organization chart. Employees can navigate the org chart using the up and down links provided automatically by Oracle9iAS Portal hierarchies and can even drill into specific information about each individual on the chart.
Publishing information using Oracle9iAS Portal is simple, but also very powerful. Oracle9iAS Portal provides an extensive web publishing service that includes folders for organizing information hierarchically, categories for classifying information, and perspectives for indicating ways in which that content might be useful. The web publishing facilities could be used for:
Gathering related documents. You could keep a virtual profile for a specific client using the Oracle9iAS Portal and its web publishing folders. Soft copies of contracts, specifications, and correspondence could all be kept in a single Oracle9iAS Portal folder for future reference. In addition, each document could be tagged with specific perspectives showing who might be interested in that document. For example, a contract might be marked as interesting to corporate lawyers, account managers, and order fulfillment personnel using perspectives.
Collecting and organizing intranet links. Oracle9iAS Portal makes it easy to add, sort, and categorize links so that your entire intranet is accessible from a central web site. By sorting these links into the appropriate folders and applying the correct category and perspective tags, you can create a site which makes navigating a previously complicated intranet extremely easy.
Dynamically presenting the latest information. Oracle9iAS Portal supports creating a web page from a pre-configured search. What makes this function interesting is that this page will always have the latest information on the search topic no matter where that information logically resides on the web site. If, for example, there are multiple team working on jet engines within the organization, a saved search page could bring up the latest information about jet engines from all teams, transparently to the reader.
Oracle9iAS Portal can also seamlessly integrate information from external sources without programming. You can use Oracle9iAS Portal to:
Publish feeds from content partners. Many content providers have programs which allow partners to display content directly from their site. Using the HTML they provide inside an Oracle9iAS Portal dynamic page, you can easily embed their content into your portal.
Support affiliate programs. By simply cutting and pasting the HTML provided by affiliates into Oracle9iAS Portal dynamic pages, you can create a portlet specifically for that affiliate program and embed it into your portal. Any click-throughs will take users directly to that external site.
As you have read above, Oracle9iAS Portal enables you to develop most, if not all, of your enterprise portal using its wizard-driven, declarative interface. However, to integrate with other existing applications (Java/J2EE, Web Services, Perl, ASP, C+, PL/SQL, etc) and to allow you to extend the portal capabilities through more complex functionality, the Oracle9iAS Portal Developer Kit (PDK) provides the tools for developing portlets programmatically.
Using the Oracle9iAS Portal Developer Kit (PDK), you can declaratively build, publish, and manage pages, content, styles, templates, admin, and security. You can build portlets in any web language and expose them as either database or web providers. The PDK provides a productive environment with a simple, easy to use declarative interface, that can be used by persons at all skill levels. This environment not only supports initial development efforts, but the complete development lifecycle of a portal. The PDK also provides a wizard-based UI called the Java Portlet Wizard that enables you to build, test, and deploy your portlets and providers all from within Oracle9i JDeveloper.
A Web provider exposes any type of web applications as portlets to Oracle9iAS Portal. Web providers are good for integrating external information sources (e.g. internet news / business information), legacy application, and other existing applications in any web language. Exposing your portlets as Web providers eliminates the need to re-create existing web sites and enables existing applications such as Java/J2EE, Perl, ASP, C+, Web Services and much more to be displayed as portlets with little or node additional coding.
Portlets exposed as Web providers usually reside on machines other than Oracle9iAS Portal nodes. These portlets communicate with Oracle9iAS Portal using Simple Object Access Protocol (SOAP), an XML-based standard. Here are some examples of how to use portlets exposed as Web providers:
Customize the appearance and behavior. You choose how your portlets look and act.
Take advantage of portlet services. The PDK provides classes which not only enable you to build portlets, but also expose APIs for end-user customization, parameter passing, session storage, NLS translations, security, and logging.
Securely integrate existing web applications. With PDK architecture, you can expose excerpts of your existing web applications as portlets. This mechanism allows your users to take the pieces of web applications that they use frequently and easily display them onto one of their portal pages for easy access. They can do so securely because the web portlet architecture supports Oracle9iAS Portal single sign-on, where users can log in once and be authenticated across all their applications.
Securely integrate corporate systems. The PDK architecture provides the means for seemingly disparate systems to be seamlessly integrated into the Oracle9iAS Portal. For example, it is possible to integrate a COM-driven system by creating a local CGI executable that communicate with the system's COM objects and passes SOAP (XML) back to Oracle9iAS Portal.
Leverage existing web skills. You can write portlets in any web-capable language since portlets exposed as Web providers use industry-standard HTTP and the open SOAP protocol. This flexibility means that you can take advantage of your existing expertise in web programming when extending Oracle9iAS Portal.
Integrate Web Services. You can also integrate off-the-shelf Web Services as portlets using the PDK. You can also take advantage of the PDK APIs to create smart portlets that communicate with each other. For example, you can have a Java/J2EE-based portlet drive content to Web Services portlets.
A Database provider exposes any type of database applications as portlets to Oracle9iAS Portal. Normally, but not a requirement, PL/SQL Portlets are exposed as Database providers. PL/SQL portlets are implemented as stored procedures inside an Oracle database. You can use both PL/SQL and Java to create PL/SQL portlets. Java implementations require a PL/SQL wrapper.
Most of the built-in portlets are actually exposed as Database providers. Typically, you would write your own PL/SQL portlet in situations where you need more flexibility than the built-in portlets provide. Here are some examples of how you can use database portlets:
Customize the appearance and behavior. You choose how your PL/SQL portlets look and act.
Take advantage of native Oracle9iAS Portal services. Oracle9iAS Portal provides APIs which you can use to provide end-user customization, session storage, security, NLS translations, error handling, and logging for your portlets.
Write data-intensive applications. Because these portlets reside inside the database, they have quick and convenient access to structured information. You can easily perform sophisticated queries and process structured information because PL/SQL portlets run inside the database.
Interact with data. PL/SQL portlets are extremely useful in applications where structured information drives the user-interface. You can quickly look at information in the database to customize how your portlet behaves.
Leveraging existing database skills. You can write, install, uninstall, and export PL/SQL portlets just like any other database packages. If you already familiar with developing for the Oracle database, you can get started building PL/SQL portlets quickly and easily. You can also display PL/SQL portlets remotely using the PL/SQL HTTP Adapter.
Streamline server architecture. You can use PL/SQL Portlets to simplify the architecture by keeping all of your portlets contained in the same database as the Oracle9iAS Portal installation. To reduce the number of machines required, you can also install the web server needed to access Oracle9iAS Portal on that machine.
When writing portlets, you should keep the following set of 'best practices' or guidelines in mind.
A show mode is an area of functionality that a portlet provides. There are currently eight different show modes each coupled with what it is supposed to display on the screen. The portlets modes are listed below.
A portlet uses shared screen mode to appear on a page with other portlets. This is the mode most people think about when they envision a portlet. Portlets are rendered inside HTML table cells when in shared screen mode. This means a portlet can display any content that can be rendered within a table cell, including among other technologies HTML, plug-ins, and Java. The actual size of the table cell is variable depending on user settings, the browser width, and the amount and style of content placed in the portlet. When developing portlets, it is important to remember not only that your portlet will share a page with others, but also that you will not have control over its dimensions or placement.
Plain HTML is the most basic way to render portlets and provides a great deal of flexibility to portlet developers. You can use almost all standard HTML paradigms such as links, forms, images, tables, and any construct that can be displayed 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 not to appear.
Use standard HTML. The official HTML specification is available from the W3C.
Watch out for unterminated and extraneous tags. The behavior of pages with improperly terminated tags is undefined, meaning the browser can do anything it wants. Many times, what the browser wants is different from what you want. Tools like weblint and HTML Tidy can help.
The HTML you use also directly affects the perceived performance of your site. Users judge performance based on how long it takes for them to see the page they requested. Browsers need time to interpret and display HTML.
Do not use deeply nested tables. Deeply nested tables slow performance dramatically on Netscape browsers. Oracle Portal draws one level of tables to render portlets. If your portlets use tables within tables, your users may have to wait quite a while for pages to render.
Avoid lengthy, complex HTML. Portlets share a page with others and the more each portlet generates, the more the browser has to do before it can show anything.
The fonts and colors of every portlet on a page should match the style settings chosen by the user. To accomplish this, these style selections are embedded automatically using a CSS stylesheet on each Oracle Portal page. The portlets can then access these settings for their fonts and colors, either directly or using the API.
While different browsers have implemented varying levels of the full CSS specification, Oracle 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. Here are guidelines for using CSS:
Use CSS. If you hardcode the fonts and colors, your portlet may look out of place when the user changes the page style settings. It is also possible that your hardcoded portlet may also print text using the same color as the background.
Use the CSS APIs to format your text. The stylesheet definition is available at the top of Oracle Portal pages but you should not call it directly. Instead, use the APIs provided to format your text appropriately. This ensures your portlets will work even if the stylesheet is modified in the future.
Avoid using CSS for absolute positioning. Since users can customize their portal pages, there is no guarantee your portlet will appear in a particular spot.
CSS is useful for allowing users the flexibility of changing the way portlets look but it does not solve every possible problem. As the developer, you have control over everything your portlet displays. You can help your users by adhering to these guidelines:
Keep portlet content concise. Do not try to take full screen content and expose that through a small portlet. You will end up with a portlet whose content is too small or cramped to be usable on smaller monitors.
Do not create fixed-width HTML tables in portlets. There is no way of being able to tell how wide of a column your portlet will have. Depending on the browser being used, if your portlet requires more room than it is given, it could overlap with another portlet.
Avoid long, unbroken lines of text. The result is similar to what happens with wide fixed-width tables.
Check behavior when resizing the page. Ensure that your portlet works in different browser sizes.
Check behavior when the default browser font is changed. Many people set their default font sizes differently. Your portlet should handle these situations gracefully.
Use standard HTML. The official HTML specification is available from the W3C.
Watch out for unterminated and extraneous tags. The behavior of pages with improperly terminated tags is undefined.
Use only elements that can be rendered properly in an HTML table cell. Frames, for example, do not appear when inserted in a table.
Do not use deeply nested tables. Deeply nested tables slow performance dramatically on Netscape browsers.
Avoid lengthy, complex HTML. Portlets share a page with others and the more each portlet generates, the more the browser has to do before it can show anything.
Use CSS. If you hardcode the fonts and colors, your portlet may look out of place when the user changes the page style settings.
Use the CSS APIs to format your text. This ensures your portlets will work even if the stylesheet is modified in the future.
Avoid using CSS for absolute positioning. There is no guarantee your portlet will appear in a particular spot.
Keep portlet content concise. Do not try to take full screen content and expose that through a small portlet.
Do not create fixed-width HTML tables in portlets. There is no way of being able to tell how wide of a column your portlet will have.
Avoid long, unbroken lines of text. The result is similar to what happens with wide fixed-width tables.
Check behavior when resizing the page. Ensure that your portlet works in different browser sizes.
Check behavior when the default browser font is changed. Your portlet should handle these situations gracefully.
Draw portlet banners (title bars) but allow them to be turned off. Check the has_title_region flag for whether to draw the title bar or not.
Edit Mode
A portlet uses edit mode to allow users to customize the behavior of the portlet. Edit mode provides a list of settings that the user can change. These customizable settings may include the title, type of content, formatting, amount of information, defaults for form elements, and anything that affects the appearance or content of the portlet.
Portal users typically access a portlet's edit mode by clicking the Customize link on the portlet banner. The user is taken to a new page in the same browser window when he clicks on this link. The portlet typically creates a Web page representing a dialog box where the portlet settings can be customized. Once the settings are applied, the user is then automatically returned to the page from which he came.
Should the portlet banners be turned off, you can also access edit mode from the Customize Page screen when you choose Customize for Myself (referred to in this document as "Customize Page - Customize for Myself"). The link is labeled "Customize" on the banner of the wire frame diagram of that portlet.
For consistency and user convenience, edit mode should implement the following buttons in the following order:
OK: This saves the user customizations and redirects the browser back to the calling portal page
Apply: This saves the user customizations and reloads the current page.
Reset to Defaults: This removes all user customizations for this current user on this portlet instance. It the redirects the browser to the calling portal page. Reset to Defaults is different from Cancel. Reset to Defaults changes the customization settings to be the defaults.
Cancel: This redirects then browser to the calling portal page without saving changes. Cancel is different from Reset to Defaults. Cancel leaves the current settings as they are.
When you show the forms used to change customization settings, you should default the values so that the user does not have to re-enter settings constantly. When rendering the customization values, a specific sequence should be followed in order to provide consistent behavior. The following is the sequence for rendering customization values:
User preference. Query and display this user's customizations, if available.
Instance defaults. If no user customizations are found, query and display system defaults for the portlet instance. These are set in edit defaults mode and only apply to this portlet instance.
Portlet defaults. If no system default customizations are found, general portlet defaults should be displayed. These defaults could be blank. General portlet defaults are sometimes hardcoded into the portlet, but should be overridden if either of the two previous conditions apply.
This logic allows the customizations to be presented in a predictable way that is consistent with the other portlets in the portal.
Allow users to customize the title of the portlet. The same portlet may be added to the same portal page several times. Allowing the user to customize the title helps alleviate confusion.
Supply an OK button. This saves the user customizations and redirects the browser back to the calling portal page.
Supply an Apply button. This saves the user customizations and reloads the current page.
Supply a Reset to Defaults button. This removes all user customizations for this current user on this portlet instance.
Supply a Cancel button. This redirects then browser to the calling portal page without saving changes.
Follow the guidelines for surfacing values for customization. Show the current user settings in your customization screen. If these are not available, show the instance defaults. If neither are available, display the portlet defaults. These portlet defaults may be blank.
If using validation-based caching, generate a new key when needed. If customizations cause a change in portlet display or content, you must regenerate your caching key. Otherwise the user may see incorrect content.
Do not use edit mode as an administrative tool. Edit mode is meant to give users a way of changing the behavior of their portlets. If you need to perform provider settings or do other administrative tasks, you should create secured portlet specifically for that task.
Edit Defaults Mode
A portlet uses edit defaults mode to allow administrators to customize the default behavior of a particular portlet instance. Edit defaults mode provides a list of settings that the administrator can change. These customizable settings may include the title, type of content, formatting, amount of information, defaults for form elements, and anything that affects the appearance or content of the portlet.
These default customization settings can be modified to change the appearance and content of that individual portlet 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.
Page administrators access edit defaults mode from the Customize Page screen when you choose Customize for Others (referred to in this document as "Customize Page - Customize for Others"). The link is labeled "Edit Defaults" on the banner of the wire frame diagram of that portlet.
The user is taken to a new page in the same browser window when he clicks on this link. The portlet typically creates a Web page representing a dialog box where the portlet instance settings can be customized. Once the settings are applied, the user is then automatically returned to the page from which he came.
For consistency and user convenience, edit mode should implement the following buttons in the following order:
OK: This saves the user customizations and redirects the browser back to the calling portal page
Apply: This saves the user customizations and reloads the current page.
Cancel: This redirects then browser to the calling portal page without saving changes. Cancel is different from Revert to Defaults. Cancel leaves the current settings as they are.
When you show the forms used to change customization settings, you should default the values so that the page administrator does not have to re-enter settings constantly. When rendering the customization values, a specific sequence should be followed in order to provide consistent behavior. The following is the sequence for rendering customization values:
Instance preferences. Query and display system defaults for the portlet instance.
Portlet defaults. If no system default customizations are found, general portlet defaults should be displayed. These defaults could be blank. General portlet defaults are sometimes hardcoded into the portlet, but should be overridden if either of the two previous conditions apply.
This logic allows the customizations to be presented in a predictable way that is consistent with the other portlets in the portal.
Supply an OK button. This saves the user customizations and redirects the browser back to the calling portal page.
Supply an Apply button. This saves the user customizations and reloads the current page.
Supply a Cancel button. This redirects then browser to the calling portal page without saving changes.
Follow the guidelines for surfacing values for customization. Show the current instance settings in your customization screen. If these are not available, display the portlet defaults. These portlet defaults may be blank.
If using validation-based caching, generate a new key when needed. If customizations cause a change in portlet display or content, you must regenerate your caching key. Otherwise the user may see incorrect content.
Do not use edit defaults mode as an administrative tool. Edit mode is meant to give users a way of changing the behavior of their portlets. If you need to perform provider settings or do other administrative tasks, you should create secured portlet specifically for that task.
Preview Mode
A portlet uses preview mode to show the user what the portlet looks like before adding it to a page. Preview mode is a visual representation of what the portlet can do.
Portal users typically access a portlet's preview mode by clicking on a portlet's title from the Add Portlet dialog. The left frame of the portlet selector dialog then displays a new page containing the preview of the chosen portlet. The user then has the option to add that portlet to his page. Portal administrators may access preview mode from the Portlet Repository.
Note that the portal does not draw the portal banner when rendering the portlet in this mode.
Provide an idea of what the portlet does. Preview should generate enough content so that the user who wants to use the portlet would get an idea about the actual content and functionality of the portlet.
Keep your portlet previews small. The amount of data produced in this mode should not exceed a few lines of HTML. Preview mode is rendered in a small window and exceeding the window's size looks unprofessional and forces users to scroll.
Do not use live hyperlinks. Links may not behave as you expect them to when rendered in the Add Portlet dialog or the Portlet Repository. Hyperlinks can be simulated using the underlined font.
Do not use active form buttons. Forms may not behave as you expect them to when rendered in the Add Portlet dialog or the Portlet Repository. If you decide to render form elements, do not link them to anything.
Full Screen Mode
portlet uses full screen mode to show more details than it can show when sharing a page with other portlets. Full screen mode lets a portlet show what it would if it had the entire screen to itself, outside of an HTML table cell.
For example, if a portlet is meant to display expense information, it could show a summary of the top ten spenders in shared screen mode and display the spending totals for everyone in full screen mode. Portlets can also provide a shortcut to web applications as well. If a portlet provided an interface to submitting receipts for expenses in shared screen mode, it could link to the entire expense application from full screen mode.
Portal users access a portlet's full screen mode by clicking the title of the portlet. The user is taken to a new page in the same browser window when he clicks on this link. The portlet can either generate the content for this new page or the link can take the user to an existing page or application.
Display relevant copyright, version, and author information. Users want to know what portlet they are using and where they can get more information. This about screen may become important when supporting your portlets.
Provide a way to navigate to the previous page. You should provide users with a link or button that takes them back to the previous page.
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 content, and its capabilities with this mode.
Portal users access a portlet's help mode by clicking the Help link on the portlet banner. The user is taken to a new page in the same browser window when he clicks on this link. The portlet can either generate the content for this new page or the link can take the user to an existing page or application.
Describe how to use the portlet. Users may not know all the features your portlet provides just from its interface. Describe the features and how to get the most out of them.
Provide a way to navigate to the previous page. You should provide users with a link or button that takes them back to the previous page.
About Mode
Users should be able to see what version of the portlet is currently running, its publication and copyright information, and how to contact the author. Portlets that require registration may link to Web-based applications or contact information from this mode as well.
Portal users access a portlet's about mode by clicking the About link on the portlet banner. The user is taken to a new page in the same browser window when he clicks on this link. The portlet can either generate the content for this new page or the link can take the user to an existing page or application.
Display relevant copyright, version, and author information. Users want to know what portlet they are using and where they can get more information. This about screen may become important when supporting your portlets.
Provide a way to navigate to the previous page. You should provide users with a link or button that takes them back to the previous page.
Link Mode
A portlet using link mode to render itself in PDA and mobile devices. The user should be able to view the same information available in shared screen mode, but in a mobile format.
Limit content. Users should see the same data as shared screen mode, but without all of the graphic images and unnecessary content.
The Portal Developer Kit provides services that your portlets can take advantage of. These services are provided for convenience, so developers do not have to write their own. While using these services, you need to keep in mind standard conventions so that your portlet behaves consistently with others.
Web Services - DOC, RPC
Java/J2EE - Java Server Pages (JSPs), Java Servlets, Enterprise Java Beans (EJBs), Java Classes
XML data sources - General XML/XSL, RSS
Other URL-accessible content built in any language (PERL, C++, ASP, etc.)
Standards
Browser technologies: HTML, JavaScript, CSS, XSL, Flash, Java Applets
Internationalization: language support, NLS, character set information
Convenience utilities: URL rewriting
Error handling
Session Management. Session: Managing, users.
End-user personalization: file-based, database-backed
Parameters: URL-based, page-based
Events
Scalability: load balancing, failover
Caching: design considerations, invalidation-based , validation-based, expires-based, Web Cache
Portlet security: design considerations, partner app, external app, portal app, mod_osso
Application security: JAAS/JAZN
The Java Portlet Wizard is an extension of Oracle9i JDeveloper. It enables you to build, test, and deploy your providers and portlets all from within Oracle9i JDeveloper. The Java Portlet Wizard enables your to build portlets in 4 easy steps:
Create Portlet & Provider
Use the wizard to create your basic portlet code and the necessary configuration files for the provider framework. In the wizard you can choose which of the portlet show modes (Edit, Edit Defaults, and so on) you want to implement and what implementation method (JSP, HTML, ...) you want to use. The wizard then creates a simple sample implementation for each of the selected modes, explaining for example how to access portlet parameters from portlet logic. Add Portlet Logic
Now that you have created the default implementation you need to replace or extend the example code with your business logic to implement the functionality you want the portlet to perform. Test Portlet and Provider
Using the built-in J2EE server of Oracle9i JDeveloper you can test your provider and its portlets by executing the application homepage (index.jsp) that was also created by the wizard. It will present you with the URL that you can use to register your provider currently running inside the built-in J2EE container. Deploy to Application Server
After you have tested your portlets and find them ready for deployment, you can use JDeveloper deployment mechanisms to deploy your application to your application server.
The Java Portlet Wizard is based on PDK release 2 (9.0.2 and higher).
For detailed information on using the Java Portlet Wizard or to download the wizard review:
| Revision History: |
|
| Oracle Corporation World Headquarters 500 Oracle Parkway Redwood Shores, CA 94065, USA http://www.oracle.com/ |
Worldwide Inquiries: 1-800-ORACLE1 Fax 650.506.7200 |
Copyright and Corporate Info |