![]() | |
Sun Java System Portal Server 6 2005Q1 Technical Reference Guide |
Chapter 58
OverviewThis chapter contains the following sections:
IntroductionSun Java System Portal Server uses two types of tags: JSP tags and Desktop template tags. JSP tags are used in the JavaServer Pages (JSPs) and template tags are used in the HTML pages of the Desktop.
Types of Tags
The Portal Server software Desktop tag library consists of six parts:
- Core tags that can be used on any provider or container that implement the PAPI interface.
- Tags that can be used to operate on a provider or container that support the ProviderContext and ContainerProviderContext interfaces.
- Tags that operate on specific container building-block providers (SingleContainer, TableContainer, TabContainer, and so on).
- JSP Standard tag libraries from Apache.
- Tags that support the Search function.
- Tags that provide theme support in the Desktop.
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.
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 JavaBeans 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.
These tags, which start with the prefix obtain, set up the context (storing the container or provider in question into the pageContext).
These tags validate that the provider in context can legally use the tags in the TLD.
These tags serve as wrappers of PAPI, ProviderContext, ContainerProviderContext, and the specific containers in the Sun Java System Portal Server software.
Tag Attributes, Return Values, and Exceptions
Attributes
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:
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.
Exceptions
The tag library provides five types of exceptions.
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.
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.
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.
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.
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 SOIF.
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.
Exceptions
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 HierarchyThe 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 DescriptorsThe Desktop tag library has the following Tag Library Descriptors (TLDs) in the /etc/opt/SUNWps/desktop/default/tld directory. The tag library is exposed, for convenience, through using multiple TLDs, so that tags are in their appropriate functional area.