Using attributes

You can code tag handlers that accept attributes. An attribute provides alternative or runtime values to a tag. Attributes or expressions that set attributes are written in the tag when it is used in a JSP. In the <A> (anchor) tag, for example, HREF is an attribute, as the following line shows:

<A HREF="http://www.hamsteak.com">Click here</A>

This section describes how to handle attributes in tag handlers and how to use the TLD file to provide additional functionality to attributes.

Coding attributes in a JSP

You code attributes as part of the custom tag. The following example shows the invocation of the test:include tag, with the page and flush attributes:

<html>

��<body>
����<%@ taglib prefix="test" uri="test.tld" %>
����<h1>Testing Custom Tags with Parameters</h1>
����<test:include page="/includedText.htm" flush="true" />
��</body>
</html>

Using attributes

To enable attribute functionality, a tag handler must define the following:

An object-scoped variable for each attribute so that the variable can be accessed.
Setter (and optionally getter) methods for each attribute. A setter method starts with set and is followed by the initial-capped variable name. For example, for variable foo, you implement a setFoo method.

You can optionally customize attribute usage and behavior using the TLD file or the TEI class:

TLD file Define attributes in a TLD file to specify required attributes and when the attribute can take a JSP runtime expression. For more information, see "Defining attributes in a TLD file".
TEI class Define attributes in a TEI class when you use the attributes as scripting variables and when you enable validation by overriding the isValid method. For more information, see "Coding a TEI class".

TLD file specifications and TEI class files provide powerful validation functionality. However, the only required functionality for attributes is bean-like setter methods that interact with class-scoped variables in the tag handler class.

The attribute elements are not required but can be useful in the following situations:

Required ��If the attribute is required, include the following in the attribute element:
```
<required>true</required>
```
Runtime expression ��If the attribute can be calculated by a runtime scriptlet expression, include the following in the attribute element:
```
<rtexprvalue>true</rtexprvalue>
```

Simple attribute example

To enable the following tag attribute usage:

...

<test:hello username="Joe"/>
...

a tag handler must implement the following:

import javax.servlet.jsp.*;

import javax.servlet.jsp.tagext.*;
import java.io.IOException;

public class TestParms extends BodyTagSupport {

��// Object-scoped variable with same name as attribute.
��String username;

��// setVariablename method called by the JSP compiler.

public void setUsername(String username) {
��this.username = username;
}

// Optional getter method.

public String getUsername() {
��return username;
}
...

When the tag is invoked in a JSP, the username variable is set in the starting tag and you can use it in the rest of the tag handler's methods.

Complete attribute example

The following complete example of a sample tag handler uses attributes to emulate the functionality provided by the JSP include action element:

import javax.servlet.jsp.*;

import javax.servlet.jsp.tagext.*;
import javax.servlet.*; 
import java.io.IOException;

public class TestInclude extends TagSupport {

��// This is required so there's no default.
��String page;
��// Default is true.
��String flush = "true";
��// Setter methods.

�public void setPage(String page) {

��this.page = page;
�}

�public void setFlush(String flush) {

��// Save as lowercase.
��this.flush = flush.toLowerCase();
�}

�public int doStartTag() throws JspException {

��// Ignore body text.
��return SKIP_BODY;
�}

��// doEndTag does all the work.

�public int doEndTag() throws JspException {
��try {
����ServletContext sc = pageContext.getServletContext();
����RequestDispatcher rd = sc.getRequestDispatcher(page);
����if (rd !=null) {
������// Access request and response.
������ServletRequest request = pageContext.getRequest();
������ServletResponse response = pageContext.getResponse();
������// Flush the buffer, if requested.
������if (flush.equals("true")) { 
��������pageContext.getOut().flush(); 
������}
������// Include the file.
������rd.include(request, response);
������return EVAL_PAGE;
����}
��} catch(IOException ioe) {
����throw new JspException(ioe.getMessage());
��} catch (Exception e) {
����pageContext.getServletContext().log("Error with " + page, e);
��}
��return EVAL_PAGE; 
�}
}

Defining attributes in a TLD file

You define attributes in the tag class handler. However, you can use the attribute element in a TLD file to provide an attribute with additional settings. Setting an attribute in the TLD file is optional, but it lets you enforce attribute requirements and allow or disallow the use of runtime expressions in an attribute's value.

The following table describes the subelements of the attribute element:

Subelement

Description

name

Attribute name.

required

Indicates whether the attribute is required. Set this to true or false. If true, then the JSP programmer must include the attribute when invoking the tag in a JSP.

rtexprvalue

Indicates whether the custom tag can use a runtime expression for the value of this attribute. Set this to true or false.

Subelement	Description
`name`	Attribute name.
`required`	Indicates whether the attribute is required. Set this to true or false. If true, then the JSP programmer must include the attribute when invoking the tag in a JSP.
`rtexprvalue`	Indicates whether the custom tag can use a runtime expression for the value of this attribute. Set this to true or false.

The following example TLD entry establishes a required attribute and an optional attribute:

<?xml version="1.0" ?>

<taglib>
��<tlibversion>0.0</tlibversion>
��<jspversion>1.0</jspversion>
��<shortname>test</shortname>
��<tag>
����<name>include</name>
����<tagclass>TestInclude</tagclass>
����<bodycontent>empty</bodycontent>
����<attribute>
������<name>page</name>
������<required>true</required>
������<rtexprvalue>true</rtexprvalue>
����</attribute>
����<attribute>
������<name>flush</name>
������<required>false</required>
������<rtexprvalue>false</rtexprvalue>
����</attribute>
��</tag>
��<tag>
����<name>hello</name>
����<tagclass>HelloTag</tagclass>
����<teiclass>HelloTEI</teiclass>
����<bodycontent>JSP</bodycontent>
��</tag>
</taglib>

Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/jrun/4/Programmers_Guide/custtags_java6.htm

Programmer's Guide
Custom Tags in Java