Custom Tags, TLD, Tag Files, El Functions, what is the difference?

If you are starting out with Java Custom Tag Development, you have probably come across the terms in the title of this article.

But if you are like me, it probably took you a while to wrap your head around all the terms, how the relate to each other, and most importantly what is the difference between them.

• What is a custom tag?
• What is a TLD file?
• What is the difference between a TLD file and a Tag File?
• What is an EL Function?

In this article I will try to explain some of these questions and terms.

There is another article on this blog which you may find useful.

Custom Tags

A Custom Tag is a generic term for code which simplifies the writing of Java code (eg. scriptlets, classes, etc).

A simple example of a custom tag is: <myTagLibrary:doSomething/>

Custom Tags - JSTL (Java Standard Tag Library)

JSTL is a collection of standard tags which give you common functionality, that you otherwise would have to write yourself as scriptlets or expressions inside your JSP pages

For example:

Instead of putting this scriptlet in your JSP page

<table>

<%
  String[] items = (String[]) request.getAttribute("movieList"); 
  String movie = null;
  for(int i = 0;i<items.length;i++){
    movie = items[i];  
%>

<%
  <tr>
     <td><%= movie %></td>
  </tr>    
%>

</table>

You can make it much simpler by using a JSTL tag

<table>
  <c:forEeach var="movie" items="${requestScope.movieList}">
  <tr>
    <td>${movie}</td>
  </tr>  
  </c:forEach>
</table>

Custom Tags - Writing your own

You can also write your own Custom Tags. See how

Custom El Functions

A custom El Function is a customized method that you can invoke using the JSP Expression Language.

A simple custom EL Function looks like this: ${myTagLibrary:randomColor()}

How do I create a custom el function?

TLD Files

A TLD file (*.tld), or Tag Library Descriptor file, is an XML file containing data which defines a Custom Tag OR an El Function

How do I create a TLD file?

Tag Files

A Tag File (*.tag), is a way for non-Java developers to build custom tags without writing a Java class (eg. a Custom Tag Handler class).

A *.tag file can be any valid *.jsp file. So you can just rename a jsp file to *.tag, but there are certain rules about where in your application's directory structure you have to place a *.tag file.

A Tag File is usually used when you need simpler functionality in your custom tags, for complex things a Custom Tag Handler class is better.

How do I create a simple Tag File?

To learn more about Tag Files also try these articles:

Easy Custom Tags with Tag Files, Part 1 and Oracle article on Tag Files

Questions

What is the difference between a TLD File and a Tag File?

A TLD File is an XML file which declares the functionality of custom tags or EL Functions, while a Tag File (which is actually a renamed *.JSP file), allows you to declare Custom Tags without writing a Custom Tag Handler (eg. a Java class).

Custom Tags and Custom EL Functions in JSP Pages

What is a Custom Tag?

A Custom Tag is a generic term for simplifying or eliminating Java code inside JSP pages (eg. eliminating scriptlets). A typical custom tag looks like this:

<myTagLibrary:doSomething/>

What is a Custom EL Function?

A Custom EL Function is a method that you can invoke using the JSP Expression Language. A typical Custom EL Function looks like this:

${myTagLibrary:randomColor()}

In order to create a Custom Tag or a Custom EL Function you will need two things:

1. A Java class to define what the Custom Tag or Custom El Function will do
2. A TLD file in which will specify the Java class and method to use, and how your Custom Tag or El Function will be called.

Creating the TLD file

Here is a TLD file which will defines an EL Function and a Custom Tag. We're going to call this file funkytaglibrary.tld.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!DOCTYPE taglib PUBLIC "-//Sun Microsystems, Inc.//DTD JSP Tag Library 1.2//EN" 
"http://java.sun.com/dtd/web-jsptaglibrary_1_2.dtd">
<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">
  
 <tlib-version>1.0</tlib-version>
    <short-name>MyLibrary</short-name> <!-- Used for tools to display -->
    <uri>FunkyTagLibrary</uri>         

    <!-- Define a Custom EL Function -->
    <function>
        <name>randomColor</name> <!-- Will be used to call your El Function:   ${myTagLibrary:randomColor()} inside your JSP page -->
        <function-class>foo.RandomColorGenerator</function-class>
        <function-signature>String pickRandomColor()</function-signature>
    </function>
 
    <!-- Define a Custom Tag -->
    <tag>
        <description>This tag prints a random number.</description>
        <name>randomNumber</name>   <!-- Will be used to call your tag  <myTagLibrary:randomNumber greaterThan="2"/> -->
        <tag-class>foo.RandomNumberGenerator</tag-class>
        <body-content>empty,scriptless,tagdependent or JSP</body-content>
        
        <!-- If your Custom Tag has attributes you will define them here --> 
        <attribute>
            <name>greaterThan</name>
            <required>true</required>
            <rtexprvalue>true</rtexprvalue>     <!-- if true, you can have things like ${myNumber} as the attribute value -->
        </attribute>
           
    </tag>
</taglib>

Your JSP file will have to contain the following directive to make use of this TLD file
<%@ taglib prefix="myTagLibrary" uri="FunkyTagLibrary" %>

Creating the Java class

In order to implement the functionality of the Custom Tag or Custom EL Function defined in the TLD field above, you also have to have a Java class for each.

Class for implementing the custom EL Function randomColor()

package foo;  

public class RandomColorGenerator{
 public static String pickRandomColor(){   //notice that this method doesn't have to be  the same as the one that will apear in your tag 'randomColor'. This is only true for a class that implements a Custom El Function.
  String [] colors = new String[3];
  colors[0] = 'Red';
  colors[1] = 'Blue';
  colors[2] = 'Yellow';
        return color[Math.abs(r.nextInt()) % 4]; //return one of the colors in array at random
    }
}

In order to implement the functionality of the Custom Tag or Custom EL Function defined in the TLD field above, you also have to have a Java class for each.

Class for implementing the custom tag functionality

Some people refer to a class that implements a custom tag functionality as a Tag Handler

package foo;
public javax.servlet.jsp.JspException;  
public javax.servlet.jsp.tagext.SimpleTagSupport;
import java.io.IOException;

public class RandomNumberGenerator extends SimpleTagSupport{
 private String greaterThan; //stores the value of the greaterThan attribute of the custom tag

 @Override
 public void doTag() throws JspException, IOException{ //this is the method that is called when the custom tag  is called from a JSP page 
  int randomNumber = (int)Math.random() * (greaterThan+1); //generate a random number, which is greater than the 'greaterThan' attribute's value 
  getJspContext().getOut().write(randomNumber); 
 }

 public void setGreaterThan(int number){ //the method name must match the attribute name defined in the TLD file
  greaterThan = number;
  } 
 }
}

Where do I put the TLD file?

In order for the Servlet Container to find the TLD file and use it, you can put the funkytaglibrary.tld in any of the following locations:

• WEB-INF/funkytaglibrary.tld
• WEB-INF/subfolder/funkytaglibrary.tld
• WEB-INF/lib/mylibrary.jar -> META-INF/funkytaglibrary.tld //inside the META-INF folder of your jar file
• WEB-INF/lib/mylibrary.jar -> META-INF/subfolder/funkytaglibrary.tld //inside a META-INF sub folder of your jar file

Calling the Custom Tag and Custom EL Function from JSP

test.jsp

<html>
 <body>
  <%-- call your custom el function --%>
  Here is a random color: ${myTagLibrary:randomColor()}.

  <%-- call your custom tag --%>
  Here is a random number: <myTagLibrary:randomNumber greaterThan="10"/> 
 </body>
</html>