Portal Guide

CHAPTER 12

About Portlets

This chapter introduces basic portlet concepts and describes how exteNd Director implements portlets. It covers these topics:

 
Top of page

What is a portlet?

A portlet is a specialized Java class that processes requests from Web clients and generates dynamic content on a portal page. Portlets are defined in the Java Portlet 1.0 specification.

You can think of portlets as pluggable user interface elements that provide a presentation layer for portal applications. Users can personalize the content and appearance of portlets, based on preferences set by an administrator or other user.

In exteNd Director you run portlets in several ways:

 
Top of section

Based on servlet technology

To a large extent, portlets are based on servlet technology, as described in The relationship between portlets and servlets. For example, both portlets and servlets are managed by a container object and both use a request/response paradigm to communicate with Web clients.

To get a feel for how portlets operate under this paradigm, consider the case of a portlet application running in a Web browser. When a user interacts with content produced by one of the portlets—perhaps by following links or clicking buttons—the browser sends a request to the portal. The portal then forwards the request to the portlet container which repackages it as an action request or render request for execution by the appropriate portlet. You can learn more about portlet request handling in Portlet requests and responses.

exteNd Director provides support for developing and running Java Portlet 1.0-compliant portlets, but in addition provides extended functionality, as described in exteNd Director extensions to Java Portlet 1.0.

 
Top of section

The Portlet specification

The Java Portlet 1.0 specification defines a standard set of APIs for developing portlets that can run in any Java Portlet 1.0-compliant portal.

Although this chapter introduces you to basic portlet concepts, you can find detailed information about Java Portlet 1.0 description at the Java Community Process Web site:

  http://jcp.org/aboutJava/communityprocess/final/jsr168/index.html

NOTE:   This URL was valid at the time this chapter was published.

 
Top of section

Portlet object model

exteNd Director implements a hierarchical portlet object model, illustrated in the following diagram:

pgPortletHierarchy

Portlet class   The Java class that defines the initialization parameters and default behavior of the portlet. Each portlet class in a portlet application must have a definition descriptor to make the portlet available to the portlet container. These descriptors must be created either as an entry in portlet.xml or as a separate portlet fragment deployment descriptor, as described in the section on portlet application deployment descriptors.

Portlet definition   An instance of the portlet class. You can create multiple portlet definitions per portlet class—for example, if you want a definition that inherits all the characteristics of a particular class, but uses different initialization parameters.

Portlet registration   A registered portlet definition. You can register one or more portlet definitions in a portlet application. A portlet registration inherits preferences and settings from its parent definition, but exteNd Director allows you to override any of these defaults in each registration. In this way, you can place multiple registrations of the same portlet definition on a single portal page, where each registration exhibits unique behavior and generates unique content.

You register portlet definitions in the Portlet Management section of the Director Administration Console (DAC), as described in the section on registering portlet definitions.

Portlet page instance   An instance of a portlet registration that is associated with a specific portal page. A portlet page instance inherits preferences and settings from its parent portlet registration. You can override any of these defaults when you assign a portlet registration to a portal page using the Portal Page Administration tool and the Portal Personalizer tool. The following references describe how to assign portlet registrations to different types of portal pages:

To assign portlet registrations to:

See:

Container pages

Adding content to a container page.

Shared pages

Adding content to a shared page.

Personal pages

Adding content to a personal page

For more information    For information about assigning preferences at each level of the portlet object model, see Portlet preferences.

 
Top of page

exteNd Director extensions to Java Portlet 1.0

The exteNd Director implementation of Java Portlet 1.0 includes the following extensions, designed to offer more flexibility in developing and running portlets:

 
Top of page

The relationship between portlets and servlets

Although portlets and servlets share many functional characteristics, they are distinct Java classes with individual—though analogous—missions: portlets encapsulate application logic to run in a portal; servlets encapsulate application logic to run on a Web server.

javax.Portlet mimics javax.Servlet and leverages the following functionality from servlets:

The following diagram compares portlets and servlets, highlighting their features in common and those that are specific to each object:

pgPortletVenn4

 
Top of page

Portlet container

Like servlets, portlets are managed by a container object. Called a portlet container, the object acts as a liaison between the portal and its associated portlets.

As specified in Java Portlet 1.0, the portlet container is responsible for:

 
Top of page

Portlet life cycle

Portlets move through several stages from initial activation to final deactivation. These stages constitute the portlet life cycle, as shown in the following diagram:

pgPortletLifeCycleStages

Portlet containers in exteNd Director automatically manage the life cycles of portlets in your deployed portlet applications.

 
Top of section

Loading and instantiation

The portlet container loads portlet classes, then instantiates them for use. The portlet container invokes the same class loader to load portlet resources as the servlet container uses to load Web application resources per Web application.

