Tag Library Documentation

Chrysalis uses several custom tag libraries to support JSP development. These libraries are named after their preferred tag prefix.

Library Description
jutil A library of JSP utility tags.
jhtml A library of JSP html-related tags.
ji18n A library of JSP internationalization tags.

The documentation of these libraries is written for page developers who know little or no Java. These page developers should have a basic understanding of objects (Java Beans) and their properties. Where appropriate, a Technical Note may be added with additional information for Java developers.

Common Tag Attributes

The tags in these libraries use some common attributes to manipulate business objects (Java Beans).

Attribute Description
var An attribute used to declare a new variable to hold an object.
object An attribute used retrieve an existing object from a variable.
property An attribute used to retrieve a property value from a object.
el An attribute used to specify a tag value using JSTL Expression Language (el).

var

A var attribute is used to declare a new variable to hold a object. This variable's scope is the entire page. The object assigned to the variable depends on the tag being used. If this object needs to be used in another tag, that tag's object attribute should match the var declaration.

<jutil:use var="item" controller="Catalog" />
<jutil:print object="item" property="name" />

Each time an object is assigned to a var, this object becomes the "default object". This object is used for tags that omit their object attribute. The default object changes each time a new variable is declared.

Some care must be taken when naming variables. If the variable name matches the name of another variable elsewhere in the page, the old value for that variable will be overwritten.

Technical Note: All variable values are stored in the JSP page scope. These libraries provide no general mechanism for defining new variables with scopes greater than that of a single page, although it is possible to retrieve values from greater scopes. This is a deliberate deliberate design feature of Chrysalis; view pages should not alter data outside their own scope.

object

An object attribute is used retrieve an existing object from a variable value. The object attribute name should match the var name holding the desired object. For most tags, the object attribute is optional. If omitted, the tag will use the "default object", which is the most recent object value assigned to a variable.

<jutil:use var="item" controller="Catalog" />

<!-- Print the "name" property of the "item" object: -->
<jutil:print property="name" />

<!-- The above is equivalent to: -->
<jutil:print object="item" property="name" />

For a few tags, an alternate name for the object attribute is used, to clarify what kind of object it should be (e.g. the collection attribute of the <jutil:forEach> tag). Where this is the case, the documentation indicates that the attribute functions as an object attribute.

property

A property attribute is used retrieve a property value from an object.

For tags that have both var and property attributes, the property attribute is optional. If omitted, the property attribute defaults to the value of the var attribute.

<!-- Use the "order" property of the Cart controller: -->
<jutil:use var="order" controller="Cart" />

<!-- The above is equivalent to: -->
<jutil:use var="order" controller="Cart" property="order" />

Technical Note: The value is retrieved using the appropriate getter method of the object, as per the JavaBean specifications.

el

In addition to the options described above, a few Chrysalis tags support JSTL (JSP Standard Tag Language) expressions. These tag have an "el" attribute, which provides an alternative to the normal "object" and "property" attributes. JSTL expressions are particularly useful for defining complex conditions in <jutil:if> tags.

<!-- Without EL -->
<jutil:print object="item" property="name" />

<!-- With EL -->
<jutil:print el="${item.name}" />

You may wonder why we are duplicating this the expression language logic of JSTL rather than simply using JSTL itself. JSTL only works with JSP 1.2+, and one of the design goals of Chrysalis is to comply with the Servlet 2.2/JSP 1.1 standard. The Chrysalis copy of the JSTL Expression Language has been modified to work on older servlet engines.

If you are using a Servlet 2.3/JSP 1.2 container, Chrysalis is compatible with JSTL, and there is nothing preventing you from combining JSTL tag logic with Chrysalis tags. There are deliberate similarities between Chrysalis tags and JSTL to simplify this integration. The only major issue is that JSTL var attributes will not set a "default object", and therefore JSTL variable values must be explicitly referenced with object attributes or by using expression language.

The documentation for the JSTL and its Expression Language can be found at: http://java.sun.com/products/jsp/jstl/.