Portlet API Version 4.1 - JSP Tag Library Syntax

The portlet container provides tags for use in portlet JSPs. To make these tags available in a JSP, the following directive is required at the beginning of the JSP:

<%@ taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>

createReturnURI

Creates a URI that points to the caller of the portlet. You can pass a parameter or action in the URI by including URIParameter or URIAction between the createReturnURI start and end tags.

Parameters

none.

Example

The following example creates a URI to provide a link that returns the user to the portlet's previous mode or state.

<a href="<portletAPI:createReturnURI/>">
   <portletAPI:text bundle="nls.my_portlet" key="back_label">
      Back
   </portletAPI:text>
</a>

For examples of passing a parameter or action with this tag, see URIParameter and URIAction.

Table of Contents

createURI

Creates an URI that points to the current portlet with the given parameters. You can pass a parameter or action in the URI by including URIParameter or URIAction between the createURI start and end tags.

Parameters

Include at least one of the following attributes:

• state = [PortletWindow.State] (optional)
  indicates the state of the portlet. For example, state="Maximize" creates a URI for a link that maximizes the portlet. If state is not specified, the URI points to the portlet;s current state.

Example

<a href="<portletAPI:createURI state="Maximize"/>">
Maximize!
</a>

For examples of passing a parameter or action with this tag, see URIParameter and URIAction.

Table of Contents

dataAttribute

Returns the value of one or more PortletData attributes. The attribute can be specified by the name parameter. You can also use this tag within a dataLoop tag to retrieve all attributes or a subset of the attributes from PortletData.

Parameters

Include at least one of the following attributes:

• name = [string] (optional)
  indicates the attribute name.

Example

The following example loops through the PortletData attributes, returning only the values with names that start with stock.user.

Your user settings of the stock portlet:<br>
<portletAPI:dataLoop pattern="stock.user.*.">
   <portletAPI:dataAttribute/><br>
</portletAPI:dataLoop>

One specific user setting of the stock portlet:<br>
<portletAPI:dataAttribute name="stock.user.quotes-count"/><br>

Table of Contents

dataLoop

Loops through all attributes in PortletData of the current concrete portlet instance. Use the dataAttribute tag to get the attributes between the dataLoop start and end tag.

Parameters

Include at least one of the following attributes:

• pattern = [string] (optional)
  a regular expression that defines which attributes should be looped.

Example

see dataAttribute

Table of Contents

encodeNamespace

Maps the given string value into this portlet's namespace. Use this tag for named elements in portlet output (for example, form fields or Javascript variables) to uniquely associate the element with this concrete portlet instance and avoid name clashes with other elements on the portal page or with other portlets on the page.

Parameters

• name = [string] (mandatory)
  The value to be mapped into the portlet’s namespace.

Example

In the following example, a text field with the name ‘email’ is encoded to ensure uniqueness on the portal page.

<input border="0"
       type="text"
       name="<portletAPI:encodeNamespace name='email' />">

Table of Contents

encodeURI (deprecated)

Use encodeURL() of the portletResponse instead. For example:

Example

<portletAPI:init/>
<%=portletResponse.encodeURL("/images/result.gif")%>

Table of Contents

if

Through the attributes of this tag, several conditions can be checked. If the condition is true, the content of the tag is written to the page. Otherwise the content is skipped. More than one condition can be evaluated. All conditions must evaluate to be true for the tag contents to be written. Also, each parameter can contain multiple values separated by commas or semicolons. Only one value in the list needs to be true for the condition to evaluate as true.

Parameters

Include at least one of the following attributes:

• mode = [Portlet.Mode]
  evaluates the current mode of the portlet. For example, mode="Edit" is true if the user has placed the portlet in Edit mode.
• previousMode = [Portlet.Mode]
  evaluates the previous mode of the portlet. For example, previousMode="View" is true after a portlet is moved from View to Edit mode.
• state = [PortletWindow.State]
  evaluates the state of the portlet. For example, state="Minimized" is true after the user clicks the minimize icon of the portlet.