In exteNd Director, portlet containers begin loading portlets and other portlet resources when you deploy a portlet application or start a server that contains deployed portlet applications.

 
Top of section

Initialization

During initialization, the portlet may execute performance-intensive, one-time activities, such as connecting to databases or to Enterprise JavaBeans (EJBs).

The portlet container initializes the portlet object based on the following configuration data:

exteNd Director provides several portlet deployment descriptors:

For more information    For more information, see the section on portlet application deployment descriptors.

 
Top of section

Invocation

After the portlet is initialized, the portlet container can invoke it to handle client requests that are triggered by portlet URLs, as described in Portlet URLs. These URLs specify that a particular portlet respond to an action request or render request from a client.

Portlets respond to action requests by changing state and respond to render requests by generating content, as described in Portlet requests and responses. Portlets display content in a portlet window constructed by the portlet container on the portal page, as described in How portlets are rendered.

 
Top of section

Removal from service

The portlet container determines when to remove a portlet from service—for example to conserve resources or as part of housekeeping prior to shutting down.

When the portlet container disables a portlet, the portlet releases its resources and saves persistent state information.

 
Top of page

How portlets are rendered

When a portal page is requested at runtime, the exteNd Director Portal Aggregator aggregates the content of all portlets assigned to the page. To render portlets, the Portal Aggregator sends a request to the portlet containers to allocate real estate on the page for displaying the content generated by each portlet. This area is called a portlet window, described in the next section.

 
Top of section

Portlet windows

A portlet window is an area on a portal page that consists of the content generated by the portlet, along with decorations and controls added by the portal. Each portlet window is constructed from a portlet class that is associated with a preferences object. The preferences object provides access to the values of preferences and settings specified in the portlet deployment descriptors.

For more information    For more information, see Portlet preferences and the section on portlet application deployment descriptors.

The portal aggregates portlet windows into a complete document, called the portal page, as in the following example:

pgPortalPageElementsAnnot

A single portal page may contain multiple portlet windows that reference the same portlet definition, but display different registered instances of the portlet—each with its own preferences and settings specified at page assignment time. For example, you might want to assign multiple registrations of a weather portlet to the same page to display forecasts for different cities.

 
Top of section

Window states

A window state indicates the amount of portal page real estate to be allocated for the content generated by a portlet. The portlet container sends the current window state to each portlet it invokes; the portlet then determines how much information to render. Portlets can programmatically change their window states when processing action requests.

Supported window states

The exteNd Director portal supports the standard window states defined in Java Portlet 1.0:

Window state

Description

Normal

The portlet may share the portal page with other portlets or components. The portlet assumes it has limited display space and restricts the size of its rendered output.

Maximized

The portlet occupies most or all of the page real estate so it generates richer content than it would in the normal state.

Minimized

The portlet renders minimal output or no output at all. In exteNd Director, the portlet renders the title bar with options, if enabled, but no content.

 
Top of page

Portlet content

The content generated by a portlet is called a fragment. Each fragment is a piece of markup—that is, a sequence of characters and other symbols that describe a document's logical structure or specify how a file should look when it is printed or displayed.

exteNd Director portlets support the following types of markup:

exteNd Director allows you to style portlets that generate XML, as described in the section on styling portlets that generate XML content.

Portlets generate content in response to render requests, as described in Portlet requests and responses. The window state and mode of a portlet determines how it renders content, as described in How portlets are rendered.

The portal aggregates the content of multiple portlets to form a portal page.

 
Top of page

Portlet modes

The mode of a portlet indicates what activities the portlet should perform and what content it should generate.

 
Top of section

Standard portlet modes

exteNd Director supports the standard portlet modes specified by Java Portlet 1.0:

Mode

Portlet activity

How to implement

View

Generates markup that reflects its current window state

NOTE:   This is the default mode. All portlets must support View mode.

Override the doView() method of the GenericPortlet class

Edit

Provides content and logic to allow users to customize portlet behavior at runtime.

Override the doEdit() method of the GenericPortlet class

Help

Provides help information about the portlet

Override the doHelp() method of the GenericPortlet class

 
Top of page

Portlet URLs

A portlet URL is an URL that triggers a request for action by the portlet it references. Portlets generate these URLs as part of their content. When users select a portlet URL—for example by clicking a link that references the URL— the client sends a request to the portal for action by the portlet.

 
Top of section

Types of portlet URLs

There are two types of portlet URLs, each triggering different sequences of portlet requests:

Type of portlet URL

Triggers:

Action URL

One action request, followed by one render request per portlet on the portal page

Render URL

One render request per portlet on the portal page

For more information    For more information about action and render requests. see Portlet requests and responses.

 
Top of section

Information associated with portlet URLs

The portlet API allows you to include the following information in portlet URLs:

 
Top of page

