jsptags6.html

j2eePDF格式的电子书

</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90242"> </a><div class="pCellBody">
<code class="cCode">name</code>
</div>
</td>
    <td><a name="wp90244"> </a><div class="pCellBody">
The unique tag name.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90246"> </a><div class="pCellBody">
<code class="cCode">path</code>
</div>
</td>
    <td><a name="wp90248"> </a><div class="pCellBody">
Where to find the tag file implementing this tag, relative to the root of the Web application or the root of the JAR file for a tag library packaged in a JAR. This must begin with <code class="cCode">/WEB-INF/tags/</code> if the tag file resides in the WAR, or <code class="cCode">/META-INF/tags/</code> if the tag file resides in a JAR.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90250"> </a><div class="pCellBody">
example
</div>
</td>
    <td><a name="wp90252"> </a><div class="pCellBody">
(optional) Informal description of an example use of the tag.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90254"> </a><div class="pCellBody">
tag-extension
</div>
</td>
    <td><a name="wp90256"> </a><div class="pCellBody">
(optional) Extensions that provide extra information about the tag for tools.
</div>
</td>
</tr>
</table>
</div>
<p class="pBody">
</p>
<a name="wp90257"> </a><h4 class="pHeading3">
Unpackaged Tag Files
</h4>
<a name="wp90258"> </a><p class="pBody">
Tag files placed in a subdirectory of <code class="cCode">/WEB-INF/tags/</code> do not require a TLD file and don't have to be packaged. Thus, to create reusable JSP code, you simply create a new tag file and place the code inside of it.
</p>
<a name="wp90259"> </a><p class="pBody">
The Web container generates an implicit tag library for each directory under and including <code class="cCode">/WEB-INF/tags/</code>. There are no special relationships between subdirectories--they are allowed simply for organizational purposes. For example, the following Web application contains three tag libraries:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
/WEB-INF/tags/
/WEB-INF/tags/a.tag
/WEB-INF/tags/b.tag
/WEB-INF/tags/foo/
/WEB-INF/tags/foo/c.tag
/WEB-INF/tags/bar/baz/
/WEB-INF/tags/bar/baz/d.tag<a name="wp90260"> </a>
</pre></div>
<a name="wp90261"> </a><p class="pBody">
The implicit TLD for each library has the following values:
</p>
<div class="pSmartList1"><ul class="pSmartList1">
<a name="wp90262"> </a><div class="pSmartList1"><li><code class="cCode">tlib-version</code> for the tag library. Defaults to 1.0.</li></div>
<a name="wp90263"> </a><div class="pSmartList1"><li><code class="cCode">short-name</code> is derived from the directory name. If the directory is <code class="cCode">/WEB-INF/tags/</code>, the short name is simply <code class="cCode">tags</code>. Otherwise, the full directory path (relative to the Web application) is taken, minus the <code class="cCode">/WEB-INF/tags/</code> prefix. Then, all / characters are replaced with -, which yields the short name. Note that short names are not guaranteed to be unique.</li></div>
<a name="wp90264"> </a><div class="pSmartList1"><li>A <code class="cCode">tag-file</code> element is considered to exist for each tag file, with the following sub-elements:</li></div>
<div class="pSmartList2"><ul class="pSmartList2">
<a name="wp90265"> </a><div class="pSmartList2"><li>The <code class="cCode">name</code> for each is the filename of the tag file, without the <code class="cCode">.tag</code> extension.</li></div>
<a name="wp90266"> </a><div class="pSmartList2"><li>The <code class="cCode">path</code> for each is the path of the tag file, relative to the root of the Web application.</li></div>
</ul></div>
</ul></div>
<a name="wp90267"> </a><p class="pBody">
So, for the previous example, the implicit TLD for the <code class="cCode">/WEB-INF/tags/bar/baz/</code> directory would be:
</p>
<div class="pPreformattedRelative"><pre class="pPreformattedRelative">
&lt;taglib&gt;
&nbsp;&nbsp;&lt;tlib-version&gt;1.0&lt;/tlib-version&gt;
&nbsp;&nbsp;&lt;short-name&gt;bar-baz&lt;/short-name&gt;
&nbsp;&nbsp;&lt;tag-file&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;name&gt;d&lt;/name&gt;
&nbsp;&nbsp;&nbsp;&nbsp;&lt;path&gt;/WEB-INF/tags/bar/baz/d.tag&lt;/path&gt;
&nbsp;&nbsp;&lt;/tag-file&gt;
&lt;/taglib&gt;<a name="wp90268"> </a>
</pre></div>
<a name="wp90269"> </a><p class="pBody">
Despite the existence of an implicit tag library, a TLD in the Web application can still create additional tags from the same tag files. To accomplish this, you add a <code class="cCode">tag-file</code> element with a <code class="cCode">path</code> that points to the tag file.
</p>
<a name="wp90271"> </a><h4 class="pHeading3">
Packaged Tag Files
</h4>
<a name="wp90272"> </a><p class="pBody">
Tag files can be packaged in the <code class="cCode">/META-INF/tags/</code> directory in a JAR file installed in the <code class="cCode">/WEB-INF/lib/</code> directory of the Web application. Tags placed here are typically part of a reusable library of tags that can be easily used in any Web application. 
</p>
<a name="wp90273"> </a><p class="pBody">
Tag files bundled in a JAR require a tag library descriptor. Tag files that appear in a JAR but are not defined in a TLD are ignored by the Web container.
</p>
<a name="wp90274"> </a><p class="pBody">
When used in a JAR file, the <code class="cCode">path</code> subelement of the <code class="cCode">tag-file</code> element specifies the full path of the tag file from the root of the JAR. Therefore, it must always begin with <code class="cCode">/META-INF/tags/</code>.
</p>
<a name="wp90275"> </a><p class="pBody">
Tag files can also be compiled into Java classes and bundled as a tag library. This is useful when you wish to distribute a binary version of the tag library without the original source. If you choose this form of packaging you must use a tool that produces portable JSP code that uses only standard APIs. 
</p>
<a name="wp90277"> </a><h3 class="pHeading2">
Declaring Tag Handlers
</h3>
<a name="wp90279"> </a><p class="pBody">
When tags are implemented with tag handlers written in Java, each tag in the library must be declared in the TLD with the <code class="cCode">tag</code> element. The <code class="cCode">tag</code> element contains the tag name, the class of its tag handler, information on the tag's attributes, and information on the variables created by the tag (see <a  href="JSPTags4.html#wp89646">Tags That Define Variables</a>). 
</p>
<a name="wp90283"> </a><p class="pBody">
Each attribute declaration contains an indication of whether the attribute is required, whether its value can be determined by request-time expressions, the type of the attribute, and whether the attribute is a fragment. Variable information can be given directly in the TLD or through a tag extra info class. <a  href="JSPTags6.html#wp90294">Table 15-9</a> lists the subelements of the <code class="cCode">tag</code> element:</p><div align="left">
<table border="1" summary="tag Subelements" id="wp90294">
  <caption><a name="wp90294"> </a><div class="pTableTitle">
