1 1

1 2 J2EE JSP Custom Tag Libraries

1 3 JSP: Custom Tag Libraries

1 4 Since JSP 1.1 there has been a very powerful tool called custom tag libraries. The idea is to make complex server-side behavior available for use on a JSP page using a very basic syntax. We have glimpsed this power in the jsp:useBean combination we explored in the previous lecture. One major advantage of custom taglibs is their ability to manipulate JSP content. JSP: Custom Tag Libraries

1 5 To use custom JSP tags, you need to define three separate components: 1.) The tag handler class—this defines the tag’s behavior. 2.) The tag library descriptor file—that maps the XML element names to the tag implementation. 3.) The JSP file that uses the tag library. JSP: Custom Tag Libraries

1 6 JSP: Tag Handler Class

1 7 First of all, this is just another Java class. When you want to define a new tag, you must first write a Java class that does the work you expect your tag to do. This class must implement the javax.servlet.jsp.tagext.Tag interface. Usually, this is accomplished by extending the TagSupport or BodyTagSupport classes. JSP: Tag Handler Class

1 8 So, without further adieu, let’s look at an example: JSP: Tag Handler Class package mypackage; import javax.servlet.jsp.*; import javax.servlet.jsp.tagext.*; import java.io.*; public class FirstTag extends TagSupport { public int doStartTag() { try { JspWriter out = pageContext.getOut(); out.print( “My First Tag” ); } catch( IOException io ) { System.out.println( “FirstTag threw an IOException io” ); } return SKIP_BODY; } If you think about XML, it always has a Start Tag and an End Tag. Usually—but not always—there is a body between the tags. In this case, we’re just giving a start tag. When we return this constant int, “Skip any text you find between the body of the tag.” Notice, I’ve put the tag handler class in a package, so that will be a directory inside the classes directory.

1 9 After we have written our tag handler class, we need to compile it and place it in a directory below the WEB-INF/classes directory. JSP: Tag Handler Class Since we placed our FirstTag class in a package, we have to account for that package in the directory below classes.

1 10 JSP: Tag Library Descriptor File

1 11 So, we’ve finished with step 1, creating the class. Next, we have to announce the tag to the server. JSP: Tag Library Descriptor File JavaclassTaglib.tld The “shortname” is the library name, which will appear to the left of the colon. The tag’s “name” is the part that will appear to the right of the colon. This is the Java class that implements the tag. The class is usually placed in a package.

1 12 JSP: A JSP That Uses The Tag

1 13 Now, we have:  the Tag Handler class  a Tag Library Descriptor File and we still need  the JSP. JSP: A JSP That Uses The Tag

1 14 Here is the JSP that we will use to execute our first tag. Just like any other JSP, we place it in the javaclass directory. JSP: A JSP That Uses The Tag TestFirstTag.jsp The.tld file we just created must be referenced here at the top in a taglib Directive. The prefix parameter tells our JSP which “shortname” prefix to look for inside the.tld file. Since the URI for our.tld file does not specify a path, then we are saying it will be found in the same directory as the JSP.

1 15 Let’s review the process. 1.) Write the tag handler class. Compile. Put in WEB-INF/classes directory in the correct package. 2.) Write the Tag Library Definition file (.tld ), place in javaclass directory. 3.) Write the JSP, place in javaclass directory. The JSP must have the taglib directive before the tag is used. JSP: A JSP That Uses The Tag

1 16 JSP: A More Ambitious Tag

1 17 As the previous tag did not seem worth the trouble, we will look at one that begins to show you how valuable these taglibs are. JSP: A More Ambitious Tag

1 18 For the price of a tiny tag, this will insert a table into our JSP. Let’s remember our three steps: 1.) Tag Handler class 2.) Tag Library Descriptor File 3.) JSP that uses the taglib. JSP: A More Ambitious Tag

1 19 JSP: A More Ambitious Tag Please note that I had to “escape” the double quotes so that the class was able to compile.

1 20 JSP: A More Ambitious Tag I next add the tag to the table definition library. JavaclassTaglib.tld