Portlet context

The portlet context provides information about the container in which each portlet is running. Through the context object, portlets can:

 
Top of section

Scope of portlet context

The scope of the portlet context depends on the type of portlet application:

Type of portlet application

Scope of portlet context

Local

One context instance per portlet application per Java Virtual Machine (JVM)

Distributed

One context instance per JVM

 
Top of section

Based on servlet context

The portlet context leverages functionality from the servlet context of the portlet application, including:

As a result, portlets can share data with servlets and JSP pages in the same Web application. Data stored in the servlet context by servlets and JSP pages can be accessed by portlets through the portlet context. In turn, servlets and JSP pages can access portlet data through the servlet context.

 
Top of page

Portlet requests and responses

Web clients communicate with portlets using a request/response paradigm implemented by the portal. The paradigm is based on the Hypertext Transfer Protocol (HTTP) request/response model.

Portlet requests are generated when users interact with content produced by portlets on a portal page—for example by navigating links or submitting forms in a Web browser. Here is a typical request/response scenario:

pgPortletRequestResponse

There are two types of portlet requests—action requests and render requests. These requests are triggered in different sequences by portlet URLs, as described in Portlet URLs.

The following sections describe each type of portal request and response.

 
Top of section

Action requests and responses

An action request requires a portlet to update its state, based on a set of input parameters, defined by the developer.

Portlets respond to action requests by performing portlet-specific logic, such as:

Action requests take precedence over render requests in an action URL to ensure that the portlet enters the desired state before rendering content. This order of operations is important because portlet window state and mode play a role in the amount and type of content to render.

For example, suppose a portlet causes an action to occur via a link. When the user clicks the link—for example, to update a record—the portal is guaranteed to process the action before rendering any of the portlets. Thus, the rendered content can reflect the updated data from the action.

When processing an action URL, portlet containers must wait for the portlet to complete the action request before initiating the render requests for the portal page.

 
Top of section

Render requests and responses

A render request requires a portlet to generate content based on its current render state.

Often, render URLs trigger multiple render requests for a given portal page. Render requests may be executed sequentially or in parallel in random order.

For more information    For more information, see the section on synchronous versus asynchronous processing.

Portlets respond to render requests by producing content directly or delegating content generation to a servlet or JSP page.

This flexibility allows you to make informed decisions about how your portlet should provide content to a portal page. For example, if you already have a servlet that generates specialized content for your Web application, you don't need to reinvent the wheel; your portlet can delegate the task of content creation to that servlet.

Content rendering is governed by the portlet's mode and window state. For example, if the portlet's window state is MINIMIZED, no content can be rendered.

For more information    For more information, see How portlets are rendered and Portlet modes.

 
Top of page

Portlet sessions

Each portlet application includes one portlet session object per user session. The portlet session object provides a mechanism for all resources in the portlet application to share information.

Recall that portlet applications may contain servlets and JSP pages in addition to portlets. To facilitate data sharing, the portlet session stores all attributes in the HTTP session of the portlet application. As a result, portlets use PortletSession methods to access data stored by servlets or JSP pages in the HttpSession object. Similarly, servlets and JSP pages use HttpSession methods to access data stored by portlets in the PortletSession object.

PortletSession methods are based on the HttpSession methods of the same names.

 
Top of page

Portlet preferences

At runtime, portlets are associated with a preferences object whose attributes determine how a portlet behaves and what content it produces. Portlet preferences are defined in the portlet class and, therefore, are unique for every portlet.

 
Top of section

Levels of priority

exteNd Director provides a flexible paradigm that allows you to apply portlet preferences at four levels of priority, based on the portlet object model:

Priority

Type

Description

Where specified

How specified

1

(highest)

User-level Preferences

Writable preferences defined on a portlet page instance by a user at runtime,

Overrides definition-level, registration-level, and page- assignment-level preferences for a given portlet instance on a specific page.

At this level, you can set different preferences for the same portlet on different pages or for each instance of a single portlet on the same page.

User preference data store

Edit portlet preferences at runtime—for example in the Edit mode of a portlet.

2

Page-Assignment-level preferences

Writable preferences defined for a portlet registration when it is assigned to a portal page, usually by an administrator after deployment and registration.

Overrides definition-level and registration-level preferences for a given portlet registration on a specific page.

At this level, you can set different preferences for the same portlet on different pages or for each registration of a single portlet on the same page.

Portal Administration tool

Assign portlets to shared and container pages using the Portal Administration tool.

For more information    See the chapter on administering the portal.

3

Registration-level preferences

Writable preferences defined for a portlet instance when it is registered, usually by an administrator after deployment.

Overrides Definition-level preferences for a given portlet registration.

NOTE:   Registered portlet instances are called portlet registrations.

Director Administration Console (DAC)

