8.4 Struts HTML Tags

The Struts HTML tag library contains tags used to create HTML input forms, as well as other tags generally useful in the creation of HTML-based user interfaces. For example, instead of using a regular HTML text-input field, you can use the text tag from this library.

These tags are designed to work very closely with the other components of the Struts framework, including ActionForms. You always should attempt to use one of these tags first, rather than using standard HTML. These tags' special knowledge of the rest of the Struts components makes it worthwhile to use them.

Most of the tags within this library must be nested inside of a Struts form tag. There are a few tags included in this library that address issues not necessarily related to forms or form widgets. Those tags also will be discussed briefly in this section. Although not every HTML tag will be discussed, Table 8-1 provides a complete list of the tags that are available in the HTML tag library.

Table 8-1. Custom tags within the Struts HTML tag library

Tag name	Description
base	Renders an HTML base element
button	Renders a button input field
cancel	Renders a cancel button
checkbox	Renders a checkbox input field
errors	Conditionally renders a set of accumulated error messages
file	Renders a file select input field
form	Defines an HTML form element
frame	Renders an HTML frame element
hidden	Renders a hidden field
html	Renders an HTML html element
image	Renders an input tag of type "image"
img	Renders an HTML img tag
javascript	Renders JavaScript validation based on the validation rules loaded by the ValidatorPlugIn
link	Renders an HTML anchor or hyperlink
messages	Conditionally displays a set of accumulated messages
multibox	Renders multiple checkbox input fields
option	Renders a select option
options	Renders a collection of select options
optionsCollection	Renders a collection of select options
password	Renders a password input field
radio	Renders a radio button input field
reset	Renders a reset button input field
rewrite	Renders a URI
select	Renders a select element
submit	Renders a submit button
text	Renders an input field of type "text"
textarea	Renders a textarea input field
xhtml	Render HTML tags as XHTML

