Portal Guide
CHAPTER 12
This chapter introduces basic portlet concepts and describes how exteNd Director implements portlets. It covers these topics:
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:
Add one or more portlets to a portal page, then display the page in a Web browser, as in this example:
In this example, an exteNd Director portal page displays the content of two portlets: My Bookmarks and Weather Service.
For more information, see the chapter on working with portal pages.
Run individual portlets directly in a Web browser. Here is an example of the Weather Service portlet running directly in a browser:
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.
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.
exteNd Director implements a hierarchical portlet object model, illustrated in the following diagram:
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 |
|
|
Shared pages |
|
|
Personal pages |
For information about assigning preferences at each level of the portlet object model, see Portlet preferences.
The exteNd Director implementation of Java Portlet 1.0 includes the following extensions, designed to offer more flexibility in developing and running portlets:
Design tools for developing specialized portlets called pageflows without the need for Java programming
See the chapter about pageflows.
An additional, optional portlet deployment descriptor—novell-portlet.xml—that allows you to specify a broader range of preferences and settings for portlets, such as title bars, automatic registration, and style sheets for portlets that generate XML.
See the section on portlet application deployment descriptors.
Ability to set and modify portlet preferences at design time—and after deployment at registration time, page assignment time, and runtime
See Portlet preferences.
Ability to style portlets that generate XML content
See the section on styling portlets that generate XML content.
Default implementation for Edit mode preference sheet
See the section on default implementation for Edit mode.
Ability to specify asynchronous versus synchronous processing at design time for individual portlets or all portlets in an application
See the section on synchronous versus asynchronous processing.
Dynamic loading of portlets using portlet fragment deployment descriptors
See the section on portlet application deployment descriptors.
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:
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:
Managing the portlet life cycle, as described in Portlet life cycle.
Establishing the portlet context, as described in Portlet context.
Providing persistent storage for portlet preferences, as described in Portlet preferences.
Responding to requests from the portal to execute on specific portlets, as described in Portlet requests and responses.
Portlets move through several stages from initial activation to final deactivation. These stages constitute the portlet life cycle, as shown in the following diagram:
Portlet containers in exteNd Director automatically manage the life cycles of portlets in your deployed portlet applications.
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.
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:
Resource bundles defined in the portlet deployment descriptor
Context object, which describes the portlet's runtime environment
exteNd Director provides several portlet deployment descriptors:
Descriptors for individual portlets in the portlet application resource set, required for dynamic loading of portlets, as described
For more information, see the section on portlet application deployment descriptors.
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.
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.
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.
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, 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:
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.
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.
The exteNd Director portal supports the standard window states defined in Java Portlet 1.0:
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.
The mode of a portlet indicates what activities the portlet should perform and what content it should generate.
exteNd Director supports the standard portlet modes specified by Java Portlet 1.0:
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.
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 about action and render requests. see Portlet requests and responses.
The portlet API allows you to include the following information in portlet URLs:
The portlet context provides information about the container in which each portlet is running. Through the context object, portlets can:
Set and store attributes that can be shared by other portlets and servlets in the portlet application
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 |
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.
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:
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.
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:
Changing mode (see Portlet modes)
Changing window state (see How portlets are rendered)
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.
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, 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, see How portlets are rendered and Portlet modes.
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.
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.
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.
|
|
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).
|
|
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.
|
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.
To learn how to get and store preferences at each level programmatically, see the section on getting and storing portlet preferences.
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:
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, see 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:
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:
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 about writing complex preferences and custom editors, see Creating complex preferences and custom preference editors.
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.
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 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 ...