• markup = [string]
  evaluates the markup language supported by the client. For example, markup="wml" is true if the client supports WML.
• mimetype = [string]
  evaluates the MIME type supported by the client. For example, mimetype="text/html" is true if the client supports HTML.
• capability = [Capability]
  evaluates the client's capabilities. For example, capability="HTML_CSS" is true if the client supports cascading style sheets.

Example

In the following example, the portlet must be in View mode and the portlet state must be either Normal or Maximized for an image to be rendered. A different image is rendered depending on if the portlet is in Normal state (one of many on the page) or if it's in Maximized state (only portlet on the page).

<portletAPI:if mode="View" state="Normal">
   <img src="images/small.gif">
</portletAPI:if>
<portletAPI:if mode="View" state="Maximized">
   <img src="images/big.gif">
</portletAPI:if>

Table of Contents

init

Provides the following variables that the JSP can use to access the corresponding objects of the portlet API:

• portletRequest
• portletResponse
• portletConfig

Example

After using the init tag, the JSP invokes the encodeNamespace() method of the portletResponse.

<portletAPI:init/>
<%=portletResponse.encodeNamespace("test")%>

Table of Contents

log

Writes a string in the portlet log.

Parameters

• text = [string] (required)
  indicates the message or trace string to be recorded in the portlet log.
• level = [ERROR | WARN | INFO | DEBUG] (optional, default: ERROR)
  indicates the level of the message to be logged. DEBUG writes to PortletTraces.log; the other levels write to Portlet.log.

Example

<portletAPI:log text="This is an error message!"/>
<portletAPI:log text="This is a debug message." level="DEBUG"/>

Table of Contents

settingsAttribute

Returns the value of one or more PortletSettings attributes. The attribute can be specified by the name parameter. You can also use this tag within a settingsLoop tag to retrieve all attributes or a subset of the attributes from PortletSettings.

Parameters

Include at least one of the following attributes:

• name = [string] (optional)
  indicates the attribute name.

Example

The following example loops through the PortletSettings attributes, returning only the values with names that start with stock.config.

Your configuration settings of the stock portlet:<br>
<portletAPI:settingsLoop pattern="stock.config.*.">
   <portletAPI:settingsAttribute/><br>
</portletAPI:settingsLoop>

One specific configuration setting of the stock portlet:<br>
<portletAPI:settingsAttribute name="stock.config.hostname"/><br>

Table of Contents

settingsLoop

Loops through all attributes in PortletSettings of the current concrete portlet. Use the settingsAttribute tag to get the attributes between start and end tag.

Parameters

Include at least one of the following attributes:

• pattern = [string] (optional)
  a regular expression that defines which attributes should be looped.

Example

see settingsAttribute

Table of Contents

text

Writes a localized string to the output stream. When no resource bundle can be found, the content between the start and end tag is written to the output stream.

Parameters

• bundle = [string] (mandatory)
  the resource bundle
• key = [string] (mandatory)
  the key to be found in the resource bundle.

Example

In the following example, the value of the welcome_message parameter is retrieved from the portlet's stockportlet.properties file.

<portletAPI:text bundle="nls.stockportlet" key="welcome_message">
Welcome!
</portletAPI:text>

Notice that "Welcome!" is a default value and is used if the key is not found in the bundle.

Table of Contents

URIAction

Adds a default action to the URI of the createURI and createReturnURI tags. The portlet must have a registered action listener to handle the event.

Parameters

• name = [string] (mandatory)
  The name of the action to add.

Example

<portletAPI:createURI>
   <portletAPI:URIAction name="Add"/>
</portletAPI:createURI>

Table of Contents

URIParameter

Adds a parameter to the URI of the createURI and CreateReturnURI tags.

Parameters

• name = [string] (mandatory)
  The name of the parameter to add.
• value = [string] (mandatory)
  The value of the parameter to add.

Example

<portletAPI:createURI state="Maximized">
   <portletAPI:URIParameter name="showQuote" value="IBM"/>
</portletAPI:createURI>

Table of Contents