Sun Java System Portal Server 7.1 Technical Reference

Chapter 52 Overview of Desktop Tag Library

This chapter contains the following sections:


Sun Java System Portal Server 7.1 uses two types of tags: JSP tags and Desktop template tags. JSP tags are used in the JSPs and template tags are used in the HTML pages of the Desktop.

Types of Tags

The Portal Server 7.1 software Desktop tag library consists of six parts:

Desktop Template Tags

This section describes the tags used in the HTML templates of the Desktop.

How the Desktop Template Tags Work

A template produces a channel, page, or table. The tags in a template are swapped with for real values at runtime. For example, the [tag:netmailSettings] tag swaps in a partial HTML template that has mail server information. The [tag:fontFace] tag swaps in the value of the font that the user has chosen on the Theme page. The [tag:switchColumns] tag swaps in the switchColumns.js template file, a JavaScript template, that lets users change how the columns are displayed on their Desktops.

Kinds of Tags Used in the Desktop Templates

The following is a two column table: column one lists the tag and column two provides a brief description of the corresponding tag.

[url: url]

url will be encoded at run time with the ProviderContext.encodeURL() method.

[surl: url]

url will be pre-appended by the static root at run time. For example, in a Web Server instance,

portal/web-apps/desktop/imag es/nothing.gif

dturl will be replaced by the desktop URL at run time. For example,


JavaServer Pages Tags

In JavaSever Pages technology, actions are elements that can create and access programming language objects and affect the output stream. JSP technology supports reusable modules called custom actions. You invoke a custom action by using a custom tag in a JSP. A tag library is a collection of custom tags. The Desktop custom tag library contains tags that you use to perform Desktop operations for JSPs.

Purpose of Tag Library

Before tag libraries, JSPs were difficult to maintain because you were forced to use JavaBeansTM components and scriptlets as the main mechanism for performing tasks. Custom actions, that is, a tag library, alleviate this problem by bringing the benefits of another level of componentization to JSP. A tag library encapsulates recurring tasks so that they can be reused across more than one application. The tags in the JSP tag library fall into three basic groups: context setup tags, validator tags, and normal tags.

Context setup tags

These tags, which start with the prefix obtain, set up the context (storing the container or provider in question into the pageContext).

Validator tags

These tags validate that the provider in context can legally use the tags in the TLD.

Normal tags

These tags serve as wrappers of PAPI, ProviderContext, ContainerProviderContext, and the specific containers in the Sun Java System Portal Server 7.1 software.

Tag Attributes, Return Values, and Exceptions


You can pass two kinds of attributes to the Desktop library tags:


The simplest way to pass in an attribute is to specify it as a string, for example:

<dt:sometag attribute1="myAttribute"/>

The string myAttribute becomes the value of attribute1. If a tag expects an integer attribute, use the following:

<dt:sometag attribute1="12345"/>

The tag uses the corresponding Java classes (java.lang.Integer) to translate the string to an integer value. The same applies to all the primitive Java types (boolean, int, and so on).


Sometimes you cannot pass in an attribute as a string. For example, it is impossible to specify a provider object as a string. In this case, the attribute needs to be passed in as a reference defined in the pageContext. You do so by concatenating the character $ with the name of the object stored in the pageContext, for example:

<dt:sometag attribute1="$myAttribute"/>

In this example, the value of attribute1 is whatever object is stored in the pageContext. The method pageContext.findAttribute() is used, not getAttribute(). So it is possible to define some value in the request object and pass this object in as a reference.

Note –

This mechanism is the main form of communication between tags in the Desktop tag library as well as other tags in other tag libraries (for example, jsptl).

Return Values

Tags with attributes id and scope (even if they are optional) are expected to return a value as a result of using the tags. Values can be “returned” in two ways:

Print to the JspWriter stream

If the attribute id is not given when using a tag, the tag prints the value to the JspWriter stream. This results in the value showing up in the HTML code generated by the JSPs. In this case, the attribute scope is ignored.

Store the value in pageContext