As stated earlier, this chapter will not discuss every tag within the Struts framework; to do so would be redundant, as that material is covered thoroughly in the Struts JavaDocs. Instead, certain tags will be selected and discussed based on their importance, on how confusing they are to new developers, and on whether there are practical strategies for using the tags. If you need a reference to the complete set of available tags, the Jakarta Struts Pocket Reference (O'Reilly) includes information and examples on all of the Struts tags.

8.4.1 The html Tag

The html tag renders an HTML html element. It allows you to include a locale attribute that will write out the user's locale, assuming one has been stored into the session:

<html:html locale="true">   <!-- Body of the JSP page --> </html:html>

Starting with Struts 1.2, the locale attribute will be deprecated and replaced with the lang attribute. In Struts, the locale is tied to a user's HttpSession object. In 1.1 and earlier, using the locale attribute requires this session object to be created; however, not all applications use sessions, and it is undesirable for those that don't to use them. The lang attribute will achieve the same functionality without the need for a session.

Struts 1.1 added a new attribute to the html tag called xhtml. Set this attribute to true in order to render xml:lang and xmlns attributes on the generated html element. This also causes all other html tags to render as XHTML 1.0.

8.4.2 The base Tag

This tag renders an HTML base element with an href attribute pointing to the absolute location of the enclosing JSP page. This tag is useful because it allows you to use relative URL references that are calculated based on the URL of the page itself, rather than the URL to which the most recent submit took place (which is what the browser normally would resolve relative references against). This tag must be placed within the HTML head element. The following is an example of using the base tag:

<html:html locale="true">  <head>    <html:base/>    <title><bean:message key="title.login"/></title>  </head> </html:html>

The base tag example here would produce the following output when executed in the main page of the Storefront application:

<html lang="en">  <head>    <base href="http://localhost:8080/storefront/index.jsp">    <title>Virtual Shopping with Struts</title>  </head> <html>

This tag is very important when using relative URLs for images in a JSP page. There are two attributes for the base tag: target and server. You can use the target attribute in order to specify a window target for this base reference. The server attribute is used to specify the server name, and overrides the value that comes from request.getServerName().

8.4.3 The form Tag

The Struts form tag is one of the most important tags in the HTML tag library. Its purpose is to render a standard HTML form tag and to link the HTML form with an ActionForm configured for the application.

Each field in the HTML form should correspond to a property of the ActionForm. When an HTML field name and a property name match, the property from the ActionForm is used to populate the HTML field. When the HTML form is submitted, the framework will store the user's input into the ActionForm, again matching up the HTML field names to the property names.

All of the HTML custom tags that render HTML controls must be nested within the html tag. DynaActionForm and its subclasses function the same way with the form tag.

The form tag controls many important aspects of the page. Its attributes are shown in Table 8-2.

Table 8-2. The form tag attributes

Name	Description
action	The URL to which this form will be submitted.
enctype	The content encoding to be used when submitting this form.
focus	The field name to which initial focus will be assigned for this page.
focusIndex	If the focus field is a field array, such as a radio button group, you can specify the index in the array to receive focus.
method	The HTTP method that will be used to submit this request.
name	The name of the ActionForm whose properties will be used to populate the input field values.
onreset	The JavaScript event handler executed if the form is reset.
onsubmit	The JavaScript event handler executed if the form is submitted.
scope	The scope of the ActionForm for this form.
style	The CSS styles to be applied to this HTML element.
styleClass	The CSS stylesheet class to be applied to this HTML element.
styleId	The identifier to be assigned to this HTML element.
target	The frame target to which this form is submitted.
type	The fully qualified class name of the ActionForm for this page.

8.4.3.1 The action attribute

The value for the action attribute is used to select the ActionMapping the page is assumed to be processing, from which we can identify the appropriate ActionForm and scope.

If extension mapping is being used (*.do), the action value should be equal to the value of the path attribute of the corresponding action element, optionally followed by the correct extension suffix. An example of this is:

<html:form action="login.do" focus="accessNumber">

If path mapping is used instead, the action attribute value should be exactly equal to the value of the path attribute of the corresponding action element:

<html:form action="login" focus="accessNumber">

8.4.3.2 The enctype attribute

Typically, you won't need to set the enctype attribute. However, if your form is performing file uploads, you should set the enctype attribute to multipart/form-data. You also must make sure the method attribute is set to POST, which is the default method if none is specified.

8.4.3.3 The name attribute

The name attribute specifies the name of the request- or session-scope ActionForm whose properties will be used to populate the input field values. If no such bean is found, a new bean will be created and added to the appropriate scope, using the Java class name specified by the type attribute.

If no value is specified for the name attribute, it will be calculated by using the value of the action attribute to look up the corresponding ActionMapping element, from which the form bean name will be determined. In other words, if no name attribute is specified for the form tag, the tag will use the value from the name attribute in the action element from the configuration file. This is a very important point that confuses many new Struts developers. Let's look at an example. Suppose there is an action element configured like the following:

<action   path="/signin"   type="com.oreilly.struts.storefront.security.LoginAction"   scope="request"   name="loginForm"   validate="true"   input="/security/signin.jsp">   <forward name="Success" path="/index.jsp" redirect="true"/>   <forward name="Failure" path="/security/signin.jsp" redirect="true"/> </action>

Now say you have a form tag that looks like this declared in a JSP page:

<html:form action="signin">

Because the name attribute is not specified in the form tag, the tag will look up the signin action from the configuration file. It will retrieve the value of the name attribute from the action element and use that to check for an ActionForm in either the request or session scope. In this case, the loginForm will be selected because it's the value for the name attribute in the action element.

8.4.3.4 The scope attribute

The scope attribute defines where the tag should look for the ActionForm. Its value must be either request or session. If the scope attribute is not specified, it will be calculated by using the value of the action attribute to look up the corresponding ActionMapping element, from which we will select the specified form bean scope. This is similar to how the name attribute is determined if it's not specified in the form tag.

8.4.3.5 The type attribute

The type attribute specifies the fully qualified class name of the ActionForm to be created if no such bean is found in the specified scope. If this attribute is not specified, it will be calculated by using the value of the action attribute to look up the corresponding ActionMapping element, from which we will select the specified form bean type.

8.4.4 Using Multiple form Tags

As with standard HTML, you can include more than one form tag within a JSP page. Obviously, only one form can be submitted at a time, but that doesn't stop you from declaring multiple form tags. For example, you might have a form tag for a search area of the page. When the user presses the search button, that form is submitted along with the search criteria fields. In that same page, you might also have another form tag that performs a different function. When a button within that form is pressed, that form and its corresponding fields are submitted. Example 8-1 provides an example of what that might look like.

Example 8-1. Using multiple form tags

<html:html locale="true">  <head>    <html:base/>  </head>  <body>   <!-     <html:form action="searchAction">     <!-- The search fields -->     <html:submit style value="Go"/>    </html:form>    <html:form action="anotherAction">     <!-- The other form fields -->     <html:submit style/>    </html:form>  </body> </html:html>

8.4.5 The button and cancel Tags

These two tags render HTML input elements of type button, populated from the specified value or from the content of the tag body. These tags are valid only when nested inside a form tag body.

Stylesheets also can be used with these tags by supplying a value for the styleClass attribute. By default, the button label is set to the value "Click" and the cancel label is set to the value "Cancel". You can override this using the value attribute.

The button produced by the cancel tag has a special characteristic that causes the validate() method to be skipped when it's pressed. The RequestProcessor just calls the execute( ) method, without going through the validation routine.

8.4.6 The checkbox Tag

This tag renders an HTML input element of type checkbox, populated from the specified value or the specified property of the bean associated with the current form. This tag is valid only when nested inside a form tag body.

The underlying property value associated with this field should be of type boolean, and any value you specify should correspond to one of the strings that indicate a true value ("true", "yes", or "on").

The browser will send values in the request only for those checkboxes that are checked. To correctly recognize unchecked checkboxes, the ActionForm bean associated with this form must include a statement setting the corresponding boolean property to false in the reset() method.

8.4.7 The messages and errors Tags

These two tags are responsible for displaying a set of general-purpose messages or errors to the user. Messages correspond to ActionMessages, and errors to ActionErrors. The messages/errors are created either in the validate() method or by the exception-handling framework. If no messages or errors are present, nothing will be rendered.

When using the errors tag, the message bundle must include message keys for the following values:

errors.header

Text that will be rendered before the error messages list. Typically, this message text will end with <ul> to start the error messages list.

errors.footer

Text that will be rendered after the error messages list. Typically, this message text will begin with </ul> to end the error messages list.

For example, we might set the header and footer values to:

errors.header=<h3><font color="red">Validation Error</font></h3> You must correct the following error(s) before proceeding:<ul> errors.footer=</ul><hr>

When the errors are written out to the HTML page, they'll appear inside a bulleted list. Now that the Struts framework supports multiple MessageResources within the configuration file, you can specify which one should be used using the bundle attribute.

8.4.8 JavaScript Event Handlers

Many of the HTML tags support JavaScript event handlers through the use of their attributes. For example, to configure an onClick handler for a supported tag, you need to include the function name in the onClick attribute for the tag. Table 8-3 lists the attributes for the supported event handlers.

Table 8-3. Attributes for the supported JavaScript event handlers

Attribute	Description
onblur	Executed when this element loses input focus.
onchange	Executed when this element loses input focus and its value has changed.
onclick	Executed when this element receives a mouse click.
ondblclick	Executed when this element receives a mouse double-click.
onfocus	Executed when this element receives input focus.
onkeydown	Executed when this element has focus and a key is depressed.
onkeypress	Executed when this element has focus and a key is depressed and released.
onkeyup	Executed when this element has focus and a key is released.
onmousedown	Executed when this element is under the mouse pointer and a mouse button is depressed.
onmousemove	Executed when this element is under the mouse pointer and the pointer is moved.
onmouseout	Executed when this element is under the mouse pointer but the pointer is moved outside the element.
onmouseover	Executed when this element is not under the mouse pointer but the pointer is moved inside the element.
onmouseup	Executed when this element is under the mouse pointer and a mouse button is released.
onreset	Executed if the parent form is reset.
onsubmit	Executed if the parent form is submitted.

8.4.9 HTML Navigation Attributes

Many of the tags also support navigation using only the keyboard. This is done using the attributes listed in Table 8-4.

Table 8-4. Attributes for the keyboard navigational support

Attribute	Description
acesskey	The keyboard character used to move focus immediately to this element.
tabindex	The tab order (ascending positive integers) for this element.