Many applications need to use a large number of checkboxes to track options or selected items. To help with this, Struts provides the multibox control. It's quite handy but a little tricky to understand at first.
The multibox leverages the way HTML handles checkboxes. If the box is not checked, the browser does not submit a value for the control. If the box is checked, then the name of the control and its value are submitted. This behavior is the reason there
is a reset() method on the ActionForm. Since the browser will never signal that a box has been un-checked, the only solution is to reset all the boxes, and then check the ones that are now present in the request.
The multibox control is designed to use an array of Strings. Each element in the array represents a checked box. To check a box, add a String to the array with the box's value. To uncheck a box, remove the element from the array. (Sound familiar?)
When passed a value, the multibox control scans the elements of its array to see if there is a match. If so, the box is checked. If not, the box is left unchecked. If the user checks the box and submits the form, the box's value will be included in the
request. The controller will then add that box to the "checked" array. If a box is unchecked, nothing is submitted, and nothing is added to the array. If the ActionForm bean is kept in the session context, in between requests, the reset() method
needs to reduce the array to zero length (but not null).
In this example,
<logic:iterate id="item" property="items">
<html:multibox property="selectedItems">
<bean:write name="item"/>
</html:multibox>
<bean:write name="item"/>
</logic:iterate>
The labels for the individual checkboxes is in the items property. The list of selected items is in an array named selectedItems. Items that are not selected are not present in the selectedItems array. The multibox checks the selectedItems array for
the current item. If it is present, it writes a checked checkbox. If not, it writes an unchecked checkbox.
Given an ActionForm setup like this
private String[] selectedItems = {};
private String[] items = {"UPS","FedEx","Airborne"};
public String[] getSelectedItems() {
return this.selectedItems;
}
public void setSelectedItems(String[] selectedItems) {
this.selectedItems = selectedItems;
}
The markup in the example would generate three checkboxes, labeled UPS, FedEx, and Airborne.
<input type="checkbox" name="selectedItems" value="UPS">UPS
<input type="checkbox" name="selectedItems" value="FedEx">FedEx
<input type="checkbox" name="selectedItems" value="AirBorne">AirBorne
Initially, the selectedItems array would be empty. If UPS were checked and submitted, it would become the equivalent of
private String[] selectedItems = {"UPS"};
If UPS and Airborne were both checked, it would become the equivalent of
private String[] selectedItems = {"UPS","Airborne"};
And when the checkboxes are rendered, the appropriate elements are automagically checked by the multibox tag.
<input type="checkbox" name="selectedItems" value="UPS" checked="checked">UPS
<input type="checkbox" name="selectedItems" value="FedEx">FedEx
<input type="checkbox" name="selectedItems" value="AirBorne" checked="checked">AirBorne
org.apache.struts.util.LabelValueBean] (since 1.1) can be used with the multibox control.
<logic:iterate id="item" property="items">
<html:multibox property="selectedItems">
<bean:write name="item" property="value"/>
</html:multibox>
<bean:write name="item" property="label"/>
</logic:iterate>
