2010-04-14 - Jakarta Taglibs has been retired.

For more information, please explore the Attic.

Using the "Input" Tag Library

Here's how to use each of the tags provided by the "Input" tag library. Syntax statements use the style of Sun's JSP Syntax Card.

Tags


<input:text>

<input:text name="fieldName" [ bean="beanName" ] [ default="defaultValue" ] [ attributes="<%= attributeMap %>" ] [ attributesText='name="value" ...' ] />

The <input:text> tag displays an HTML <input type="text" ... > element. The element's name in the HTML will be fieldName. Additionally, the element's value will be drawn from the fieldName property in the bean beanName if supplied and if the property exists, otherwise the fieldName parameter in the current ServletRequest if it exists, or from defaultValue if it does not (as long as default is given a value).

See documentation on attributes bean, attributes, attributesText and how tag values are derived.


<input:hidden>

<input:hidden name="fieldName" [ bean="beanName" ] [ default="defaultValue" ] [ attributes="<%= attributeMap %>" ] [ attributesText='name="value" ...' ] />

The <input:hidden> tag creates an HTML <input type="hidden" ... > element. The element's name in the HTML will be fieldName. Additionally, the element's value will be drawn from the fieldName property in the bean beanName if supplied and if the property exists, otherwise the fieldName parameter in the current ServletRequest if it exists, or from defaultValue if it does not (as long as default is given a value).

See documentation on attributes bean, attributes, attributesText and how tag values are derived.


<input:textarea>

<input:textarea name="fieldName" [ bean="beanName" ] [ default="defaultValue" ] [ attributes="<%= attributeMap %>" ] [ attributesText='name="value" ...' ] />

The <input:textarea> tag displays an HTML <textarea> element and, potentially, its body too. The element's name in the HTML will be fieldName. Additionally, the element's body (its logical "value") will be drawn from the fieldName property in the bean beanName if supplied and if the property exists, otherwise the fieldName parameter in the current ServletRequest if it exists, or from defaultValue if it does not (as long as default is given a value).

This tag does not take a body. It may produce a body in the underlying HTML if appropriate, but all of the logic is encapsulated into this single tag in order to make it easier to use.

See documentation on attributes bean, attributes, attributesText and how tag values are derived.


<input:select>

<input:select name="fieldName" [ bean="beanName" ] options="<%= optionsMap %>" [ default="defaultValue" ]> [ attributes="<%= attributeMap %>" ] [ attributesText='name="value" ...' ] />

The <input:select> tag displays an HTML <select> element and its subordinate <options>. The element's name in the HTML will be fieldName. A list of <option> tags will come from the optionsMap Map, and each individual option will be marked selected if it corresponds to the fieldName property in the bean beanName, or the fieldName parameter in the current ServletRequest if it exists, or from defaultValue if it does not (as long as default is given a value).

This tag does not take a body. It may produce a body in the underlying HTML if appropriate, but all of the logic is encapsulated into this single tag in order to make it easier to use.

See documentation on attributes bean, attributes, attributesText and how tag values are derived.

You might find that code like this is easier to read and maintain in bulk than tags with multiple attribute/value pairs.

This tag supports multiple selections if it retrieves them from the ServletRequest and the box is labelled as a multiple selection box (i.e., attributeMap contains multiple as a key). If there are multiple selections in the ServletRequest and the <select> box is not labelled multiple, the selections are thrown away (instead of choosing one at random).


<input:radio>

<input:radio name="buttonGroupName" value="buttonValue" [ bean="beanName" ] [ default="defaultValue" ] [ attributes="<%= attributeMap %>" ] [ attributesText='name="value" ...' ] />

The <input:radio> tag displays a single HTML <input type="radio" ...>. To display all buttons in a radio group, you need to use this tag multiple times with different values.

The element's name in the HTML will be buttonGroupName. (You can have as many buttons with the same buttonGroupName as you need.) Additionally, each particular button will be marked checked if its buttonValue equals the value of the fieldName parameter in the current ServletRequest if it exists, or the defaultValue if it does not (as long as default is given a value).

See documentation on attributes bean, attributes, attributesText and how tag values are derived.


<input:checkbox>

<input:checkbox name="buttonGroupName" value="buttonValue" [ bean="beanName" ] [ default="defaultValue" ] [ defaults="<%= defaultStringArray %>" ] [ attributes="<%= attributeMap %>" ] [ attributesText='name="value" ...' ] />

