The HTML Tag Library Tags (Continued) | Struts: The Complete Reference, 2nd Edition

The HTML Tag Library Tags

The following table lists each of the tags in the HTML Tag Library and a short description of each tag's purpose.

Tag	Description
base	Generates an HTML <base> tag with its href attribute set to the absolute URL of the enclosing JSP.
button	Generates an HTML <input type="button"> tag.
cancel	Generates an HTML <input type="submit"> tag that, when executed, causes Struts' Cancel feature to be triggered.
checkbox	Generates an HTML <input type="checkbox"> tag populated with data from a specified object.
errors	Displays a set of error messages stored as an org.apache.struts.action. ActionErrors object, a String, or a String array in any scope.
file	Generates an HTML <input type="file"> tag populated with data from a specified object.
form	Generates an HTML <form> tag tied to an Action object and its corresponding Form Bean from the struts-config.xml file.
frame	Generates an HTML <frame> tag.
hidden	Generates an HTML <input type="hidden"> tag populated with data from a specified object.
html	Generates an HTML <html> tag with language attributes set to the current user's locale.
image	Generates an HTML <input type="image"> tag.
img	Generates an HTML <img> tag.
javascript	Generates client-side JavaScript validation code for validations defined in the Validator framework's validation.xml file.
link	Generates an HTML hyperlink <a> tag whose URL is composed by specifying a base URL and optionally specifying an anchor and/or query string parameters to add to the URL.
messages	Displays a set of messages stored as an org.apache.struts.action. ActionErrors object, an org.apache.struts.action.ActionMessages object, a String, or a String array in any scope.
multibox	Generates an HTML <input type="checkbox"> tag whose checked status is based on whether a specified value matches one of the values in a specified array of values.
option	Generates an HTML <option> tag.
options	Generates a set of HTML <option> tags for each element in a collection.
optionsCollection	Generates a set of HTML <option> tags for each element in a collection.
password	Generates an HTML <input type="password"> tag populated with data from a specified object.
radio	Generates an HTML <input type="radio"> tag populated with data from a specified object.
reset	Generates an HTML <input type="reset"> tag.
rewrite	Generates a URL by specifying a base URL and optionally specifying an anchor and/or query string parameters to add to the URL.
select	Generates an HTML <select> tag.
submit	Generates an HTML <input type="submit"> tag.
text	Generates an HTML <input type="text"> tag populated with data from a specified object.
textarea	Generates an HTML <textarea> tag populated with data from a specified object.
xhtml	Instructs the rest of the tags in the HTML Tag Library to generate their output as XHTML instead of HTML.

The remainder of this chapter discusses each tag in detail, including a complete description of the tag, a table listing each of the tag's attributes, and a usage example for the tag. In the tables that describe each tag's attributes, pay special attention to the Required and Accepts JSP Expression columns.

The Required column simply denotes whether the given attribute is required when using the tag. In addition to the required column denoting whether an attribute is required, the rows for required attributes are highlighted in gray so that you can determine at a glance which attributes are required.

If an attribute is required and you do not specify it when using the tag, the tag will throw a javax.servlet.jsp.JspException at run time. Note that you can declare an error page in your JSP with a page directive to capture any JspExceptions that might be thrown, as shown here:

<%@ page errorPage="error.jsp" %>

If an exception occurs, the page specified by the errorPage attribute will be internally redirected to display an error page.

The Accepts JSP Expression column denotes whether the given attribute's value can be specified with a JSP expression. If a JSP expression is used to specify an attribute value, the expression must comprise the complete value, quote (") to quote ("), as shown here. Correct:

<html:checkbox property="<%=prop%>">

Incorrect:

<html:checkbox property="<%=result%>-checked">

Notice in the incorrect example that "-checked" is used as part of the value for the property attribute following the expression. This is invalid because there are extra characters between the end of the expression and the ending quote.

A corrected version of the incorrect example follows:

<html:checkbox property="<%=result + "-checked"%>"/>

The concatenation of "-checked" is now part of the expression, and the expression comprises the complete value for the attribute.

One other point: Several of the tags have a set of tag attributes in common, such as onclick, onmousedown, and onkeypress. Rather than repeat the description for these common attributes numerous times, they are described once, at the end of this chapter, in the section"Common Tag Attributes." The Description column in each tag's table of attributes refers you to the section "Common Tag Attributes" for any of the common tag attributes that the tag has in its set of tag attributes.

The base Tag

