<taglib:tutorial lesson="2">

In this part of the tutorial, we will create a Tag that accepts and displays a parameter.

Lesson 2, Your first parameterised Tag
Creating the Hello Tag
Writing the descriptor
Creating a presentation
Using your new Tag

1 Lesson 2, Your first parameterised Tag

In this part of the tutorial, we will create a Tag that accepts and displays a parameter. We will continue to use the setup previously defined.

As you might have noticed in lesson 1, even a simple Tag requires us to write a number of methods that we will be using over and over again. The natural thing to do would be to make a generic Tag that we can extend throughout this tutorial. But surprise! Sun has already done so for us. In the javax.servlet.jsp.tagext package, there is a class called TagSupport that looks like in figure 1 below:

Figure 1: The TagSupport class.

Apart from the methods that is required by the Tag interface, the TagSupport class holds some utility methods that we can take advantage of. Amongst these are:

findAncestorsWithClass() will go one step further of the getParent() method and traverse all parent Tags to this one to find the closest occurrence of a certain Tag.
getId() and setId() gives us ready-to-go methods for setting a parameter called Id for all Tags that extends the TagSupport class. Perfect for simple single parameter type Tags.

We will now leave the TagSupport to get on with the tutorial. If you want to learn more or get a deeper understanding about the TagSupport, read the JSP API or the JSP 1.1 Specification.

2 Creating the Hello Tag

We will now create a Tag called 'HelloTag' that extends the TagSupport class as shown in Figure 2 below.

Figure 2: The HelloTag extends the TagSupport class.

In the '/WEB-INF/classes/com/acme/tag/' directory, create a new class called 'HelloTag.java' with the following content:
package com.acme.tag;

import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;

public class HelloTag extends TagSupport
{
private String name="";
Listing 1: Starting of the Tag.
As you can see in the code given above, we declare that our HelloTag will extend the TagSupport class. The variable name above will hold an optional name that will be used later in the Tag.

Add the constructor:

public HelloTag()
{
super();
}

Listing 2: The constructor.

Add the following method:
public void setName(String name)
{
this.name=name;
}
Listing 3: Adding the setName method.
The JSP container calls the method above if a name is submitted to the Tag. How then will the JSP container know what to set? Well, well go into that below.

Now add the following method:

public int doEndTag() throws javax.servlet.jsp.JspTagException
{
try
{
pageContext.getOut().write("Hello "+name+"!");
}
catch(java.io.IOException e)
{
throw new JspTagException("IO Error: " + e.getMessage());
}
return EVAL_PAGE;
}
}

Listing 4: Overriding the doEndTag method.

The method above will use the PageContext to get a JspWriter class. It will then use this Writer to write a message to the encapsuling JSP page.

As the SupportTag has implemented a doStartTag() method that returns SKIP_BODY, we do not need to implement that or any other method that we don't want to override.

By now, your HelloTag.java should look like this. Store the sourcecode in the /WEB-INF/classes/com/acme/tag/ directory as HelloTag.java

Compile your Tag

3 Writing the descriptor

With the new Tag in place, we should add a descriptor of our new Tag to the Tags descriptor we created in the first lesson.

Open your 'taglib.tld' from your '/WEB-INF' directory with your favourite editor.

Add the following description for your new Tag:

<tag>
<name>hello</name>
<tagclass>com.acme.tag.HelloTag</tagclass>
<bodycontent>empty</bodycontent>
<info>A Hello Tag</info>
<attribute>
<name>name</name>
<required>false</required>
<rtexprvalue>false</rtexprvalue>
</attribute>
</tag>

Listing 5: Adding a Tag descriptor for the Tag.

This will tell our JSP container that the new tag can accept an attribute called Name and that the Tags body should be empty. The <rtexprvalue> that is set to false will tell the Container that the name attribute will not be evaluated at runtime (i.e. can not be a dynamic value).

By now, your taglib.tld should look like this. Store the descriptor in the /WEB-INF/ directory as taglib.tld.

4 Creating a presentation

In order to test our new Tag, we need to write a JSP page that uses it.

Create a new file called 'hello.jsp' in your '/taglib-tutorial-web/' directory with the following content:

<%@ taglib uri="mytags" prefix="mt" %>
<HTML>
<HEAD>
<TITLE>Hello!</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF">
<HR>
<mt:hello name="foo"/>
<HR>
</BODY>
</HTML>

Listing 6: A sample JSP page.

In the page above, we first tell the Container a reference to our Taglib descriptor. We then use the HelloTag by using its defined name ('hello') with a name attribute of "foo".

By now, your hello.jsp should look like this. Store the file in the taglib-tutorial-web/ directory as hello.jsp.

5 Using your new Tag

Its now time to test your new tag.

Open the URL http://localhost/taglib/hello.jsp in a normal web browser. Hopefully the result looks like this.

Continue with lesson 3, "Writing a BodyTag".