Binding data to a list Web control is very similar to binding data to a GridView or DetailsView. The only difference is that whereas a GridView or DetailsView can be bound to a variable number of database table columns, list Web controls can be bound to, at most, two columns. The reason is that each item in a list control has two properties, Text and Value. The Text property is the value displayed onscreen—the text shown in the drop-down list item or the text of the radio button or check box—whereas the Value property is not displayed, but provides an additional bit of information about each item.

Let’s not get bogged down with the differences between the Text and Value properties at this point; if the distinction is not clear now, it will be as we work through some examples. For now, let’s practice binding database results to the various list Web controls.

Start by creating a new ASP.NET page named ListControls.aspx. Next, add a SqlDataSource control to the page and configure it to return all columns and all rows of the Books table. You don’t need to configure the SqlDataSource control to include the INSERT, UPDATE, and DELETE statements. After you have finished this, drag a DropDownList, CheckBoxList, and RadioButtonList onto the page, preceding each with text that shows the name of the control. After you have added the SqlDataSource control and the three list Web controls, your screen should look similar to Figure 17.1.

Figure 17.1. A SqlDataSource and the three list Web controls have been added to the page.

Each of these list Web controls has a smart tag with a Choose Data Source link. Clicking this link displays the Data Source Configuration Wizard, which prompts for the data source control to use and the column(s) to bind to the Text and Value properties of each list Web control. Take a moment to configure the data source for each of the three list Web controls, having each one display the Title column and use the BookID column as the value. Figure 17.2 shows this dialog box when configuring the DropDownList control’s data source.

Figure 17.2. Choose the data source control and the columns to bind to the list Web control.

After you specify a data source for the list Web control, the Design view in Visual Web Developer will change slightly; instead of using the word Unbound for the DropDownList, RadioButtonList, or CheckBoxList (see Figure 17.1), the word Databound is used instead. To see the actual values displayed in the drop-down list, check boxes, or radio buttons, you’ll need to view the ASP.NET page through a browser. Take a moment to do this and ensure that your screen looks similar to Figure 17.3.

Figure 17.3. The list Web controls have five items, one for each book in the Books table.

Note that each list Web control has five items, one for each record returned by its SqlDataSource. The difference among the three list Web controls is the way they render their items.

In Hour 11 we looked at how to populate the items in a DropDownList control statically, using the ListItem Collection Editor dialog box. Both the CheckBoxList and RadioButtonList can have their list items specified statically in this manner. Simply click the Edit Items link in their smart tags.

Although the list Web controls do support having their items set statically, it’s often advantageous to do so dynamically, through binding the control to a data source. The problem with statically assigning the items to a list control is that if there are changes to the items to be displayed in the future, you must visit each and every page that uses this data and update the list control appropriately. If you dynamically bind your items, though, and if any changes occur, you can just update the database table from which the items are retrieved and you’re done!

For example, in Hour 11 we looked at using a DropDownList that was statically populated with a list of ice cream flavors, from which we asked visitors to choose their favorite. These values were entered statically but could have been entered dynamically. That is, we could have created a table in our database called IceCreamFlavors that had two columns:

Then, in our ASP.NET page, we could use a SqlDataSource control to grab the contents of this table and bind it to the DropDownList. This may sound like a lot of work just to display some ice cream flavors, and this approach obviously isn’t as quick as just typing in a handful of flavors in the DropDownList’s ListItem Collection Editor dialog box. However, it will save you time if you need to replicate this functionality on other pages, if you expect the list of ice cream flavors to change in the future, or if you need to provide some association, for instance, in the database between users and their favorite ice cream flavors.

I encourage you to use dynamic list Web controls for all but the most trivial scenarios that are guaranteed not to change in the future, such as a drop-down list with gender options, Yes/No options, hours of the day, and so on.

