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

As was 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, you can find information in the Struts framework API documents at http://jakarta.apache.org/struts/api/.

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>

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 no attributes associated with this tag.

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.
`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 styleClass="button" value="Go"/>

   </html:form>

   <html:form action="anotherAction">

    <!-- The other form fields -->

    <html:submit styleClass="button"/>

   </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.