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.
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>
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.
The form tag controls many important aspects of the page. Its attributes are shown in Table 8-2.
18.104.22.168 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">
22.214.171.124 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.
126.96.36.199 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:
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.
188.8.131.52 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.
184.108.40.206 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").
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:
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.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.