When using list Web controls on a web page, we are often interested in knowing when a list control’s selected item has changed. Each of the list controls contains a SelectedIndexChanged event that fires upon postback if the list control’s selection has changed. Returning to our earlier example, ListControls.aspx, add a Button Web control and a Label Web control to the page. Set the Button’s ID and Text properties to SubmitButton and Click Me, respectively. Set the Label’s ID property to Status, and clear out its Text property.

Next, create a SelectedIndexChanged event handler for the DropDownList. You can accomplish this by double-clicking the DropDownList in the Design view, or by going to the code view and choosing the DropDownList’s ID and the SelectedIndexChanged event from the drop-down lists at the top of the screen. After you have added this event handler, your ASP.NET page’s source code portion should look like this:

Partial Class ListControls
    Inherits System.Web.UI.Page

    Protected Sub DropDownList1_SelectedIndexChanged(ByVal sender As Object, ByVal e As System.EventArgs) Handles DropDownList1.SelectedIndexChanged

    End Sub
End Class

This event handler—DropDownList1_SelectedIndexChanged—executes whenever the page is posted back and a change has occurred in the selected item of the DropDownList. To test this, add the following line of code in the event handler:

Status.Text = "The drop-down list value is now " & DropDownList1.SelectedValue

Set a breakpoint at this line by positioning your cursor on the line and pressing F9, or by clicking in the margin; next, start the debugger by going to the Debug menu and choosing Start. This loads the ASP.NET page in a browser. Notice that on the initial page load, the SelectedIndexChanged event does not fire because there’s been no change to the selected state of the DropDownList. At this point your screen should look similar to Figure 17.3, except with the addition of a button.

Without changing the value of the DropDownList, click the button, posting back the ASP.NET page. Again, the SelectedIndexChanged event does not fire because the selected DropDownList item—Visual Studio Hacks—has yet to change. This time, however, select a different book from the DropDownList and click the button. Upon postback, the SelectedIndexChanged event will fire, and the debugger will break on the breakpoint we set. Continue debugging by pressing F5. The browser window should now refresh, displaying a message in the Status Label indicating the BookID value of the selected book (see Figure 17.4).

Figure 17.4. The Label displays the BookID of the currently selected book.

Note that if you click the button again without changing the book selection, the SelectedIndexChanged event does not fire. As we’ve seen, it fires only on the postback immediately following a change in the list Web control’s selection state.

As we discussed in Hour 9, “Web Form Basics,” server-side events and code, such as a list control’s SelectedIndexChanged event and its associated event handler, can fire and execute on the web server only when the browser explicitly rerequests the page (a postback). By default, changing the selection of a list control does not cause a postback. Therefore, the control’s SelectedIndexChanged event does not fire immediately after the user changes the selection state of a list control, but only when a postback ensues. For instance, in our previous example, you can change the drop-down list from The Number to Visual Studio Hacks, but the DropDownList Web control’s SelectedIndexChanged event doesn’t fire until the Click Me button is clicked, thereby causing a postback.

If the drop-down list’s selection was changed from The Number to Visual Studio Hacks to Fight Club, and then the Click Me button was clicked, the SelectedIndexChanged event would fire only once, because from the web server’s perspective, the drop-down list’s selection has changed only once, from The Number to Fight Club. Similarly, if the drop-down list is changed from The Number to Visual Studio Hacks, and then back to The Number, and then the Click Me button is clicked, the SelectedIndexChanged event won’t fire because from the web server’s perspective, no selection change has been made—when the web server initially rendered the page, the DropDownList Web control’s initial selection was The Number and on postback the selection was still The Number.

Let’s first concentrate on adding the DropDownList of genres. The DropDownList of genres will list each of the genres defined in the Books table. The user visiting the page can then filter the GridView results depending on the selected genre from the DropDownList. To create a DropDownList control listing the available genre choices, perform the following steps:

At this point, test your ASP.NET page through a browser (see Figure 17.5). Notice that the drop-down list contains five items—one for each record in the Books table—even though the table contains only three unique genre values.

