Tag files must be kept in the WEB-INF/tags directory(or subdirectory) or or META-INF/tags directory or subdirectory) of a jar
© Copyright Marcus Green 2007
10.5 Describe the semantics of the Tag File model; describe the web application structure for tag files; write a tag file; and explain the constraints on the JSP content in the body of the tag
Tag files were introduced with the JSP 2 standard and are quite a radical departure to any previous JSP technology. Do not in any way confuse the term Tag Files with custom tags or any other use of the term tag, tag files have more in common with JSP or even HTML pages than custom tags. The idea is that non Java programmers can create tag files without needing to be able to write Java code or scriptlets. In some ways Tag flies are like a slightly sophisticated include mechanism but there are a few peculiarities that you need to be aware of. The simplest of tag files is to take a plain JSP page, rename the extension from JSP to tag (or tagx if it uses the jsp XML syntax). Tag files must be stored in the WEB-INF/tags directory (or subdirectory).
|
|
Tag files must be kept in the WEB-INF/tags directory(or subdirectory) or or META-INF/tags directory or subdirectory) of a jar |
The Tag file can be accessed (think included) from a calling jsp page with the code. The following file is called menu.tag and is stored in the WEB-INF/tags directory.
<%@tag description="Descriptive Text" pageEncoding="UTF-8"%> <h1> Menu </h1>
The description tag is not mandatory and so the file could just consist of the HTML tags. The tag file can be used from within a JSP file containing the following.
<%@ taglib prefix="mytagfile" tagdir="/WEB-INF/tags" %> <html> <head> <title>Demonstration of Tag Files</title> </head> <body> <mytagfile:menu /> </body> </html>
The tagdir attribute is the equivalent of the uri attribute in a custom tag, and when using/calling the tag file the part after the prefix (menu in this case), is the name of the file minus the tld extension.
Note that it was not necessary to create a TLD (tag library descriptor file or to give the exact name of the tag file that is being used. A combination of the tagdir and the name of the tag file (menu) allows the container to work out the path. Tag files have access to the following implicit objects,
request response out session application config jspContext
This is similar, but not identical to the implicit objects available to standard JSP pages. JSP pages have a page object, pageContext object and can have an exception object.
It is possible to pass information into a Tag File either by passing the information as a tag attribute, or by placing the information between the start and end of the tag. So the call to the Tag file in the previous example can be modified as follows.
<mytagfile:menu menutext="This is the menuText" />
The Tag file itself must be configured to expect the attribute and this can be done through the attribute element as follows
<%@ attribute name="menutext" rtexprvalue="true"%>
The attribute directive is exclusive to tag files, it is not used in custom tags or JSP pages. The value of the attribute can be retrieved using EL as follows
<h1> ${menutext}</h1>It is possible to send information to a tag file by putting content between the opening and closing tags of the tag file call. The content of the body can be retrieved by using the <jsp:doBody/> call. Thus the following tag file invocation
<mytagfile:menu> Calling JSP hello </mytagfile:menu>
And the text in the body will be output in the tag file with a simple call to
<jsp:doBody/>
The body of a tag file call cannot contain any scripting elements. You will get a compile time error if you try to include any. I'm not sure why you would want to include scripting anyway. You can explicitly declare the body-content for a tag file in a similar way you would do with the <body-content> tag within a TLD for a custom tag. The three possible values are empty, tagdependent and scriptless.
Using a tag file that is not wrapped in a jar is very convenient because it needs no Tag Library Descriptor File (tld). However when wrapped in a jar (Java archive) tag files require a tld. A tag file is similar but not identical to a regular tld. Instead of matching tags to handlers it matches the names of tag files to their paths, and so it uses the new <tag-file> element instead of the <tag> element of a standard taglib tld.
The details of the tag file tld are fairly easy to remember as the tag-file element only has two sub elements which is <name>, and that points to the tag file name without its file extension and <path> which must begin with /META-INF/tags or a sub directory of /META/INF/tags (similar to the need for unwrapped tag files to live in /WEB-INF/tags . The following file called menu.tld was created with the name menu.tld and placed in the META-INF directory.
<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.1//EN"
"http://java.sun.com/j2ee/dtds/web-jsptaglibrary_1_1.dtd">
<taglib>
<tlibversion>1.0</tlibversion>
<jspversion>1.1</jspversion>
<shortname>menutagfile</shortname>
<uri>www.examulator.com/menutagfile</uri>
<tag-file>
<name>menu</name>
<path>/META-INF/tags/menu.tag</path>
</tag-file>
</taglib>The following file called menu.tag was created and placed in the META-INF\tags directory
<%@ tag body-content="tagdependent" %> <%@ attribute name="menutext" rtexprvalue="true"%> <h1>This is my tag file</h1> <jsp:doBody/>
The following command line was used from within the web application directory to wrap the menu.tag into a jar file.
Jar cvf menutagfile.jar .\META-INF\*.*
(note the full stop in front of \META-INF)
The menutagfile.jar file that was created was then copied into the WEB-INF\lib directory. You could now safely delete the META-INF directory and its subdirectories as the code will be executed from within the jar. The jarred up tag file can be accessed from within a standard JSP file with code like the following.
<%@ taglib prefix="mytagfile" uri="www.examulator.com/menutagfile" %> <html> <head> <title>Demonstration of Tag Files</title> </head> <body> <h1> What is going down? </h1> <mytagfile:menu/> </body> </html>
Note how the URI makes no reference to the actual jar file or the META-INF directory, but the URL is matched to the tag file within the jar because the container (Apache Tomcat in my setup) automatically searches through any of the jars in the WEB-INF\lib directory.
Other sources
Developing Custom Tag Libraries as Tag Files by Hans Bergsten
http://www.onjava.com/pub/a/onjava/excerpt/jserverpages3_ch11/index.html
Easy Custom Tags with Tag Files by Budi Kurniawan
http://today.java.net/pub/a/today/2003/11/14/tagfiles.html
According to Mikalai Zaikin
http://java.boot.by/wcd-guide/ch10s05.html