How to define an example in a JSP taglib <tag-file> element?

Question

I'm currently writing a bunch of JSP tags for our designers to use. In my .tld file I have some <tag> and many more <tag-file> elements.

Now, I want to give the users of the tag library some examples about how to use them. According to Sun's documentation both <tag-file> and <tag> elements are allowed to have an <example> element.

This works fine for <tag>, but whenever I try to put an example in <tag-file> both Eclipse and Tomcat throw an error.

Anybody got experience with this?

Answer 1

The <example> element was introduced in Servlet 2.4 / JSP 2.0.

Apart from declaring the taglib root as JSP taglib 2.0 like follows

<taglib 
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee/web-jsptaglibrary_2_0.xsd"
    version="2.0">

are you also using an appserver which is capable of Servlet 2.4 / JSP 2.0? For example Tomcat 5.x or newer. If not, then you need to upgrade. If so, then this question: is a proper Servlet version (at least 2.4) been declared in web.xml? If not, then ensure that you're doing so:

<web-app 
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"
    version="2.4">

or, if you're already using a Servlet 2.5 capable appserver (for example Tomcat 6.x) then just declare Servlet 2.5 to be the best up to date:

<web-app 
    xmlns="http://java.sun.com/xml/ns/j2ee"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee http://java.sun.com/xml/ns/j2ee/web-app_2_5.xsd"
    version="2.5">

If you don't want to upgrade the appserver or to change the Servlet API version declaration in web.xml, then you need to live with the fact that you cannot use the <example> element.

Answer 2

It works for me on Tomcat 6.0. Here is my file,

<tagtoc name="Configuration Components">
  <tag-file>
    <description>Get configured value</description>
    <display-name>get</display-name>
    <name>get</name>
    <path>/META-INF/tags/config/get.tag</path>
    <example>
       <![CDATA[
               <config:get key="username" echo="true" />
      ]]>
      <usage>
        <comment>
          <p>
            See config-test.jsp in the example application.
          </p>
        </comment>
      </usage>
    </example>
  </tag-file>

...