April 15, 2010

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:


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:


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" 
<taglib xmlns="http://java.sun.com/xml/ns/j2ee"
    <short-name>MyLibrary</short-name> <!-- Used for tools to display -->

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

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

 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 

 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


  <%-- 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"/>