| Oracle® Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal 10g Release 3 (10.3.2) Part Number E14244-04 |
|
|
View PDF |
| Oracle® Fusion Middleware Portlet Development Guide for Oracle WebLogic Portal 10g Release 3 (10.3.2) Part Number E14244-04 |
|
|
View PDF |
This chapter discusses features for developing and configuring portlets. This chapter contains the following sections:
Portlet properties are named attributes of the portlet that uniquely identify it and define its characteristics. Some properties—such as title, definition label, and content URI—are required; many optional properties allow you to enable specific functions for the portlet such as scrolling, presentation properties, pre-processing (such as for authorization) and multi-threaded rendering. The specific properties that you use for a portlet vary depending on your expected use for that portlet.
During the development phase of the portal life cycle, you generally edit portlet properties using the Oracle Enterprise Pack for Eclipse interface; this section describes properties that you can edit using Oracle Enterprise Pack for Eclipse.
During staging and production phases, you typically use the WebLogic Portal Administration Console to edit portlet properties; only a subset of properties are editable at that point. For instructions on editing portlet properties from the WebLogic Portal Administration Console, refer to Section 17.2.2, "Modifying Library Portlet Properties" and Section 17.2.3, "Modifying Desktop Portlet Properties."
For a detailed description of all portlet properties, refer to Section 9.1.3, "Portlet Properties in the Portal Properties View" and Section 9.1.4, "Portlet Properties in the Portlet Properties View."
This section contains the following topics:
Section 9.1.3, "Portlet Properties in the Portal Properties View"
Section 9.1.4, "Portlet Properties in the Portlet Properties View"
To edit portlet properties, follow these steps:
Navigate to the location of the portlet whose properties you want to edit, and double-click the .portlet file to open it in the workbench editor.
Click the border of the desired portlet component to display the properties for that component in the Properties view.
The displayed properties vary according to the active area that you select. If you click the outer border, properties for the entire portlet appear; if you click the inner border, properties for the content of the portlet appear, and so on.
Navigate to the Properties view to view the current values for the portlet properties. Figure 9-1 shows a segment of a JSP portlet's Properties view:
Figure 9-1 Editing Portlet Properties - JSP Portlet Properties View Example
Double-click the field that you want to change.
If you click on a property field, a description of that field displays in the status bar.
Values for some portlet properties are not editable after you create the portlet.
In some cases, from the property field you can view associated information pertaining to that portlet property; for example, the Java portlet Class Name property contains a read-only value with an Open button to view the associated Java file. For more information about options available in the Properties view, refer to Section 9.1.2, "Tips for Using the Properties View."
The behavior of the Properties view varies depending on the type of field you are editing. The following tips might help you as you manipulate the content of the data fields in the Properties view.
If a file is associated with a portlet property, the Properties view includes an Open button in addition to a Browse button; you can click Open to display the appropriate Eclipse editor/view for the file type.
If you want to edit the XML source for a portlet, you can right-click the .portlet file in the Package Explorer view and choose Edit with > XML Editor to open the file using the basic XML editor that Eclipse provides.
Caution:
The Eclipse XML editor has limited validation capabilities. Oracle recommends the use of a robust validation tool to ensure that your hand-edited XML is valid.The book, page, and portlet actions in the palette display properties in the Properties view when you select them in the palette. The cell editor for the content file property is read only, and includes an Open button; clicking Open displays the Eclipse editor/view for the applicable file type.
For page flow portlets, a property editor is available for page flow content paths when displaying a page flow portlet in the editor. The property editor is a dialog cell editor that allows you to type in the URI of the page flow directly, or you can click the ellipses button to launch the page flow class picker dialog. If you open the dialog, the page flow class name is converted to a URI when you leave the dialog. WebLogic Portal stores the URI in the .portlet file when you save the portlet. The property editor validates the page flow URI specified and warns you if you choose a URI that has no corresponding page flow class. You can choose to proceed anyway and store an invalid URI; you should create a valid class later so that the portlet works correctly.
For page flow portlets, while in the portlet editor you can double-click the portlet content view to launch the corresponding Java element specified in the portlet content path. This consists of the page flow source if the source is available in the project or attached to the JAR containing the class. If the source cannot be located, then the disassembled class browser is displayed showing the contents of the class.
Due to a limitation in Eclipse, some long property descriptions are truncated in the Status bar. To display the entire description, while the property is highlighted click the Show Property Description button in the menu. A popup window displays the full text of the property's description. Click outside the window to close it.
Note:
Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.The properties described in this section are contained within the .portal file and are editable using Oracle Enterprise Pack for Eclipse. The values you enter here override the corresponding value in the .portlet file, if a value exists there.
To display the portlet properties that display in the Properties view for a portal, follow these steps:
Note:
These steps assume that you have an existing portal that contains portlets.Double-click the .portal file of the portal for which you want to view portlet instance properties.
A WYSIWYG view of the portal appears in the editor.
Click a portlet to highlight it.
An orange border appears around the outside edge of the portlet.
The Properties view displays the properties of the portlet instance; Figure 9-2 shows an example.
Figure 9-2 Portlet Instance Properties in the Portal Properties View
Table 9-1 describes these properties and their values.
Table 9-1 Portlet Instance Properties in the Properties View
| Property | Value |
|---|---|
|
Default Minimized |
Optional. Select |
|
Instance Label |
Required. A single portlet, represented by a |
|
Orientation |
Optional. Hint to the skeleton to position the portlet title bar on the top, bottom, left, or right side of the portlet. You must build your own skeleton to support this property. The allowable values are: default, top=0, left,=1 right=2, bottom=3. Enter a value for this property only if you want to override the orientation specified in the |
|
Portlet URI |
Required. The path (relative to the project) of the parent |
|
Theme |
Optional. Select a theme to give the portlet a different Look & Feel than the rest of the desktop. |
|
Title |
Enter a title if you want to override the default title specified in the |
The properties described in this section are contained within the .portlet file and are editable using Oracle Enterprise Pack for Eclipse. The values you enter here override the corresponding value in the .portlet file, if a value exists there.
When you select the outer border of a portlet in the portlet editor, a related set of properties appears in the Properties view. The displayed properties vary according to the type of portlet that you are viewing. Figure 9-3 shows a portion of the Properties view for a portlet.
Figure 9-3 Properties View Example Showing Portlet Properties
Table 9-2 describes these properties and their values.
Table 9-2 Properties in the Portlet Properties View
| Property | Value |
|---|---|
|
Portlet Backing File |
Optional. If you want to use a class for preprocessing (for example, authentication) prior to rendering the portlet, enter the fully qualified name of that class. That class should implement the interface com.bea.netuix.servlets.controls.content.backing.JspBacking or extend com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking. From the data field you can choose to browse to a class or open the currently displayed class. |
|
Singleton Backing Instance |
Optional. Performance setting for books, pages, and portlets that use backing files. When Singleton Backing Instance is set to When Singleton Backing Instance is set to |
|
Content Path |
Required. The path (relative to the project) to the file/class to be used for the portlet's content. From the data field you can choose to browse to a file (or class for page flow portlets) or open the currently displayed file/class. For example, if the content is stored in |
|
Error Page Path |
Optional. The path (relative to the project) to the JSP or HTML file to be used for the portlet's error message if the main content cannot be rendered. For example, if the error page is stored in |
|
Async Content Rendering |
Allows you to specify whether to use asynchronous content for a given portlet and the implementation to use. An editable dropdown menu provides the selections For more information, refer to Section 10.5, "Asynchronous Portlet Content Rendering." Note: The Tip: You can also enable asynchronous rendering for an entire portal desktop by setting a portal property in either Oracle Enterprise Pack for Eclipse or the WebLogic Portal Administration Console. For more information on asynchronous desktop rendering, see the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Cache Expires (seconds) |
Optional. When the |
|
Cache Render Dependencies |
This instance-scoped boolean property appears in the Properties view whenever a window portlet or proxy portlet is loaded, allowing render dependencies to be cached. See also Section 9.5.1, "Portlet Dependencies." The value defaults to This property does not affect requests targeted to the portlet. |
|
Client Classifications |
Optional. Select the multichannel devices on which the portlet can be viewed. The list of displayed devices is obtained from the file In the Manage Portlet Classifications dialog: Select whether you want to enable or disable classifications for the portlet. Move the client classifications you want to enable or disable from the Available Classifications to the Selected Classifications. Click OK. When you disable classifications for a portlet, the portlet is automatically enabled for the classifications that you did not select for disabling. |
|
Default Minimized |
Required. Select |
|
Definition Label |
Required. Each portlet must have a unique value within the web project. For Java portlets, you type the desired value when creating the portlet; for the remaining portlet types, a value is generated automatically when you create the portlet. Definition labels can be used to navigate to portlets. Also, components must have Definition Labels for entitlements and delegated administration. As a best practice, you should edit this value in Oracle Enterprise Pack for Eclipse to create a meaningful value. This is especially true when offering portlets remotely, as it makes it easier to identify them from the producer list. |
|
Description |
Optional. A short text description of the portlet. The description is displayed in the Administration Console and Visitor Tools areas, and is sent from a WSRP producer where applicable. |
|
Event Handlers |
Optional. Use this value to configure interportlet communication using portlet events. The default is |
|
Forkable |
For details on this property, refer to Section 10.4, "Portlet Forking." |
|
Fork Pre-Render |
For details on this property, refer to Section 10.4, "Portlet Forking." |
|
Fork Pre-RenderTimeout (seconds) |
For details on this property, refer to Section 10.4, "Portlet Forking." |
|
Fork Render |
For details on this property, refer to Section 10.4, "Portlet Forking." |
|
Fork Render Timeout (seconds) |
For details on this property, refer to Section 10.4, "Portlet Forking." |
|
Orientation |
Optional. Hint to the skeleton to position the portlet title bar on the top, bottom, left, or right side of the portlet. You must build your own skeleton to support this property in the You can override the orientation in each instance of the portlet (in the Properties view). |
|
Packed |
Optional. Rendering hint that can be used by the skeleton to render the portlet in either expanded or packed mode. You must build your own skeleton to support this property. When packed="false" (the default), the portlet takes up as much horizontal space as it can. When packed="true," the portlet takes up as little horizontal space as possible. From an HTML perspective, this property is most useful when the window is rendered using a table. When packed="false," the table's relative width would likely be set to "100%." When packed="true," the table width would likely remain unset. |
|
Render Cacheable |
Optional. To enhance performance, set to Do not set this to true if you are doing your own caching. For more information, refer to Section 10.2, "Portlet Caching." |
|
Render Dependencies Path |
Optional. Lets you specify the path to a render dependency file (also called a portlet dependency file). Render dependencies are resources that are required for rendering a portlet. For details, see Section 9.5.1, "Portlet Dependencies." |
|
Shared Parameters |
Optional. Portlet shared parameters are similar to JSR 286-based public render parameters. The primary difference is that shared public render parameters handle complex data types while shared parameters only handle String data. For details, see Section 9.3, "Using Shared Parameters." |
|
Required User Properties Mode |
For remote portlets only. Optional. Possible values are |
|
Required User Properties Names |
For remote portlets only. Optional. Use this field if you entered a value of |
|
Title |
Required. Enter the title for the portlet's title bar. You can override this title in each instance of the portlet (in the portal editor, as described in Section 9.1.3, "Portlet Properties in the Portal Properties View"). |
|
Page Flow Action |
Optional. The initial action to be executed in a page flow. If not specified, the Note: Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Page Flow Refresh Action |
Optional. The action to be executed in the page flow when the page is refreshed but the portlet is not targeted. This is equivalent to using portlet event handlers configured on the |
|
Request Attribute Persistence |
Optional. Possible values are JPF or Struts portlets that have the Portlets that have the Note: Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. Apache Struts is also an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Faces Events |
(Optional) Lets you add name/action pairs to a JSF portlet. The name field is simply an alias. Event handlers (and the Event Handler dialog) can simply reference this name. The action is a reference to a JSF view ID, such as |
|
Content Presentation Class |
A CSS class that overrides any default CSS class used by the component's skeleton. For proper rendering, the class must exist in a cascading style sheet (CSS) file in the Look and Feel's selected skin, and the skin's skin.xml file must reference the CSS file. Sample: If you enter "my-custom-class", the rendered HTML from the default skeletons looks like this: <div class="my-custom-class"> The properties you enter are added to the component's parent <div> tag. This property also applies to books and pages. For more information, refer to the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Content Presentation Style |
Optional. The primary uses are to allow content scrolling and content height-setting. For scrolling, enter the following attributes: overflow:auto – Enables vertical and horizontal scrolling For setting height, enter the following attribute: height:200px where 200px is any valid HTML height setting. You can also set other style properties for the content as you would using the Presentation Style property. The properties are applied to the component's content/child <div> tag. |
|
Offer as Remote |
Optional. Defines whether the portlet is accessible using the WSRP producer. The default is |
|
Content Backing File |
Optional. If you want to use a backing file for content prior to rendering the portlet, enter the fully qualified name of the appropriate class. That class should implement the interface com.bea.netuix.servlets.controls.content.backing.JspBacking or extend com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking. |
|
Can Delete |
Optional. If set to |
|
Can Float |
Optional. If set to |
|
Can Maximize |
Optional. If set to |
|
Can Minimize |
Optional. If set to |
|
Edit Path |
Optional. The path (relative to the project) to the portlet's edit page. |
|
Help Path |
Optional. The path (relative to the project) to the portlet's help file. |
|
Icon Path |
Optional. The path (relative to the project) to the graphic to be used in the portlet title bar. You must create a skeleton to support this property. |
|
Content Path |
Required. The path (relative to the project) to the JSP, HTML, or Although a Browse button appears for this property, if you want to point to a page flow you must manually enter the path to the |
|
Error Path |
Optional. The path (relative to the project) to the JSP, HTML, or Although a Browse button appears for this property, if you want to point to a page flow you must manually enter the path to the |
|
Visible |
Optional. Makes the mode icon (such as the edit icon) in the title bar or menu invisible ( |
|
Name |
Optional. Displayed when you select an individual mode. An optional name for the mode, such as |
|
Presentation Class |
This property is described in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Presentation ID |
This property is described in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Presentation Style |
This property is described in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Properties |
Optional. A comma-delimited list of name-value pairs to associate with the object. This information can be used by skeletons to affect rendering. |
|
Skeleton URI |
This property is described in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Connection Establishment Timeout |
Optional. The number of milliseconds after which this portlet will time out when establishing an initial connection with its producer. |
|
Connection Timeout |
Optional. The number of milliseconds after which this portlet will time out when communicating with its producer, after the physical connection has been established. If not specified here, the default value contained in the file |
|
Group ID |
Optional. This value is assigned by the producer and is not editable. Portlets with the same Group ID from the same producer can share sessions. The Group ID value is meaningful only to the producer and not manipulated by WebLogic Portal. |
|
Invoke Render Dependencies |
This boolean property allows the consumer to obtain render dependencies from the producer during the pre-render life cycle of a proxy portlet. When a portlet on a producer has a Note: Provide an absolute path for the The value defaults to |
|
Portlet Handle |
Required. The producer's unique identifier for the portlet that this proxy references. The value is not editable. |
|
Producer Handle |
Required. The producer's unique identifier. |
|
Templates Stored in Session |
Indicates whether the producer stores URL templates in the user's session on the producer side. This boolean is meaningful only when URL Template Processing boolean is set to |
|
URL Template Processing |
Indicates whether the producer uses URL templates to create URLs. If true, the consumer supplies URL templates. If false, the producer rewrites URLs using special rewrite tokens. |
|
User Context Stored In Session |
Required. The purpose of this value is to cut down on network traffic by sending the user's context (including the profile) only once per session. For WebLogic Portal producers it will always be This boolean value defaults to The value is read-only, and is initialized from the producer whenever a proxy portlet is generated from the portlet wizard. |
|
Listen To |
(Deprecated) Allows this portlet to invoke an action when another portlet invokes the same action. This functionality has been replaced with the more complete interportlet communication mechanism. For more information on interportlet communication, refer to Chapter 12, "Configuring Local Interportlet Communication." |
|
Struts Action |
The begin action that this struts portlet should invoke on the first request to the portlet. Note: Apache Struts is also an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Struts Module |
The struts module that is associated with this struts portlet. A "struts module" is a means of scoping a particular set of struts actions to a group called a module, which generally maps to a single subdirectory of web resources and a separate |
|
Struts Refresh Action |
Optional. The action to be performed in the struts module when the page is refreshed but the portlet itself is not targeted. |
|
Content Url |
Required. The content control takes a URI that is expected to be a URL for a standalone application or web page, and embeds the URL as portlet content. |
Portlet preferences provide the primary means of associating application data with portlets. This feature is key to personalizing portlets based on their usage. This section describes portlet preferences in detail.
After you create a portlet, you can instantiate it several times. Because you can create several instances of a portlet, it is natural to expect each instance to behave differently yet use the same code and user interface. For instance, consider a typical portlet to display a Stock Portfolio. Given a list of stock symbols, this portlet retrieves quotes from a stock quote web service periodically, and displays the quotes in the portlet window. By letting each user change the list of stock symbols and a time interval to reload the quote data, you can let each user customize this portlet.
The portlet needs to be able to store the list of stock symbols and the retrieval interval persistently, and update these values whenever a user customizes these values. In particular, the following data must be persistently managed:
Default Values – Your portlet may specify a default list of stock symbols and a reasonable retrieval interval. These values are applicable to all usages of the portlet no matter who the user is. The user could even be anonymous.
Customized Values – Your portlet also needs to be able to store these values when a user updates the values for a given portlet instance. Note that your portlet should also scope this data to an instance, such that other instances of this portlet are not affected by this customization.
Technically, a portlet preference is a named piece of string data. For example, a Stock Portfolio portlet could have the following portlet preferences:
A preference with name "stockSymbols" and value "ORCL, MSFT"
Another preference with name "refreshInterval" and value "600" (in seconds).
You can associate several such preferences with a portlet. WebLogic Portal provides the following means to manage portlet preferences:
Specify portlet preferences during the development phase
When you are building a portlet using the Oracle Enterprise Pack for Eclipse workbench, you can specify the names and default values of preferences for each portlet. All portlet instances derived from this portlet will, by default, assume the values specified during development.
Let administrators modify portlet preferences
WebLogic Portal allows portal administrators to modify preferences for a given portlet instance.This task occurs during the staging phase and uses the WebLogic Portal Administration Console.
Let portlets access and modify preferences at request time
At request time, your portlets can programmatically access and update preferences using a javax.portlet.PortletPreferences object. You can create an edit page for your portlet to let users update preferences, or you can automatically update preferences as part of your normal portlet application flow.
This section contains the following topics:
Section 9.2.2, "Using the Preferences API to Access or Modify Preferences"
Section 9.2.4, "Best Practices in Using Portlet Preferences"
The steps to associate preferences with a portlet depend on the type of portlet you are building. If you are using the Java Portlet API, described in Section 9.2.2.3, "Getting and Setting Preferences for Java Portlets Using the Preferences API," the steps follow those specified in the Java Portlet Specification. For other kinds of portlets, you can use the Oracle Enterprise Pack for Eclipse workbench to add preferences to a portlet.
You can also allow the administrator to create new preferences using the Administration Console. However, because the portlet developer is more likely to be aware of how portlet preferences are used by the portlet, it is generally better to create portlet preferences during the development phase.
For portlets using Java Portlet API, you can specify preferences in the portlet deployment descriptor according to the specification. For all portlets in a web project, the deployment descriptor is portlet.xml, found in the WEB-INF directory of the web project. Example 9-1 provides an example.
Example 9-1 Specifying Portlet Preferences in portlet.xml with a Single Value
<portlet>
<description>This portlet displays a stock portfolio.</description>
<portlet-name>portfolioPortlet</portlet-name>
<portlet-class>portlets.stock.PortfolioPortlet </portlet-class>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>edit</portlet-mode>
</supports>
<portlet-info>
<title>My Portfolio</title>
</portlet-info>
<portlet-preferences>
<preference>
<name>stockSymbols</name>
<value>ORCL, MSFT</value>
</preference>
<preference>
<name>refreshInterval</name>
<value>600</value>
</preference>
</portlet-preferences>
</portlet>
This snippet deploys the portfolio portlet with two preferences: a preference with name stockSymbols and value ORCL, MSFT, and another preference refreshInterval with value 600.
Instead of specifying a single value for the stockSymbols preference, you can declare each symbol as a separate value as shown in Example 9-2 below, with the value elements shown in bold.
Example 9-2 Specifying Portlet Preferences with Values Specified Separately
<portlet>
<description>
This portlet displays a stock portfolio.
</description>
<portlet-name>portfolioPortlet</portlet-name>
<portlet-class>portlets.stock.PortfolioPortlet </portlet-class>
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>edit</portlet-mode>
</supports>
<portlet-info>
<title>My Portfolio</title>
</portlet-info>
<portlet-preferences>
<preference>
<name>stockSymbols</name>
<value>ORCL</value>
<value>MSFT</value>
</preference>
<preference>
<name>refreshInterval</name>
<value>600</value>
</preference>
/portlet-preferences>
</portlet>
If you prefer that portlets should not be allowed to programmatically update any given preference, you can mark the preference as read-only. Example 9-3 shows an example of preventing a portlet from changing the refreshInterval.
Example 9-3 Specifying a Read-Only Portlet Preference Value
<portlet>
<description>
This portlet displays a stock portfolio.
</description>
<portlet-name>portfolioPortlet
<portlet-class>portlets.stock.PortfolioPortlet
<supports>
<mime-type>text/html</mime-type>
<portlet-mode>edit</portlet-mode>
</supports>
<portlet-info>
<title>My Portfolio</title>
</portlet-info>
<portlet-preferences>
<preference>
<name>stockSymbols</name>
<value>ORCL</value>
<value>MSFT</value>
/preference>
<preference>
<name>refreshInterval</name>
<value>600</value>
<read-only>true</read-only>
</preference>
</portlet-preferences>
</portlet>
Note that by marking a preference read-only, you are preventing the portlet from changing the current value only at request time. Portal administrators can always change the value(s) of a preference using the Administration Console.
If you are building other kinds of portlets besides Java portlets, you can add preferences using Oracle Enterprise Pack for Eclipse.
To add a preference, follow these steps:
Click to select the portlet for which you want to add a preference.
In the Outline view for the portlet, right-click Preferences and in the context menu click Add Preference. Figure 9-4 shows an example of the preferences context menu.
Figure 9-4 Portlet Preferences Context Menu
A new preference is added to the tree hierarchy with the name New Preference Preference.
Click the new item to display its properties in the Properties view.
Edit the values in the Properties view. Figure 9-5 shows an example of the fields in the Properties view.
Figure 9-5 Portlet Preferences Properties View
Table 9-3 describes the attributes for portlet preferences as shown in the Properties view.
Table 9-3 Portlet Preference Properties
| Field | Value |
|---|---|
|
Modifiable |
Indicates whether the preference is read-only or can be modified by the user. The default is |
|
Multi Valued |
Indicates whether the preference can have multiple values. The default is To specify multiple values for a preference, create multiple preferences with the same name. |
|
Description |
A brief description of the preference. |
|
Name |
Name of the preference. |
|
Value |
Each preference can have one or more values. Each value is of type java.lang.String. |
By default, changes to portlet preferences made in a .portlet or portlet.xml are not propagated to the WebLogic Portal Administration Console. For example, if you change the name of a preference in a .portlet file and republish the portlet, the name change does not appear in the Administration Console. Instead, the renamed preference appears in the Administration Console as a new preference. For example, if you change the name of preference Pref_1 to Pref_2 in a .portlet and republish the portlet, in the Administration Console you will not see this name change; instead, you will see two separate preferences show up: Pref_1 and Pref_2.
To change this default behavior, add the following sub-element to the customization element of the netuix-config.xml file in your portal web application:
<propagate-preferences-on-deploy propagate-to-instances="true" master="file"/>
For example:
<customization>
<enable>true</enable>
<exclude-dir dir="/portlets_excluded" />
<propagate-preferences-on-deploy propagate-to-instances="true" master="file"/>
</customization>
With this setting, changes you make to a portlet preference in a .portal or portlet.xml file will be propagated to the Administration Console. Changes made to the attributes Name, Modifiable, Multi-valued, and Value are propagated.
At request time, portlet preferences for a given portlet are represented as instances of the javax.portlet.PortletPreferences interface. This interface is part of the Java Portlet API. This interface specifies methods to access and modify portlet preferences.
Table 9-4 describes methods that allow a portlet to access its preferences.
Table 9-4 Methods that Allow a Portlet to Access its Preference Values
| Method | Purpose |
|---|---|
|
String getValue(String name, String default) |
Use this method to get the first value of a preference. |
|
String[] getValues(String name, String[] defaults) |
Use this method to get all the values of a preference. |
|
boolean isReadOnly(String name) |
Use this method to determine whether a given preference is read-only. |
|
Enumeration getNames() |
Use this method to get an enumeration of the names of all preferences. |
|
Map getMap() |
Use this method to get a map of preferences. The keys in this map are the names of all the preferences, and the values are the same as those returned by getValues(String name, String[] defaults) |
Table 9-5 describes methods that allow a portlet to change preference values.
Table 9-5 Methods that Allow a Portlet to Change Preference Values
| Method | Purpose |
|---|---|
|
void setValue(String name, String value) |
Use this method to set the value of a preference |
|
void setValues(String name, String[] values) |
Use this method to set several values for a preference |
|
void store() |
Use this method to commit the changes made to preferences for a portlet. |
|
void reset(String name) |
Use this method to reset the value of a preference to its default, or remove the preference if there is no default |
After modifying preferences by calling setValue(), setValues() and reset() methods, you must call store() explicitly to make the changes permanent; otherwise, changes will not be made permanent.
For portlets written using the Java Portlet API, you can obtain an instance of javax.portlet.PortletPreferences object from the incoming portlet request – javax.portlet.RenderRequest within the processAction() method, or javax.portlet.ActionRequest within the render() method.
In Example 9-4, the portlet displays a form to edit the current values of portlet preferences in a JSP page included from the doEdit() method of the portfolio portlet.
Example 9-4 Portlet Displays a Form to Edit Preferences
<%@ taglib uri="http://java.sun.com/portlet" prefix="portlet"%>
<%@ page import="javax.portlet.PortletPreferences" %>
<portlet:defineObjects/>
<%
PortletPreferences prefs = renderRequest.getPreferences();
String refreshInterval = prefs.getValue("refreshInterval", "600");
String symbols = prefs.getValue("stockSymbols", "ORCL, MSFT");
%>
<form method="POST" action="">
<table>
<tr>
<td>Symbols</td><td><input name="symbols"
value="<%=symbols>"/></td>
</tr>
<tr>
<td>Refresh Interval</td><td><input name="refreshInterval"
value="<%=refreshInterval>"/></td>
</tr>
<tr>
<td></td>
<td><input type="submit" value="Submit"/></td>
</tr>
</table>
</form>
The portlet updates the preferences in its processAction() method, as shown in Example 9-5.
Example 9-5 Portlet Updates the Preferences in the processAction() Method
public class PortfolioPortlet extends GenericPortlet
{
{
public void doEdit(RenderRequest renderRequest, RenderResponse
renderResponse)
throws IOException, PortletException
{
...
}
public void processAction(ActionRequest actionRequest, ActionResponse
actionResponse)
throws PortletException
{
String refreshInterval =
actionRequest.getParameter("refreshInterval");
String symbols = actionRequest.getParameter("stockSymbols");
PortletPreferences prefs = actionRequest.getPreferences();
prefs.setValue("refreshInterval", refreshInterval);
prefs.setValue("stockSymbols", symbols);
try
{
prefs.store();
}
catch(SecurityException se) {
// Thrown when the user does not have enough privileges to store
// preferences. Make sure that the user logged into the portal.
...
}
catch(catch(IOException ioe) {
// There is an error storing preferences
...
}
}
}
During processAction(), this portlet uses the javax.portlet.ActionRequest object to obtain preferences.
Portlet preferences can be accessed and updated from other kinds of portlets too. The main difference is in the way your portlets obtain an instance of the javax.portlet.PortletPreferences object.
Before rendering, portlets can use com.bea.netuix.servlets.controls.portlet.PortletBackingContext to obtain portlet preferences; for example, in a page flow action, or in the handlePostbackData() method of the backing file associated with the portlet.
During the render phase portlets can use com.bea.netuix.servlets.controls.portlet.PortletPresentationContext to obtain portlet preferences; for example, in a JSP associated with a page flow.
Both these classes provide a method getPortletPreferences(HttpServletRequest req) that takes javax.servlet.HttpServletRequest as an argument and return an object of type javax.portlet.PortletPreferences. For more information, see Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal .
Note:
Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.WebLogic Portal provides a JSP tag library for setting up portlet preferences. Table 9-6 describes the applicable JSP tags.
Table 9-6 JSP Tags for Getting Portlet Preferences
| Method | Purpose |
|---|---|
|
getPreference |
Use this tag to get the value of a portlet preference. |
|
getPreferences |
Use this tag to get all the values of a portlet preference. This tag can also used to write multiple values to the output separated by a separator. |
|
forEachPreference |
Use this tag to iterate through all the preferences of a portlet. You can nest other tags (getPreference, getPreferences, ifModifiable and Else) inside this tag. |
|
ifModifible |
Use this tag to include the body of this tag if the given portlet preference is not read-only. |
|
else |
Use this tag in conjunction with the ifModifiable tag to include the body of this tag if the given portlet preference is read-only |
For more information on the Java classes associated with these tags, refer to the Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal
In WebLogic Portal, the framework includes a default implementation that manages portlet preferences in the built-in PF_PORTLET_PREFERENCE and PF_PORTLET_PREFERENCE_VALUE database tables. If desired, you can replace this implementation with your own.
You can use the Portlet Preferences SPI to allow portal applications to manage portlet preferences outside framework-managed database tables. For example, you can store preferences along with other application data in another back-end system or a different set of database tables.
When propagating a portal, the preferences SPI participates in the propagation process. When you exporting data for the propagation, the SPI is called to obtain the preferences, and when you are importing data, the SPI is called to store the preferences.
The following sections describe how to use the Portlet Preferences SPI.
You specify the SPI using the interface com.bea.portlet.prefs.IPreferenceAppStore. An implementation of this class must be deployed as a EJB jar file.
Example 9-6 provides an example.
Example 9-6 Implementing the SPI Using the Interface IPreferencesAppStore
public interface IPreferenceAppStore extends EJBObject
{
/**
* Returns preferences for a portlet entity with the given uniqueId.
*
* The returned java.util.Map contains
* com.bea.netuix.application.prefs.Preference
* objects keyed against their names.</p>
*
* @param uniqueId unique ID
* @return preferences
*/
public Map getPreferences(PortletPreferencesId uniqueId) throws
RemoteException, PreferenceAppStoreException;
/**
* Writes the preferences to the underlying persistence.
*
* This method should be implemented to be atomic. That is, the
* implemenation should guarantee that either all preference
* values are persisted or none at all.
*
* The java.util.Map argument should contain
* com.bea.netuix.application.prefs.Preference
* objects keyed against their names.
*
* @param uniqueId unique ID
* @param preferences preferences
*/
public void storePreferences(PortletPreferencesId uniqueId,
Map preferences) throws RemoteException, PreferenceAppStoreException;
/**
* Clear all preferences for the given unique ID from the
* underlying persistence store.
*
* @param uniqueIds unique IDs
*/
public void removePreferences(PortletPreferencesId[] uniqueIds) throws
RemoteException, PreferenceAppStoreException;
}
To cause the framework to use a new SPI in place of the default SPI, you must update the EJB named PreferencePersistenceManager in the ejb-jar.xml file within netuix.jar. The value BEA_netuix.DefaultStore must be changed to the name of the SPI EJB as specified in its deployment descriptor (ejb-jar.xml). The value com.bea.portlet.prefs.provider.DefaultStoreHome must be changed to the home interface of the SPI implementation.
Caution:
To edit the ejb-jar.xml file you need to copy the J2EE library resources into your project. Keep in mind that with future updates to the WebLogic Portal product, you might have to perform manual steps in order to incorporate product changes that affect those resources.The code segment in Example 9-7 shows the default entries, which you must change to use the SPI.
Example 9-7 Example Code Showing Default Entries that Must be Changed
<session>
<ejb-name>PreferencePersistenceManager</ejb-name>
<home>com.bea.portlet.prefs.PreferencePersistenceManagerHome</home>
<remote>com.bea.portlet.prefs.PreferencePersistenceManager</remote>
<ejb-class>com.bea.portlet.prefs.PreferencePersistenceManagerImpl
</ejb-class>
<session-type>Stateless</session-type>
<transaction-type>Container</transaction-type>
<env-entry>
<env-entry-name>prefs-spi-jndi-name</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>BEA_netuix.DefaultStore</env-entry-value>
</env-entry>
<env-entry>
<env-entry-name>prefs-spi-home-class-name</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>com.bea.portlet.prefs.provider.DefaultStoreHome
</env-entry-value>
</env-entry>
<!-- Snip -->
</session>
This section discusses best practices in using portlet preferences.
In order to view and test the preferences that you have created, you must use a desktop view from the WebLogic Portal Administration Console rather than Oracle Enterprise Pack for Eclipse's Open on Server view.
Portlets accessed from .portal files cannot store preferences. If you update a preference using a .portal file, your portlet encounters a java.lang.UnsupportedOperationException error.
You must provide a means for users to log in before they can update preferences; users who are updating portlet preferences must first be authenticated. If an anonymous user attempts to update a portlet, a java.lang.SecurityException error occurs.
Note that portlets can always get portlet preferences whether or not the user is anonymous or whether the portlet is accessed via a .portal file.
It is tempting to store arbitrary application data as portlet preferences. For example, if you have a portlet that allows users to upload and store documents on the server, it might seem appropriate to store those documents as portlet preferences. This is not a good practice. The purpose of portlet preferences is to associate some properties for a portlet instance without having to be aware of any implementation-specific portlet instance IDs. These properties allow customization of the portlet's behavior. The underlying implementation of portlet preferences is not designed for storing arbitrary application data.
The following steps outline an alternative implementation that can meet the needs of the portlet:
Perform setup steps:
Add a preference to your portlet. This preference acts as the primary key to your portlet's application data. Assign a default value for this preference.
Create tables in your database to store application data with the value of the preference as the primary key.
Set up preferences in your portlet:
When you want to associate application data with the current portlet instance, check the value of the preference. If the value is the default, generate a new value (for example, using a sequence number generator), and set this as the value of the preference, and store the preference.
If the value of the preference is not the default, you do not need to generate a new value.
Store your application data using the value of the preference as the primary key.
This procedure ensures that your application data is always scoped to portlet instances.
The portal framework maintains instance identity using internally generated instance IDs. Portlets can access their instance IDs using getInstanceId() methods on com.bea.netuix.servlets.controls.portlet.PortletPresentationContext and com.bea.netuix.servlets.controls.portlet.PortletBackingContext.
Storing data directly in the database using portlet instance IDs does not work, for the following reasons:
The portal framework generates instance IDs, and portlets have no control over when and how those instance IDs are generated.
Instance IDs might change at any time without the portlet's knowledge. For example, as the user or administrator customizes a desktop using Visitor Tools or the Administration Console, the framework can create new instances or change the instance ID of a portlet. If the instance ID changes, your portlet cannot load the data from your database; the primary key has changed without your portlet being aware of it.
Shared parameters permit portlets to share parameter values with other portlets, allowing a simple form of interportlet communication. For instance, if portlet A and portlet B are both configured to use a particular shared parameter, any changes in the parameter's value made by portlet A will be seen by portlet B.
Note:
Shared parameters provide the same functionality as, and interoperability with, JSR 286 portlet public render parameters (see also Section 6.8, "Public Render Parameters"). Shared parameters have the same semantics as JSR 286 public render parameters.Shared parameters can only contain string values. Like HTTP parameters, shared parameter can have zero or more values. A shared parameter value remains unchanged until the portlet (or another portlet) explicitly changes it. The values of shared parameters can be shared within a single portlet application or across multiple portlet applications. For instance, if Portlet A sets a shared parameter, Portlet B can read the value of that parameter, if both portlets are properly configured.
You can set shared parameter values during the handlePostback and event-handling portlet life cycles. You can also set shared parameters on a portlet postback URL.
To set the value of a shared parameter, the portlet must use the PortletBackingContext.setSharedParameterValue() or PortletBackingContext.setSharedParameterValues() methods during handlePostback or event-handling, or you can set a value for the parameter on any postback URL. If the value is set using the PortletBackingContext methods, the change in value will take effect immediately, and all other portlets using the same shared parameter will see the new value. If set on a postback URL, the new value will take effect when the URL is clicked on, and all portlets sharing that parameter will see the new value.
You can access (read) shared parameter values during the handlePostback, event handling, preRender, and render portlet life cycles.
The current values of shared parameters can be read using the getSharedParameterValue() and getSharedParameterValues() methods of the PortletBackingContext class during handlePostback and event-handling. The same methods can be called on the PortletPresentationContext class during preRender and render portlet life cycle phases. Using these methods will ensure that the most current value of the shared parameter is returned.
If a shared parameter is set on a postback URL, the portlet will be able to access the value of the parameter that was set on the URL using the HttpServletRequest.getParameter() method, but this may not be the most current value of the parameter.
For example, assume Portlet A and Portlet B are both configured to have a shared parameter X. Portlet A sets a value of "1" for X on one of its postback URLs, which then gets clicked on. Portlet B has a backing file with a handlePostbackData() method, which gets called and reads the value of X as 1, then sets the value of X to "2". When rendering, in Portlet A a call to HttpServletRequest.getParameter("X") will return "1" (as this is the value for parameter "X" in the request), but a call to the method PortletPresentationContext.getSharedParameterValue("X") will return "2" (as this is the current value for the shared parameter).
Unlike "normal" portlet parameters, shared parameter values are retained until they are explicitly set to a new value. For example, for a "normal" portlet parameter Y, if the portlet doesn't include a value for Y in a portlet URL, when the URL is clicked on, the portlet will see no value for Y. If the portlet sets a value for a shared parameter X in its backing file during a handlePostback operation, the value for X will remain accessible and constant no matter how many interactions happen with the portlet, until the portlet (or another portlet) explicitly changes the value of the shared parameter.
To create a shared parameter:
In the Portlet Properties view, select the Shared Parameters button.
In the Provide List of Shared Parameter(s) dialog, select New. The Provide Shared Parameter Components dialog appears, as shown in Figure 9-6.
Figure 9-6 Provide Shared Parameter Components Dialog
In the Provide Shared Parameter Components dialog, enter the following values:
Param ID – The identifier is a string that identifies the shared parameter within the .portlet file. This identifier is the name of the parameter that this particular portlet will use to read and set the shared parameter's value. Other portlets may access the same shared parameter using a different name (identifier) as long as the QName is identical.
QName – The QName, or qualified name, uniquely identifies the shared parameter. The QName consists of a required local part and a namespace URI. If you do not provide the namespace URI, the default namespace URI for the portal application is used. Click Edit to bring up a dialog for providing QName components. For information on QNames, see Section 12.12, "About QNames and Aliases."
Aliases – You can optionally specify one or more (comma separated) alias names. For more information about aliases, see Section 12.12, "About QNames and Aliases."
Click OK in both dialogs.
Example 9-8 illustrates how to get and set shared parameters in a JSP portlet's backing file.
Example 9-8 Getting and Setting Shared Parameter Values
public boolean handlePostbackData(HttpServletRequest request, HttpServletResponse response)
{
PortletBackingContext ctx = PortletBackingContext.getPortletBackingContext(request);
// Read the shared parameter configured with an identifier of "distanceKM"
String kilometers = ctx.getSharedParameterValue("distanceKM");
int km = Integer.parseInt(kilometers);
// Set a shared parameter for the distance in meters
ctx.setSharedParameterValue("distanceMeters", Integer.toString(km * 1000));
return(true);
}
The most common means of influencing portlet behavior within the control life cycle is to use a portlet backing file. A portlet backing file is a Java class that can contain methods corresponding to portal control life cycle stages, such as init() and preRender(). A portlet's backing context, an abstraction of the portlet control itself, can be used to query and alter the portlet's characteristics. For example, in the init() life cycle method, a request parameter might be evaluated, and depending on the parameter's value, the portlet backing context can be used to specify whether the portlet is visible or hidden. For more information about backing contexts, refer to the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Backing files can be attached to portlets either by using Oracle Enterprise Pack for Eclipse or by referencing them directly in a .portlet file.
Backing files are simple Java classes that implement the com.bea.netuix.servlets.controls.content.backing.JspBacking interface or extend the com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking interface abstract class. The methods on the interface are callbacks corresponding to the control's lifecycle methods (refer to Section 9.4.1, "How Backing Files are Executed") and are invoked at the same time the control's life cycle methods are invoked.
The following portal controls support backing files:
Desktops
Books
Pages
Portlets
JspContent controls (generic view controls)
The interportlet communication example in Chapter 12, "Configuring Local Interportlet Communication" uses backing files.
This section contains the following topics:
All backing files are executed before and after the portal control is called. In its life cycle, each backing file calls these methods:
init()
handlePostBackData()
preRender()
dispose()
Figure 9-7 illustrates the life cycle of a backing file.
On every request, the following sequence occurs:
Note:
In the following steps, the methods are called unless items on inactive pages have been "optimized away" if tree optimization is enabled. For example, if tree optimization is enabled and items on an inactive page are not included on the resulting partial control tree, then the method is not called.All init() methods are called on all backing files in depth-first order (that is, in the order they appear in the tree). This method is called whether or not the control (the portal, page, book, or desktop) is on an active page.
If the _nfpb parameter is set to true, all handlePostbackData() methods are called.
If the backing file's handlePostbackData() method returns true, the raiseChangeEvents() method is called. This method causes events to fire, which is necessary if the backing file tries to make any state or mode changes.
Tip:
You can use the method AbstractJspBacking.isRequestTargeted(request) to determine if a request is for a particular portlet.All preRender() methods are called for all portal framework controls on an active (visible) page.
The controls are called and rendered on the active page.
The dispose() method is called on each backing file.
A new instance of a backing file is created per request, so you do not have to worry about thread safety issues. New Java VMs are specially tuned for short-lived objects, so this is not the performance issue it was in the past. Also, JspContent controls support an attribute that allows you to specify whether or not the backing file is thread safe, called Singleton Backing Instance. If this value is set to true, only one instance of the backing file is created and shared across all requests.
The difference between having a backing file as part of <netuix: portlet backingfile =some_value> or part of <netuix: jspContent backingfile=some_value> is related to scoping.
For example, if you have the backing file on the portlet itself, you can actually stop the portlet from rendering. If the backing file is at the jspContent level, the portlet portion of the control tree has already run; you use this implementation to run processes that are specifically for the JSP in the portlet.
Follow these guidelines when creating a backing file:
Ensure netuix_servlet.jar is included in the in the project classpath; otherwise, compilation errors occur.
When implementing the init() method, avoid any heavy processing, because the init() method is called on all controls, whether they are visible or not.
Example 9-9 shows an example backing file.In this example, the AbstractJspBacking class is extended to provide the backing functionality required by the portlet. The example uses a session attribute because of the volatility of the HTTPRequest object; Oracle recommends that you pass data between life cycle methods using the session rather than the request object.
Example 9-9 Backing File Example
package backing;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import javax.servlet.http.HttpSession;
import com.bea.netuix.events.Event;
import com.bea.netuix.events.CustomEvent;
import com.bea.netuix.servlets.controls.content.backing.AbstractJspBacking;
public class ListenCustomerName extends AbstractJspBacking
{
public void listenCustomerName(HttpServletRequest request,
HttpServletResponse response, Event event)
{
CustomEvent customEvent = (CustomEvent) event;
String message = (String) customEvent.getPayload();
HttpSession mySession = request.getSession();
mySession.setAttribute("customerName", message);
}
}
You can add a backing file to a portlet either from within Oracle Enterprise Pack for Eclipse or by coding it directly into the file to which you are attaching it. In Eclipse, you can specify the backing file in the Backing File field of the Properties view, as shown in Figure 9-8. You need to specify the backing directory and, following a dot-separator, only the backing file name. Do not include the backing file extension; for example enter this:
backing.ListenCustomerName
Not this:
backing.ListenCustomerName.java
For the preceding example, if you include the file extension, the application interprets it as the file name—because the file path is specified by a dot-separator—and looks for a non-existent file called java in a non-existent directory called ListenCustomerName.
Figure 9-8 Adding a Backing File Using Oracle Enterprise Pack for Eclipse
The Portlet Wizard provides an optional Assign Supporting Files step, shown in Figure 9-9. This step lets you add a backing file and/or a render dependencies file to your portlet when you create it.
To add the backing file by coding it into a .portlet file, use the backingFile parameter within the <netuix:jspContent> element, as shown in Example 9-10.
Some aspects of portlet appearance are controlled by default at the portal level, such as colors, layouts, and themes. Appearance/rendering characteristics and portlet-specific features include the use of title bars and associated states (minimize, maximize, float, and delete) and modes that affect portlet content (edit mode, help mode, and custom modes).
The following sections describe how to work with portlet-specific appearance/content features and modes:
This section explains discusses portlet dependency files (also called render dependency files), a feature that lets you specify resources that are required for rendering a portlet.
Note:
You can also add render dependency files to books and pages. For details, see "Adding Render Dependencies to Books and Pages" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.This section contains the following topics:
Section 9.5.1.3, "Creating, Editing, and Adding a Dependency File"
Section 9.5.1.6, "Scoping JavaScript Variables and CSS Styles"
In a rendered HTML page, the proper place to include most types of resources, such as script files or style sheet references, is in the header of the document. Portlets sometimes need to specify resources that are required for rendering the portlet in the page. In the past, methods for making required elements available on the page included placing elements into the skeleton, which is not recommended because this creates a coupling between the skeleton and the portlet; or putting references directly in the portlet content, leading to the possibility of creating invalid HTML.
The problem was exacerbated in a federated (WSRP) environment because remote portlets are potentially included in several places and there was no way for one of these portlets to indicate that it relies on, for example, a piece of a CSS that resides in an external file.
WebLogic Portal now provides an explicit way to handle this requirement, using the portlet dependencies feature.
The concepts related to skin and skeleton resource dependencies are more formally known as render dependencies and script dependencies. Typical examples of such dependencies are CSS files and JavaScript files.
Both skins and skeletons can now specify such dependencies as well as associated search paths to be used for resolving these dependencies. Additionally, mechanisms exist to eliminate redundancy and to provide a reliable ordering for dependencies related to skins, skeletons, and theme skin and skeletons. These same capabilities are available for portlets, as well as books and pages, so that a portlet can specify necessary dependencies in a standards-compliant way; you identify these dependencies using appropriate elements located in the head section of the rendered page. The other advantages of the Look & Feel dependencies framework are also realized at a portlet level, such as reliable ordering and redundancy elimination.
The configuration of portlet dependencies shares the same mechanisms as the standard Look & Feel—you use an XML configuration document conforming to a standard Look & Feel schema. This XML document is referenced from a .portlet file using an attribute on the portlet element.
As with a Look & Feel's render dependencies, you can resolve a portlet's render dependencies utilizing a set of application search paths. Additionally, the search paths of the Look & Feel skin, or any appropriate Theme skin, are used before the portlet's own search paths to resolve a portlet's render dependencies.
You can specify a portlet's dependencies configuration file in the Oracle Enterprise Pack for Eclipse Properties view by entering the value in LAF Dependencies Path field. Alternatively, you can add the attribute lafDependenciesUri to the portlet element in a .portlet file, as shown in the following example:
<netuix:portlet definitionLabel="myPortlet" title="My Portlet" lafDependenciesUri="/portlets/example/myPortlet.dependencies">
Tip:
You can add multiple dependencies files to a portlet by specifying a comma-separated list of paths in the
lafDependenciesUri attribute.By convention, you should adhere to the following guidelines when setting up a portlet's dependencies configuration file:
Give the file the same name as the .portlet file.
Assign the file a .dependencies extension.
Locate the file at the same level in the file hierarchy as the .portlet file.
Although the guidelines listed here are not required, deviating from them can lead to unexpected behavior. For more information, refer to Section 9.5.1.5, "Considerations and Limitations."
The portlet dependencies configuration file uses standard types from the standard Look & Feel schemas and looks similar to the example shown in Example 9-11.
Example 9-11 Portlet Dependencies Configuration File Example
<?xml version="1.0" encoding="UTF-8"?>
<p:window
xmlns:p="http://www.bea.com/servers/portal/framework/laf/1.0.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/servers/portal/framework/laf/1.0.0
laf-window-1_0_0.xsd ">
<p:render-dependencies>
<p:html>
<p:links>
<p:search-path>
<p:path-element>.</p:path-element>
</p:search-path>
<p:link rel="stylesheet" type="text/css" href="my.css"/>
</p:links>
</p:html>
</p:render-dependencies>
</p:window>
The configuration file shown in Example 9-11 causes a CSS file to be included in the rendered page output (as a link element in the HTML head section). First, the search occurs for the CSS file relative to the Look & Feel or Theme skin search paths for the links element. If the CSS file is not found, then the search path in the configuration file is used. Relative search paths use the directory of the configuration file as a base.
The default behavior is to look first in the Look & Feel or Theme–specified search paths. This behavior allows a Look & Feel/Theme the ability to properly skin portlet resources. However, portlet-level resources should not be placed in the Look & Feel/Theme directories. If a situation arises when you do not want to use this behavior, you can disable it by specifying a value of false for the use-skin-paths attribute on the render-dependencies element.
You can use the New Render Dependencies dialog box in Oracle Enterprise Pack for Eclipse to create a valid dependency file that you can then complete using Oracle Enterprise Pack for Eclipse's XML editor.
WLP provides several ways to access the New Render Dependencies dialog box. This dialog lets you create a Render Dependencies file (a .dependencies file) in the web project.
You can attach multiple dependencies files to a portlet, book, or page. You can set the Render Dependencies Path for a portlet, book, or page to be a comma-delimited list of paths. All of the dependencies files in those multiple paths will be used to resolve dependencies. This feature includes filtering to avoid duplicates so that the same artifacts are not injected multiple times in the markup.
Note:
The.dependencies file must reside in a WebLogic Portal framework project, within the web content folder (typically named WebContent).The following actions bring up the New Render Dependencies dialog. This dialog lets you create a render dependency file. You can then associate the file with a portlet with the portlet's Render Dependencies Path property.
Right-click in the main body of a portlet in the portlet editor and select Create Render Dependency File. This brings up the New Render Dependencies Dialog, which lets you create the file.
Select File > New > Other > WebLogic Portal > Markup Files > Render Dependencies. This brings up the New Render Dependencies Dialog, which lets you create the file.
In the portlet Properties view, edit the Render Dependencies Path property. The Properties view provides a button that brings up the New Render Dependencies dialog.
Use the Assign Supporting Files page of the New Portlet Wizard to create a dependencies file. See Section 5.5, "Assigning Supporting Files."
You can also create a dependency file from scratch as follows:
Select File > New > Other.
In the New dialog, open the XML folder and select XML. The New XML File wizard opens.
Choose Create XML From XML Schema File and click Next.
Enter a name for the XML file in the XML File Name dialog and click Next.
In the Select XML Schema File dialog, choose Select XML Catalog Entry and in the Key column select laf-window-1_0_0.xsd as the schema. Click Next.
In the Select Root Element dialog, choose the root element window.
Optionally check the boxes that add optional attributes/elements to your new XML file.
Click Finish.
Rename the generated file's extension from .xml to .dependencies.
You can use the Oracle Enterprise Pack for Eclipse XML editor to add elements and attributes to the dependency file. Right-click on an element and use the menu to select child elements and add attributes. As shown in Figure 9-10, valid choices based on the schema file are automatically populated in the menu.
Tip:
Source view of the XML editor. Simply hover the mouse pointer over the element and a help pop-up appears. Also, in the Source view, you can click in an element and press F2 to display the help pop-up.This section includes the following examples:
Section 9.5.1.4.1, "Including JavaScript in a Render Dependencies File"
Section 9.5.1.4.2, "Including Meta and Style Elements in a Render Dependencies File"
Example 9-12 illustrates how to include both an external JavaScript file as well as an embedded script.
Example 9-12 Including JavaScript
<p:window
xmlns:p='http://www.bea.com/servers/portal/framework/laf/1.0.0'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.bea.com/servers/portal/framework/laf/1.0.0
laf-window-1_0_0.xsd '>
<p:render-dependencies>
<p:html>
<p:scripts>
<p:search-path>
<p:path-element>.</p:path-element>
</p:search-path>
<p:script type='text/javascript' src='my.js'/>
<p:script type='text/javascript'>
alert('hello world');
</p:script>
</p:scripts>
</p:html>
</p:render-dependencies>
</p:window>
Example 9-13 shows the use of both the metas and styles elements. The metas element lets you specify HTML meta tags, and the styles element lets you embed HTML style tags.
Example 9-13 Use of Meta and Styling Elements
<p:window
xmlns:p='http://www.bea.com/servers/portal/framework/laf/1.0.0'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://www.bea.com/servers/portal/framework/laf/1.0.0
laf-window-1_0_0.xsd '>
<p:render-dependencies>
<p:html>
<p:metas>
<p:meta name='keywords' content='pirate, ninja'/>
</p:metas>
<p:styles>
<p:style type='text/css'>
div.myClass {
background-color: red;
}
</p:style>
</p:styles>
</p:html>
</p:render-dependencies>
</p:window>
At this time, Oracle Enterprise Pack for Eclipse does not provide editing capabilities for portlet render dependencies configuration files; you can use the included Eclipse-based XML file editor for this purpose.
Oracle recommends that you not share a single .dependencies file across several portlets. Although WebLogic Portal does not prevent this usage, sharing a single file might lead to confusion when coordinating updates to the file later.
Whenever you place multiple instances of a portlet on a page, you can encounter scoping problems with JavaScript variables and CSS styles. For example, if a portlet includes inlined JavaScript and you place two instances of that portlet on a page, it is possible that changing a JavaScript variable in one portlet will affect the other portlet.
To ensure that JavaScript and CSS styles are scoped to a specific portlet instance, add the token wlp_rewrite_ to the front of the variable or style class name. When the portlet is rendered, this token is replaced by the portlet instance label, which is unique for each portlet instance.
For example, to ensure portlet instance-level scoping of a JavaScript variable called stockQuote that is defined in a .js file that is referenced from a .dependencies file, you need to append wlp_rewrite_ to the front of the variable name:
var wlp_rewrite_stockQuote
To ensure portlet instance-level scoping of a CSS class name called portlet_bg that is defined in a .css file that is referenced from a .dependencies file, you need to append wlp_rewrite_ to the front of the class name. For example:
.wlp_rewrite_portlet_bg { background_color:white; }
In both of these cases, the wlp_rewrite_ token is replaced by the portlet's instance label, which is a unique identifier.
Note:
The scoping mechanism described in this section only works for .css and .js files that are referenced with the content-uri dependency file attribute. Files linked with the src attribute or the link tag will not be rewritten.Some portals have several look and feels that include resources that are named the same. For example, look and feel ABC and XYZ might both have a graphic called logo.gif. As a portlet developer, you do not know which look and feel a portal administrator or user might choose. To avoid hard coding pathnames to resources in your portlets, you can enclose the resource name with the wlp_rewrite? and /wlp_rewrite tokens. For example, the following image source is hard coded:
<IMG SRC="/framework/skins/bighorn/images/titlebar-button-help.gif">
To avoid associating the resource path with a particular look and feel (for example, /bighorn), you can do this:
<IMG SRC="wlp_rewrite?titlebar-button-help.gif/wlp_rewrite">
When you use these tokens, WebLogic Portal searches for the named resource using the same mechanism it uses to search for resources associated with the currently specified look and feel. This means that whichever look and feel is selected, the correct graphics will be retrieved (assuming that the named graphic exists for that look and feel). If the resource cannot be found in the scope of the current look and feel, the original value specified will be used as-is (for example, titlebar-button-help.gif).
All portlets created with WebLogic Portal support the use of modes. Modes allow you to affect the end user's ability to edit the portlet or display Help for the portlet. You add icon buttons to a portlet's title bar to indicate the availability of a mode.
The following pre-defined modes exist for WebLogic Portal:
Edit – Lets you specify a custom file that lets users modify the portlet's content when they click the Edit button.
Help – Lets you specify a custom file that shows users help content for the portlet when they click the Help button.
You can also create your own custom portlet modes using WebLogic Portal.
Buttons for the selected modes appear in the portlet's title bar. Figure 9-11 shows an example of the default buttons for the portlet modes when displayed in the editor; Figure 9-12 shows the appearance of the mode icons in a running portlet.
Figure 9-11 Portlet Mode and State Buttons in Editor
Figure 9-12 Portlet Mode and State Buttons in a Running Portlet
When you use the Portlet Wizard to create a portlet, mode and state settings are available on the Portlet Details dialog. These settings can also be edited in the portlet's Properties view: The following sections describe possible methods of performing these tasks.
To add or remove the Help or Edit mode from the title bar, follow these steps:
Display the portlet for which you want to add or remove a mode.
Right-click the title bar of the displayed portlet to display the context menu. Figure 9-13 shows an example of the title bar context menu.
Figure 9-13 Available Portlet Modes - Title Bar Context Menu
Click Available Modes.
Checkmarks on the submenu indicate the available modes for this portlet, which were determined when you created it. Figure 9-14 shows an example of the submenu.
Figure 9-14 Portlet Mode - Available Modes Submenu
Click the mode for which you want to change the availability status. For example, in Figure 9-14, the Help mode is checked (available); when you click Help, the Help button disappears from the title bar.
Select File > Save to save your changes.
You can view and edit the mode's property details in the Properties view. For example, you can edit the Portlet Backing File property if you want to perform preprocessing before rendering the portlet's mode page (such as the edit page).
To display the mode properties for the portlet, click the expand/contract toggle button in the Portlet Mode area of the portlet. Edit mode properties and Help mode properties display in the Properties view.
For descriptions of the mode properties, refer to Table 9-7.
A custom mode is a portlet mode that you implement. Like with the help and edit modes, a custom mode is activated with a button that appears in the portlet's title bar. To implement a custom mode, you need to supply a display part, typically a JSP, and a backing file. This section includes an example that explains how to create a simple custom mode that lets a user add or remove the Maximize button from a portlet. Once you understand the basic principles involved in writing a custom mode, you can create a custom mode to perform the specific tasks you want.
Figure 9-15 shows the example portlet and the portlet's custom mode view. When the user clicks the custom mode button in the example portlet on the left, the portlet display changes to the custom mode view on the right. In this example, the custom mode offers a way for the user to add or remove the portlet's Maximize button.
Create a JSP portlet in which to embed the custom mode. For information on JSP portlets, see Section 5.4.1, "Building JSP and HTML Portlets." For this example, any JSP portlet will suffice.
Create a JSP page to display the custom mode view when a user clicks the custom mode button. For example, Example 9-14 shows a JSP for a custom mode that lets a user add or remove the Maximize button from a portlet. The code to execute this action is in a backing file, which is discussed next. In this example, the JSP is called togglebutton.jsp.
Example 9-14 Sample Custom Mode JSP
<%@ page import="com.bea.portlet.PostbackURL"%>
<%
PostbackURL url = PostbackURL.createPostbackURL(request, response);
%>
<TABLE CELLSPACING="10" ID="toggleButtonsTable">
<TH>Using a Button and Backing File</TH>
<TR>
<TD>
Click <b>Toggle</b> Off to remove the Maximize button from the portlet.<br>
Click <b>Toggle On</b> to restore it.
</TD>
</TR>
<TR>
<TD>
<FORM method="post" name="Toggle" action="<%=url.toString()%>">
<INPUT ID="toggle_off" TYPE="SUBMIT" NAME="toggle_off" VALUE="Toggle Off">
<INPUT ID="do_nothing" TYPE="SUBMIT" NAME="do_nothing" VALUE="Toggle On">
</FORM>
</TD>
</TR>
</TABLE>
Create a backing file for the custom mode. Example 9-15 implements the JspBacking interface and implements the preRender() method of that interface. In this example, the preRender() method removes the Maximize button from the portlet in response to a request. Refer to Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal for details on the API used in this example.
Example 9-15 Sample Backing File
package modes;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import com.bea.netuix.servlets.controls.content.backing.JspBacking;
import com.bea.netuix.servlets.controls.portlet.backing.PortletBackingContext;
import com.bea.netuix.servlets.controls.window.WindowCapabilities;
import com.bea.p13n.util.debug.Debug;
public class MyMode implements JspBacking {
public void dispose() {
}
public boolean handlePostbackData(HttpServletRequest arg0,
HttpServletResponse arg1) {
return true;
}
public void init(HttpServletRequest arg0, HttpServletResponse arg1) {
}
public boolean preRender(HttpServletRequest request, HttpServletResponse response) {
PortletBackingContext pbc =
PortletBackingContext.getPortletBackingContext(request);
if (request.getParameter("toggle_off") != null)
{
try
{
pbc.setCapabilityVisible(WindowCapabilities.MAXIMIZED.getName(),
false);
}
catch (NullPointerException npe)
{
//
}
}
return true;
}
}
Add a new custom mode to the portlet by dragging the New Custom Mode icon from the Design Palette to the portlet, as shown in Figure 9-16. You will be prompted to enter a name for the mode. You can enter a name now, or accept the default and change the name later.
Open the Properties view for the custom mode. To do this, click in the Custom Mode region of the portlet in the portlet editor, as shown in Figure 9-17. The properties for the custom mode appear in the Properties view.
In the Properties view, enter the path of the custom mode JSP in the Content Path field. This is the JSP that is displayed when the mode is activated. You can find the Content Path field in the Mode Properties section of the Properties view, as shown in Figure 9-18.
In the Properties view, enter the name of the backing file class, including the full package name. You can find the Portlet Backing File field in the Mode Properties section of the Properties view, as shown in Figure 9-18.
Figure 9-18 Specifying a Content File and a Backing File
Tip:
The Properties view lets you set many other custom mode properties, such as an image for the custom mode button, a rollover image, button text, alternate text, and others. Refer to Table 9-7 at the end of this section for information on each of the custom mode properties.Test the custom mode by placing the example portlet in a portal and running it on the server. Select the portlet's custom mode button, as shown previously in Figure 9-15, to display the custom mode view. Click Toggle Off to remove the Maximize button, as shown in Figure 9-19.
Section 9.5.4, "Custom Mode Properties" briefly describes each of the custom mode properties.
Table 9-7, Table 9-8, and Table 9-9 describe the mode, presentation, and toggle button properties.
| Property | Value |
|---|---|
|
Content Path |
Required. The path (relative to the project) to the file/class to be used for the custom mode portlet's content. From the data field you can choose to browse to a file (or class for page flow portlets) or open the currently displayed file/class. For example, if the content is stored in |
|
Error Path |
Optional. The path (relative to the project) to the JSP, HTML, or page flow file to be used for the error message if the portlet's mode page cannot be rendered. For example, if the error page is in |
|
Portlet Backing File |
Optional. If you want to use a class for preprocessing (for example, authentication) prior to rendering the portlet, enter the fully qualified name of that class. That class should implement the JspBacking interface or extend AbstractJspBacking. From the data field you can choose to browse to a class or open the currently displayed class. |
|
Visible |
Optional. Makes the mode icon in the title bar or menu invisible ( |
Table 9-8 Presentation Properties
| Property | Value |
|---|---|
|
Presentation Class |
This property is described in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Presentation ID |
This property is described in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Presentation Style |
This property is described in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
|
Properties |
Optional. A comma-delimited list of name-value pairs to associate with the object. This information can be used by skeletons to affect rendering. |
|
Skeleton URI |
This property is described in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. |
Table 9-9 Toggle Button Properties
| Property | Value |
|---|---|
|
Activate Alternate Text |
Popup text that appears when the mouse pointer hovers over the custom mode button. |
|
Activate Image |
An image for the button that activates the custom mode. Place the image in the images directory of the skin that your portal uses. |
|
Activate Rollover Image URI |
Provides a rollover image for the custom mode button. Place the image in the images directory of the skin that your portal uses. |
|
Active |
Not generally used, but available for use by custom skeletons. |
|
Alternate Text |
Not generally used, but available for use by custom skeletons. |
|
Deactivate Alternate Text |
Popup text that appears when the mouse pointer hovers over the custom mode button. |
|
Deactivate Image URI |
An image for the button that deactivates the custom mode. Place the image in the images directory of the skin that your portal uses. |
|
Deactivate Rollover Image UI |
Provides a rollover image for the button that deactivates the custom mode. Place the image in the images directory of the skin that your portal uses. |
|
Image |
Not generally used, but available for use by custom skeletons. |
|
Name |
The name of the custom mode. If specified, the name appears in the Portlet editor view, Outline view, and Properties view. If no name is supplied, a default name is used. |
|
Rollover Image |
Not generally used, but available for use by custom skeletons. |
States determine the end user's ability to affect the rendering of a portlet. WebLogic Portal supports these portlet states:
Normal – the typical rendered appearance of the portlet.
Minimize – Collapses the portlet, leaving only the title bar, when the user clicks the Minimize button.
Maximize – Makes the portlet take up the entire desktop area (not including the desktop header and footer) when the user clicks the Maximize button.
Float – Displays the portlet in a popup window when the user clicks the Float button.
Delete – Removes the portlet from the desktop when the user clicks the Delete button.
When you use the Portlet Wizard to create a portlet, state and mode settings are available on the Portlet Details dialog. These settings can also be edited in the portlet's Properties view: The following sections describe possible methods of performing these tasks.
You can select which of the states you want to include with the portlet by following these steps:
Right-click the portlet title bar.
A context menu showing applicable states appears. Figure 9-20 shows an example of the title bar context menu showing all states as available.
Figure 9-20 Portlet State - Title Bar Context Menu
Click to select the state that you want to change.
Selecting a state adds it to the portlet, while deselecting the state removes it from the portlet. For example, in Figure 9-20, all four states are selected, and appear in the title bar. If you click to deselect Deletable, the Delete button on the portlet disappears.
Select File > Save to save your changes.
You can minimize or maximize a portlet either in the portlet file or in a portlet's backing file. The actual code is the same for both. Here is an example of maximizing a (Java page flow) portlet:
PortletBackingContext context = PortletBackingContext.getPortletBackingContext(request);
context.setupStateChangeEvent(WindowCapabilities.MAXIMIZED.getName());
You can put this code in an action method of the Java page flow or in the handlePostbackData method of the backing file. When using the backing file, in order to get the handlePostbackData method to be called, you must have '_nfpb=true' in the URL.
These mechanisms do not work if asynchronous content rendering is enabled for the portlet.
Note:
Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.The default state and mode icons used in portlet title bars are stored in the wlp-lookandfeel-web-lib J2EE Shared Library; you can view them in Merged Projects view in the various subdirectories of framework/skins.
All portlets created with WebLogic Portal support height and scrolling.
Height affects the portlet's displayed height on the portlet page.
Scrolling affects whether or not the portlet is scrollable.
You can control the height of portlets and determine whether or not their contents scroll.
Portlet height and scrolling is controlled by the following CSS style attributes:
overflow: auto – Enables vertical and horizontal scrolling
height: 200px (where 200px is any valid HTML setting)
You can set these attributes on a portlet that is open in the workbench editor.
To set these properties, follow these steps:
Open a portlet in the workbench editor.
Click the outer border of the portlet to display the portlet properties in the Properties view.
In the Properties view, set one of the following properties:
Presentation Style - Enter any of the previously listed attributes for this property. You can use overflow and height. Separate the values with a semicolon.
Presentation Class - Enter the name of a style sheet class that contains the height or scrolling attributes that you want to use.
Content Presentation Style - Enter any of the previously listed attributes for this property. You can use overflow and height. Separate the values with a semicolon.
Content Presentation Class - Enter the name of a style sheet class that contains the height or scrolling attributes that you want to use.
Note:
The distinction between Presentation Style and Content Presentation Style, for example, is the location where the styling is applied (portlet or content). The use of one or the other depends on the specifics of what the specific styling is trying to accomplish.Figure 9-21 shows an example of a height property, set using Content Presentation Style.
Figure 9-21 Portlet Height and Scrolling Presentation Properties Example
Based on the entries shown in Figure 9-21, the result looks similar to the example in Figure 9-22.
Figure 9-22 Portlet Height and Scrolling—Portlet Appearance Results
If you use the Presentation Class property instead of the Presentation Style property, you must have the corresponding style class defined in a CSS file.
For example, if you use the value .portlet-scroll in the Content Presentation Class field, you must have the following style class definition already set up in your CSS file:
.portlet-scroll
{
overflow:auto;
height:250px;
}
Select File > Save to save your changes.
To provide portlet height and scrolling automatically, you can specify an additional rule for the standard portlet content CSS class. For example, you can do one of the following:
Add a <style> element to the skin.xml file for your Look & Feel containing this rule:
.bea-portal-window-content
{
height: 250px;
overflow: auto;
}
Alternatively, you can place the above rule in a custom CSS file and create a <style> or <link> element in the skin.xml file that references the custom CSS file.
For more information on portal skins, themes, and skeletons, refer to the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.
Note:
Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.A page flow stores information in the requests. If you have a portal page with multiple page flow portlets, you need a way for each page flow to individually store and retrieve that information. For example, the request object for a page might have a variable car_type, with a value of x. When the page flow runs, it obtains this value and uses it in some way. If you have another page flow portlet with a car_type value of z, and if only one request exists for the whole page, the two page flow portlets might interfere with each other. To prevent this problem, WebLogic Portal essentially makes a copy of the outer (portal) request to make separate scoped requests, one for each portlet. This gives each page flow portlet its own unique request to use to store its information.
In some cases, you might want to use information that is stored at the outer request rather than within the scoped request.
For example, if you use regular HTML tags within Netui form tags, you might have something similar to this:
<netui:form action="myAction"> <input type="check box" name="test"/> <netui:button value="myAction"></netui:button> </netui:form>
Based on the tags used above, you might typically use a regular getParameter request like this:
<%request.getParameter("test")%>
However, to get that HTML input value from the outer request, use the following:
<%@page import="org.apache.beehive.netui.pageflow.scoping.ScopedServletUtils"%>
<%
HttpServletRequest outerRequest = ScopedServletUtils.getOuterRequest
( request );
%>
test: <%=outerReq.getParameter("test")%>
WebLogic Portal provides JSP tags that you can use within JSPs. You can view available JSP tags in the Design Palette and then drag them into the Source View of your JSP, and use the Properties view to edit elements of the code.
WebLogic Portal also provides custom Apache Beehive controls that make it easy for you to quickly add pre-built modules to your portal; custom Java controls exist for event management, Visitor Tools, Community management, and so on. For example, most user management functionality can be easily exposed with a User Manager Control on a page flow.
Note:
Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.Note:
The term control is also used to refer to the portal (netuix) framework controls, such as desktop, book, page, and so on. These controls are referred to in the text as portal framework controls.When you open a JSP in Oracle Enterprise Pack for Eclipse, you can use the Design Palette to display all the JSP tags currently loaded and available; Figure 9-23 shows a portion of the display.
Figure 9-23 Design Palette Showing Available JSP Tags
To use a tag, drag it into the editor, use the Source View to edit the code directly, and use the Properties view to set properties, as shown in Figure 9-24:
Figure 9-24 Dragging a JSP Tag into the Design View – Properties for Add User JSP Tag
For information about the Java class associated with each JSP tag, refer to Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal.
To view the available custom controls provided by WebLogic Portal when viewing a page flow:
Note:
Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.Open an existing page flow (.java file) or create a new page flow.
For information about creating page flows using Oracle Enterprise Pack for Eclipse, refer to the Oracle Enterprise Pack for Eclipse User's Guide.
If you are not already using the Page Flow Perspective, Oracle Enterprise Pack for Eclipse asks if you want to switch to it. Do so.
Right-click in the source view for the Page Flow and select Insert > Control, as shown in Figure 9-25.
Figure 9-25 Insert > Control Menu Selection
The Select Control dialog box displays, as shown in Figure 9-26.
Expand the desired folder to view the custom Java controls for WebLogic Portal that you can choose from.
After you add a custom WebLogic Portal control, all the methods in the control become available to your Page Flow.
For more information about the custom controls provided by WebLogic Portal, refer to the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal. For details about each control, refer to the Oracle Fusion Middleware Java API Reference for Oracle WebLogic Portal. (Links to the Javadoc for each of the controls packages are conveniently listed in the Javadoc Overview frame.)
You can control portlet state persistence using the persistence-enabled attribute in the netuix-config.xml file, which is located by default in the WEB-INF directory. Using this attribute causes the state to be saved in the WebLogic Portal database. The attribute is set to false by default.
The following code segment shows an example of the attribute syntax:
<control-state-location> <session persistence-enabled="true"/> </control-state-location>
WebLogic Portal places an entry for the control tree state in the PROPERTY_KEY table, with the following PROPERTY_SET_NAME value:
BEA_PORTAL_FRAMEWORK_CONTROL_TREE_STATE
During the Development phase, you can use tag libraries to add features to a custom Community or a portal web application. This section discusses the following tag libraries:
The ActiveMenus JSP tag library
The DragDrop JSP tag library
The DynamicContent JSP tag library
The UserPicker JSP tag library
See the Oracle Fusion Middleware Communities Guide for Oracle WebLogic Portal for additional information.
You can add the ActiveMenus JSP tag library to a custom Community or a portal web application.
Note:
You do not need to follow the procedures in this section for GroupSpace communities. ActiveMenus are enabled by default for GroupSpace communities. Note that the GroupSpace application is deprecated. Oracle recommends that you consider using Oracle WebCenter Collaboration as a foundation for collaboration.The ActiveMenus JSP tag library lets you set up a popup menu that displays when the mouse hovers over specific text. An activemenus-config.xml file controls the contents of each menu. The activemenus_taglib.jar file contains the ActiveMenus tag library.
You can tie a user's capability to the ActiveMenu that you see when you hover your mouse over an item (an Issue, for example) and hover over the arrow that appears. In this example, if your assigned capabilities include the ability to delete items, you will see the Delete choice.
Perform the following steps to enable ActiveMenus in a custom Community:
In Oracle Enterprise Pack for Eclipse, make the activemenus_taglib.jar file available to your portal web project. When you create your portal web project, you must enable the WebLogic Portal Collaboration check boxes.
Add the activemenus-config.xml file to your /WEB-INF directory in your portal web project. Add the file by right-clicking the activemenus-config.xml file and choosing Copy To Project. Configure the file by follow the instructions in Section 9.9.1.1, "Configuring the ActiveMenus Tag" to edit the activemenus-config.xml file.
Register the GetActiveMenusResourceServlet by adding the servlet and servlet-mapping to the web.xml file in the /WEB-INF directory in your portal web project. You can edit the file in Oracle Enterprise Pack for Eclipse by double-clicking the web.xml file. Right-click the web-app line in the file and choose Add Child > message-destination - welcome-file-list > servlet. Add GetActiveMenusResourceServlet to the servlet-name line. Add com.bea.apps.groupspace.servlets.GetActiveMenusResourceServlet to the servlet-class line. See Figure 9-27 to view the edited file in Oracle Enterprise Pack for Eclipse.
Figure 9-27 Editing the web.xml File in Oracle Enterprise Pack for Eclipse
The code sample in Example 9-16 shows the new information you added.
Example 9-16 Code Sample of GetActiveMenusResourceServlet
<!-- ActiveMenus Servlet Mappings -->
<servlet>
<servlet-name>GetActiveMenusResourceServlet</servlet-name>
<servlet-class>
com.bea.apps.groupspace.servlets.GetActiveMenusResourceServlet
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>GetActiveMenusResourceServlet</servlet-name>
<url-pattern>GetActiveMenusResourceServlet</url-pattern>
</servlet-mapping>
Redeploy the application for the changes to take effect.
After you enable the ActiveMenus, you must configure the ActiveMenus tag.
To use the ActiveMenus tag, you must set up the activemenus-config.xml file (the XSD that defines this config file is located in the activemenus_taglib.jar file as activemenus-config.xsd). This activemenus-config.xml file file must exist in your web application's /WEB-INF directory. Multiple menus can be set up that consist of completely different items, styles, and icons.
Use the following sections to configure the activemenus-config.xml file:
Use the typeInclude tag to keep your configuration file clean. Rather than adding the type tag (see Section 9.9.1.1.2, "Using The Type Tag") you can add this tag and point its href attribute to an XML file (relative to the web application) that contains all of the type information. An example of the typeInclude tag is:
<typeInclude xhref="/WEB-INF/activemenuTypes/username.xml"/>.
You can also use the type tag with the typeInclude tag in the configuration file. See the code sample in Example 9-17.
Example 9-17 You Can Use the typeInclude Tag with the Type Tag in the activemenus-config.xml File
<typeInclude xhref="/WEB-INF/activemenuTypes/username.xml"/>
<type>
<menuItem>
<param name="linkId"/>
<action action="editLink">
<i18nNamebundleName="com.bea.apps.groupspace.links.
LinksPopupMenu" key="edit.link"/>
</action>
<img xsrc="wlpAppsCollaborationCore/images/wlp-edit-16.gif"/>
</menuItem>
</type>
When you point to another XML file, ensure that you namespace it correctly, as shown in Example 9-18.
Example 9-18 Pointing to Another XML File Called username.xml
<type name="username"
xmlns="http://www.bea.com/servers/apps/groupspace/ui/
activemenus-config/9.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.bea.com/servers/apps/groupspace/ui/
activemenus-config/9.0">
...
</type>
The type tag defines the individual menus to use within the web application. The name attribute must be unique for each menu, because the name is how the menu is referenced when you use the ActiveMenus tag. Following is an example of the type tag:
<type name="foo"> </type>
Note:
The TypeDefault and MenuItem tags must be contained within the type tag.The typeDefault tag defines what displays in the browser where the ActiveMenus tag is used. You can control the text that displays, the style of the text, and the image that appears on the mouseover of that text (which denotes the menu itself).
The following items display within the browser where you used the ActiveMenus tag:
The displayText Attribute – Defines the actual text that displays. If the displayText is not defined, whatever text is placed in the display attribute of the ActiveMenus tag appears. However, if you want to display other text, you can specify a class and a method within that class that returns a String to display. The following example shows how to display other text.
GetUserNameFromProfile.java
public class GetUserNameFromProfile
{
public static String getName(String userName)
{
return "XXX-" + username + "-XXX";
}
}
If you use this code, the configuration defined above, and the following ActiveMenus tag: <activemenus display="UserName" type="foo"/>, the following displays in the browser: XXX-UserName-XXX.
This example allows you to use the information entered in the body of the ActiveMenus tag to look up other information to display. For instance, a username can be used to look up a user's full name to display. The only rules surrounding this action is that the method used for the display text is public, static, takes in a String, and returns a String. No other information can be passed into that method.
The displayTextStyle Attribute – Defines the CSS style or class that stylizes the display text. In order for the class attribute to work correctly, the class must be defined on the page (or the CSS file that defines the class must be imported).
The displayMenuImage Attribute – Defines the image that appears when the display text is passed over with the mouse. If this tag is not defined, the default image is used. This image is in the activemenus_taglib.jar file and is called menu_default.gif.
The menuStyle Attribute – Defines the CSS style or class that stylizes the menu itself, which can include the border or background color. For the class attribute to work correctly, the class must be defined on the page (or the CSS file that defines the class must be imported).
Note:
The TypeDefault and MenuItem tags must be contained within the type tag.The menuItem tag defines the individual items within the popup menu. Example 9-19 shows a code sample using the menuItem tag.
<menuItem>
<param name="userId"/>
<xmlHttp url="GetFirstNameServlet"/>
<row class="menuRow" style="backround-color:red"/>
<text class="menuText" style="color:#000000"/>
<rowRollover class="menuRowRollover" style="background-color:green"/>
<textRollover class="menuTextRollover" style="color:#FFFFFF"/>
</menuItem>
<menuItem>
<javascript>
<name>Testing</name>
<script>testing(this);</script>
</javascript>
</menuItem>
<menuItem default="true" showMenuItem="false">
<param name="q" value="foo"/>
<link url="http://www.google.com">
<name>Google</name>
</link>
</menuItem>
<menuItem>
<showMenuItem className="com.foo.CheckUserRights" methodName=
"doesUserHaveRights">
<rights name="can_view"/>
<rights name="can_edit"/>
</showMenuItem>
<allParams/>
<action action="addEditLink" disableAsync="true">
<i18nName bundleName="com.foo.LinksPopupMenu" key="edit.link"/>
</action>
</menuItem>
<menuItem>
<allParams/>
<dcAction action="showFeedData" dcContainerId="feedDataContainer">
<i18nName bundleName="com.foo.LinksPopupMenu" key="show.
feedData"/>
</dcAction>
</menuItem>
The menuItem tag defines the individual items within the popup menu with the following four types:
The javascript Element – This element can be any JavaScript that you want to run when the user clicks this menu item. To make this more useful, you can retrieve the values that you specify in the param tag (see the code sample below) through custom parameters that are added to the menu item. Following is a basic example of how to implement JavaScript.
...
<activeMenus:activemenus display="Foo Link" type="link">
<param name="linkId" value="${fooLink.id}"/>
<param name="linkParent" value="${fooLink.parent}"/>
</activeMenus:activemenus>
...
The next step is to define the custom JavaScript in your configuration file. The JavaScript must pass in the code shown in the following sample.
...
<type name="link">
<menuItem>
<allParams/>
<javascript>
<name>Testing</name>
<script>fooTest(this);</script>
</javascript>
</menuItem>
</type>
...
The last step in implementing the JavaScript element is to access the values in your JavaScript function, as shown in the following code sample.
...
<script>
function fooTest(object)
{
var linkId = object.getAttribute("linkId");
var linkParentName = object.getAttribute("linkParent");
}
</script>
...
The xmlHttp Element – The xmlHttp references a servlet (which must follow all standard servlet configuration). Whatever the servlet outputs is shown in that row of the menu. If "" or null is returned from the xmlHttp servlet, the menu item row does not appear in the menu. The information is retrieved through an xmlHttp request, which allows the information to be updated without refreshing the page. For example, you could show a user's online status that would update without having to make a full post. The two rules that surround writing your servlet for this is that all the processing must happen in the servlet's doPost() method. The second rule is that the defined parameters are passed in as request parameters. Following is an example of getting the query parameters:
String userName = request.getHeader("linkId");
The link Element – This static URL opens a new browser window pointed to the defined URL. This tag can take in either a name tag or an i18nName tag (defined below) that is displayed within the menu itself. Any defined parameters are added to the end of the link as regular request parameters.
The action Element – This action name must be available to the page or portlet that contains the ActiveMenus tag. This element runs the action within the current browser, so you can use forwards to control your page flow. This tag can take in a name tag or an i18nName tag (defined below) that will appear within the menu itself. Any defined parameters passed in are available on the request as parameters. Following is an example of retrieving these values from a page flow:
String linkId = getRequest().getParameter("linkId");
You can also use an attribute called disableAsync within AJAX-enabled portlets. If you want your menu item action to submit outside of the AJAX framework (so the page makes a full post), set this attribute to true. By default, the attribute is set to false.
The dcAction Element – If you have a Dynamic Content container set up within your page, you can set up a menu item to call an action and have it update the Dynamic Content container. This works the same as an action menu item, and takes in the action name to execute. The only difference is you must specify the dcContainerId and it must correspond to a dcContainerId that is defined within a <dc:executeContainerAction> tag on the page.
Other attributes and elements that you might use include the following:
The showMenuItem Element – Add this element if you need to conditionally show the menu item (for example, based on a set of rights for the current user). You define a class name and a method name that determines if the menu item should be shown. You can use multiple showMenuItem tags, each using different classes, methods, or rights. If you use more than one tag, all cases must be satisfied in order for the menu item to appear. For example, if the user passes nine of 10 cases, the menu item does not appear because all cases were not passed. Example 9-20 shows how you can use the showMenuItem tag.
Example 9-20 The CheckUserRights.java Class with the showMenuItem Tag
public class CheckUserRights
{
public static boolean doesUserHaveRights(HttpServletRequest request,
String[] rights)
{
for(int i=0;i<rights.length;i++)
{
if(!checkAccess(request, rights[i]))
{
return false;
}
}
return true;
}
}
The default Attribute – When this attribute is used in a menuItem tag and set to true, the display text anchor's href will be the link or action. Use this attribute when you want a default action to occur when clicking the main link, and you also want to display the action for consistency purposes. The default value for this attribute is false.
The showMenuItem Attribute – When this attribute is used in a menuItem tag and set to false, the menu item does not appear in the ActiveMenu. Use this attribute when you want a default action to occur when you click the main link, but you do not want to display the action. The default value for this attribute is true.
Note:
Do not wrap an ActiveMenus tag in an anchor tag because you can get undesired results. Instead, use the default and showMenuItem attributes to control the ActiveMenu display text link.The allParams Element – This element specifies that all of the parameters defined on the tag (see Section 9.9.1.2, "Using the ActiveMenus Tag") are set up on this menu item. If this element is not used (and the param element is not used), then parameters are not set up on the menu item.
The param Element – This element sets the specified parameters on the menu item. The param element has a name attribute that must match the name attribute on a param element that is set within the ActiveMenu tag (see Section 9.9.1.2, "Using the ActiveMenus Tag"). This also has a value attribute that can be used to hard code a value at configuration time. If this value attribute has been set, but a value was also specified at run-time (for example, using the param tag within the ActiveMenu tag), the run-time value takes precedence over the hard-coded value. Also, if just the hard-coded value is to be used, the param tag does not have to be specified when you use the ActiveMenus tag.
The name Element – This element displays only the static name defined within the tag as the menu item.
The i18nName Element – This element has both a bundleName attribute, which must map to an available .properties file, and a key attribute. The bundleName attribute uses the standard Java ResourceBundle convention. The key attribute defines the key to grab within the specified bundle. The text that relates to this key within this bundle is what appears in the menu item.
The img Element – This element adds the specified image to the left column as an icon. You must specify the path to the image file in relation to your web application.
The bgImg Element – This element replaces the background image used in the left column with the specified image. You must specify the path to the image file in relation to your web application.
The row Element – This element defines the CSS style or class that stylizes the row of the menu item. For the class attribute to work correctly, the class must be defined on the page (or the CSS file that defines the class must be imported).
The text Element – This element defines the CSS style or class that stylizes the text of the menu item. For the class attribute to work correctly, the class must be defined on the page (or the CSS file that defines the class must be imported).
The rowRollover Element – This element defines the CSS style or class that stylizes the row of the menu item when it is rolled over. For the class attribute to work correctly, you must define the class on the page (or the CSS file that defines the class must be imported).
The textRollover Element – This element defines the CSS style or class that stylizes the text of the menu item when it is rolled over. For the class attribute to work correctly, you must define the class on the page (or the CSS file that defines the class must be imported).
Note:
The TypeDefault and MenuItem tags must be contained within the type tag.The taglib.tld file is located in the activemenus_taglib.jar file.
You can use the following attributes and elements with the ActiveMenus tag:
The display Attribute – This attribute defines what appears in place of the tag itself. If you use the displayText attribute, this is the value that is passed to the method defined in the displayText tag.
The type Attribute – This required attribute defines what is in the menu and must match a type defined in the activemenus-config.xml file.
The href Attribute – This optional attribute can override the default anchor href for the display text of the tag.
The newWindow Attribute – This optional href attribute specifies the link to open in a new browser window. This is a Boolean attribute, and you set it to true or false.
The class Attribute – This optional attribute defines a CSS class for the display text.
The style Attribute – This optional attribute defines a CSS style to place on the display text.
The rightClick Attribute – This Boolean attribute turns the menu into a right-click menu, rather than a rollover menu. The default is false. If this attribute is set to true, you right-click the display text to bring up the menu. The menu appears under the mouse.
The escapeXml Attribute – This attribute is the same as escapeXml within the JSTL tags. If you set it to true, characters are converted to their corresponding character entity codes.
The param Element – This element sets up parameters that can be passed in and used for the different menu items. The following two attributes are both required:
The name Attribute – This is the parameter name and must match the name attribute (if used) when defining a menu item in the activemenus-config.xml file. The name attribute also references the parameter within your menu item code. You can use a runtime expression.
The value Attribute – This is the parameter value, and you can use a runtime expression.
Note:
If a class is specified on the tag, the default class specified in the activemenus-config.xml file is overridden and the default style is not placed on the activename. If a style is specified on the tag, the default class is placed on the activename. If a class="" is specified on the tag, the default class is not placed on the activename.You can use the DragDrop JSP tag library to enable placeable movement functionality in a custom Community or a portal web application. You must identify moveable objects that are displayed on a JSP, and identify drop zones that are configured to react to a dropped moveable object. The drop zones react by triggering Page Flow actions, calling JavaScript functions, or posting data to a servlet.
Perform the following actions before you use the DragDrop tag library:
Include the dragdrop_taglib.jar file in the web application's CLASSPATH
Place the code shown in Example 9-21 into your web.xml file
Example 9-21 Code Entry in the web.xml File
<servlet>
<servlet-name>DragDropResourceServlet</servlet-name>
<servlet-class>com.bea.apps.communities.servlets.
GetDragDropResourceServlet
</servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>DragDropResourceServlet</servlet-name>
<url-pattern>DragDropResourceServlet</url-pattern>
</servlet-mapping>
Three tags are defined in the DragDrop tag library. Following are descriptions of how each tag is used, along with sample JSP code:
The dragDropScript Tag – This tag includes the necessary DragDrop JavaScript libraries in the page. The logic embedded into the tag ensures that these libraries are included only once per request.
The draggableResource Tag – This tag identifies a moveable resource on the page.
The resourceDropZone Tag – This tag identifies an area on the page that reacts when a moveable resource is dropped.
You must include the dragDropScript tag before you use any other DragDrop tags on the page. This tag ensures that the appropriate JavaScript libraries are included. The dragDropScript tag does not take any attributes.
The following example shows how to use the dragDropScript tag: <dragdrop:dragDropScript/>.
The draggableResource tag specifies a moveable resource on the page. The tag takes the following attributes:
The resourceId Attribute – The unique identifier of the resource that is being moved. This identifier should be an ID that can be used by the underlying business logic to uniquely identify the resource.
The resourceName Attribute – The representative name of the resource being moved.
The draggableResource tag performs a search for a child img tag that has a dragdrop:image attribute. This image becomes the image that is displayed while performing the placeable movement operation. The image must have an absolute height and width attribute.
The resourceId value is accessible through the JavaScript function getSourceId(), when the value is dropped onto a resourceDropZone. The resourceId value is also available as a parameter in the request named sourceId, when it is dropped onto a resourceDropZone that triggers a POST action. See Example 9-22.
The resourceDropZone tag identifies an area where moveable resources can be placed.
The tag takes the following attributes:
The targetId Attribute – The unique identifier of the drop zone object. This identifier can be an ID that can be used by the underlying business logic to uniquely identify which object received the drop action.
The jsFunctionCall Attribute – A JavaScript function that executes when a draggableResource is dropped on this resourceDropZone.
The pageFlowAction Attribute – A valid Page Flow action that is initiated when a draggableResource is dropped on this resourceDropZone.
The formAction Attribute – A valid JSP or servlet that receives a POST action when a draggableResource is dropped on this resourceDropZone.
Only one of the following attributes is required: jsFunctionCall, pageFlowAction, or formAction. The jsFunctionCall takes precedence, then pageFlowAction, and finally formAction.
The targetId value is accessible through the JavaScript function getTargetId() when a moveable resource is placed. It is also available as a parameter in the targetId request when a moveable resource is placed that triggers a POST action. The following code shows how this works:
<dragdrop:resourceDropZone targetId="${id}" pageFlowAction="moveIssue">
<img src="/folder.gif"/>Issues Folder
</dragdrop:resourceDropZone>
Example 9-23 demonstrates how the moveIssue action can be coded in a file called IssuesPageFlowController.java.
Example 9-23 Coding the moveIssue Action
@Jpf.Action(forwards={ @Jpf.Forward(name = "success", path =
"displayIssuesTree.do")})
protected Forward moveIssue() {
Forward forward = new Forward("success");
String sourceId = getRequest().getParameter("sourceId");
String targetId = getRequest().getParameter("targetId");
move(sourceId, targetId);
return forward;
}
You can use the DynamicContent tag library to quickly update parts of a JSP page in a custom Community or a portal web application.
Tip:
See also the Oracle Fusion Middleware Client-Side Developer's Guide for Oracle WebLogic Portal for information on developing rich, interactive applications.The DynamicContent tags let you use an AJAX request to update part of a JSP page within a Page Flow-based portlet. The tags allow parts of the page to be updated without performing a full portal request. These AJAX requests are smaller and faster than full portal requests, and therefore provide a more responsive user experience when interacting with a portal application.
Note:
Page Flows are a feature of Apache Beehive, which is an optional framework that you can integrate with WLP. See "Apache Beehive and Apache Struts Supported Configurations" in the Oracle Fusion Middleware Portal Development Guide for Oracle WebLogic Portal.These tags are easy to incorporate into standard Page Flow-based portlet development and can help create advanced user interface features that improve a user's portal experience.
Note:
The DynamicContent tags are not related to Asynchronous Portlet Content Rendering. Asynchronous portlets allow for the entire portlet content to be rendered independently of the portal. The DynamicContent tags are designed to affect small parts of a JSP page within a portlet.This section describes the main tags in the DynamicContent tag library.
The Container tag designates a place on the JSP page that contains the HTML output from the execution of a Page Flow action. The only required attribute for this tag is a container id. This id is referenced by other DynamicContent tags to identify the container. The following code shows how this tag is used: <dc:container dcContainerId="outputContainer"/>.
This tag is a child of the Container tag and identifies a Page Flow action that can be executed and whose HTML output is placed inside the parent container. The containerActionScript tag takes the following attributes:
The action attribute – The Page Flow action name.
The initial attribute – Designates an action in the container as the initial action. This is the action that initially populates the container.
The async attribute – Specifies if the action is performed synchronously or asynchronously. The default is synchronous.
The onErrorCallback Attribute – A user-defined JavaScript function that is called if a client-side error occurs during the AJAX request creation and processing.
Only the action attribute is required. The following code sample shows how this tag is used in the parent Container tag:
<dc:container dcContainerId="outputContainer">
<dc:containerActionScript action="resetDynamicContentContainer"
initial="true"/>
<dc:containerActionScript action="showServerTime"/>
<dc:container/>
The Execute Container Action tag is used to create a call to a specific action inside a container. This tag takes the following attributes:
The dcContainerId attribute – The id of the container in which the action is defined.
The action attribute – The Page Flow action name.
The async attribute – This specifies if the action is performed synchronously or asynchronously. The default is synchronous.
The var attribute – A request attribute variable that holds a reference to the action JavaScript call.
The dcContainerId and action attributes are required. Following is a sample of how this tag is used:
<dc:executeContainerAction action="showServerTime" dcContainerId=
"outputContainer"
var="showServerTimeVar"/>
In the previous example, the call to the specified action is stored in the variable showServerTimeVar. This variable can then be referenced, as shown in the following HTML code:
<form>
<input type="button" onclick="${showServerTimeVar}" value="Show Server
Time"/>
</form>
When the user clicks a button, an AJAX request is created that executes the showServerTime action and places the HTML output generated by that action into the container with the id of outputContainer.
The DynamicContent tags also include tags for parameters that are passed into the action through the request. You can define parameters within the executeContainerAction tag or the containerActionScript tag. These parameters are then accessible in the Page Flow action by calling the request.getParameter() method.
Some critical limitations are associated with the DynamicContent tags. The AJAX requests used to trigger the Page Flow actions are not processed through the main portal servlet. These requests go through a special servlet that performs some processing to ensure that the proper Page Flow instance is used. Many key elements that are normally available in the request are not accessible from these AJAX requests. For example, in Community-based portal applications, the CommunityContext object is not accessible from the AJAX request. The lack of access to some of these framework elements could have an impact on things like entitlements and security.
Because of these limitations, the DynamicContent tags are best suited for specific uses that involve small amounts of processing, with few dependencies on larger framework services. The following use cases could benefit from the DynamicContent tags:
Update a small location on a JSP page to display frequently updated data obtained through periodic client-side polling. For example, you could notify users of unread mail or display the number of users logged onto a system.
Use the tags as a pagination mechanism for tabled data presented across multiple pages.
Send multiple requests to the server to obtain successive images to navigate through a series of images in a photo gallery. The DynamicContent tags provide a tool to avoid an expensive portal request to view each photo.
Obtain remote data, such as stock quotes or weather information from remote sites. The obtained data can be displayed in a designated area on the page without updating other parts of the page.
During the Development phase, you can use the UserPicker tag library to add a form button to a JSP page in a custom Community or a portal web application.
The UserPicker:popupButton tag provides the developer with the ability to add a form button to a JSP page which opens a popup window that displays a list of current users. You can select a user from this list. The name of the selected user is populated into a specified form field on the parent window.
This section describes the UserPicker:popupButton tag in a custom Community and how to use the following attributes:
The inputId Tag – The id of the HTML form input element that is populated with the selected user's name. This tag is optional.
The inputTagId Tag – The tagId of the netui-based form input element that is populated with the selected user's name. If the inputId tag is provided, the inputTagId tag is ignored. This tag is optional.
The buttonImage Tag – The src path to the image for the popup button. This tag is required.
The atnProviderName Tag – The Authentication Provider name. If an atnProviderName is supplied, there is no provider drop-down box in the popup window. If an atnProviderName is not supplied, the default provider is used. If you have configured multiple Authentication Providers, a drop-down box appears in the popup window to allow you to specify a provider. This tag is optional.
Tip:
When the UserPicker:popupButton tag is used in a Community, the Community members are listed, rather than users.WebLogic Portal supports the use of detached portlets, which provide popup-style behavior. Technically, a detached portlet is defined as anything outside of the calling portal context. Any portlet type supported by WebLogic Portal can be rendered as a detached portlet.
Note:
Opening the same portal desktop in multiple browser windows that share the same process (and, therefore, the same session) is not supported. For example, using therender:pageURL tag or the JavaScript window.open function to open a portal desktop in a new window is not supported and can result in unwanted side effects. For instance, if a portlet is deleted in the new window, and then the user tries to interact with that portlet in the main window, the interaction will fail.Keep the following considerations in mind as you implement detached portlets:
Detached portlets are never referenced from within a portal; there is no portlet instance in the portal associated with a detached portlet.
The detached or "pop-up" portlet feature is not supported for remote (WSRP) portlets.
Detached portlets can be streamed but generally cannot be entitled or customized; the library instance can be entitled, but portlet instances that are de-coupled from the portlet library cannot. For more information about library portlet instances and de-coupling, refer to the Oracle Fusion Middleware Production Operations Guide for Oracle WebLogic Portal.
Detached portlet are not visible or accessible from the WebLogic Portal Administration Console portlet library.
In a streamed portal, the primary instance of the portal is used. In some cases, the primary instance cannot be determined; for example, you might have set entitlements on the primary instance to make it not viewable, or you could have set up a configuration that excludes portlets from the scanner and poller so that they are not streamed into the database. If the primary instance cannot be determined, a static version of the portlet is used (the portlet will be served in file mode). In these cases, some features related to a streamed portal (such as a community context) will not be available, and applications might be required to implement workarounds.
Although technically a detached portlet can be implemented to use asynchronous rendering, this is not a best practice and is not recommended.
No presentation mechanism is provided as part of the detached portlet feature; the application must define how to actually present the portlet. For example, a floated portlet will automatically be popped up in a separate window; detached portlets have no such mechanism, so your application must handle popping up the window.
When developing detached portlets, you can place them anywhere in the hierarchy of your portal web application; the portal references the absolute path to the portlet.
The framework for standalone portlets creates a "dummy" control tree above the portlet, including desktop, book, and page controls. The context objects associated with such controls reflect the state of the dummy controls, and not of the main control tree; for example, if a portlet tries to get information about its current book or page, the Book/Page Presentation/Backing Context objects will not reflect the actual structure of the portal. There might also be cases where the dummy control tree does not support certain backing context APIs. When developing your portal, you need to keep this artificial control tree structure in mind.
You use the standalonePortletUrl class or associated JSP tag to create URLs to detached portlets.
To create a detached portlet URL from a JSP page, you use the render:standalonePortletUrl JSP tag or class; the following example shows the syntax of the JSP tag:
<render:standalonePortletUrl portletUri="/absolute_path/detached_portlet_name.portlet" .../>
To create a detached portlet URL from Java code, use the following example as a guide:
StandalonePortletURL detachedURL = StandalonePortletURL.createStandalonePortletURL(request, response);
detachedURL.setPortletUri("/path/to/detached.portlet");
A file-based portlet can exist either as a stand-alone .portlet file or as an inlined portlet. Typically, within the Oracle Enterprise Pack for Eclipse portal editing framework, .portlet files are included in portals by reference. For instance, when you drag a .portlet file onto a portal, page or book, a reference is created to the portlet file inside the portal, page, or book. On the other hand, an inlined portlet's entire XML definition is embedded directly in a page or book.
Inlined portlets are created under the following circumstances:
If you create a remote book or page that contains portlets, those portlets will be inlined in the .book or .page file. For detailed information on creating remote books and pages, see the Oracle Fusion Middleware Federated Portals Guide for Oracle WebLogic Portal.
If you use the Export/Import Utility to extract a .book or .page file that contains portlets, those portlets will be inlined if they were originally inlined. If the original page contained referenced portlets, they will be referenced when the page is extracted. For detailed information on the Export/Import Utility, see the Oracle Fusion Middleware Production Operations Guide for Oracle WebLogic Portal.
You can drag and drop, cut, copy, and paste inline portlets from one page or book to another from within the portal editor.
Figure 9-28 shows a remote page that contains an inlined portlet and a referenced portlet. Note that the icon used in an inlined portlet is distinct from a referenced portlet.
Figure 9-28 Inlined Portlet in the Portlet Editor
Tip:
You can edit the properties of inlined portlets exactly like file-based portlets; however, portlet states and modes are not editable for inlined portlets.You can export an inlined portlet to a .portlet file. When you do this, the resulting .portlet file is functionally equivalent to any other .portlet file. When you extract an inlined portlet, the inlined portlet XML code is automatically removed from the source file (a page or book) and replaced with a reference to the newly created .portlet file.
Note:
After you extract an inlined portlet, you can undo the operation (re-inline the portlet). However, note that the .portlet file that was created during the extraction will not be deleted from your system. The source document will simply not reference the .portlet file any longer.To extract an inlined portlet, do the following:
Right-click the inlined portlet in the Book or Page Editor and select Extract Portlet to New File, as shown in Figure 9-29.
In the Save As dialog, enter a name for the new portlet.
Tip:
Project > Clean command.You can set the theme of an inlined portlet exactly as you would for a referenced portlet. To set the theme, right-click the inlined portlet in the book or page editor, and pick a theme from the Theme menu. The theme is retained for that portlet as long as it remains referenced in the page or book.
You can extract any book or page in a portal to a .book or .page file. Once a book or page is extracted, you are free to use it in another portal within the same portal web application if you wish.
The procedure for extracting books and pages is similar to the procedure for extracting inlined portlets, described in Section 9.11.1, "Extracting Inlined Portlets." To extract a book or page, do the following:
Right-click border of the book or page in the Portal Editor and select Extract Book (or Page) to New File.
In the Save As dialog, enter a name for the new book or page file.
Tip:
Any theme applied to a book or page is retained for an extracted book or page as long as the book or page remains referenced in the portal.The WebLogic Portal framework generally uses a non-buffered model for rendering portlets, meaning that each portlet renders directly to the underlying portal response. This generally scales and performs better than a fully buffered response.
Because individual portlets write to the underlying portal HttpServletResponse, the actions of individual portlets or portlet components may commit the response. For example, simply flushing an outputstream or writer, as is frequently automatically done for JSPs and simple println() calls, will automatically commit the response. Once the response is committed, certain operations such as setting cookies become impossible for other portlets when they render.
In general, the best practice for portlet developers in WebLogic Portal is to perform such operations during the pre-render life cycle (such as in a backing file's preRender() method), but this may not always be possible, for example if JSR168 or JSR286 portlets are being used, or if the portlet is accessed over WSRP.
To allow portlets to set cookies and headers during the render life cycle, you can use a setting in the WEB-INF/wlp-framework-common-config.xml file. If you set the <avoid-response-commit> element to true, a response wrapper will be put on the base portal response to avoid committing the response as long as possible.
This response wrapper is used when rendering portal pages and ignores calls to flushBuffer(). The wrapper also ensures that flushes of the response output stream or response writer do not automatically commit the response. The response may still be automatically committed when the output exceeds the response buffer size; the optional bufferSize attribute can be used to set a response buffer size other than the servlet container's default buffer size.
When using this configuration option for non-Java portlets, use the PortletPresentationContext object's addCookie() and addHeader() methods to add cookies and headers on the response from portlets during the render life cycle. You can do this as long as the response buffer has not overflowed and forced the response to commit. Cookies or headers set on the HttpServletResponse (instead of the PortletPresentationContext) are generally ignored during the render phase of the portlet life cycle.
For Java portlets' (JSR168/JSR286), the PortletResponse addCookie() and addProperty() methods automatically set the cookies or headers on the underlying response, as long as the response buffer has not overflowed and forced the response to commit.
For WSRP portlets returning cookies or headers during a getMarkup operation, the framework will also automatically set the cookies or headers on the underlying response. If using a WSRP interceptor on a getMarkup operation, the PortletPresentationContext methods must be used to set cookies or headers on the consumer's response.
|
 Copyright © 2010, 2011, Oracle and/or its affiliates. All rights reserved. Legal Notices |
|
