Using List Controls

The List controls enable you to display simple lists of options. For example, you can use the RadioButtonList control to display a group of radio buttons, or the BulletedList control to display a list of links. In this chapter, you learn how to use each of the List controls included in the ASP.NET Framework. In particular, it discusses the DropDownList, RadioButtonList, ListBox, CheckBoxList, and BulletedList controls. You learn how to bind the different types of List  controls to a data  source such as a database table. You also learn how to work directly with the list items contained by a List control.

Overview of the List Controls

All five of the List controls inherit from the base ListControl class. This means that all the List controls share a common set of properties and methods. In this section, you are provided with an overview of the common features of the List controls.

Declaring List Items

The List controls render a list of options. Each option is represented by an instance of the  ListItem class. For example, you can use the page in Listing 10.1 to render a set of options for selecting your favorite movie

The page in Listing 10.1 contains a RadioButtonList control. This control contains three ListItem controls that correspond to the three radio buttons. All the List controls use the ListItem control to represent individual list items.

The ListItem control supports the following five properties:

• Attributes—Enables you to add HTML attributes to a list item.
• Enabled—Enables you to disable a list item.
• Selected—Enables you to mark a list item as selected.
• Text—Enables you to specify the text displayed by the list item.
• Value—Enables you to specify a hidden value associated with the list item.

You use the Text property to indicate the text that you want the option to display, and the Value property to indicate a hidden value associated with the option. For example, the hidden value might represent the value of a primary key column in a database table. The Selected property enables you to show a list item as selected. Selected radio buttons and check boxes appear checked. The selected option in a DropDownList is the default option displayed. Selected options in a ListBox appear highlighted. And, in the case of a BulletedList control, the selected property has no effect whatsoever.

The Enabled property has different effects when used with different List controls. When you set a ListItem control’s Enabled property to the value False when using the DropDownList or ListBox controls, the list item is not rendered to the browser. When you use this property with a CheckBoxList, RadioButtonList, or BulletedList control, then the list item is ghosted and non-

functional.

Binding to a Data Source

You can bind any of the List controls to a data source. The List controls support both declarative databinding and programmatic databinding. For example, the page in Listing contains a DropDownList control that is bound to the Movies database table with declarative databinding 

Notice that the DropDownList control’s DataSourceID property points to the ID of the SqlDataSource control. When you open the page in Listing, the SqlDataSource control retrieves the records from the Movies database table. The DropDownList control grabs these records from the SqlDataSource control and creates a ListItem control for each data item.

You also should notice that the DropDownList control has both its DataTextField and DataValueField properties set. When the DropDownList control creates each of its list items, it uses the values of the DataTextField and DataValueField properties to set the Text and Value properties of each list item.

As an alternative to declarative databinding, you can programmatically bind any of the List controls to a data source. For example, the page in Listing  binds a ListBox control to a collection which represents a shopping cart.

In Listing 10.3, the ListBox is bound to the collection in the Page_Load() method. Notice that the DataTextField and DataValueField properties of the ListBox control represent properties of the CartItem class.

Determining the Selected List Item

Displaying options with the List controls is all very nice, but at some point you need to be able to determine which option a user has selected. The List controls support three properties that you can use to determine the selected list item:

• SelectedIndex—Gets or sets the index of the selected list item.
• SelectedItem—Gets the first selected list item.
• SelectedValue—Gets or sets the value of the first selected list item.

Appending Data Items

You can mix the list items that you declare in a List control and the list items that are added to the control when it is bound to a data source. This is useful when you want to display a default selection.

For example, imagine that you are creating a form in which you want to require a user to pick an item from a List control. In this situation, you should add a default item to the List control so you can detect whether a user has actually picked an item.

Using the Items Collection

All the list items rendered by a List control are contained in the List control’s list item collection. This collection is exposed by the Items property. You can work directly with the list items in this collection. For example, you can add or remove particular list items or you can change the  order of the list items.

Working with the DropDownList Control

The DropDownList control enables you to display a list of options while requiring a minimum of screen real estate. A user can select only one option at a time when using this control. The page in Listing 10.9 illustrates how you can use the DropDownList control to display all the movie titles from the Movies database table

Working with the RadioButtonList Control

The RadioButtonList control, like the DropDownList control, enables a user to select only one list item at a time. The RadioButttonList control displays a list of radio buttons that can be arranged either horizontally or vertically. The page in Listing  illustrates how you can use the RadioButtonList control to display a list of movie titles.

The radio buttons are rendered in a three-column layout. The RadioButtonList control includes three properties that have an effect on its layout:

• RepeatColumns—The number of columns of radio buttons to display.
• RepeatDirection—The direction that the radio buttons are repeated. Possible values are Horizontal and Vertical.
• RepeatLayout—Determines whether the radio buttons are displayed in an HTML table. Possible values are Table and Flow.

By default, the radio buttons rendered by the RadioButtonList control are rendered in an HTML table. If you set the RepeatLayout property to the value Flow, then the radio buttons are not rendered in a table. Even when the RadioButtonList renders its items in Flow layout mode, you can specify multiple columns.

Working with the ListBox Control

The ListBox control is similar to the DropDownList control with two important differences. First, the ListBox control requires more screen real estate because it always displays a certain number of list items. Furthermore, unlike the DropDownList control, the ListBox control enables a user to select multiple items.

Notice that the ListBox control in Listing includes a Rows property. The Rows property

determines the number of list items that the ListBox displays. You can also configure the ListBox control to enable a user to select multiple items. This is illustrated in the page in Listing.

Working with the CheckBoxList Control

The CheckBoxList control renders a list of check boxes. The check boxes can be rendered horizontally or vertically. Unlike the other List controls, a user always can select multiple items when using a CheckBoxList control.

When you click the Submit button, the values of the Text property of any selected check boxes are displayed in a Label control. The selected check boxes are retrieved from the CheckBoxList control’s Items property.

The CheckBoxList control includes three properties that affect its layout:

• RepeatColumns—The number of columns of check boxes to display.
• RepeatDirection—The direction in which the check boxes are rendered. Possible values are Horizontal and Vertical.
• RepeatLayout—Determines whether the check boxes are displayed in an HTML table. Possible values are Table and Flow.

Normally, a CheckBoxList control renders its list items in an HTML table. When the RepeatLayout property is set to the value Flow, the items are not rendered in a table.

Working with the BulletedList Control

The BulletedList control renders either an unordered (bulleted) or ordered (numbered) list. Each list item can be rendered as plain text, a LinkButton control, or a link to another web page.

You can modify the appearance of each list item by modifying the value of the DisplayMode property. This property accepts one of the following values from the BulletedListDisplayMode enumeration:

• HyperLink—Each list item is rendered as a link to another page.
• LinkButton—Each list item is rendered by a LinkButton control.
• Text—Each list item is rendered as plain text.

Each list item has both its Text and Value properties set. The Text property contains the text that is displayed for the list item, and the Value property contains the URL for the other website. Notice that the Target property is set to the value blank. When you click one of the hyperlinks, the page is opened in a new window.