Check Boxes and Radio Buttons

This section provides information on the following tags:

<html:checkbox> Render an HTML <form> element
<html:multibox> Place a text box INPUT element on a form
<html:radio> Place a Cancel INPUT element on a form

If you point your browser to the URL http://myAppServer/StrutsTaglibs/html.jsp

you'll bring up the main page that links to all the sample code for the Struts tag chapters. This section uses the Checkboxes and Radio Buttons page at /StrutsTaglibs/CheckboxRadio.do . The page rendered is shown in Figure 12.4.

Figure 12.4. The Checkboxes and Radio Buttons page at `/StrutsTaglibs/CheckboxRadio.do` .

graphics/12fig04.gif

This page contains two <html:checkbox> tags, two <html:multibox> tags, and two <html:radio> tags. Listing 12.4 is the JSP file that creates this page.

Listing 12.4 JSP File Demonstrating the Use of `<html:checkbox>` , `<html:multibox>` , and `<html:radio>` Tags ( `CheckboxRadio.jsp` )

 <%@ page language="java" %> <%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %> <%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %> <html:html> <head> <title>Checkboxes and Radio Buttons</title> </head> <body bgcolor="white"> <h3>Checkboxes and Radio Buttons</h3> <p>This page provides examples of the following Struts HTML tags:<br> <ul> <li>&lt;html:checkbox&gt;</li> <li>&lt;html:multibox&gt;</li> <li>&lt;html:radio&gt;</li> </ul> <html:form action="CheckboxRadio.do"> <table border="1" width="100%">   <tr>     <th align="left" width="20%">     &lt;html:checkbox&gt;     </th>     <th align="left" width="80%">     Struts code for example     </th>   </tr>   <tr>     <td align="left">       Checkbox 1:       <html:checkbox property="checkbox1"/>     </td>     <td align="left">         &lt;html:checkbox property="checkbox1"&gt;         - Normal checkbox     </td>   </tr>   <tr>     <td align="left">       Checkbox 2:       <html:checkbox property="checkbox2" />     </td>     <td align="left">         &lt;html:checkbox property="checkbox2" /&gt;         - Strange behavior - form bean doesn't reset     </td>   </tr> </table> <table border="1" width="100%">   <tr>     <th align="left" width="20%">       &lt;html:multibox&gt;     </th>     <th align="left" width="80%">       Struts code for example     </th>   </tr>   <tr>     <td align="left" width="20%">       Multibox 1:       <html:multibox property="strArray" value="Value1"/>     </td>     <td align="left" width="80%">       Multibox 1:       &lt;html:multibox property="strArray" value="Value1"/&gt;     </td>   </tr>   <tr>     <td align="left" width="20%">       Multibox 2:       <html:multibox property="strArray">Value2</html:multibox>     </td>     <td align="left" width="80%">       Multibox 2:       &lt;html:multibox property="strArray"&gt;Value2&lt;/html:multibox&gt;     </td>   </tr> </table> <table border="1" width="100%">   <tr>     <th align="left" width="20%">     &lt;html:radio&gt;     </th>     <th align="left" width="80%">     Struts code for example     </th>   </tr>   <tr>     <td align="left" width="20%">       <html:radio property="radioVal" value="Value1"/>       Radio Button 1     </td>     <td align="left" width="80%">       &lt;html:radio property="radioVal" value="Value1"/&gt;       Radio Button 1     </td>   </tr>   <tr>     <td align="left" width="20%">       <html:radio property="radioVal" value="Value2"/>       Radio Button 2     </td>     <td align="left" width="80%">       &lt;html:radio property="radioVal" value="Value2"/&gt;       Radio Button 2     </td>   </tr> </table> <table border="0" width="100%">   <tr>     <td align="left" width="20%">&nbsp;</td>     <td align="left">       <html:submit>Submit</html:submit>       <html:reset>Reset</html:reset>       <html:cancel>Cancel</html:cancel>     </td>   </tr> </table> </html:form> </body> </html:html>

For this example, reviewing the form bean is valuable to help demonstrate how these three types of elements are managed. Listing 12.5 is the form bean that goes with this JSP file ( CheckboxRadioForm.java ).

