Encapsulating Reusable Content Using Tag Files
| A tag file is a source file that contains a fragment of JSP code that is reusable as a custom tag. Tag files allow you to create custom tags using JSP syntax. Just as a JSP page gets translated into a servlet class and then compiled, a tag file gets translated into a tag handler and then compiled. The recommended file extension for a tag file is .tag. As is the case with JSP files, the tag can be composed of a top file that includes other files that contain either a complete tag or a fragment of a tag file. Just as the recommended extension for a fragment of a JSP file is .jspf, the recommended extension for a fragment of a tag file is .tagf. The following version of the Hello, World application introduced in Chapter 2 uses a tag to generate the response. The response tag, which accepts two attributesa greeting string and a nameis encapsulated in response.tag: <%@ attribute name="greeting" required="true" %> <%@ attribute name="name" required="true" %> <h2><font color="black">${greeting}, ${name}!</font></h2>The highlighted line in the greeting.jsp page invokes the response tag if the length of the username request parameter is greater than 0: <%@ taglib tagdir="/WEB-INF/tags" prefix="h" %> <%@ taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c" %> <%@ taglib uri="http://java.sun.com/jsp/jstl/functions" prefix="fn" %> <html> <head><title>Hello</title></head> <body bgcolor="white"> <img src="/books/1/370/1/html/2/duke.waving.gif"> <c:set var="greeting" value="Hello" /> <h2>${greeting}, my name is Duke. What's yours?</h2> <form method="get"> <input type="text" name="username" size="25"> <p></p> <input type="submit" value="Submit"> <input type="reset" value="Reset"> </form> <c:if test="${fn:length(param.username) > 0}" > <h:response greeting="${greeting}" name="${param.username}"/> </c:if> </body> </html>To deploy and run the hello3 application with NetBeans 5.5, follow these steps:
To deploy and run the hello3 application with ant, follow these steps:
To learn how to configure the example, refer to the deployment descriptor (the web.xml file), which includes the following configurations:
Tag File LocationTag files can be placed in one of two locations: in the /WEB-INF/tags/ directory or subdirectory of a web application or in a JAR file (see Packaged Tag Files, page 234) in the /WEB-INF/lib/ directory of a web application. Packaged tag files require a tag library descriptor (see Tag Library Descriptors, page 229), an XML document that contains information about a library as a whole and about each tag contained in the library. Tag files that appear in any other location are not considered tag extensions and are ignored by the web container. Tag File DirectivesDirectives are used to control aspects of tag file translation to a tag handler, and to specify aspects of the tag, attributes of the tag, and variables exposed by the tag. Table 71 lists the directives that you can use in tag files.
Declaring TagsThe tag directive is similar to the JSP page's page directive but applies to tag files. Some of the elements in the tag directive appear in the tag element of a TLD (see Declaring Tag Handlers, page 234). Table 72 lists the tag directive attributes.
body-content AttributeYou specify the type of a tag's body content using the body-content attribute: bodycontent="empty | scriptless | tagdependent" You must declare the body content of tags that do not accept a body as empty. For tags that have a body there are two options. Body content containing custom and standard tags and HTML text is specified as scriptless. All other types of body contentfor example, SQL statements passed to the query tagis specified as tagdependent. If no attribute is specified, the default is scriptless. Declaring Tag Attributes in Tag FilesTo declare the attributes of a custom tag defined in a tag file, you use the attribute directive. A TLD has an analogous attribute element (see Declaring Tag Attributes for Tag Handlers, page 236). Table 73 lists the attribute directive attributes.
Declaring Tag Variables in Tag FilesTag attributes are used to customize tag behavior much as parameters are used to customize the behavior of object methods. In fact, using tag attributes and EL variables, it is possible to emulate various types of parametersIN, OUT, and nested. To emulate IN parameters, use tag attributes. A tag attribute is communicated between the calling page and the tag file when the tag is invoked. No further communication occurs between the calling page and the tag file. To emulate OUT or nested parameters, use EL variables. The variable is not initialized by the calling page but instead is set by the tag file. Each type of parameter is synchronized with the calling page at various points according to the scope of the variable. See Variable Synchronization (page 221) for details. To declare an EL variable exposed by a tag file, you use the variable directive. A TLD has an analogous variable element (see Declaring Tag Variables for Tag Handlers, page 238). Table 74 lists the variable directive attributes.
Variable SynchronizationThe web container handles the synchronization of variables between a tag file and a calling page. Table 75 summarizes when and how each object is synchronized according to the object's scope.
If name-given is used to specify the variable name, then the name of the variable in the calling page and the name of the variable in the tag file are the same and are equal to the value of name-given. The name-from-attribute and alias attributes of the variable directive can be used to customize the name of the variable in the calling page while another name is used in the tag file. When using these attributes, you set the name of the variable in the calling page from the value of name-from-attribute at the time the tag was called. The name of the corresponding variable in the tag file is the value of alias. Synchronization ExamplesThe following examples illustrate how variable synchronization works between a tag file and its calling page. All the example JSP pages and tag files reference the JSTL core tag library with the prefix c. The JSP pages reference a tag file located in /WEB-INF/tags with the prefix my. AT_BEGIN ScopeIn this example, the AT_BEGIN scope is used to pass the value of the variable named x to the tag's body and at the end of the tag invocation. <%-- callingpage.jsp --%> <c:set var="x" value="1"/> ${x} <%-- (x == 1) --%> <my:example> ${x} <%-- (x == 2) --%> </my:example> ${x} <%-- (x == 4) --%> <%-- example.tag --%> <%@ variable name-given="x" scope="AT_BEGIN" %> ${x} <%-- (x == null) --%> <c:set var="x" value="2"/> <jsp:doBody/> ${x} <%-- (x == 2) --%> <c:set var="x" value="4"/>NESTED ScopeIn this example, the NESTED scope is used to make a variable named x available only to the tag's body. The tag sets the variable to 2, and this value is passed to the calling page before the body is invoked. Because the scope is NESTED and because the calling page also had a variable named x, its original value, 1, is restored when the tag completes. <%-- callingpage.jsp --%> <c:set var="x" value="1"/> ${x} <%-- (x == 1) --%> <my:example> ${x} <%-- (x == 2) --%> </my:example> ${x} <%-- (x == 1) --%> <%-- example.tag --%> <%@ variable name-given="x" scope="NESTED" %> ${x} <%-- (x == null) --%> <c:set var="x" value="2"/> <jsp:doBody/> ${x} <%-- (x == 2) --%> <c:set var="x" value="4"/>AT_END ScopeIn this example, the AT_END scope is used to return a value to the page. The body of the tag is not affected. <%-- callingpage.jsp --%> <c:set var="x" value="1"/> ${x} <%-- (x == 1) --%> <my:example> ${x} <%-- (x == 1) --%> </my:example> ${x} <%-- (x == 4) --%> <%-- example.tag --%> <%@ variable name-given="x" scope="AT_END" %> ${x} <%-- (x == null) --%> <c:set var="x" value="2"/> <jsp:doBody/> ${x} <%-- (x == 2) --%> <c:set var="x" value="4"/>AT_BEGIN and name-from-attributeIn this example the AT_BEGIN scope is used to pass an EL variable to the tag's body and make to it available to the calling page at the end of the tag invocation. The name of the variable is specified via the value of the attribute var. The variable is referenced by a local name, result, in the tag file. <%-- callingpage.jsp --%> <c:set var="x" value="1"/> ${x} <%-- (x == 1) --%> <my:example var="x"> ${x} <%-- (x == 2) --%> ${result} <%-- (result == null) --%> <c:set var="result" value="invisible"/> </my:example> ${x} <%-- (x == 4) --%> ${result} <%-- (result == 'invisible') --%> <%-- example.tag --%> <%@ attribute name="var" required="true" rtexprvalue="false"%> <%@ variable alias="result" name-from-attribute="var" scope="AT_BEGIN" %> ${x} <%-- (x == null) --%> ${result} <%-- (result == null) --%> <c:set var="x" value="ignored"/> <c:set var="result" value="2"/> <jsp:doBody/> ${x} <%-- (x == 'ignored') --%> ${result} <%-- (result == 2) --%> <c:set var="result" value="4"/>Evaluating Fragments Passed to Tag FilesWhen a tag file is executed, the web container passes it two types of fragments: fragment attributes and the tag body. Recall from the discussion of fragment attributes that fragments are evaluated by the tag handler as opposed to the web container. Within a tag file, you use the jsp:invoke element to evaluate a fragment attribute and use the jsp:doBody element to evaluate a tag file body. The result of evaluating either type of fragment is sent to the response or is stored in an EL variable for later manipulation. To store the result of evaluating a fragment to an EL variable, you specify the var or varReader attribute. If var is specified, the container stores the result in an EL variable of type String with the name specified by var. If varReader is specified, the container stores the result in an EL variable of type java.io.Reader, with the name specified by varReader. The Reader object can then be passed to a custom tag for further processing. A translation error occurs if both var and varReader are specified. An optional scope attribute indicates the scope of the resulting variable. The possible values are page (default), request, session, or application. A translation error occurs if you use this attribute without specifying the var or varReader attribute. ExamplesThis section introduces examples that demonstrate using custom tags. Simple Attribute ExampleThe Duke's Bookstore shipDate tag, defined in shipDate.tag, is a custom tag that has a simple attribute. The tag generates the date of a book order according to the type of shipping requested. <%@ taglib prefix="sc" tagdir="/WEB-INF/tags" %> <h3><fmt:message key="ThankYou"/> ${param.cardname}.</h3><br> <fmt:message key="With"/> <em><fmt:message key="${param.shipping}"/></em>, <fmt:message key="ShipDateLC"/> <sc:shipDate shipping="${param.shipping}" />The tag determines the number of days until shipment from the shipping attribute passed to it by the page bookreceipt.jsp. From the number of days, the tag computes the ship date. It then formats the ship date. <%@ attribute name="shipping" required="true" %> <jsp:useBean /> <jsp:useBean /> <c:choose> <c:when test="${shipping == 'QuickShip'}"> <c:set var="days" value="2" /> </c:when> <c:when test="${shipping == 'NormalShip'}"> <c:set var="days" value="5" /> </c:when> <c:when test="${shipping == 'SaverShip'}"> <c:set var="days" value="7" /> </c:when> </c:choose> <jsp:setProperty name="shipDate" property="time" value="${now.time + 86400000 * days}" /> <fmt:formatDate value="${shipDate}" type="date" dateStyle="full"/>.<br><br>Simple and Fragment Attribute and Variable ExampleThe Duke's Bookstore catalog tag, defined in catalog.tag, is a custom tag with simple and fragment attributes and variables. The tag renders the catalog of a book database as an HTML table. The tag file declares that it sets variables named price and salePrice via variable directives. The fragment normalPrice uses the variable price, and the fragment onSale uses the variables price and salePrice. Before the tag invokes the fragment attributes using the jsp:invoke element, the web container passes values for the variables back to the calling page. <%@ attribute name="bookDB" required="true" type="database.BookDB" %> <%@ attribute name="color" required="true" %> <%@ attribute name="normalPrice" fragment="true" %> <%@ attribute name="onSale" fragment="true" %> <%@ variable name-given="price" %> <%@ variable name-given="salePrice" %> <center> <table> <c:forEach var="book" begin="0" items="${bookDB.books}"> <tr> <c:set var="bookId" value="${book.bookId}" /> <td bgcolor="${color}"> <c:url var="url" value="/bookdetails" > <c:param name="bookId" value="${bookId}" /> </c:url> <a href="${url}">< strong>${book.title} </strong></a></td> <td bgcolor="${color}" rowspan=2> <c:set var="salePrice" value="${book.price * .85}" /> <c:set var="price" value="${book.price}" /> <c:choose> <c:when test="${book.onSale}" > <jsp:invoke fragment="onSale" /> </c:when> <c:otherwise> <jsp:invoke fragment="normalPrice"/> </c:otherwise> </c:choose> </td> ... </table> </center>The page bookcatalog.jsp invokes the catalog tag that has the simple attributes bookDB, which contains catalog data, and color, which customizes the coloring of the table rows. The formatting of the book price is determined by two fragment attributesnormalPrice and onSalethat are conditionally invoked by the tag according to data retrieved from the book database. <sc:catalog bookDB ="${bookDB}" color="#cccccc"> <jsp:attribute name="normalPrice"> <fmt:formatNumber value="${price}" type="currency"/> </jsp:attribute> <jsp:attribute name="onSale"> <strike> <fmt:formatNumber value="${price}" type="currency"/> </strike><br/> <font color="red"> <fmt:formatNumber value="${salePrice}" type="currency"/> </font> </jsp:attribute> </sc:catalog>The screen produced by bookcatalog.jsp is shown in Figure 72. You can compare it to the version in Figure 42. Figure 72. Book Catalog Dynamic Attribute ExampleThe following code implements the tag discussed in Dynamic Attributes (page 209). An arbitrary number of attributes whose values are colors are stored in a Map named by the dynamic-attributes attribute of the tag directive. The JSTL forEach tag is used to iterate through the Map and the attribute keys and colored attribute values are printed in a bulleted list. <%@ tag dynamic-attributes="colorMap"%> <ul> <c:forEach var="color" begin="0" items="${colorMap}"> <li>${color.key} = <font color="${color.value}">${color.value}</font><li> </c:forEach> </ul> |
Open Project.
page