E-mail    Print       Blog

Easy Custom Tags with Tag Files, Part 1

Two new features in JSP 2.0 deal with custom tag libraries. The first is the new javax.servlet.jsp.tagext.SimpleTag interface, which simplifies the life-cycle of a tag handler. The second feature simplifies the whole process of writing tag extensions entirely. The latter is a radical change, I would say. For the first time, you don't need a tag library descriptor for your custom tags. Nor do you have to compile your tag handlers. Now, even those who don't understand Java can write custom tags. This article discusses tag files in detail. The first part of this article introduces tag files and presents a few examples. Part two will deal with the more advanced aspects of tag files and will discuss the packaging of tag handlers based on tag files. The sample application that is covered in this article can be downloaded here. To run the application, you need a JSP-2.0-compliant JSP container, such as Tomcat 5. You need to be familiar with JSP and tag extensions to understand this article well.

Tag extensions are great. They allow you to write completely script-free JSP pages, thus promoting the separation of labor: page authors and Java programmers can work simultaneously, on the tasks that best suit them. However, writing custom tags is a tedious chore, involving writing and compiling a tag handler and defining a tag in the tag library descriptor. JSP 2.0 adds the javax.servlet.jsp.tagext.SimpleTag interface, which you can use to write simple tag handlers. However, SimpleTag does not make the whole process simpler.

Introduction to Tag Files

Writing a traditional custom tag requires two steps:

1. Writing and compiling a tag handler.
2. Defining the tag that is associated with the tag handler.

Tag files simplify the process. First, tag files don't need to be compiled. They are compiled as they are invoked. Also, tag files allow tag extensions to be written using only JSP syntax. This means someone who does not know Java can also write tag extensions!

Secondly, a tag element in a tag library descriptor describes the name to be used in a JSP page to reference the custom action. Using tag files, the name of a custom action is the same as the tag file representing the action. Therefore, you don't need a tag library descriptor at all.

Note: JSP containers may choose to compile tag files into Java tag handlers, or interpret the tag files. For example, Tomcat 5 translates tag files into simple tag handlers whose classes implement the javax.servlet.jsp.tagext.SimpleTag interface.

A tag file looks like a JSP page. It can have directives, scripts, EL expressions, and standard and custom tags. A tag file has the .tag or .tagx extension and can also include other files that contain a common resource. An include file for a tag file has a .tagf extension.

To work, tag files must be placed in the WEB-INF/tags directory under your application directory or a subdirectory under it. Just like tag handlers, tag files can also be packaged.

A number of implicit objects are available from inside of a tag file. You can access these objects from a script or an EL expression. Table 1 lists all of the implicit objects available in a tag file.

Table 1. The implicit objects

Note that these implicit objects are similar to those available in a JSP page.

Your First Tag File

This section shows how easy it is to write a tag file and use it. The example consists of one tag file and one JSP page that uses the tag file. The directory structure of the application is depicted in Figure 1.

Figure 1. The directory structure

The tag file is called firstTag.tag and looks like this:

<%@ tag import="java.util.Date" 
  import="java.text.DateFormat"%>
<% 
  DateFormat dateFormat = 
    DateFormat.getDateInstance(DateFormat.LONG);
  Date now = new Date(System.currentTimeMillis());
  out.println(dateFormat.format(now));
%>

As you can see in the above listing, a tag file looks similar to a JSP page. The firstTag.tag file has a tag directive with two import attributes and some script. The output of this tag file is the current date in long format. To use this tag file as a tag extension, all you need to do is save it in the WEB-INF/tags directory of your application. The tag file name is important because it indicates the tag name. Therefore, for the tag file with the name firstTag.tag, the tag name will be firstTag.

Here's the firstTagTest.jsp page that uses the firstTag.tag file.

<%@ taglib prefix="easy" 
  tagdir="/WEB-INF/tags" %>
Today is <easy:firstTag/>

You can invoke the firstTagTest.jsp page using this URL (assuming you use Tomcat 5 on port 8080):

http://localhost:8080/tagfiles/firstTagTest.jsp

The result is shown in Figure 2.

Figure 2. Tag file in action

Tag File Directives

Just like JSP pages, tag files can use directives to control how the JSP container will compile or interpret the tag files. Tag file directives have the same syntax as the directives you can use in JSP pages:

<%@ directive (attribute="value")* %>

The asterisk (*) means that what is enclosed in the brackets can be repeated zero or more times. The syntax can be rewritten in a more informal way, as follows:

<%@ directive attribute1="value1"
  attribute2="value2" ... %>

Attributes must be enclosed by single quotes or double quotes. White space after the opening <%@ and before the closing %> is not required, but can improve readability.

Some of the directives you can use in a tag file are the same as those for JSP pages, except that you don't have a page directive. Instead of the page directive, you have the tag directive. Also, in tag files, there are two more directives: attribute and variable. Table 2 lists all of the directives that can appear in a tag file.

Table 2. Tag file directives

Each of the directives is given below.

The tag Directive

The tag directive is similar to the page directive you can use in a JSP page. Here is the syntax of the tag directive:

<%@ tag (attribute="value")* %>

The syntax can be expressed in the following more informal form:

<%@ tag attribute1="value1" attribute2="value2" ... %>

The list of attributes for the tag directive is given in Table 3. Note that all tag directive attributes are optional.

Table 3. The tag directive's attributes

Except for the import attribute, all other attributes can only appear once within a tag directive or in multiple tag directives of the same tag file. For example, the following tag file is invalid because the body-content attributes appear more than once in multiple tag directives:

<%@ tag display-name="Your first tag file"
 body-content="scriptless" %>
<%@ tag body-content="empty" %>

The following is a valid tag directive because the import attribute can appear as many times as desired.

<%@ tag import="java.util.Enumeration"
 import="java.util.Iterator" %>

The following is also valid:

<%@ tag body-content="empty"
import="java.util.Enumeration" %>
<%@ tag import="java.sql.*" %>

Related Articles

Easy Custom Tags with Tag Files, Part 2
In part two of his series on JSP Tag Files, Budi Kurniawan continues his coverage of this hassle-reducing technology. This week he looks at variables, jsp:doBody, jsp:invoke, and how to package your tag files in a jar file.

View all java.net Articles.