Portal Guide
CHAPTER 7
This chapter explains how to use portal options to control the appearance of the controls in the title bar of a portlet. It contains the following sections:
A portal option is an image or text string that appears in the title bar of a portlet. Each portal option specifies a link that controls which action will be performed when the user clicks on the option. For example, a portlet title bar can provide buttons to allow the user to edit, minimize, or restore the portlet. Each button can have several images associated with it, so that the button image changes in response to user events.
Themes can alter the appearance of portal options. A theme can provide an image for each user event associated with a portal option, giving a consistent look when the user changes the theme.
Once you've defined a portal option, you can specify that this option is supported by a particular portlet.
exteNd Director ships with several predefined options:
|
Option |
Description |
|---|---|
|
Edit |
Displays a screen to edit portlet preferences. This option puts the portlet in Edit mode, if the doEdit() method is supported; otherwise, it displays the default portlet preference sheet. |
|
Help |
Provides additional information about the content |
|
Maximize |
Maximizes the portlet so it occupies the entire browser page |
|
Minimize |
Minimizes this content generated by the portlet, leaving only the title bar visible |
|
Remove |
Removes portlet content from the page. This option applies only to personal pages. |
|
Restart |
Restarts the current pageflow
|
|
Restore |
Restores a minimized or maximized portlet to its normal window state |
All of these options are defined in the portal_core_resource.jar.
You can also create your own custom options. To do this, you use the Portal Option Wizard in the exteNd Director development environment.
For details on using the Portal Option Wizard, see Creating Custom Options.
Each option in a portal application must provide each the following files:
|
File(s) |
Description |
|---|---|
|
Describes the option. This file provides the following information: The portal option descriptor file can have any name you like. |
|
|
Define images for the option. |
The portal option descriptor is stored in the portal-option directory within a resource set.
For more information about where files are located in a resource set, see the section on subdirectories for resources and Java classes in Developing exteNd Director Applications.
The link for a portal option can specify one or more of the following predefined portal URL query parameters:
Here are some examples of portal option links that illustrate how the various parameters are used:
The strings $COMPONENT_ID$ and $COMPONENT_INSTANCE_ID$ shown above are examples of portal replacement strings. Replacement strings allow you to include runtime, context-based information in a portal application. Replacement strings are keywords that reference things that can change dynamically at runtime, such as a user's current theme or the currently rendered component ID. When these keywords are detected at runtime, they are replaced based on information from the current HTTP request or the current portal context.
For more information about portal replacement strings, see Portal Replacement Strings.
Mode and window state influence the content generated by portlets. For example, a portlet in edit mode might generate a list of properties that allows a user to customize the portlet's behavior. In help mode, a portlet might display a brief explanation of the its features. To determine the current mode for a portlet, the portlet container calls getPortletMode() on the request object.
When a user interacts with a portlet, its window state may change. For example, when the user minimizes a portlet, the state changes to minimized, which indicates that the portlet's title bar should be displayed, but not its content.
Window states are defined as constants on the EbiPortalContext interface.
The portal option descriptor file provides several elements that describe the portal option. Each option used by a portal application must have a separate portal option file.
Each element in the portal option descriptor file is described below:
|
Element name |
Description |
|---|---|
|
portal-option |
The root node of the portal option |
|
display-name |
The name used to identify the option in the user interface of a portal application. This string can be localized. |
|
description |
The description of the option. This string can be localized. |
|
link |
The link associated with the option. The link can be a fully qualified or relative URL. It can also contain portal replacement strings. The link for a portal option can also use JavaScript. To use JavaScript in a link, start the link with: "javascript:"
|
|
link-target |
The target for the link. The target can specify the name of a frame, or specify one of the following standard values for the TARGET attribute of an HTML hyperlink: |
|
tool-tip |
The tip that appears when the user hovers over the link |
|
text |
Text for the link, if no image is provided for the normal event |
|
show-by-default |
Indicator that this option should show in the title bar by default even if the portlet does not include this option in its descriptor |
|
order |
Relative placement in the order of options from left to right. The smaller the integer the farther left it is positioned in the tool bar. If two options have the same order number, they are placed in random order. For example, if a particular portlet has 1,2,2, and 4 as the order numbers for its options, the option with number 1 is placed first and the one with the number 4 is placed last. The two options that have the number 2 are randomly placed between 1 and 4. |
|
images |
The set of images associated with a portal option. Each theme can supply a unique set of images for the various events associated with a portal option. These events map to JavaScript event handlers. The following event names can be specified for an image: The path to each image can be a fully qualified URL or an URL that contains portal replacement strings. For more information on portal replacement strings, see Portal Replacement Strings. |
|
hide-states |
One or more states in which this option should not be displayed. For example, when a portlet is maximized, you would typically want to hide the maximize option on the title bar. exteNd Director lets you specify any of the predefined portlet window states as hide-states. These states are: |
Here is an example of a descriptor file for a portal option called maximize:
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE portal-option PUBLIC "-//SilverStream Software, LLC//DTD Portal Option 5.0//EN" "portal-option_5_0.dtd"> <portal-option> <display-name>Maximize</display-name> <description>Maximizes the portlet, giving it the entire browser page</description> <link>?urlType=Render&wsrp-windowstate=maximized&novl-regid=$COMPONENT_ID$&novl-inst=$COMPONENT_INSTANCE_ID$</link> <link-target>_new</link-target> <tool-tip>Maximize this portlet</tool-tip> <text>Max</text> <show-by-default>true</show-by-default> <order>25</order> <images> <image event="normal">$THEME_URL$/images/maximize.gif</image> <image event="onmouseout">$THEME_URL$/images/maximize.gif</image> <image event="onmouseover">$THEME_URL$/images/maximize.gif</image> <image event="onmousedown">$THEME_URL$/images/maximize.gif</image> </images> <hide-states> <state>maximized</state> </hide-states> </portal-option>
Each theme can supply a unique set of images for the various events associated with a portal option. However, the file names for these images should be the same in each portal theme. By using a consistent naming convention across themes, you can ensure that each user event will have an image to display, regardless of which theme has been selected. For example, the Edit option associated with a portlet could have an image called edit_onmouseover.gif to handle the edit user event. In this case, each theme supported by the application would need to include a file with the same name. This would ensure that the onmouseover event always has an image to display for each theme.
To theme-enable a portal option, you need to use the $THEME_URL$ replacement string keyword in the path to each option image in the portal option descriptor file, as shown below:
<images> <image event="normal">$THEME_URL$/images/edit.gif</image> <image event="onmouseout">$THEME_URL$/images/edit_mouseout.gif</image> <image event="onmouseover">$THEME_URL$/images/edit_mouseover.gif</image> <image event="onmousedown">$THEME_URL$/images/edit_mousedown.gif</image> </images>
Each supported theme would provide a unique set of images with these names, as in this example for the BasicBlue theme:
...\portal-theme\ \BasicBlue theme.xml theme.css \images edit.gif edit_mousedown.gif edit_mouseout.gif edit_mouseover.gif ...etc.
Once you've defined a portal option, you can specify that this option is supported by a particular portlet. Portlet options are specified in novell-portlet.xml, the Novell extension to the portlet deployment descriptor.
A portlet can reuse the complete definition of one or more portal options simply by specifying the IDs for these options:
<portlet name="AppletLauncher"> <supported-option>edit</supported-option> <supported-option>help</supported-option> ... </portlet>
You can also specify options for portlets at registration time and
The exteNd Director API provides two interfaces for working with options:
EbiOptionManager provides methods for accessing EbiOptionInfo objects. EbiOptionInfo provides methods for retrieving various kinds of information about a portal option, including the property setting values specified in the portal option descriptor.
To access an EbiOptionManager object, you need to use the getOptionManager() method on the EboFactory class for the Portal subsystem.
Copyright © 2004 Novell, Inc. All rights reserved. Copyright © 1997, 1998, 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. more ...