Figure 17.5. A drop-down list item is available for each record in the Books table, rather than one for each unique genre.

To remedy this, we need to configure the SqlDataSource to return only the unique genres in the Books table. To accomplish this, reopen the SqlDataSource control’s wizard, and in the Configure the Select Statement screen, check the Return Only Unique Rows check box, as shown in Figure 17.6.

Figure 17.6. Only the unique genres will be returned.

After making this change, view the page through a browser again. This time the drop-down list will have only three items: Business, Fiction, and Technology.

Our next step is to add a GridView control that displays only those books that belong to the selected genre. Let’s first add a GridView that displays all books from the Books table. We’ve done this many times in the past two hours, so this should be an easy task. Just drag a SqlDataSource onto the page and configure it to return all columns and all records from the Books table. As we did with the genre-returning SqlDataSource, change this SqlDataSource control’s ID from SqlDataSource1 to a more descriptive BooksDataSource. Next, add a GridView to the ASP.NET page, binding it to the BooksDataSource data source control. Rename the GridView’s ID property to Books.

Take a moment to test the page in a browser. Because the BooksDataSource SqlDataSource isn’t filtering the books based on the genre yet, the GridView shows all the books, regardless of what genre is selected from the drop-down list. Our next step, then, is to implement filtering within the BooksDataSource SqlDataSource. To accomplish this, return to the data source control’s wizard and from the Configure Select Statement screen, click the WHERE button to bring up the Add WHERE Clause dialog box.

We want to add a WHERE clause to the SELECT statement that looks like this:

SELECT *
FROM [Books]
WHERE [Genre] = Genre selected in the DropDownList

Because we want this WHERE clause to operate on the Genre column, choose Genre from the Column drop-down list. Select the = operator from the Operator drop-down list and then, from the Source drop-down list, choose Control because we want the filter expression to be based on the value of a Web control on the page. Choosing the Control option updates the Parameter Properties box in the upper-right corner to provide a drop-down list titled Control ID and a text box titled Default Value. From the Control ID drop-down list, select the Genres control (the ID of our DropDownList); you don’t need to pick a default value, so you can leave this text box blank.

Make sure your screen looks similar to Figure 17.7 and then click the Add button to add the parameter to the SqlDataSource. Click OK to return to the Configure the Select Statement screen and then complete the wizard.

Figure 17.7. Add a WHERE clause parameter whose value is the selected value of the genres DropDownList.

View the ASP.NET page through a browser again. This time, when the page first loads, the GridView should display only one book, The Number, because that’s the only book that falls within the Business genre (see Figure 17.8). Go ahead and try changing the drop-down list to another genre. Nothing happens! We still see the GridView with one record, listing The Number. The reason is that we’ve yet to enable AutoPostBack in the DropDownList control. Simply changing the DropDownList doesn’t cause a postback unless the DropDownList’s AutoPostBack property is set to True. Take a moment to fix this and then revisit the page. Now selecting a different genre from the drop-down list invokes a postback and causes the GridView to be updated (see Figure 17.9).

Figure 17.8. The DropDownList.aspx page, when first visited.

Figure 17.9. The page after the user has changed the drop-down list’s selection from Business to Technology.

As discussed earlier in this hour, all three list Web controls have an Items property that is a collection of list items. This collection can be programmatically enumerated using the following code:

'Enumerate the list of items in the CheckBoxList
For Each li As ListItem In listWebControlID.Items
  ' Work with the list item, li
Next

Within the For Each loop, you can access the properties of the current list item (li); the germane ones are

If we wanted to display a list of the selected items in the Results Label Web control, we could use the following code:

Results.Text = String.Empty

'Enumerate the list of items in the CheckBoxList
For Each li As ListItem In CheckBoxList1.Items
    If li.Selected Then
        Results.Text &= li.Text & " was selected!<br />"
    End If
Next

