[ Team LiB ] Previous Section Next Section

Recipe 22.11 Creating a JSP Tag File


You want to create a custom tag in the form of a tag file.


Create the tag file using JSP syntax and with an extension of .tag or .tagx. Place the tag file in WEB-INF/tags or in META-INF/tags inside a JAR file, or in a subdirectory of either of these directories.


JSP 2.0 introduced tag files, which are custom tags that you write using JSP syntax. Tag files are designed to allow developers with little or no Java experience to create simple tags using only JSP and XML elements. In addition, tag files do not require a TLD, although you can describe a tag file in a TLD (see Recipe 22.12). If you create the tag file, then drop it in the WEB-INF/tags directory, the JSP container compiles the file into a tag handler class the first time its associated tag is used in a JSP.

The JSP container converts the tag file into a class that extends javax.servlet.jsp.tagext.SimpleTagSupport. See Recipe 22.8 for more details on that class.

Tag files have introduced a few more directives and standard actions, such as the tag and attribute directives, as well as the jsp:doBody action. Example 22-9 shows these new syntax elements. The example creates the same logo tag we have worked on throughout this chapter, but uses tag file format.

Recipe 22.14 shows how the resulting custom tag can be used in a JSP.

Example 22-9 uses a tag directive to specify that the tag's body content (the text that appears between the start and end tags) is scriptless. This means that the body content contains only template text, EL code, and JSP action elements.

If you are defining an empty tag, the body-content value is "empty." If the tag accepts JSP code in its body, use "JSP" for this value. The fourth body-content option is "tagdependent," meaning that the tag itself interprets the code in its body (such as SQL statements).

Since a tag file can use normal JSP syntax, Example 22-9 uses a taglib directive to use the JSTL (see Chapter 23). Then the example defines each one of the tag's attributes.

Remember that tag and attribute are directives, so their code starts with "<%@."

Example 22-9. A tag file generates a custom tag that inserts a logo in a JSP
<%@ tag body-content="scriptless" description="Writes the HTML code for inserting a logo." 

<%@ taglib prefix="c" uri="http://java.sun.com/jstl/core" %>

<%@ attribute name="heading" required="true" rtexprvalue=
  "true" description="The heading level for the logo."%>

<%@ attribute name="image" required="true" rtexprvalue=
  "true" description="The image name for the logo."%>

<%@ attribute name="width" required="true" rtexprvalue=
  "true" description="The image width for the logo."%>

<%@ attribute name="height" required="true" rtexprvalue=
  "true" description="The image height for the logo."%>
<img src="<c:out value="${imgDir}${image}"/>" width=
  "<c:out value="${width}"/>" height="<c:out value=
    "${height}"/>" align="left">

<H<c:out value="${heading}"/>><jsp:doBody/></H<c:out value="${heading}"/>>

The attributes for the attribute directive are the same as the attributes that you use for a JSP 1.2-style TLD file (see Recipe 22.2). Since a tag file accepts plain template text, this is how we have set up the HTML img tag that the tag file is designed to generate.

The img tag gets the values for its own attributes using the c:out JSTL tag and the EL (see Chapter 23). For example, the expression "${imgDir}" returns the value for a stored object attribute of the same name, which specifies a directory that contains the image used in the logo. The expression "${image}" returns the value of the tag's image attribute which, by this line of the code, has already been set by the user.

The jsp:doBody standard action is a nifty way to output the text between the custom action's start tag and end tag.

The jsp:doBody action, as well as the tag , attribute, and variable (not shown in this recipe) directives, can be used only in tag files.

See Also

The JSP 2.0 specification web page: http://jcp.org/en/jsr/detail?id=152; Recipe 22.2 and Recipe 22.3 on creating TLD files for tag libraries; Recipe 22.4 and Recipe 22.5 on packaging a tag library in a web application; Recipe 22.6 on using the custom tag in a JSP; Recipe 22.7 on handling exceptions in tags; Recipe 22.8 and Recipe 22.9 on creating a simple tag handler; Recipe 22.10 on using the simple tag handler in a JSP; Recipe 22.12-Recipe 22.14 on using a JSP tag file; Recipe 22.15 on adding a listener class to a tag library; the custom tag sections of Hans Bergsten's JavaServer Pages, Third Edition (O'Reilly).

    [ Team LiB ] Previous Section Next Section