1 21 Finally, here is the JSP that uses this new tag. JSP: A More Ambitious Tag I don’t know about you, but this part looks pretty easy. And, in a normal environment, all of these tags would have already been written. TestTableTag.jsp

1 22 This is the resulting page. JSP: A More Ambitious Tag

1 23 Recall that our doStartTag() method ended with the return value SKIP_BODY, which tells the tag to skip anything it found between the start and end tags. Let’s see if that really does what we expect. JSP: A More Ambitious Tag

1 24 We change our JSP so that it includes an end tag. JSP: A More Ambitious Tag from TableTag.java

1 25 JSP: More on the TLD

1 26 For simplicity, I omitted one of the tags that you should include if your body content is supposed to be empty. JSP: More on the TLD If the tag is expecting normal JSP content in the body, you use this: If the tag takes care of its own body:

1 27 JSP: Assigning Attributes to Tags

1 28 Although our examples so far have not used them, it is common to pass attributes to tags so the values of the attributes can be incorporated into the HTML that is generated in the tag. This is where our knowledge of the ways of JavaBeans comes in handy, because that’s exactly the way it works. JSP: Assigning Attributes to Tags

1 29 The tag handler that corresponds to the tag below would have to have methods named: public void setAttribute1( String value1 ) and public void setAttribute2( String value2 ) When the tag gets processed, it will automatically call these methods in the tag handler class. JSP: Assigning Attributes to Tags

1 30 Here we see how the method getMyAttribute() is inserted into the tag. JSP: Assigning Attributes to Tags Also, notice how nowhere does this class call “ setMyAttribute() ”

1 31 We’re not done yet—we need to add our ParameterTag class to the tld file. JSP: Assigning Attributes to Tags The name here is case sensitive. Remembering the rules of JavaBeans, it must match the getters and setters in your class. This optional attribute rtexprvalue shows whether it is okay for the value to be the result of a JSP Expression. When you have chosen to include an attribute in your tag, you need to add the attribute tag, which itself has three possible sub elements.

1 32 Last but not least we build a JSP to take advantage of our tag. JSP: Assigning Attributes to Tags See how this is going to work? Whatever we insert in myAttribute gets inserted into the tag when it’s made.

1 33 Granted, these have been pretty simple examples. But, hopefully, you can see how we could pass in multiple attributes and get some pretty complex structures. The tags give us canned code. Everybody shares the same code base and nothing is hard- coded in our JSPs. JSP: Assigning Attributes to Tags

1 34 JSP: Including the Tag Body

1 35 Up until now, all of our Custom Tags have omitted the body. Let’s see how the body can be included. Our doStartTag() methods have always returned the constant SKIP_BODY. JSP: Including the Tag Body return SKIP_BODY; } If, instead, we would have had our doStartTag() method return the constant EVAL_BODY_INCLUDE, then we can have the body contain JSP scripting elements, directives and actions. return EVAL_BODY_INCLUDE; }

1 36 To make sure you understand what I’m saying, here’s an example: body stuff can go in here including any legal JSP stuff. JSP: Including the Tag Body

1 37 Often, when you’re bothering to include the body, you also want to do something special with the end tag. Naturally, there is a method you can override called: doEndTag() For its return value, you can have the doEndTag() method either: return EVAL_PAGE; or return SKIP_PAGE; JSP: Including the Tag Body This means, after you’re done with the end tag, continue to evaluate the rest of the JSP page. This means, after you’re done with the end tag, abandon the rest of the JSP page.

1 38 Quickly, let’s look at the Tag Handler class: JSP: Including the Tag Body

1 39 JSP: Including the Tag Body Here’s the Start Tag This means the body should be evaluated.

1 40 And, finally, here’s the End Tag. JSP: Including the Tag Body

1 41 This is the.tld file. As you can see, all of the attributes need to be listed. JSP: Including the Tag Body

1 42 This example, when we see how it renders, will start to show how powerful this technique is. JSP: Including the Tag Body HeadingExample.jsp

1 43 JSP: Including the Tag Body HeadingExample.jsp

1 44 Package com.hp.bco.pl.wpa.taglib.hpweb WPA HPWeb Layout Plug-in Version 1.1.7