This code starts by clearing out the Text property of the Label control and then enumerates the list items of the CheckBoxList CheckBoxList1. If an item is selected—that is, if li.Selected is True—the Label’s Text property has appended a string indicating that the particular list item was selected. (The <br /> in the string is an HTML element that adds a breaking line; it’s used to help improve the readability of the output in the page.)

Figure 17.10 shows this ASP.NET page. Note that for each selected check box a corresponding message is displayed in the Label. (This approach works equally well for RadioButtonLists.)

Figure 17.10. The Label’s output is dictated by what check boxes were selected.

In Hour 11 we saw how to programmatically determine the selected item or value of the DropDownList using the SelectedItem and SelectedValue properties. The SelectedItem property returns the ListItem instance of the selected item; SelectedValue returns the value of the selected item. Both the RadioButtonList and CheckBoxList have these two properties as well; however, more care must be taken when using these properties with either of these two controls.

When you’re using a RadioButtonList or CheckBoxList, understand that the user may not choose any item. With either of these controls, the user can avoid selecting a check box or radio button. (This concern doesn’t exist with the DropDownList control.) Before using these properties, then, you must first ensure that a value was selected. The simplest way to ensure that a value has been selected is to test to see whether the SelectedItem property is equivalent to Nothing; if it is, that means an item was not selected.

We can use the following code to proceed within the conditional only if an item has been selected. That is, we test to see whether SelectedItem is not Nothing and, if so, we can then work with the SelectedItem or SelectedValue properties (see Figure 17.11):

'See what item was selected in the RadioButtonList
If RadioButtonList1.SelectedItem IsNot Nothing Then
    results.Text &= "From the RadioButtonList you selected " & RadioButtonList1.SelectedItem.Text
End If

Figure 17.11. The selected radio button’s text is displayed in the Results Label.

Another concern with SelectedItem and SelectedValue is that they return a single ListItem instance or value. How does this work with the CheckBoxList, which might have multiple selected items? SelectedItem and SelectedValue return the first selected item from the list. Therefore, we typically use SelectedItem or SelectedValue only with DropDownLists or RadioButtonLists. For determining the selected items in a CheckBoxList, stick with enumerating the CheckBoxList’s Items collection, as we saw in the previous section.

Like the other ASP.NET Web controls we’ve examined throughout this book, the RadioButtonList and CheckBoxList controls have Font, ForeColor, BackColor, and other common formatting properties we’ve seen before. As with other Web controls, these properties can be found in the Appearance section within the Properties window.

The RadioButtonList and CheckBoxList also have some properties in the Layout section worth noting. By default, both the RadioButtonList and CheckBoxList are rendered in a single column. Although a one-column layout will likely suffice for CheckBoxLists or RadioButtonLists with a small number of items, displaying dozens of check boxes or radio buttons in this vertical, single-column manner can easily chew up a lot of screen real estate. Rather than confining the items to a single column, we might want to have the check boxes or radio buttons span multiple columns.

To accomplish this, use the RepeatColumns property, which specifies how many columns to display and can be assigned any non-negative integer value. The RepeatDirection property indicates the direction the items are laid out and can be either Horizontal or Vertical (the default).

Figure 17.12 shows a CheckBoxList and RadioButtonList with three columns. The figure also illustrates the effects of the RepeatDirection property: The CheckBoxList has its RepeatDirection property set to Vertical, whereas the RadioButtonList’s is set to Horizontal. The results here are ordered by BookID, so Visual Studio Hacks is the first book, then Create Your Own Website, followed by The Number, and so on. As you can see, with the CheckBoxList, the first two books are in the first column, the second two in the second column, and so on. In essence, the output is grouped by row. With the RadioButtonList’s Horizontal RepeatDirection value, the output is grouped by column, with the first three books in the first column and last two books in the second column.

Figure 17.12. A RadioButtonList and CheckBoxList, with RepeatColumns set to 3.