DataList Web Server Control Overview

Article
10/22/2014

The DataList Web server control displays rows of database information in a customizable format. The format for displaying the data is defined in templates that you create. You can create templates for items, alternating items, selected items, and edit items. Header, footer, and separator templates are also available to let you customize the overall appearance of the DataList. By including Button Web server controls in the templates, you can connect the list items to code that allows users to switch between display, selection, and editing modes.

This topic contains:

Background
Code Examples
Class Reference

Background

The DataList Web server control displays data in a format that you can define using templates and styles. The DataList control is useful for data in any repeating structure, such as a table. The DataList control can display rows in different layouts, such as ordering them in columns or rows.

Note

The DataList control renders items in a list using HTML table elements. To precisely control the HTML that is used to render a list, use the Repeater Web server control instead of the DataList control.

Optionally, you can configure the DataList control to allow users to edit or delete information. You can also customize the control to support other functionality, such as selecting rows.

You use templates to define the layout of data items by including HTML text and controls. For example, you might use a Label Web server control in an item to display a field from the data source.

The following sections introduce you to the features of the DataList control.

Binding Data to the Control

The DataList Web server control must be bound to a data source. The most common data source is a data source control, such as a SqlDataSource or ObjectDataSource control. Alternatively, you can bind a DataList control to any class that implements the IEnumerable interface, which includes the ADO.NET datasets (the DataSet class), data readers (the SqlDataReader or OleDbDataReader classes), or most collections. When binding data, you specify a data source for the DataList control as a whole. When you add other controls to this control — for example, labels or text boxes in list items — you can bind the child controls' properties to fields in the current data item.

Defining Templates for DataList Items

In the DataList control, you can define the layout of your information by using templates.

Note

For an overview of using templates, see ASP.NET Web Server Controls Templates.

The following table describes the templates that are supported by the DataList control.

Template property	Description
ItemTemplate	Contains the HTML elements and controls to render once for each row in the data source.
AlternatingItemTemplate	Contains the HTML elements and controls to render once for every other row in the data source. Typically, you use this template to create a different look for the alternating rows, such as a different background color than the color that is specified in the ItemTemplate property.
SelectedItemTemplate	Contains the elements to render when the user selects an item in the DataList control. Typically, you use this template to visually distinguish the selected row with a different background or font color. You can also expand the item by displaying additional fields from the data source.
EditItemTemplate	Specifies the layout of an item when it is in edit mode. This template typically contains editing controls, such as TextBox controls.
HeaderTemplate and FooterTemplate	Contains the text and controls to render at the beginning and end of the list, respectively.
SeparatorTemplate	Contains the elements to render between each item. A typical example might be a line (using an HR element).

Styles

To specify the appearance of items in a template, you can set the template's style. For example, you might specify the following:

Items are rendered with black text on a white background.
Alternating items are rendered with black text on a light gray background.
The selected item is rendered with bold, black text on a yellow background.
Items being edited are rendered with black text on a light blue background.

Each template supports its own style object, the properties of which you can set at design time and at run time. The styles you can work with are the following:

For more information, see ASP.NET Web Server Controls and CSS Styles.

Item Layout

The DataList control uses an HTML table to lay out the rendering of items to which the template is applied. You can control the order, direction, and number of columns for the individual table cells used to render DataList items. The following table describes the layout options that are supported by the DataList control.

Layout option	Description
Flow layout	In flow layout, list items are rendered inline, as in a word-processing document.
Table layout	In table layout, the items are rendered in an HTML table. This gives you more options for specifying the look of items because it allows you to set table-cell properties, such as gridlines. For details, see How to: Specify Flow or Table Format in DataList Web Server Controls.
Vertical and horizontal layout	By default, the items in a DataList control are displayed in a single vertical column. However, you can specify that the control contain more than one column. If so, you can further specify whether the items are ordered vertically (like newspaper columns) or horizontally (like days in a calendar). For details, see How to: Specify Horizontal or Vertical Layout in DataList Web Server Controls.
Number of columns	Whether items in a DataList control are ordered vertically or horizontally, you can specify how many columns the list will have. This permits you to control the rendered width of the Web page, usually to avoid horizontal scrolling.

Events

The DataList control supports several events. One of them, the ItemCreated event, gives you a way to customize the item-creation process at run time. The ItemDataBound event also gives you the ability to customize the DataList control, but after the data is available for inspection. For example, if you were using the DataList control to display a to-do list, you could display overdue items in red text, completed items in black text, and other tasks in green text. Either event can be used to override formatting from the template definition.

The remaining events are raised in response to button clicks in list items. They are designed to help you respond to the most commonly used functionality of the DataList control. Four events of this type are supported:

To cause these events to be raised, add Button, LinkButton, or ImageButton controls to the templates in the DataList control and set the buttons' CommandName property to a keyword, such as edit, delete, update, or cancel. When a user clicks a button in an item, the event is sent to the button's container — the DataList control. The exact event that the button raises depends on the value of the CommandName property of the button that was clicked. For example, if the CommandName property of a button is set to edit, the button raises an EditCommand event when clicked. If the CommandName property is set to delete, the button raises a DeleteCommand event, and so on.

The DataList control also supports the ItemCommand event that is raised when a user clicks a button that does not have a predefined command, such as edit or delete. You can use this event for custom functionality by setting a button's CommandName property to a value that you need and then testing for it in the ItemCommand event handler. For example, you could use this approach when selecting an item, as described in How to: Allow Users to Select Items in DataList Web Server Controls.

For more information about Web Forms events, see ASP.NET Web Server Control Event Model.

Editing and Selecting Items

You can allow users to edit individual items in the control. Other data controls, such as the GridView, DetailsView, and FormView controls, can interact with data source controls to support automatic updates and paging. In contrast, the DataList control cannot automatically take advantage of the update capabilities of data source controls, or of automatic paging or sorting. To perform updates, paging, and sorting using the DataList control, you must perform the update task in code that you write.

The general strategy is to create an EditItemTemplate that provides the appropriate layout and controls for editing. You must also provide a way for users to indicate that they want to edit the item. The most common way do this is to include a button in the item template (and if you are using it, in the AlternatingItemTemplate property), and then set the button's CommandName property to edit. Then, when the button is clicked, the DataList control automatically raises the EditCommand event. In the code that you write for the event handler, set the item to edit mode, which displays the EditItemTemplate.

The EditItemTemplate usually includes buttons that allow users to save or discard their changes (for example, the Update and Cancel buttons). These buttons work similarly to the Edit button — they send a predefined command message (update or cancel) to the DataList control, which raises an UpdateCommand or CancelCommand event that you can respond to appropriately. For more information, see How to: Allow Users to Edit Items in DataList Web Server Controls.

The process for selecting an item is similar, using the SelectedIndexChanged event. You add a button to the ItemTemplate and set its CommandName property to select. You then write an event handler for the SelectedIndexChanged event. The SelectedIndexChanged event is raised when the user clicks the Select button. For details, see How to: Allow Users to Select Items in DataList Web Server Controls. For more information, see How to: Allow Users to Select Items in DataList Web Server Controls.