The base tag is used to generate an HTML <base> tag with its href attribute set to the absolute URL of the enclosing JSP. Note that this tag must be nested inside of an HTML <head> tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
ref	Specifies what the base URL will be based on. This attribute accepts two values: page (default) for basing the URL on the location of the enclosing JSP or site for basing the URL on the application's context path. Added in Struts 1.3.	Yes	No
server	Specifies the server name to use when generating the corresponding HTML tag's href attribute.	Yes	No
target	Same as the corresponding HTML tag's attribute with the same name. Specifies the frame or window target in which links will be opened.	Yes	No

Attribute

Description

Accepts JSP Expression

Required

ref

Specifies what the base URL will be based on. This attribute accepts two values: page (default) for basing the URL on the location of the enclosing JSP or site for basing the URL on the application's context path.

Added in Struts 1.3.

Yes

server

Specifies the server name to use when generating the corresponding HTML tag's href attribute.

Yes

target

Same as the corresponding HTML tag's attribute with the same name.

Specifies the frame or window target in which links will be opened.

Yes

Example Usage

The following snippet shows the basic usage of the base tag:

<html:html> <head>   <title></title>   <html:base/> </head>

Remember that this tag must be enclosed by opening and closing HTML <head> tags.

The button Tag

The button tag is used to generate an HTML <input type="button"> tag. Note that this tag must be nested inside of this library's form tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
accesskey	See the section "Common Tag Attributes" at the end of this chapter.	Yes	No
alt	See "Common Tag Attributes."	Yes	No
altKey	See "Common Tag Attributes."	Yes	No
bundle	See "Common Tag Attributes."	Yes	No
disabled	See "Common Tag Attributes."	Yes	No
indexed	See "Common Tag Attributes."	Yes	No
onblur	See "Common Tag Attributes."	Yes	No
onchange	See "Common Tag Attributes."	Yes	No
onclick	See "Common Tag Attributes."	Yes	No
ondblclick	See "Common Tag Attributes."	Yes	No
onfocus	See "Common Tag Attributes."	Yes	No
onkeydown	See "Common Tag Attributes."	Yes	No
onkeypress	See "Common Tag Attributes."	Yes	No
onkeyup	See "Common Tag Attributes."	Yes	No
onmousedown	See "Common Tag Attributes."	Yes	No
onmousemove	See "Common Tag Attributes."	Yes	No
onmouseout	See "Common Tag Attributes."	Yes	No
onmouseover	See "Common Tag Attributes."	Yes	No
onmouseup	See "Common Tag Attributes."	Yes	No
property	Same as the corresponding HTML tag's name attribute. Specifies the name that will be associated with this control.	Yes	Yes
style	See "Common Tag Attributes."	Yes	No
styleClass	See "Common Tag Attributes."	Yes	No
styleId	See "Common Tag Attributes."	Yes	No
tabindex	See "Common Tag Attributes."	Yes	No
title	See "Common Tag Attributes."	Yes	No
titleKey	See "Common Tag Attributes."	Yes	No
value	Specifies a constant value that this control will be populated with. This value will be used for the button's label. If not specified, this tag will attempt to use its body content as the value for the button's label.	Yes	No

Example Usage

The following snippet illustrates the basic usage of the button tag:

<html:button property="direction" value="Next Page"/>

The value specified with the value attribute will be used for the button's label. Alternatively, you can specify the button's label value by nesting a string between opening and closing button tags, as shown here:

<html:button>Next Page</html:button>

The cancel Tag

Struts has a built-in Cancel feature that will cause it to bypass calling a Form Bean's validate( ) method if a request parameter named "org.apache.struts.taglib.html.CANCEL" is present in an incoming request. Additionally, Action objects can call an isCancelled( ) method to determine whether a request was canceled. Note that as of Struts 1.3 an org. apache.struts.action.InvalidCancelException will be thrown at run time if the cancel button generated by this tag is clicked and the form's associated action mapping in the Struts configuration file does not have its cancellable attribute set to true.

