Directives 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 8–1 lists the directives that you can use in tag files.
Table 8–1 Tag File Directives
Directive |
Description |
---|---|
taglib |
Identical to taglib directive (see Declaring Tag Libraries) for JSP pages. |
include |
Identical to include directive (see Reusing Content in JSP Pages) for JSP pages. Note that if the included file contains syntax unsuitable for tag files, a translation error will occur. |
tag |
Similar to the page directive in a JSP page, but applies to tag files instead of JSP pages. As with the page directive, a translation unit can contain more than one instance of the tag directive. All the attributes apply to the complete translation unit. However, there can be only one occurrence of any attribute or value defined by this directive in a given translation unit. With the exception of the import attribute, multiple attribute or value (re)definitions result in a translation error. Also used for declaring custom tag properties such as display name. See Declaring Tags. |
attribute |
Declares an attribute of the custom tag defined in the tag file. See Declaring Tag Attributes in Tag Files. |
variable |
Declares an EL variable exposed by the tag to the calling page. See Declaring Tag Variables in Tag Files. |
The 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). Table 8–2 lists the tag directive attributes.
Table 8–2 tag Directive Attributes
Attribute |
Description |
---|---|
display-name |
(optional) A short name that is intended to be displayed by tools. Defaults to the name of the tag file without the extension .tag. |
body-content |
(optional) Provides information on the content of the body of the tag. Can be either empty, tagdependent, or scriptless. A translation error will result if JSP or any other value is used. Defaults to scriptless. See body-content Attribute. |
dynamic-attributes |
(optional) Indicates whether this tag supports additional attributes with dynamic names. The value identifies a scoped attribute in which to place a Map containing the names and values of the dynamic attributes passed during invocation of the tag. A translation error results if the value of the dynamic-attributes of a tag directive is equal to the value of a name-given of a variable directive or the value of a name attribute of an attribute directive. |
small-icon |
(optional) Relative path, from the tag source file, of an image file containing a small icon that can be used by tools. Defaults to no small icon. |
large-icon |
(optional) Relative path, from the tag source file, of an image file containing a large icon that can be used by tools. Defaults to no large icon. |
description |
(optional) Defines an arbitrary string that describes this tag. Defaults to no description. |
example |
(optional) Defines an arbitrary string that presents an informal description of an example of a use of this action. Defaults to no example. |
language |
(optional) Carries the same syntax and semantics of the language attribute of the page directive. |
import |
(optional) Carries the same syntax and semantics of the import attribute of the page directive. |
pageEncoding |
(optional) Carries the same syntax and semantics of the page-Encoding attribute in the page directive. |
isELIgnored |
(optional) Carries the same syntax and semantics of the isEL-Ignored attribute of the page directive. |
You 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 content (for example, SQL statements passed to the query tag) is specified as tagdependent. If no attribute is specified, the default is scriptless.
To 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). Table 8–3 lists the attribute directive attributes.
Table 8–3 attribute Directive Attributes
Tag 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 parameters: IN, 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 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). Table 8–4 lists the variable directive attributes.
Table 8–4 variable Directive Attributes
Attribute |
Description |
---|---|
description |
(optional) An optional description of this variable. Defaults to no description. |
name-given | name-from-attribute |
Defines an EL variable to be used in the page invoking this tag. Either name-given or name-from-attribute must be specified. If name-given is specified, the value is the name of the variable. If name-from-attribute is specified, the value is the name of an attribute whose (translation-time) value at the start of the tag invocation will give the name of the variable. Translation errors arise in the following circumstances: 1. Specifying neither name-given nor name-from-attribute or both. 2. If two variable directives have the same name-given. 3. If the value of a name-given attribute of a variable directive is equal to the value of a name attribute of an attribute directive or the value of a dynamic-attributes attribute of a tag directive. |
alias |
Defines a variable, local to the tag file, to hold the value of the EL variable. The container will synchronize this value with the variable whose name is given in name-from-attribute. Required when name-from-attribute is specified. A translation error results if used without name-from-attribute. A translation error results if the value of alias is the same as the value of a name attribute of an attribute directive or the name-given attribute of a variable directive. |
variable-class |
(optional) The name of the class of the variable. The default is java.lang.String. |
declare |
(optional) Whether or not the variable is declared. True is the default. |
scope |
(optional) The scope of the variable. Can be either AT_BEGIN, AT_END, or NESTED. Defaults to NESTED. |
The web container handles the synchronization of variables between a tag file and a calling page. Table 8–5 summarizes when and how each object is synchronized according to the object’s scope.
Table 8–5 Variable Synchronization Behavior
Tag File Location |
AT_BEGIN |
NESTED |
AT_END |
---|---|---|---|
Beginning |
Not sync. |
Save |
Not sync. |
Before any fragment invocation using jsp:invoke or jsp:doBody (see Evaluating Fragments Passed to Tag Files) |
Tag->page |
Tag->page |
Not sync. |
End |
Tag->page |
Restore |
Tag->page |
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.
The 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.
In 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"/>
In 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"/>
In 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"/>
In 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 by 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"/>