Table 15-9   tag Subelements&nbsp;
</div>
</caption>
  <tr align="center">    <th><a name="wp90298"> </a><div class="pCellHeading">
Element
</div>
</th>
    <th><a name="wp90300"> </a><div class="pCellHeading">
Description
</div>
</th>
</tr>
  <tr align="left">    <td><a name="wp90302"> </a><div class="pCellBody">
<code class="cCode">description</code>
</div>
</td>
    <td><a name="wp90304"> </a><div class="pCellBody">
(optional) A description of the tag.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90306"> </a><div class="pCellBody">
<code class="cCode">display-name</code>
</div>
</td>
    <td><a name="wp90308"> </a><div class="pCellBody">
(optional) name intended to be displayed by tools.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90310"> </a><div class="pCellBody">
<code class="cCode">icon</code>
</div>
</td>
    <td><a name="wp90312"> </a><div class="pCellBody">
(optional) Icon that can be used by tools.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90314"> </a><div class="pCellBody">
<code class="cCode">name</code>
</div>
</td>
    <td><a name="wp90316"> </a><div class="pCellBody">
The unique tag name.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90318"> </a><div class="pCellBody">
<code class="cCode">tag-class</code>
</div>
</td>
    <td><a name="wp90320"> </a><div class="pCellBody">
The fully-qualified name of the tag handler class.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90322"> </a><div class="pCellBody">
<code class="cCode">tei-class</code>
</div>
</td>
    <td><a name="wp90324"> </a><div class="pCellBody">
(optional) Subclass of <code class="cCode">javax.servlet.jsp.tagext.TagExtraInfo</code>. See <a  href="JSPTags6.html#wp90424">Declaring Tag Variables for Tag Handlers</a>.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90329"> </a><div class="pCellBody">
<code class="cCode">body-content</code>
</div>
</td>
    <td><a name="wp90334"> </a><div class="pCellBody">
