Struts: The Complete Reference, 2nd Edition

The Nested Tag Library Tags

The following table lists each of the tags in the Nested Tag Library and provides a short description of each tag's purpose.

As mentioned, the majority of the tags in the Nested Tag Library are simply tags from the Bean, HTML, and Logic Tag Libraries to which support for nesting has been added. Thus, they are not individually covered in detail here. Instead, the basic concepts of nesting are discussed because they apply to all the extended tags in the same way. For nonnesting-related information on each of the extended tags, see the descriptions of their base tags in their respective chapters.

The remainder of this section discusses in detail each of the tags that are specific to the Nesting Tag Library, including a complete description of the tag, a table listing each of the tag's attributes, and a usage example for the tag. In the tables that describe each tag's attributes, pay special attention to the Required and Accepts JSP Expression columns.

The Required column simply denotes whether the given attribute is required when using the tag. In addition to the required column denoting whether an attribute is required, the rows for required attributes are highlighted in gray so that you can determine at a glance which attributes are required.

If an attribute is required and you do not specify it when using the tag, the tag will throw a javax.servlet.jsp.JspException at run time. Note that you can declare an error page in your JSP with a page directive to capture any JspExceptions that might be thrown, as shown here:

<%@ page errorPage="error.jsp" %>

If an exception occurs, the page specified by the errorPage attribute will be internally redirected to display an error page.

The Accepts JSP Expression column denotes whether the given attribute's value can be specified with a JSP expression. If a JSP expression is used to specify an attribute value, the expression must comprise the complete value, quote (") to quote ("), as shown here. Correct:

<nested:nest property="<%=result%>">

Incorrect:

<nested:nest property="<%=result%>-result">

Notice in the incorrect example that "-result" is used as part of the value for the property attribute following the expression. This is invalid because there are extra characters between the end of the expression and the ending quote.

A corrected version of the incorrect example follows:

<nested:nest property="<%=result + "-result"%>"/>

The concatenation of "-result" is now part of the expression, and the expression comprises the complete value for the attribute.

The nest Tag

The nest tag is used to define a logical level in a nesting hierarchy and associate an object with it that all of its nested tags are relative to.

Attribute

Example Usage

The following example illustrates how to use the nest tag:

<nested:nest property="address"> Line 1: <nested:text property="line1"/> Line 2: <nested:text property="line2"/> City: <nested:text property="city"/> State: <nested:text property="state"/> Zip: <nested:text property="zip"/> </nested:nest>

Because the nest tag specifies the object that all of its nested tags are relative to, the nested tags only have to specify properties of the nested object.

The equivalent without the Nested Tag Library is shown here:

Line 1: <html:text property="address.line1"/> Line 2: <html:text property="address.line2"/> City: <html:text property="address.city"/> State: <html:text property="address.state"/> Zip: <html:text property="address.zip"/>

As you can see, nesting simplifies JSP development for even this short example; however, the real benefit comes when you have several layers of nesting to handle.

The root Tag

The root tag is used to define the root object of a nested hierarchy of objects. Typically, tags from this tag library and the HTML Tag Library are nested inside the HTML Tag Library's form tag and use the form's Form Bean object as the root of the nested hierarchy. However, the root tag can be used to explicitly set the hierarchy's root object, effectively overriding the Form Bean object.

Attribute

Example Usage

The following example illustrates how to use the root tag:

<nested:root name="employee"> <nested:nest property="address"> Line 1: <nested:text property="line1"/> Line 2: <nested:text property="line2"/> City: <nested:text property="city"/> State: <nested:text property="state"/> Zip: <nested:text property="zip"/> </nested:nest> </nested:root>

All tags nested inside the root tag will use its associated object as the root object for a nested hierarchy. Thus, in the example, the nested text tags will actually be accessing "employee. address.line1" even though they only specify "line1".

The writeNesting Tag

The writeNesting tag is used to render or create a JSP scripting variable for a string representation of the object related to the current nesting level.

Attributes

Example Usage

The following snippet shows the basic usage of the writeNesting tag:

<nested:nest property="address"> Line 1: <nested:writeNesting property="line1"/> </nested:nest>

This example will generate the following output:

Line 1: address.line1

Essentially, this tag generates the fully qualified nested reference for the given property.