The <input:checkbox> tag displays a single HTML <input type="checkbox" ...>. To display all buttons in a checkbox group, you need to use this tag multiple times with different values.

The element's name in the HTML will be buttonGroupName. (You can have as many checkboxes with the same buttonGroupName as you need.) Additionally, this checkbox will be marked as checked if the tag believes it ought to be checked. The rules are as follows: if the current ServletRequest is empty (i.e., contains no parameters), then we combine the default and defaults String and String[] (respectively), and if the current checkbox's buttonValue is in that list of defaults, then the tag marks the checkbox as checked. Otherwise, the tag marks the checkbox as checked if and only if the box's buttonValue is in the list of values associated with buttonGroupName in the current ServletRequest.

Note: The rules for determining whether a checkbox is checked or not are different than the rules for other input or selection types. This is the result of underlying differences between the way CGI handles checkboxes and other fields. If a text box is empty, browsers assert, via the POST or GET to the server, an empty value; however, if all checkboxes for a given checkbox group are unchecked, the browser doesn't include any information about the checkbox group in its POST or GET. Thus, if this tag simply looked toward the parameter in the current ServletRequest, defaults would be restored on the resulting page--that is, checkboxes wouldn't necessarily stay unchecked. (As an aside, we'd have to do the same thing with radio buttons, but browsers don't let users uncheck all radio buttons, and if the default provides for no buttons to be checked, then there's, tidily enough, no problem with accepting the default in the case where all buttons remain unchecked.)

See documentation on attributes bean, attributes, attributesText and how tag values are derived.


Attributes

Most of the tags in the input tag library share a common set of attributes.

attributes="<%= attributeMap %>"

Any key/value pairs in the attributeMap Map provided will be used as attribute/value pairs in the HTML element. For example, for an <input type="text" ... > element the key/value pair "size" -> "50" will show up as <input type="text" size="50" ... >

Note that some HTML elements contain attributes without values, such as <input type="checkbox" disabled ... >. For compatibility with XHTML these will always be rendered with values as per the XHTML 1.0 documentation, <input type="checkbox" disabled="disabled" ... >.

Also see attributesText.


attributesText='name="value" ...'

The attributesText attribute is a simplification of the attributes attribute. Any text may be given in the attributesText attribute, and it will be output in the HTML element. For example, for an <input type="text" ... > element, attributesText='size="50" class="plain"' will show up as <input type="text" size="50" class="plain"... >.

Note the use of single quotes and double quotes in this example. This is purely stylistic to allow double quotes to be used easily inside the attributesText value.

Also see attributes.


bean="beanName"

The bean attribute allows a JavaBean to be named as the source of initial value for the given tag (or for all input tags in a form, if specified on an <input:form ...> tag). For example,

<jsp:useBean name="myBean" class="my.Bean" />
<input:text name="myValue" bean="myBean" />

A property with the same name as the input element is retrieved from the bean. If the property exists and is not null, it is used as the value of the input element. If not, the request and default attribute values are considered as usual.

If a bean attribute is specified on an <input:form ...> tag, all tags within the <input:form ...> ... </input:form> use that bean by default. You can remove this default on a tag by specifying the bean attribute with an empty string value, eg. <input:text name="notFromBean" bean="" />.

Any property type is supported - all values are converted to Strings internally. Array properties are also supported for tags that can have multiple values, such as checkbox and select. Again, the array may have components of any type.


How tag values are derived

There are three places that the tag "value", "selected" or "checked" state may come from. These are the bean, ServletRequest or default (or defaults) attribute value.

The method for determining which of these to use is consistent across all of the tags:

1. If there is a bean name provided by the bean attribute, or a default bean provided on the <input:form> tag, then it is checked first. If there is a property with the same name as the tag and it is not null, that property is the value of the tag.

2. Otherwise, if the request contains a parameter with the same name as the tag, that value is the value of the tag.

3. Finally, if a default or defaults attribute is specified on the tag, that becomes the value of the tag.

Note: For tags <input:select>, <input:radio> and <input:checkbox> the "value" indicates which tag or option should be marked as checked or selected, rather than an actual value attribute that is generated. That is,

<select name="...">
    <option value="thisWasTheValue" selected="true"> This was the value</option>
    <option value="thisWasNotTheValue"> This was not the value</option>
</select>

Shawn Bayern
shawn.bayern@oooo.com

Karl von Randow
karl@xk72.com