The name attribute determines the name of the submitted value, just like the name attribute of an HTML form input element. As we've already seen, if the action we're submitting to contains a property of the same name, the form value will be set on that property (with the help of XWork's type conversion).

<!-- Value will be initialized to action's "foo" property
value (null values will be blank, *not* "null") -->
<s:textfield name="foo" />

The value attribute, if specified, sets the initial value of the input element. If no value is specified, the value will be initialized from the action property in the name attribute. The value attribute can be an OGNL expression.

<!-- Sets text element's value to "hello" -->
<s:textfield name="foo" value="%{'hello'}" />
<!-- Sets text element's value to "10" -->
<s:textfield name="foo" value="%{5 + 5}" />

The %{} syntax forces Struts 2 to evaluate the expression. The Struts 2 tag documentation lists which attributes are evaluated (in theory), but that may mean by default. The value attribute is listed as not being evaluated. However, when wrapped in the OGNL escape sequence %{}, the attribute will be evaluated. Some people prefer to use the %{} characters around all OGNL expressions to resolve any ambiguity. Suppose that we use the following:

value="hello"

This would actually put the word hello into the text input, without calling getHello() in our action. In this particular case, we must use the %{} characters to force evaluation:

value="%{hello}"

In this case, our action's getHello() method is called.

The label attribute sets the label of the input element. We can set this to a simple string and use our action's getText() methods, if we extended ActionSupport (remember Chapter 3?). We might set an input element's label as we see here:

<s:textfield name="text1" label="%{getText('text1')}" />

This uses the same resource lookup logic we've seen previously.

The key attribute replaces all three attributes, cleaning up our JSP pages quite a bit. It does the label text lookup and sets the name attribute. For the key attribute to work properly, our action must extend ActionSupport, as we're relying on its getText() methods. The key attribute reduces the most common use case to:

<s:textfield key="text1" />

One possible disadvantage of the key attribute is that our label messages must have the exact same name as our field names. Sometimes, we'll see labels named by the field name, and a prefix or suffix, such as text1.label.

If our application is not internationalized with messages stored in resource files, this might seem like an extra, unnecessary step. In some cases, particularly in smaller applications, it can be frustrating and is arguably not worth the extra hassle. However, separating text like this can make both development and documentation easier. It may also provide long-term benefits not originally anticipated.

Most of the standard HTML input element attributes are supported. As with<s:form>, CSS styles and classes are handled with the cssStyle and cssClass attributes. All the event handler attributes are supported. A complete attribute list for each tag is available on the Struts 2 documentation wiki.

The default table layout may not work for a particular application. In that case, we can use the simple theme (which may actually be too simple, as error messages are not rendered) or the css_xhtml theme. If neither of these work, we must either create a custom theme (which can be as simple as taking an existing theme and tweaking it slightly, or as complicated as completely redoing every template) or avoid the Struts 2 form tags altogether, which may make sense in some circumstances.

We've already seen<s:textfield> in the previous examples. It renders a text input element and accepts the maxlength and size attributes as a normal HTML text input element. It is used to enter strings, numbers, and so on. The<s:password> and<s:hidden> tags render password and hidden fields, respectively. The<s:hidden> tag does not render a label.

<s:textfield key="firstname" />
<s:password key="password" />
<s:hidden key="hiddenField" />

The<s:textarea> tag renders an HTML<textarea> tag, taking similar attributes like cols, rows, and so on.

<s:textarea key="directions" />

The<s:label> tag isn't an input element per se, but can still be useful. It renders a table row, as the other input elements do, and emits two HTML<label> tags. The first label is like the other input elements—the label is either defined explicitly using the label attribute or by lookup using the key attribute.

The second label is the value of the named element. Instead of rendering an input element, the<s:label> tag renders the value in an HTML<label> tag, providing a read-only view of the value. For example, assume that our action property firstname is set to Albert (and we have a message named firstname):

<s:label key="firstname" />

It will be rendered as:

<tr>
<td>
<label for="firstname" class="label">
First Name:
</label>
</td>
<td><label id="firstname">Albert</label></td>
</tr>

Styling the label containing the data can be done using the normal cssClass and/or the cssStyle attributes. Note that this only styles the label containing the data (column two) and not the label for the label (column one). We can use CSS tricks and style label elements, but it is just not as flexible as it could be.

The<s:radio> tag renders a collection of radio buttons. As such, the tag requires a List or Map to be used for the radio button values. There are various ways to control what gets rendered as the radio button value and label. The simplest method is to supply a List of any type. Its toString() representation will be used as both the value and the label. In our action:

public List<String> getGenderOptions() {
return new ArrayList<String>() {{
add("Male"); add("Female"); add("Other");
}};
}

We then use the radio tag, providing a list attribute value. Here, we use the key attribute to retrieve both the form element label and define the action property that will be set.

<s:radio key="gender" list="genderOptions" />

We can also use an immediate list:

<s:radio key="gender" list="{'male', 'female', 'other'"/>

This renders a row of radio buttons like this:

Relying on the toString() representation is fine for simple types, such as strings or integers. However, complex values usually require the specification of listKey and listValue attributes. These attributes specify which bean properties will be used for the radio button value and label. Perhaps confusingly, the listKey property is used as the radio button value, while the listValue property will be used as the label.

For example, our action property coolBeans is a collection of beans, each with id and text fields. We could specify our<s:radio> tag like this:

<s:radio key="stringFromRadio" list="coolBeans"
listKey="id" listValue="text"/>

Radio button collections can also be created from maps. The map keys will be used as the radio button values, the map entry's toString() being used as the label. We cannot use the listKey and listValue with maps. If we use them, we'll get a FreeMarker exception.

This is a bit of a hassle, as that means we can only use a map containing simple objects, or we must provide a toString() method suitable for use on our view side. In other words, we can't have a more complete toString(), which could be used for logging, and so on.

Maps, of course, are generally unordered. If we need the radio buttons to appear in a specific order, we'd need to use a TreeMap or another ordered map.

The<s:checkbox> tag renders a single checkbox. At the time of this writing it only works well with Boolean (or boolean) properties. Attempting to preselect a checkbox with, for example, a string value only works if the string is true or false.

<s:checkbox key="checkbox1" />

We can set the value that will be sent back to the browser with the fieldValue attribute:

<s:checkbox key="checkbox1" value="Y" fieldValue="Y"/>

Browsers do not send a value for unchecked checkboxes to the server on a form submit. This causes some confusion, particularly among those who choose not to learn how browsers work. In the "xhtml" theme, the<s:checkbox> tag also renders a hidden element containing the current value of the checkbox property.

<tr>
<td valign="top" align="right"></td>
<td valign="top" align="left">
<input type="checkbox" name="checkbox1" value="true"
id="forms1_checkbox1"/>
<input type="hidden" id="__checkbox_forms1_checkbox1"
name="__checkbox_checkbox1" value="true" />
<label for="forms1_checkbox1" class="checkboxLabel">
Checkbox 1
</label>
</td>
</tr>

Notice the funky name for the hidden input element. The hidden form value is used by the checkbox interceptor. The checkbox interceptor looks for request parameters with a leading __checkbox_. If anything is found with no corresponding checkbox value, it indicates that the checkbox wasn't checked and the hidden value is set on the checkbox's action property. It's a nice way to work around how browsers handled unchecked checkboxes, neatly encapsulated in a custom tag and an interceptor. Our mainline code doesn't have to worry about any of this anymore (Yes, no more ActionForm.reset())

The<s:checkboxlist> tag, of course, renders a list of checkboxes. It operates similar to the<s:radio> tag, except that the action property being set should be a collection (or array) rather than a single value. Similar to the<s:radio> tag, using a map will result in the map keys being the checkbox value and the map entry's toString() as the label. You may also use the listKey and listValue attributes, as with the radio tag.

<s:checkboxlist key="cblist" list="listOfCbs"/>

At the time of writing this chapter, the hidden fields rendered by the<s:checkbox> tag are not rendered by<s:checkboxlist>. For example, if we needed to do something with the collection of options that were unselected, we'd need to do that on our own.

Moreover, as of this writing,<s:checkboxlist> ignores the cssClass and cssStyle attributes, making styling it a bit more problematic than the other UI tags.

Let's return to our recipe application for a moment, create a user story, and prototype an implementation. This user story, like all user stories, is short and sweet:

First, we'll create a RecipeType class, which seems to consist only of an integer ID and a string name. Mercifully, we won't list the code here (it's as we'd expect).

We'll also create a RecipeTypeService interface and a fake implementation, as we did with the recipes. We give the interface a getAll() method, returning a list of RecipeTypes. The fake implementation just returns a hard-coded list.

For now, our recipe class will get a List<String> recipeTypes to hold its collection of recipe type names, and our FakeRecipeService is modified to add some recipe types to each of our test recipes.

We'll also take this opportunity to modify our new recipe form to use Struts 2 tags, significantly cleaning it up and again making us crabby as we didn't do it that way in the first place. As a brutal reminder, here's what the JSP looked like for just the recipe name:

<tr>
<th>Name</th>
<td>
<s:if test="getFieldErrors().get('recipe.name') != null">
<div class="error">
<s:property
value="getFieldErrors().get('recipe.name')[0]" />
</div>
</s:if>
<input name="recipe.name" type="text" size="20"
value="<s:property value="recipe.name"/>" />
</td>
</tr>

Converting the form to use Struts 2 form tags, putting our labels in a resource file, and adding the new recipe type field, reduces our form JSP to this:

<s:form action="newRecipe">
<s:textfield key="recipe.name" />
<s:textfield key="recipe.description" />
<s:checkboxlist key="recipe.recipeTypes"
list="recipeTypeOptions"
listKey="name" listValue="name" />
<s:textarea key="recipe.ingredients" rows="5" cols="40" />
<s:textarea key="recipe.directions" rows="5" cols="40" />
<s:submit />
</s:form>

It's marginally cleaner (just like I have a marginal penchant for understatement).

In the above JSP fragment, we see that we're providing the list of recipe type options using an action property named recipeTypeOptions. Here's the rub: to get to our form we're requesting /recipes/new-recipe, and relying on Convention Plug-in to create the backing action for us. We need a way to get the recipe types into our action for use on the JSP.

There are several ways to accomplish this. We could just put the recipe types into application scope, so they can be used across the application with no database calls. However, this is not contrived enough for a book example. Therefore, we'll look at two additional options.

One solution would be to create a recipe action subclass—NewRecipeAction. It would implement the Preparable interface and contain a recipeTypeOptions property. We'd put code in its prepare()method to load up the recipe types.

We'll go a second route. We'll create a single class, NewRecipeAction, which implements Preparable, and uses the @Action annotation to create another URL handler. Both the initial form display (handled by ActionSupport's default execute() method) and the form submit (defined using the @Action annotation) are handled in the same class. The action, minus saving new recipes, and without imports, getters, and setters is shown next:

package com.packt.s2wad.ch06.actions.recipes;
public class NewRecipeAction extends ActionSupport
implements Preparable {
private Recipe recipe;
private Collection<RecipeType> recipeTypeOptions;
private static RecipeTypeService recipeTypeService =
new FakeRecipeTypeService();
public void prepare() throws Exception {
recipeTypeOptions = recipeTypeService.getAll();
}
@Action(value = "new-recipe-process")
public String process() {
// Handle saved recipe.
return "thanks";
}
}

We'd also need to make sure that validation errors return us to /recipes/new-recipe. There are several ways we could do this with the Convention Plug-in, including using the @Result annotation to define an "input" result.

The<s:select> tag renders a select box, with the options filled from its list attribute, similar to the radio and checkbox list tags.

As with the other collection-oriented tags, if our collection is contained in a map, the map key will be used as the value, and the map's toString() value will be used as the option text. When using a map, the listKey and listValue attributes are ignored. However, the select tag doesn't give us a FreeMarker exception. The attributes are just ignored, and we get a select box with empty values and text.

The optional headerKey and headerValue attributes specify an<option> rendered first, at the top of the list of options. This can be used to specify instructional text—for example, "-- Select State --" or similar. The headerKey attribute specifies the header option value, while the headerValue specifies the header option's text.

The emptyOption attribute specifies whether or not a blank<option> will be generated at the top of the<option>s, although, if one is specified after the header option. In general, it's likely that only one of the emptyOption and headerKey/headerValue attributes is used—it's not a requirement though (it's fine to use both, at least from a technical standpoint).

The<s:select> tag also accepts a multiple attribute, which does what we expect. Additionally, if the value passed to the tag (through either the key or the value attributes) is a collection, the multiple preselects will be rendered appropriately.

The<s:optgroup> tag provides an HTML<optgroup> element within a<s:select> tag. It takes a label attribute to specify the label of the option group. It can either be an immediate value or a getText() call as we've seen previously.

The<s:optgroup> tag is a bit quirky when using a list as an argument to the list attribute. If we use a map as the list argument, everything is fine (although once again, providing listKey and listValue attributes produce a FreeMarker exception). When we use a List, we must provide both the listKey and listValue attributes, or we'll receive a FreeMarker template exception.

One potential gotcha with<s:optgroup> is that if all our options are contained in optgroups, we must still provide a list to the surrounding select tag because the list attribute is required. We can use OGNL's immediate list syntax to provide this:

<s:select name="optg1" list="{}">

Not a huge deal, but it is something to keep in mind.

The<s:submit> tag renders a "submit" input element. Either the key or the value attributes may be used to specify the text of the submit button. As usual, the key attribute will perform a property lookup, while the value attribute will use its value as the button text.

The submit button accepts a type attribute, which may be input, button, or image. The input type renders a normal submit input element, while the button and image types render what we'd expect. IE (of course) has certain issues with button input elements. However, if we are targeting other browsers, button inputs are nice because we can use different values for the button text and value.

The<s:submit> tag also accepts the action and method parameters. These require a bit of hackery on the server side to let us specify the action we'll submit to, and/or the action method to execute, when we click to submit.

If we specify an action attribute and examine the emitted HTML (always a good idea), we'll notice that the input element's name attribute has changed to action: plus whatever we specified as the action attribute's value. Similarly, specifying a method attribute sets the name to method: plus the value of the method attribute.

If we specify both, the input element's name attribute is set to action: plus the action and method attributes joined by "!" (an exclamation mark). The action-plus-method attributes require that dynamic method invocation is enabled, and may not always leave the expected URL in the browser's address bar, if such things matter to us.

This tag renders a "reset" input element. It accepts the same attributes as the<s:submit> tag. However, if neither the action nor the method attributes are specified as a normal HTML reset, it will just clear the form and will not perform a submit.

The<s:combobox> tag renders both a text input element and a select box.

<s:combobox key="combo1" list="hellos" />

The text element can be filled directly, or by changing the select box's value. The text value is updated only when the select box value changes, meaning, we'll almost always want to include either the emptyOption or the headerKey/headerValue attributes.

As the text box won't be filled (or cleared) if the select box value is empty, the default behavior of the<s:combobox> tag may not always be what we want. Also, selecting an empty option will not clear the text box—the JavaScript checks for nonempty values.

Using a map for the list attribute will again act in a way that is a bit counter intuitive. The listKey and the listValue attributes are ignored completely, although no exception is thrown. However, if the map uses something like an integer as its key, the text box will be filled with an integer rather than text, opposite of what we probably want.

The<s:updownselect> tag renders a select box along with an optional set of buttons for moving the currently selected list item (or items) up or down in the list, or to select all items in the list. Note that all the items in the list are submitted. This is a control for ordering a list, not for selecting individual list items.

<s:updownselect key="updown1" list="goodbyes"/>

The creation of the buttons is controlled by three attributes—allowMoveUp, allowMoveDown, and allowSelectAll—each of which controls the button we would expect. The label for each may be specified with the moveUpLabel, moveDownLabel, and selectAllLabel attributes. The defaults are "^", "v", and "*".

Again, the listKey and listValue attributes are ignored if the list attribute evaluates to a map, but no exception is thrown.

The<s:optiontransferselect> tag renders two select boxes along with a set of buttons for moving selected options between the two selects, moving all elements from one to the other, and ordering selections within each. Button rendering and button labels are controlled by a long list of attributes.

The only required attributes are:

The simplest use looks like this, and renders as follows:

<s:optiontransferselect label="Transfer" list="options"
doubleList="{}" doubleName="rightList" />

The usual suspects for list-oriented attributes are available for both the rendered select boxes—prefix the attribute name with double to apply to the second (righthand) select box. The same applies for event handler attributes. For example, the onclick attribute is for the lefthand list, whereas the doubleOnclick attribute is for the righthand list.

All entries of the righthand select box are submitted.

All of the control buttons are optional and are controlled using tag attributes. For example, the buttons labeled<<-- and -->> (which move the original list of items into the lefthand or righthand boxes) can be removed by setting the allowAddAllToLeft and/or allowAddAllToRight attributes to false.

Perhaps surprisingly, removing the "add all" buttons won't change the height of the combination control. Setting the size attribute doesn't quite work either. We actually need to set both size and doubleSize to reduce the height of the entire control.

There are also attributes for specifying JavaScript to run on the click of any of the buttons, and so on (see the Struts 2 documentation wiki for an exhaustive list).

Finally, the<s:doubleselect> tag renders two select boxes where selecting an item in the first select box (the lefthand select) determines which values are visible in the second select box (the righthand select). The collection for the second select box is chosen using an OGNL expression. The example provided on the Struts 2 documentation wiki looks something like the following, but has only two elements in the lefthand list. Here, we're using a three-element list, making the doubleList attribute's OGNL a bit awkward.

<s:doubleselect
doubleName="dsel2"
list="{'one', 'two', 'three'}"
doubleList="top == 'one' ? {'1a', '1b'}
: top == 'two' ? {'2a', '2b'}
: {'3a', '3b'}"/>

At the time of writing this book, the JavaScript generated for this tag fails under Convention-based actions because of the hyphen in the action names (this will be addressed later). Note also that we must use CSS if we want equally sized select boxes.

For longer lists (in either select box), the immediate lists aren't really an option. However, we recall that OGNL can call arbitrary methods with parameters. Using this and the idea that the currently-selected item in the first select box is called "top", leads us to the following solution. It's more realistic because in many (most?) applications, both sets of lists will come from the server.

<s:doubleselect doubleName="dsel4"
list="doublelist1"
doubleList="getDoublemap1(top)"/>

Here, we've created a method getDoublemap1(String s) in our action that returns the appropriate collection type for our application. We just use the currently selected value of the first list to determine the contents of the second list.