AVAJAVA Web Tutorials

The JSPW 2.0 specification introduced Simple Tag Handlers for writing custom tags. A Simple Tag Handler implements the SimpleTag interface. SimpleTagSupport is a class that implements all of the methods of the SimpleTag interface. In general, if you're writing a basic tag, you can extend SimpleTagSupport and override the doTag() method, where you can place your code to generate content for the tag.

This tutorial uses a project with the following structure.

We'll create a simple tag handler class for displaying images called ImageTag. It extends SimpleTagSupport and implements the doTag() method. It contains three fields, "url", "showBorder", and "showUrl" and has setter methods for these variables so that they can be set. The real work happens in doTag(). We get the PageContext by calling getJspContext(), and then we get a JspWriter from the PageContext by calling getOut() on the PageContext. This is the writer that allows us to write out content to our JSP.

If "showUrl" is true, ImageTag will display an h3 header with the URL of the image. It will create an img HTMLW tag, setting its src value to the value of the "url" variable. If "showBorder" is true, it will create a 1 pixel border around the image.

ImageTag.java

package test;

import javax.servlet.jsp.JspException;
import javax.servlet.jsp.JspWriter;
import javax.servlet.jsp.PageContext;
import javax.servlet.jsp.tagext.SimpleTagSupport;

public class ImageTag extends SimpleTagSupport {

	private String url = "";
	private boolean showBorder = false;
	private boolean showUrl = false;

	public void setUrl(String url) {
		this.url = url;
	}

	public void setShowBorder(boolean showBorder) {
		this.showBorder = showBorder;
	}

	public void setShowUrl(boolean showUrl) {
		this.showUrl = showUrl;
	}

	public void doTag() throws JspException {

		PageContext pageContext = (PageContext) getJspContext();
		JspWriter out = pageContext.getOut();

		try {
			StringBuffer sb = new StringBuffer();
			if (showUrl) {
				sb.append("<h3>");
				sb.append(url);
				sb.append("</h3>\n");
			}
			sb.append("<img ");
			if (showBorder) {
				sb.append("border=\"1\" ");
			}
			sb.append("alt=\"\" src=\"");
			sb.append(url);
			sb.append("\"/>");

			out.println(sb.toString());

		} catch (Exception e) {
			e.printStackTrace();
		}

	}
}

We define our tag in the test.tld file, which we place in WEB-INF/tlds. I used the JSP Tag Library 1.2 DTD, which helped me write the TLD in EclipseSW since it validated my TLD and I could do code completion (control-space) to automatically insert tags. The tag handler class is specified via the tag-class element. The tag has three attributes (url, showBorder, and showUrl). The url attribute is required and can be a calculated value (its rtexprvalue is set to true). The showBorder and showUrl attributes are boolean and are not required.

test.tld

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" "http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
<taglib>

	<tlib-version>1.0</tlib-version>
	<jsp-version>2.0</jsp-version>
	<short-name>testing</short-name>
	<uri>http://www.tomcat-demo.com/testing</uri>
	<description>This is a demonstration tag library</description>

	<tag>
		<name>img</name>
		<tag-class>test.ImageTag</tag-class>
		<body-content>empty</body-content>
		<description>This tag is for displaying images</description>
		<attribute>
			<name>url</name>
			<required>true</required>
			<rtexprvalue>true</rtexprvalue>
		</attribute>
		<attribute>
			<name>showBorder</name>
			<required>false</required>
			<rtexprvalue>false</rtexprvalue>
			<type>boolean</type>
		</attribute>
		<attribute>
			<name>showUrl</name>
			<required>false</required>
			<rtexprvalue>false</rtexprvalue>
			<type>boolean</type>
		</attribute>
	</tag>

</taglib>

Now, I'll create an index.jsp file that utilizes the tag that we just specified. To reference the TLD file, I added the following taglib directive, which has its uri value set to the uri value specified in the TLD file.

<%@ taglib prefix="mytest" uri="http://www.tomcat-demo.com/testing"%>

This lets me reference the tags (in this case, just one tag) in the TLD file via 'mytest'. Here, we can see how I can use code-completion in Eclipse to reference the tag that we created.

The completed index.jsp file is shown here. It displays images in four different ways. First, it displays the tools.gif image and doesn't set the optional other attributes. Next, calls the tag with tools.gif, but includes the showBorder attribute set to true. Next, it displays the world.gif image with showUrl set to true, and finally it displays world.gif with showUrl set to true and showBorder set to true.

index.jsp

<%@ page contentType="text/html; charset=ISO-8859-1"%>
<%@ taglib prefix="mytest" uri="http://www.tomcat-demo.com/testing"%>

<table border="1" cellpadding="2" cellspacing="0">
	<tr>
		<td><mytest:img url="tools.gif" /></td>
		<td><mytest:img url="tools.gif" showBorder="true" /></td>
		<td><mytest:img url="world.gif" showUrl="true" /></td>
		<td><mytest:img url="world.gif" showUrl="true" showBorder="true" /></td>
	</tr>
</table>

(Continued on page 2)