The cancel tag is used to generate an HTML <input type="submit"> tag with its name attribute set to "org.apache.struts.taglib.html.CANCEL" so that, when executed, Struts' Cancel feature will be triggered. Note that this tag must be nested inside of the form tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
accesskey	See the section "Common Tag Attributes" at the end of this chapter.	Yes	No
alt	See "Common Tag Attributes."	Yes	No
altKey	See "Common Tag Attributes."	Yes	No
bundle	See "Common Tag Attributes."	Yes	No
disabled	See "Common Tag Attributes."	Yes	No
onblur	See "Common Tag Attributes."	Yes	No
onchange	See "Common Tag Attributes."	Yes	No
onclick	See "Common Tag Attributes."	Yes	No
ondblclick	See "Common Tag Attributes."	Yes	No
onfocus	See "Common Tag Attributes."	Yes	No
onkeydown	See "Common Tag Attributes."	Yes	No
onkeypress	See "Common Tag Attributes."	Yes	No
onkeyup	See "Common Tag Attributes."	Yes	No
onmousedown	See "Common Tag Attributes."	Yes	No
onmousemove	See "Common Tag Attributes."	Yes	No
onmouseout	See "Common Tag Attributes."	Yes	No
onmouseover	See "Common Tag Attributes."	Yes	No
onmouseup	See "Common Tag Attributes."	Yes	No
property	Same as the corresponding HTML tag's name attribute. Specifies the name that will be associated with this control. See the Caution about this attribute following this table.	Yes	No
style	See "Common Tag Attributes."	Yes	No
styleClass	See "Common Tag Attributes."	Yes	No
styleId	See "Common Tag Attributes."	Yes	No
tabindex	See "Common Tag Attributes."	Yes	No
title	See "Common Tag Attributes."	Yes	No
titleKey	See "Common Tag Attributes."	Yes	No
value	Specifies a constant value that this control will be populated with. This value will be used for the button's label. If not specified, this tag will attempt to use its body content as the value for the button's label.	Yes	No

Caution

If you set the property attribute to a value other than its default, Struts' Cancel feature will not be triggered.

Example Usage

The following snippet illustrates the basic usage of the cancel tag:

<html:cancel value="Cancel Update"/>

<html:cancel>Cancel Update</html:cancel>

The checkbox Tag

The checkbox tag is used to generate an HTML <input type="checkbox"> tag populated with data from a specified object. Note that this tag must be nested inside of this library's form tag. Additionally, the underlying Form Bean field associated with this control must be of primitive type boolean or of type Boolean and the Form Bean's reset( ) method must include a statement that resets the field to false.

Attributes

Attribute	Description	Accepts JSP Expression	Required
accesskey	See the section "Common Tag Attributes"	Yes	No
	at the end of this chapter.
alt	See "Common Tag Attributes."	Yes	No
altKey	See "Common Tag Attributes."	Yes	No
bundle	See "Common Tag Attributes."	Yes	No
disabled	See "Common Tag Attributes."	Yes	No
errorKey	Specifies the name of the org.apache. struts.util.MessageResources object that contains the messages to be rendered. Defaults to the value stored in the org. apache.struts.Globals.ERROR_KEY constant.	Yes	No
errorStyle	Specifies the CSS style to apply to this control if an error exists for it.	Yes	No
errorStyleClass	Specifies the CSS class to apply to this control if an error exists for it.	Yes	No
errorStyleId	Specifies the CSS ID to apply to this control if an error exists for it.	Yes	No
indexed	See "Common Tag Attributes."	Yes	No
name	Specifies the name of an object (in any scope) whose field, specified by the property attribute, will be used to populate this control with data.	Yes	No
onblur	See "Common Tag Attributes."	Yes	No
onchange	See "Common Tag Attributes."	Yes	No
onclick	See "Common Tag Attributes."	Yes	No
ondblclick	See "Common Tag Attributes."	Yes	No
onfocus	See "Common Tag Attributes."	Yes	No
onkeydown	See "Common Tag Attributes."	Yes	No
onkeypress	See "Common Tag Attributes."	Yes	No
onkeyup	See "Common Tag Attributes."	Yes	No
onmousedown	See "Common Tag Attributes."	Yes	No
onmousemove	See "Common Tag Attributes."	Yes	No
onmouseout	See "Common Tag Attributes."	Yes	No
onmouseover	See "Common Tag Attributes."	Yes	No
onmouseup	See "Common Tag Attributes."	Yes	No
property	Specifies the value to set the corresponding HTML tag's name attribute to. Additionally, this attribute is used to specify the field of the object specified by the name attribute whose getter method will be called to return an object whose value will be used to populate this control. If no object is specified with the name attribute, the Form Bean object associated with the enclosing form tag will be used to retrieve the property specified by this attribute.	Yes	Yes
style	See "Common Tag Attributes."	Yes	No
styleClass	See "Common Tag Attributes."	Yes	No
styleId	See "Common Tag Attributes."	Yes	No
tabindex	See "Common Tag Attributes."	Yes	No
title	See "Common Tag Attributes."	Yes	No
titleKey	See "Common Tag Attributes."	Yes	No
value	Specifies a constant value that the control will be populated with.	Yes	No