If you specify the attribute id when using a tag, the tag stores the value to the pageContext as an attribute with a name specified by the id attribute. This operation overwrites whatever original value the attribute has. In addition to the id, you can also define the attribute scope. It can have one of the following values: page, request, session, or application. These values correspond to the PAGE_SCOPE, REQUEST_SCOPE, SESSION_SCOPE, and APPLICATION_SCOPE defined in javax.servlet.jsp.PageContext. This specifies the scope in which to save the value. If no or unrecognized scope is given, the default is to save it in page scope.


The tag library provides five types of exceptions.

Invalid Tag Sequence

Occurs when obtain tags are nested in an invalid sequence. See Using the Desktop Tag Library in Your Application for the sequencing of the obtain tags. The name of the first tag that violates the sequence is provided.

Invalid Provider Type

Occurs when a validation test is not passed. That is, the TLD does not support the current provider in the context. The name of the validator tag that failed is provided.

Invalid Parameter

Occurs when an attribute passed in with the tag is not a legal parameter for the tag. The name of the attribute that causes the problem is provided.

Undefined Parameter

Occurs when an attribute is passed in as reference, but the attribute is not defined in the page context. The name of the attribute is provided.

Empty Context

Occurs when there is no container or provider in the context to operate on. Most likely, the appropriate obtain tag is missing so the context is not set up properly.

The many of the Java classes that support these tags reside in a JAR file desktoptl.jar in the Web-Container-Instance/portal/web-apps/WEB-INF/lib directory. The classes for the jx.tld and jr.tld tags reside in the jsptl.jar file.

Search Tags

The Search tag library contains tag wrappers for the SearchContext Java API. SearchContext is an extension of the Search API with convenient methods for advanced search and search result status. The Search tag library can be divided into various categories depending upon where the tags should be used.

Types of Tags

The search.tld file does not have any context setup or validator tags. All of the normal tags in the search.tld file have a bodycontent of empty except searchContext and search result.

Tag Attributes

A number of attributes have a value of true for rtexprvalue, which means the value for this attribute can be obtained at run time or it can be hardcoded. These attributes are listed as dynamic attributes.


When you are developing JSPs or doing Search administration tasks, you may see the following exceptions:

Taglib Use Errors

Search Request Errors

Desktop Tag Library Hierarchy

The Desktop tag library can be viewed as a wrapper of PAPI, ProviderContext, ContainerProviderContext, and specific container building-block providers in the Portal Server software. Thus, a hierarchy is implied.

For example, the ContainerProviderContext (interface) extends ProviderContext (interface). When you use a tag in desktopContainerProviderContext.tld, it also make sense to use it in desktopProviderContext.tld. Similarly, when you use a tag in desktopProviderContext.tld, it also makes sense to use provider tags in desktop.tld because ProviderAdapter implements Provider. By putting the tag in the level that provides the most use, you will not have to make duplicate tags.

At the bottom of this chain are the specific containers (single, table, and tab). Because all these containers extend JSPContainerProviderAdapter, they can use tags in their respective TLDs, as well as tags in desktopContainerProviderContext.tld, desktopProviderContext.tld, and desktop.tld.

Tag Library Descriptors

The Desktop tag library has the following Tag Library Descriptors (TLDs) in the /var/opt/SUNWportal/portals/<portal_id>/desktop/default/tld directory. The tag library is exposed, for convenience, through using multiple TLDs, so that tags are in their appropriate functional area.


Contains core Desktop tags that bring forward the functionality available from the ProviderContext interface.


Contains tags that bring forward the functionality available from the ContainerProviderContext interface.


Contains tags to operate on providers that extend the ProviderContext.


Contains tags to operate on single container channels. Single container channels are based on JSPSingleContainerProvider or a subclass thereof.


Contains tags to operate on table container channels. Table container channels are based on JSPTableContainerProvider or a subclass thereof.


Contains tags to operate on tab container channels. Tab container channels are based on JSPTabContainerProvider or a subclass thereof.


Contains tags for theme support in the Desktop.


Contains tags for IMProvider class.


Contains tags that accept rtexprvalues for their attributes. This is a JSP Standard tag library from Apache.


Contains tags that accept attribute values specified using the “expression languages” that JSPTL introduces, which currently is only simplest possible expression language (SPEL). This is a JSP Standard tag library from Apache.


Contains tags for search support in the Desktop.