Tag File Directives

Like JSP pages, tag files also have directives. The taglib and include directives are identical. Tag files have these additional directives:

• tag

• attribute

• variable

The tag directive defines the overall tag characteristics. It's similar to the page directive. The attribute directive is used to declare custom action attributes. Lastly, the variable directive defines the variables that are exposed to the calling JSP or tag handler.

The tag Directive

The tag directive describes tag files. Like the page directive, there can be more than one tag directive in a translation unit, but there can be only one occurrence of any attribute/value, excepting the import attribute.

These attributes have the same syntax and semantics of the equivalent attribute in the page directive: language, import, pageEncoding, and isELIgnored.

The display-name attribute is a short name used by tools to identify the tag. It defaults to the name of the tag file, without the .tag extension.

The body-content and dynamic-attributes attributes are analogous to their counterparts in the tag library descriptor for tag extensions and use the same values.

Both small-icon and large-icon are intended to provide the location of an image that represents the tag as an icon in a tool.

A description gives the tag developer an opportunity to provide text that describes the tag. The developer can further document the tag by giving an example of how to use the tag in an example attribute.

The attribute Directive

As mentioned earlier, custom action attributes are declared using the attribute directive. Its own attributes correspond with the subelements of the attribute element in the TLD. Consequently, you're already familiar with them. They are name, required, fragment, rtexprvalue, type, and description.

The variable Directive

Within a tag file, scripting variables that are exposed to calling pages are defined by the variable directive. Like the attribute directive, its attributes mirror the subelements of the variable element in the TLD. They are name-given, name-from-attribute, variable-class, declare, scope, and description. One additional directive attribute, alias, works with name-from-attribute to define a locally scoped member variable in the tag handler that holds the value of the scripting variable. The container will synchronize the member variable with the scripting variable automatically, in much the same way that we did it manually when we discussed variables earlier.

Standard Actions Used with Tag Files

Two additional standard actions are necessary to work with tag files. There has to be a way to work with the body of the tag and another to work with attributes that are JSP fragments. <jsp:doBody> and <jsp:invoke> are standard actions that respectively evaluate the tag body and attributes that are fragments. The actions' syntax and semantics are nearly identical. Both operate on JSP fragments. The only difference appears because <jsp:doBody> does not need to identify the fragment it invokes. As a result, <jsp:invoke> has an additional action element attribute, fragment, which supplies the name of the fragment associated with the action.

The common action element attributes are var, varReader, and scope. var and varReader are used to store the result of the fragment invocation. The value of var is the name of a java.lang.String object, and the value of varReader is the name of a java.io.Reader object. These objects will be created by the container in the scope identified by scope. The possible values for scope are page, request, session, and application. The default scope is page. var and varReader cannot be used together. When neither is specified, the result of the invocation goes to the JspWriter of the JspContext associated with the JspFragment.

Using Tag Files

The simple example shown in Listing 16.23 demonstrates how to use tag files with fragment attributes.

Listing 16.23 Source Code for showtext.tag

<%@ attribute name="italic" fragment="true" %>
<%@ attribute name="bold" fragment="true" %>
<%@ variable name-given="text" scope="NESTED" %>

<jsp:doBody var="text" />

<table border="0">
   <tr>
     <td>
        <jsp:invoke fragment="italic"/>
     </tdD>
   </tr>
   <tr>
     <td>
        <jsp:invoke fragment="bold"/>
     </td>
   </tr>
</table>

Examining showtext.tag, you can see that it declares two attributes that are fragments. It also declares a scripting variable, text, that becomes visible to the calling page for the time between the start and end tags of the custom tag. It then invokes the standard action <jsp:doBody>, saving the result to a page-scoped String object named text. This object is synchronized by the container with the scripting variable declared earlier. The bulk of the tag is template text to create a simple table. The content of the table detail (TD) elements is the output produced by attributes that are fragments. Listing 16.24 shows showtext.jsp.

Listing 16.24 Source Code for showtext.jsp

<%@ taglib prefix="tags" tagdir="/WEB-INF/tags" %>

<tags:showtext>
    <jsp:attribute name="italic">
       <i>${text}</i>
   </jsp:attribute>

   <jsp:attribute name="bold">
      <b>${text}</b}
   </jsp:attribute>

   <jsp:body>
      Sample Text
   </jsp:body>
</tags:showtext>

The first act of showtext.jsp is to declare that it uses the custom tag that was created earlier and to give it a prefix of "tags". It then calls the tag handler, giving it two attributes and a body. Each of the attributes is designed to simply display the value of the text scripting variable in an italicized or bolded font. As you recall from Listing 16.20, the tag handler invokes the body and both attributes to produce the overall output.