Example Usage

The following snippet illustrates the basic usage of the checkbox tag:

<html:form action="/register"> Subscribe to mailing list: <html:checkbox property="subscribe"/><br> <html:submit/> </html:form>

This tag will look up the Form Bean associated with the Action specified by the form tag's action attribute and then call the getter method for the field specified by this tag's property attribute. The field's value will then be used to populate the HTML control with data.

The errors Tag

The errors tag is used to display a set of error messages stored as an org.apache.struts. action.ActionErrors object, a String, or a String array in any scope. This tag will take the stored error messages and iterate over them, displaying them in succession. Additionally, this tag uses the values for the following table of keys from the application resource bundle file (e.g., MessageResources.properties) to format the messages.

Key	Purpose
errors.header	Text that will be output before the list of error messages.
errors.footer	Text that will be output after the list of error messages.
errors.prefix	Text that will be output before each error message.
errors.suffix	Text that will be output after each error message.

Attributes

Attribute	Description	Accepts JSP Expression	Required
bundle	Specifies the logical name of a resource bundle that will be used when looking up message keys. The referenced resource bundle must be defined in the application's Struts configuration file.	Yes	No
footer	Specifies text that will be output after the list of error messages. If not specified, defaults to text stored under the "errors.footer" key in your application's resource bundle.	Yes	No
header	Specifies text that will be output before the list of error messages. If not specified, defaults to text stored under the "errors.header" key in your application's resource bundle.	Yes	No
locale	Specifies the key for a java.util.Locale instance stored as a session attribute that will be used when looking up error keys.	Yes	No
name	Specifies the key (in any scope) under which the errors to be displayed are stored. If not specified, the default org.apache.struts. Globals.ERROR_KEY key will be used.	Yes	No
prefix	Specifies text that will be output before each error message. If not specified, defaults to text stored under the "errors.prefix" key in your application's resource bundle.	Yes	No
property	Specifies the field for which errors will be displayed. If not specified, all errors will be displayed.	Yes	No
suffix	Specifies text that will be output after each error message. If not specified, defaults to text stored under the "errors.suffix" key in your application's resource bundle.	Yes	No

Example Usage

The following snippet illustrates the basic usage of the errors tag:

<html:errors/>

This example will display all the errors currently stored. If you want to limit the errors that are displayed to a specific property, you can specify that property when using the errors tag, as shown here:

<html:errors property="username"/>

In this case, only the errors associated with the property specified by the property attribute will be displayed.

The file Tag

The file tag is used to generate an HTML <input type="file"> tag populated with data from a specified object. Note that this tag must be nested inside of the form tag. Additionally, the enclosing form tag must specify its HTTP method as being POST and its encoding type as being multipart/form-data, as shown here:

<html:form method="POST" enctype="multipart/form-data"> … </html:form>

Attributes

