The CheckBoxList Web Control

The CheckBoxList control is a single control that acts as a parent control for a collection of checkable list items, each of which is rendered through an individual CheckBox control. You insert a check box list as follows:

<asp:CheckBoxList runat="server" id="cbEmployees">

The CheckBoxList control supports data binding by using five properties: DataSource, DataMember, DataTextField, DataValueField, and DataTextFormatString. You bind the CheckBoxList control to a data source by using the following code:

cbEmployees.DataSource = oDS.Tables["EmployeesList"];
cbEmployees.DataTextField = "lastname";
cbEmployees.DataValueField = "employeeid";

The properties of the CheckBoxList control play the same role as the properties for the DropDownList control, which we discussed earlier in the chapter. Unlike the DropDownList control, however, the CheckBoxList control does not supply properties that reveal information about the selected items. As you know, this information is vital for any Web application that uses checkable elements.

At any time, CheckBoxList can have one or more items selected. How can you retrieve these items? All list controls have an Items property that contains the collection of the child items. The Items property is implemented through the ListItemCollection class, and each list item can be accessed via a ListItem object. The following code loops through the items stored in a CheckBoxList control and checks the Selected property of each. (Selected is a Boolean property that indicates whether the item is selected.) The code then uses the StringBuilder object to concatenate the text of each selected item into a single comma-­separated string.

StringBuilder buf = new StringBuilder(""); 
foreach(ListItem item in chkList.Items)
{
    if (item.Selected)
    {
        buf.Append(item.Text);
        buf.Append(", ");
    }
}

Notice in the following code that the ASP.NET CheckBox control is a bit more powerful than the ASP.NET counterpart of the well-known HTML <input> tag. The ASP.NET CheckBox control also supplies the Text property that allows you to automatically associate the check box with descriptive text.

<asp:checkbox runat="server" id="theCheckBox" 
    Text="Click me..." />

When the preceding code is processed by the ASP.NET run time, the ASP.NET CheckBox control generates the following HTML code:

<input id="theCheckBox" type="checkbox" name="theCheckBox" />
<label for="theCheckBox">Click me...</label>

This code displays the check box shown here:

A slick trick used by ASP developers to quickly obtain the selected items of a logically related group of check boxes does not work in ASP.NET. When you have several check boxes with identical names in an ASP application, you can use a single line of code to obtain the corresponding values of check boxes that are selected when a form is posted.

<input type="checkbox" name="foo" value="...">

After the form values in the above code are posted, the following line of code written in Microsoft Visual Basic, Scripting Edition (VBScript) sets an array with all the checked values:

<% arrSelected = split(Request.Form("foo"), ",") %>

Request.Form("foo") returns a comma-separated string formed by the value strings of all checked items. You then pass this string to VBScript’s Split function, which transforms the string into an array.

This code won’t work in ASP.NET if you use the CheckBox server control to render the check box component, but it will work if you use the <input> tag. However, using the CheckBoxList control is the preferred ASP.NET way to handle lists of check boxes.