Using a sample portlet as an example, learn how user settings
can be stored and retrieved in portlets.
This topic describes how user settings can be stored and retrieved
in portlets. Examples in this topic build off of the HelloJSP samples
described in Generating output.
All sample portlets are available from the portlet catalog by searching
for navcode 1WP10017Z. See Sample portlets for more
information.
For standard portlets, user settings are stored, set, and retrieved
using the PortletPreferences object, which represents
name/value pairs in <preference/> elements of the portlet deployment
descriptor. Preferences can be marked read-only, in which case they
can only be modified by someone with administrative privileges, typically
using a configure mode. Otherwise, the portlets can be modified in
any portlet mode.
In the following example, the userName preference is provided,
but set to a null value. This preference is not marked read-only,
so it can be changed by any user with edit access to the portlet.
The portlet retrieves a reference to an instance of PortletPreferences
by calling the getPreferences() method of the PortletRequest object.
The store() method saves the information PortletData. The Java Portlet
Specification allows the portlet to define a preference validator
in the portlet deployment descriptor. If one is defined, then the
validator is called before the store operation is performed.
The following example from jsrHelloUser.war builds
on the jsrHelloJSP.war
sample by adding the doEdit() and processAction() methods to allow
the user to edit preferences. The getValue() method allows the portlet
developer to designate a default value if the preference has not been
set.
For IBM portlets, user settings are saved, retrieved, or deleted
using the Portletdata object. Portlets can store values in the PortletData
object only when the portlet is in edit mode. If the portlet is on
a group page, then information saved in PortletData is available to
all users of the portlet. The portlet retrieves a reference to an
instance of PortletData by calling the getData() method of the PortletRequest
object. The store() method saves the information PortletData. Only
data of the Java String type can be saved in the PortletData object.
PortletData is used in the ibmHelloUser.war sample
to allow users to edit and save their names in which they are addressed
in the greeting. This sample builds on the ibmHelloJSP sample by
adding the doEdit() and the actionPerformed() methods, thus allowing
users to edit the greeting and save their preferences.
The default greeting to display is obtained from the portlet deployment descriptor . The
following example shows the portion of this descriptor with the configuration
parameter defaultUserName set to "User".
Configuration data that is set by the <init-param>
tags are read-only and maintained for all users and every concrete
portlet derived from the portlet. If you need to allow different
configurations for each concrete portlet, then the data should be
set in the <concrete-portlet> tag of the portlet deployment
descriptor.
The doView() method receives control prior to the standard display
for this portlet. The PortletData object is accessed
to obtain the string to display. If the user has not yet specified
a string to display, the default string will be used. The string is
stored in the PortletRequest object to make it
available to the JSP that generates the view markup for this portlet
(viewJSP).
The doEdit() method receives control prior to the display of the
edit page for this portlet. A return URI is created and passed
to the JSP for edit mode using the PortletRequest object.
The save action is included in the return URI using the addAction()
method. The portal passes control to the ActionListener upon
processing the save action. The ActionListener can
preserve the user entered "edit" information in the persistent storage.
As mentioned previously, an ActionListener is
implemented by HelloUser to process the save action. The user enters
a name on the edit page and the actionPerformed() method of the ActionListener obtains
the user-specified string from the PortletRequest object
for storing in the user's persistent storage. The ActionListener is
invoked prior to returning to the doView() method of the portlet,
thus if the user failed to enter a name, the ActionListener can
force the portlet to remain in edit mode, waiting for input from the
user.