Attribute	Description	Accepts JSP Expression	Required
accept	Same as the corresponding HTML tag's attribute with the same name. Specifies a comma-delimited list of content types that the server you submit the enclosing form to knows how to process. Browsers can use this list to limit the set of files made available for selection.	Yes	No
accesskey	See the section "Common Tag Attributes" at the end of this chapter.	Yes	No
alt	See "Common Tag Attributes."	Yes	No
altKey	See "Common Tag Attributes."	Yes	No
bundle	See "Common Tag Attributes."	Yes	No
disabled	See "Common Tag Attributes."	Yes	No
errorKey	Specifies the name of the org.apache. struts.util.MessageResources object that contains the messages to be rendered. Defaults to the value stored in the org. apache.struts.Globals.ERROR_KEY constant.	Yes	No
errorStyle	Specifies the CSS style to apply to this control if an error exists for it.	Yes	No
errorStyleClass	Specifies the CSS class to apply to this control if an error exists for it.	Yes	No
errorStyleId	Specifies the CSS ID to apply to this control if an error exists for it.	Yes	No
indexed	See "Common Tag Attributes."	Yes	No
maxlength	Same as the corresponding HTML tag's attribute with the same name. Specifies the maximum number of characters that this control will accept.	Yes	No
name	Specifies the name of an object (in any scope) whose field, specified by the property attribute, will be used to populate this control with data.	Yes	No
onblur	See "Common Tag Attributes."	Yes	No
onchange	See "Common Tag Attributes."	Yes	No
onclick	See "Common Tag Attributes."	Yes	No
ondblclick	See "Common Tag Attributes."	Yes	No
onfocus	See "Common Tag Attributes."	Yes	No
onkeydown	See "Common Tag Attributes."	Yes	No
onkeypress	See "Common Tag Attributes."	Yes	No
onkeyup	See "Common Tag Attributes."	Yes	No
onmousedown	See "Common Tag Attributes."	Yes	No
onmousemove	See "Common Tag Attributes."	Yes	No
onmouseout	See "Common Tag Attributes."	Yes	No
onmouseover	See "Common Tag Attributes."	Yes	No
onmouseup	See "Common Tag Attributes."	Yes	No
property	Specifies the value to which the corresponding HTML tag's name attribute is set. Additionally, this attribute is used to specify the field of the object specified by the name attribute whose getter method will be called to return an object whose value will be used to populate this control. If no object is specified with the name attribute, the Form Bean object associated with the enclosing form tag will be used to retrieve the property specified by this attribute.	Yes	Yes
size	Same as the corresponding HTML tag's attribute with the same name. Specifies the number of characters that will be visible in the control.	Yes	No
style	See "Common Tag Attributes."	Yes	No
styleClass	See "Common Tag Attributes."	Yes	No
styleId	See "Common Tag Attributes."	Yes	No
tabindex	See "Common Tag Attributes."	Yes	No
title	See "Common Tag Attributes."	Yes	No
titleKey	See "Common Tag Attributes."	Yes	No
value	Specifies a constant value that is used to populate the control.	Yes	No

Example Usage

The following snippet illustrates the basic usage of the file tag:

<html:form method="POST"           enctype="multipart/form-data"            action="/attachFile"> Upload File: <html:file property="uploadFile"/><br> <html:submit/> </html:form>

The form Tag

The form tag is used to generate an HTML <form> tag tied to an Action and its corresponding Form Bean from the Struts configuration file (e.g., struts-config.xml). The Action's Form Bean will be used by other tags from this library to populate them with data when they are nested inside this tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
acceptCharset	Specifies the list of character encodings that the server should accept for field input data.	Yes	No
action	Specifies the logical name of an Action, defined in the Struts configuration file, whose path will be used to define the corresponding HTML tag's attribute with the same name. If not specified, the original URI for the request will be used.	Yes	No
disabled	See the section "Common Tag Attributes" at the end of this chapter.	Yes	No
enctype	Same as the corresponding HTML tag's attribute with the same name. Specifies the encoding to be used when submitting this form if the POST method is used. This must be set to "multipart/form-data" if you are using the file tag to upload files.	Yes	No
focus	Specifies the name of a field inside this form that initial focus will be assigned to using JavaScript.	Yes	No
focusIndex	Specifies an index to be used if the field specified with the focus attribute is a field array such as a radio button group.	Yes	No
method	Same as the corresponding HTML tag's attribute with the same name. Specifies the HTTP method that will be used when submitting this form (e.g., GET or POST).	Yes	No
onreset	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when this form is reset.	Yes	No
onsubmit	Same as the corresponding HTML tag's attribute with the same name. Specifies the JavaScript code to execute when this form is submitted.	Yes	No
readonly	Same as the corresponding HTML tag's attribute with the same name. Accepts true or false to specify whether the form elements will be read-only, preventing them from being changed. Defaults to false.	Yes	No
scriptLanguage	Accepts true or false to specify whether the language attribute of the <focus> tag generated by this tag's focus attribute should be omitted. Note that the generated <focus> tag's language attribute is omitted regardless when the tags in this library are in XHTML mode. Defaults to true.	Yes	No
style	See "Common Tag Attributes."	Yes	No
styleClass	See "Common Tag Attributes."	Yes	No
styleId	See "Common Tag Attributes."	Yes	No
target	Same as the corresponding HTML tag's attribute with the same name. Specifies the frame or window target in which this form will be submitted.	Yes	No

Example Usage

The following snippet illustrates the basic usage of the form tag:

 <html:form action="/logon"> UserName: <html:text property="username"/><br> Password: <html:password property="password"/><br> <html:submit/> </html:form>

The Form Bean associated with the Action specified by the action attribute will be used for populating the nested HTML controls inside the opening and closing form tags.

If you want to use a postback form, use the form tag as shown here:

 <html:form> UserName: <html:text property="username"/><br> Password: <html:password property="password"/><br> <html:submit/> </html:form>