The body content type. See <a  href="JSPTags6.html#wp90362">body-content Element&nbsp;</a>.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90336"> </a><div class="pCellBody">
<code class="cCode">variable</code>
</div>
</td>
    <td><a name="wp90338"> </a><div class="pCellBody">
(optional) Declares an EL variable exposed by the tag to the calling page. See <a  href="JSPTags6.html#wp90424">Declaring Tag Variables for Tag Handlers</a>.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90343"> </a><div class="pCellBody">
<code class="cCode">attribute</code>
</div>
</td>
    <td><a name="wp90347"> </a><div class="pCellBody">
Declares attributes of the custom tag. See <a  href="JSPTags6.html#wp90370">Declaring Tag Attributes for Tag Handlers</a>.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90350"> </a><div class="pCellBody">
dynamic-attributes
</div>
</td>
    <td><a name="wp90352"> </a><div class="pCellBody">
Whether the tag supports additional attributes with dynamic names. Defaults to <code class="cCode">false</code>. If true, the tag handler class must implement the <code class="cCode">javax.servlet.jsp.tagext.DynamicAttributes</code> interface.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90354"> </a><div class="pCellBody">
example
</div>
</td>
    <td><a name="wp90356"> </a><div class="pCellBody">
(optional) Informal description of an example use of the tag.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90358"> </a><div class="pCellBody">
tag-extension
</div>
</td>
    <td><a name="wp90360"> </a><div class="pCellBody">
(optional) Extensions that provide extra information about the tag for tools.
</div>
</td>
</tr>
</table>
</div>
<p class="pBody">
</p>
<a name="wp90362"> </a><h4 class="pHeading3">
body-content Element
</h4>
<a name="wp90364"> </a><p class="pBody">
You specify the type of body that is valid for this tag with the <code class="cCode">body-content</code> element.  This element is used by the Web container to validate that a tag invocation has the correct body syntax and by page composition tools to assist the page author in providing a valid tag body. There are four possible values:
</p>
<div class="pSmartList1"><ul class="pSmartList1">
<a name="wp90365"> </a><div class="pSmartList1"><li><code class="cCode">tagdependent</code>--The body of the tag is interpreted by the tag implementation itself, and is most likely in a different language, for example, embedded SQL statements.</li></div>
<a name="wp90366"> </a><div class="pSmartList1"><li><code class="cCode">JSP</code>--The body of the tag contains nested JSP syntax.</li></div>
<a name="wp90367"> </a><div class="pSmartList1"><li><code class="cCode">empty</code>--The body must be empty.</li></div>
<a name="wp90368"> </a><div class="pSmartList1"><li><code class="cCode">scriptless</code>--The body accepts only template text, EL expressions, and custom tags. No scripting elements are allowed.</li></div>
</ul></div>
<a name="wp90370"> </a><h3 class="pHeading2">
Declaring Tag Attributes for Tag Handlers
</h3>
<a name="wp90371"> </a><p class="pBody">
For each tag attribute, you must specify whether the attribute is required, whether the value can be determined by an expression, optionally, the type of the attribute in an <code class="cCode">attribute</code> element, and whether the attribute is a fragment. If the <code class="cCode">rtexprvalue</code> element is <code class="cCode">true</code> or <code class="cCode">yes</code>, then the <code class="cCode">type</code> element defines the return type expected from any expression specified as the value of the attribute.For static values, the type is always <code class="cCode">java.lang.String</code>. An attribute is specified in a TLD in an <code class="cCode">attribute</code> element. <a  href="JSPTags6.html#wp90383">Table 15-10</a> lists the subelements of the <code class="cCode">attribute</code> element.</p><div align="left">
<table border="1" summary="attribute Subelements" id="wp90383">
  <caption><a name="wp90383"> </a><div class="pTableTitle">
Table 15-10   attribute Subelements&nbsp;
</div>
</caption>
  <tr align="center">    <th><a name="wp90387"> </a><div class="pCellHeading">
Element
</div>
</th>
    <th><a name="wp90389"> </a><div class="pCellHeading">
Description
</div>
</th>
</tr>
  <tr align="left">    <td><a name="wp90391"> </a><div class="pCellBody">
description
</div>
</td>
    <td><a name="wp90393"> </a><div class="pCellBody">
(optional) A description of the attribute.
</div>
</td>
</tr>
  <tr align="left">    <td><a name="wp90395"> </a><div class="pCellBody">
<code class="cCode">name</code>
</div>
</td>
    <td><a name="wp90397"> </a><div class="pCellBody">