Register portlet instances using the Director Administration Console (DAC).

For more information    See the chapter on using the Portlet Management section of the DAC.

4

(lowest)

Definition-level preferences

Default, read-only preferences defined for a portlet definition. These preferences cannot be modified after deployment.

Portlet deployment descriptor

Edit portlet deployment descriptors.

For more information    See the section on portlet deployment descriptors.

The portlet container determines what preferences and values are presented to the user. At runtime, the portlet container searches from highest to lowest level for preference values, stopping at the level where it finds the first occurrence. For example, if the portlet container finds the target in page assignment preferences, it does not continue searching in registration or descriptor preferences.

Portlets are associated with a preferences object during these activities:

The portlet may read, modify and add preference attributes.

For more information    To learn how to get and store preferences at each level programmatically, see the section on getting and storing portlet preferences.

 
Top of section

Preference data types

Java Portlet 1.0 defines portlet preferences to be of type String. However, exteNd Director allows you to assign a variety of other data types to preferences. In addition, exteNd Director provides a default preference editor that displays a graphical user interface (GUI) for each supported data type. Each interface presents a graphical control that is appropriate for editing the value of the preference when you register a portlet or assign it to a page.

Here is a list of supported data types and their associated GUI controls:

Data type

GUI control

String

Text box

Integer

Text box

Password

Text box

Boolean

Radio button

Select

Dropdown list

Complex

Link to a custom preference editor

You assign data types to preferences by adding the <data-type> element to the preference descriptor in novell-portlet.xml or in the portlet fragment deployment descriptor, as described in Assigning data types to preferences.

For example, here are the preference descriptors in novell-portlet.xml for the Shortcut portlet, an accessory portlet that ships with exteNd Director:

  <portlet name="ShortcutPortlet">
         ...
          <portlet-preferences>
              <preference name="layout">
                  <data-type>Select</data-type>
                  <required>true</required>
                  <hide-from-user>false</hide-from-user>
                  <choice value="vertical" display-value="vertical" />
                  <choice value="horizontal" display-value="horizontal" />
              </preference>
              <preference name="links">
                  <data-type>Complex</data-type>
                  <required>true</required>
                  <config-portlet>ShortcutComplexPrefEditor</config-portlet>
              </preference>
          </portlet-preferences>
          ...
  </portlet>

As you can see, the Shortcut portlet defines two preferences:

The preference editor displays GUI controls for these preferences based on their data types:

pgComplexPrefsDataTypes

Note that the default preference editor displays a dropdown list for editing the layout preference of type Select and displays a link to a custom preference editor for the links preference of type Complex.

For more information    For more information, see Complex preferences.

 
Top of section

Complex preferences

A complex preference is a preference that has its own set of nested preferences—instead of just a single value. All complex preferences are of type Complex and most require a custom preference editor to provide the appropriate graphical user interface (GUI) for editing the nested preferences.

For example, the Shortcut portlet that ships with exteNd Director has a complex preference called links. You set this preference in a custom graphical editor that allows you to add one or more shortcut links, each with its own set of preferences.

Here is what the graphical editor looks like for the links preference:

pgComplexPrefsShortcutLinks

In this example, there are seven shortcut links defined for the links preference. Each shortcut link has its own set of preferences which can be displayed by expanding Details for the link.

In the next example, Details has been expanded to show the preferences you can edit for the first link, Novell Developer Kit:

pgComplexPrefsShortcutLinksExpanded

The interface for updating and validating the values for this complex preference is generated by a custom preference editor portlet, ShortcutComplexPrefEditorPortlet. The source code for this portlet is available in:

  Novell exteNd install directory\Director\templates\TemplateResources\accessory-portlets\accessory_portlets_src.jar\ShortcutComplexPrefEditorPortlet.java

For more information    For more information about writing complex preferences and custom editors, see Creating complex preferences and custom preference editors.

Getting and setting complex preference values

For preferences that are NOT of type Complex, you can get and set values by calling methods on the standard javax.portlet.PortletPreferences interface. However, these methods do not access the nested values associated with complex preferences.

 
Top of page

Portlet settings

Portlet settings govern how portlets should interact with the portal. Settings are defined by the portal and can be applied to portlet registrations and portlet page instances in the application.

For more information    For more information about portlet registrations and portlet page instances, see Portlet object model.

Standard settings   exteNd Director defines the following portlet settings:

These settings are defined by a portal administrator in the exteNd Director portlet deployment descriptor, novell-portlet.xml. They can also be modified by the administrator at the registration and page assignment levels.

Portal options   exteNd Director defines the following optional portal settings, also known as portal options:

Each portlet specifies which of these options it supports (if any) in the <supported-options> element, defined in novell-portlet.xml. For more information see the chapter on working with portal options.



Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved.  more ...