In this scenario, the URI of the original request is used to populate the rendered HTML tag's action attribute.

The frame Tag

The frame tag is used to generate an HTML <frame> tag. The frame's URL is composed by specifying a base URL and optionally specifying an anchor and/or query string parameters to add to the URL.

There are four ways to specify the base URL:

You can use the action attribute to specify the name of an Action from the Struts configuration file whose URL will be used.
You can use the forward attribute to specify the name of a forward from the Struts configuration file whose URL will be used.
You can use the href attribute to specify an absolute URL, including protocol (e.g., http://www.yahoo.com/).
You can use the page attribute to specify an application-relative URL.

In addition to specifying the base URL, you have two options for specifying query string parameters to add to the base URL:

You can use the paramId attribute in conjunction with the paramName attribute, and optionally the paramProperty attribute, to specify a single parameter.
You can use the name attribute, either alone or in tandem with the property attribute, to specify a java.util.Map object that will be used to add several parameters.

Attributes

Attribute	Description	Accepts JSP Expression	Required
action	Specifies the name of an Action, from the Action Mappings section of the Struts configuration file, which contains the URL for this frame.	Yes	No
anchor	Specifies the anchor (e.g., "#bottom") to be added to the URL for this frame. This value must be specified without the leading hash (#) character.	Yes	No
bundle	See the section "Common Tag Attributes" at the end of this chapter.	Yes	No
forward	Specifies the name of a forward, from the Global Forwards Configuration section of the Struts configuration file, that contains the URL for this frame.	Yes	No
frameborder	Same as the corresponding HTML tag's attribute with the same name. Specifies the border size for this frame (0 for no border).	Yes	No
frameName	Same as the corresponding HTML tag's name attribute. Specifies the logical name to give the frame.	Yes	No
href	Specifies the absolute URL, including protocol (e.g., http://www.yahoo.com), for this frame.	Yes	No
longdesc	Same as the corresponding HTML tag's attribute with the same name. Specifies the URL for a long description of the frame that supplements the short description provided by the title attribute.	Yes	No
marginheight	Same as the corresponding HTML tag's attribute with the same name. Specifies the number of pixels that will be placed between this frame's contents and its top and bottom margins.	Yes	No
marginwidth	Same as the corresponding HTML tag's attribute with the same name. Specifies the number of pixels that will be placed between this frame's contents and its left and right margins.	Yes	No
module	Specifies the name of a module that contains the action mapping for the Action specified with the action attribute.	Yes	No
name	Specifies the name of the java.util.Map object whose elements are added as query string parameters to the URL for this frame. If the property attribute is also specified, one of the fields of the object defined by this attribute will have its getter method called to return the java.util.Map object whose elements are added as query string parameters to the URL for this frame.	Yes	No
noresize	Same as the corresponding HTML tag's attribute with the same name. Accepts true or false to specify whether this frame will not be resizable. Defaults to false.	Yes	No
page	Specifies the application-relative URL (starts with a leading slash, /) for this frame.	Yes	No
paramId	Specifies the name of a single parameter to add to the URL for this frame.	Yes	No
paramName	Specifies the name of an object whose value will be used as the value for the parameter specified with the paramId attribute. If the property attribute is also specified, one of the fields of the object defined by this attribute will have its getter method called to return an object whose value will be used as the value for the parameter specified with the paramId attribute.	Yes	No
paramProperty	Specifies the field of the object specified by the name attribute whose getter method will be called to return an object whose value will be used as the value for the parameter specified with the paramId attribute.	Yes	No
paramScope	Specifies the scope (application, page, request, or session) to look in for the object specified by the paramName attribute. If not specified, each scope will be searched, in this order: page, request, session, and then application.	Yes	No
property	Specifies the field of the object specified by the name attribute whose getter method will be called to return the java.util.Map object whose elements are added as query string parameters to the URL for this frame.	Yes	No
scope	Specifies the scope (application, page, request, or session) to look in for the object specified by the name attribute. If not specified, each scope will be searched, in this order: page, request, session, and then application.	Yes	No
scrolling	Same as the corresponding HTML tag's attribute with the same name. Specifies whether this frame is scrollable. Specify yes to have scroll bars unconditionally, no to never have scroll bars, or auto to have scroll bars automatically based on how much content is in the frame.	Yes	No
style	See "Common Tag Attributes."	Yes	No
styleClass	See "Common Tag Attributes."	Yes	No
styleId	See "Common Tag Attributes."	Yes	No
title	See "Common Tag Attributes."	Yes	No
titleKey	See "Common Tag Attributes."	Yes	No
transaction	Accepts true or false to specify whether the current transaction token is included in the URL for this frame. Defaults to false.	Yes	No

Example Usage

There are a few different ways to use the frame tag. The first way, shown here, uses the href attribute to specify an absolute URL for the frame:

<html:frame href="http://www.yahoo.com/"/>

The following example adds to the first example by specifying a single query string parameter to add to the base URL specified by the href attribute:

<html:frame href="http://www.yahoo.com/"          param        paramName="queryObj"/>

This example takes the base URL specified by the href attribute and appends the query string parameter specified by the paramId and paramName attributes and composes a URL for the frame.

Another way to use the frame tag is shown here:

<html:frame page="/search.jsp" name="params"/>

This example uses the page attribute to specify an application-relative base URL and uses the name attribute to specify a java.util.Map object whose entries are added to the URL as query string parameters.

The hidden Tag

The hidden tag is used to generate an HTML <input type="hidden"> tag populated with data from a specified object. Note that this tag must be nested inside of the form tag.

Attributes

Attribute	Description	Accepts JSP Expression	Required
accesskey	See the section "Common Tag Attributes" at the end of this chapter.	Yes	No
alt	See "Common Tag Attributes."	Yes	No
altKey	See "Common Tag Attributes."	Yes	No
bundle	See "Common Tag Attributes."	Yes	No
disabled	See "Common Tag Attributes."	Yes	No
indexed	See "Common Tag Attributes."	Yes	No
name	Specifies the name of an object (in any scope) whose field, specified by the property attribute, will be used to populate this control with data.	Yes	No
onblur	See "Common Tag Attributes."	Yes	No
onchange	See "Common Tag Attributes."	Yes	No
onclick	See "Common Tag Attributes."	Yes	No
ondblclick	See "Common Tag Attributes."	Yes	No
onfocus	See "Common Tag Attributes."	Yes	No
onkeydown	See "Common Tag Attributes."	Yes	No
onkeypress	See "Common Tag Attributes."	Yes	No
onkeyup	See "Common Tag Attributes."	Yes	No
onmousedown	See "Common Tag Attributes."	Yes	No
onmousemove	See "Common Tag Attributes."	Yes	No
onmouseout	See "Common Tag Attributes."	Yes	No
onmouseover	See "Common Tag Attributes."	Yes	No
onmouseup	See "Common Tag Attributes."	Yes	No
property	Specifies the value to which the corresponding HTML tag's name attribute is set. Additionally, this attribute is used to specify the field of the object specified by the name attribute whose getter method will be called to return an object whose value will be used to populate this control. If no object is specified with the name attribute, the Form Bean object associated with the enclosing form tag will be used to retrieve the property specified by this attribute.	Yes	Yes
style	See "Common Tag Attributes."	Yes	No
styleClass	See "Common Tag Attributes."	Yes	No
styleId	See "Common Tag Attributes."	Yes	No
title	See "Common Tag Attributes."	Yes	No
titleKey	See "Common Tag Attributes."	Yes	No
value	Specifies a constant value that this control will be populated with.	Yes	No
write	Accepts true or false to specify whether this control's value will also be written out to the page so that it is visible. Defaults to false.	Yes	No

Example Usage

The following snippet illustrates the basic usage of the hidden tag:

<html:form action="/search"> <html:hidden property="lastId"/> <html:submit/> </html:form>

The html Tag

The html tag is used to generate an HTML <html> tag with language attributes set to the current user's locale. Additionally, you can use this tag to instruct the rest of the tags in the HTML Tag Library to generate their output as XHTML instead of HTML. More information on XHTML can be found at http://www.xhtml.org/.

Attributes

Attribute	Description	Accepts JSP Expression	Required
lang	Accepts true or false to specify whether an attribute of the same name will be rendered on the generated <html> tag. If set to true, the attribute will be set to the language from the locale currently stored in the user's session. If there is not a locale stored in the session, the language will be set to that specified by the current request's "AcceptLanguage" HTTP header. Finally, if there is not an "AcceptLanguage" header value, the language will be set to server's default. Defaults to false.	Yes	No
xhtml	Accepts true or false to specify whether the rest of the tags in the HTML Tag Library will generate their output as XHTML instead of HTML. Defaults to false.	Yes	No

Attribute

Description

Accepts JSP Expression

Required

lang

Accepts true or false to specify whether an attribute of the same name will be rendered on the generated <html> tag. If set to true, the attribute will be set to the language from the locale currently stored in the user's session. If there is not a locale stored in the session, the language will be set to that specified by the current request's "AcceptLanguage" HTTP header. Finally, if there is not an "AcceptLanguage" header value, the language will be set to server's default.

Defaults to false.

Yes

xhtml

Accepts true or false to specify whether the rest of the tags in the HTML Tag Library will generate their output as XHTML instead of HTML.

Defaults to false.

Yes

Example Usage

The following snippet shows the basic usage of the html tag:

<html:html/>

If you want the HTML Tag Library's tags to generate XHTML instead of HTML, use the html tag as shown here:

<html:html xhtml="true"/>

The image Tag

The image tag is used to generate an HTML <input type="image"> tag. Note that this tag must be nested inside of a form tag.

There are two ways you can use the image tag, as listed here and shown later, in the section "Example Usage":

You can use the page or pageKey attribute to specify a module-relative URL that will be used as the generated HTML tag's src attribute.
You can use the src or srcKey attribute to specify a URL that will be used as the generated HTML tag's src attribute.

Attributes

Attribute	Description	Accepts JSP Expression	Required
accesskey	See the section "Common Tag Attributes" at the end of this chapter.	Yes	No
align	Same as the corresponding HTML tag's attribute with the same name. Specifies how the image will be aligned (i.e., left, right, top, bottom, and so on).	Yes	No
alt	See "Common Tag Attributes."	Yes	No
altKey	See "Common Tag Attributes."	Yes	No
border	Same as the corresponding HTML tag's attribute with the same name. Specifies the width of the border surrounding the image.	Yes	No
bundle	See "Common Tag Attributes."	Yes	No
disabled	See "Common Tag Attributes."	Yes	No
indexed	See "Common Tag Attributes."	Yes	No
locale	Specifies the key for a java.util.Locale instance stored as a session attribute that will be used when looking up message keys specified by other attributes of this tag (i.e., pageKey and srcKey).	Yes	No
onblur	See "Common Tag Attributes."	Yes	No
onchange	See "Common Tag Attributes."	Yes	No
onclick	See "Common Tag Attributes."	Yes	No
ondblclick	See "Common Tag Attributes."	Yes	No
onfocus	See "Common Tag Attributes."	Yes	No
onkeydown	See "Common Tag Attributes."	Yes	No
onkeypress	See "Common Tag Attributes."	Yes	No
onkeyup	See "Common Tag Attributes."	Yes	No
onmousedown	See "Common Tag Attributes."	Yes	No
onmousemove	See "Common Tag Attributes."	Yes	No
onmouseout	See "Common Tag Attributes."	Yes	No
onmouseover	See "Common Tag Attributes."	Yes	No
onmouseup	See "Common Tag Attributes."	Yes	No
page	Specifies a module-relative URL for this button's image.	Yes	No
pageKey	Specifies a key from the application resource bundle whose value will be used to set the corresponding HTML tag's src attribute with a module-relative URL.	Yes	No
property	Same as the corresponding HTML tag's name attribute. Specifies the name that will be associated with this control.	Yes	No
src	Same as the corresponding HTML tag's attribute with the same name. Specifies the source URL for this button's image.	Yes	No
srcKey	Specifies a key from the application resource bundle whose value will be used to set the corresponding HTML tag's src attribute.	Yes	No
style	See "Common Tag Attributes."	Yes	No
styleClass	See "Common Tag Attributes."	Yes	No
styleId	See "Common Tag Attributes."	Yes	No
tabindex	See "Common Tag Attributes."	Yes	No
title	See "Common Tag Attributes."	Yes	No
titleKey	See "Common Tag Attributes."	Yes	No
value	Specifies a constant value that this control will be populated with. If not specified, this tag will attempt to use its body content as the value.	Yes	No

Example Usage

As mentioned, there are two ways you can use the image tag. The first way, shown here, uses the page attribute to specify a module-relative URL for the generated HTML tag's src attribute:

<html:image page="previous.gif"/>

The second way to use the image tag is shown here:

<html:image src="/books/1/249/1/html/2//images/next.gif"/>

This example uses the src attribute to specify a URL for the generated HTML tag's src attribute. The image tag will be used in this way for most applications; however, if you are taking advantage of Struts' module functionality, you will use the page or pageKey attribute.