Listing 12.5 Form Bean That Corresponds with `CheckboxRadio.jsp` ( `CheckboxRadioForm.java` )

 package ch12; import javax.servlet.http.HttpServletRequest; import org.apache.struts.action.ActionForm; import org.apache.struts.action.ActionMapping; /**  * <p>Title: HtmlCheckboxForm.java </p>  * <p>Description: Form Bean for the &lt;html:checkbox&gt; example</p>  * <p>Copyright: Copyright (c) 2002</p>  * @author Kevin Bedell & James Turner  * @version 1.0  *  */ public class CheckboxRadioForm extends ActionForm {   // Default bean constructor   public CheckboxRadioForm() { }   // For <html:checkbox> sample code   private boolean checkbox1;   public boolean getCheckbox1() { return this.checkbox1; }   public void setCheckbox1(boolean checkbox1) { this.checkbox1 = checkbox1;}   // For <html:checkbox> sample code   private boolean checkbox2;   public boolean getCheckbox2() { return this.checkbox2; }   public void setCheckbox2(boolean checkbox2) { this.checkbox2 = checkbox2;}   // For <html:multibox> sample code   private String strArray[] = new String[0];   public String[] getStrArray() { return (this.strArray); }   public void setStrArray(String strArray[]) { this.strArray = strArray;}   // For <html:radio> sample code   private String radioVal = "";   public String getRadioVal() { return (this.radioVal); }   public void setRadioVal(String radioVal) { this.radioVal = radioVal;}   public void reset(ActionMapping mapping, HttpServletRequest request) {     this.setCheckbox1(false);  //   Note: With checkbox2 never reset here, it won't ever appear "unset"  //   this.setCheckbox2(false);     this.strArray = new String[0];     this.radioVal = "";   } }

The properties and methods in this class are discussed in the following sections.

The `<html:checkbox>` Tag

The <html:checkbox> tag generates a standalone check box tied to a specific property in a form bean. It should be used when you have a property that can be represented as being either chosen or not chosen (that is, its status is true or false ).

The sample code contains two <html:checkbox> elements. They're mapped, appropriately, to the checkbox1 and checkbox2 properties in the CheckboxRadioForm form bean.

The Struts tags for both elements in this sample are of the following format:

 <html:checkbox property="checkbox1"/>

The only difference between them is the value of the property they map to. They both render similar HTML <input> tags:

 <input type="checkbox" name="checkbox2" value="on">

The first thing to notice is that the underlying properties in the form bean behind the <html:checkbox> tag are boolean . This is the only tag that requires its underlying property to be boolean .

This example doesn't specify a default value for the check boxes, which causes them to take their initial value from the property they're associated with. If you want to, you can override this behavior as follows :

value="true" When the box is checked and the form is submitted, set the boolean value to true .
value="false" When the box is checked and the form is submitted, set the boolean value to false .

Notice that this could be misleading. For example, specifying the attribute to value="false" causes the boolean to be set to true if the box is submitted unchecked.

The string "true" can also be specified as "on" or "yes" . Similarly, the value "false" can be set to "off" or "no" .

By looking at the form bean, you can see an additional difference in how the two properties are handled during the reset() method. Here's the code:

 this.setCheckbox1(false); //    Note: With checkbox2 never reset here, it won't ever appear "unset" //    this.setCheckbox2(false);

Notice that the reset() method doesn't reset the value of checkbox2 . This was done to demonstrate a common gotcha: forgetting to reset a check box value. Because the field isn't reset, after the underlying boolean is set to true , the form always initializes as checked. If you uncheck the check box and submit again, it again returns as checked. In other words, the check box value is never reset.

The `<html:multibox>` Tag

The <html:multibox> tag renders an HTML <input type="checkbox" > tag similar to <html:checkbox> . The difference is in the underlying interactions with the form bean.

The <html:multibox> tag expects its underlying property value to be an array, as opposed to an individual property. Use this tag if you have a number of check boxes and want to manage them all in a single array in the form bean, rather than creating individual form bean properties for each check box.

Here's how to use this tag:

First, define an array in the form bean to hold the values submitted by the check boxes on the form.
Second, add <html:multibox> elements to your form and map each one to the underlying array in the form bean using the property="arrayName" attribute.
For each of the <html:multibox> elements, specify the value to be stored in the array if that element is checked when the form is submitted. This value can be specified in one of two ways: either by using the value="valueToSubmit" attribute, or by nesting the value between opening and closing <html:multibox> tags. For example, you can use either

 <html:multibox property="strArray" value="Value1"/>

 <html:multibox property="strArray">Value2</html:multibox>

When the form is submitted, the array is populated with the values from each of the multiboxes that's checked. If an <html:multibox> element is unchecked, the array simply won't contain its value.

This provides more flexibility than the simpler <html:checkbox> elements in that they allow you to store more than just true or false boolean values. In addition, the form beans end up being much simpler if you have more than just a few check box elements.

A potentially more important benefit is that the number of <html:multibox> elements on a page can be dynamic. That is, you have to add a boolean property to the form bean for each <html:checkbox> element on the form, but any number of <html:multibox> elements can be posted to the same array as long as they have different values.

The `<html:radio>` Tag

The <html:radio> tag renders an HTML <input type="radio"> tag.

Struts <html:radio> tags are used in groups all having the property attribute. For example, here are the two <html:radio> tags included in the sample application:

 <html:radio property="radioVal" value="Value1"/> <html:radio property="radioVal" value="Value2"/>

These tags differ only in that they have different value attributes. Here are the HTML tags that they render:

 <input type="radio" name="radioVal" value="Value1"> <input type="radio" name="radioVal" value="Value2">

Because these two elements share the same name attribute, only one of them can be selected at a time. When the form is submitted, the value of whichever element is selected is posted to the form bean property specified in the <html:radio> tag. If neither element is selected, an empty string is stored in the form bean property.

Figure 12.4. The Checkboxes and Radio Buttons page at /StrutsTaglibs/CheckboxRadio.do .

Listing 12.4 JSP File Demonstrating the Use of <html:checkbox> , <html:multibox> , and <html:radio> Tags ( CheckboxRadio.jsp )

Listing 12.5 Form Bean That Corresponds with CheckboxRadio.jsp ( CheckboxRadioForm.java )

The <html:checkbox> Tag