ASP.NET 2.0 Quickstart Tutorials

The DataList control displays data items in a repeating list, and optionally supports selecting and
editing the items. The content and layout of list items in DataList is defined using templates. At a
minimum, every DataList must define an ItemTemplate; however, several optional templates can be used to
customize the appearance of the list. The following table describes those templates.

Template Name

Description

ItemTemplate

Defines the content and layout of items within the list. Required.

AlternatingItemTemplate

If defined, determines the content and layout of alternating items. If not defined, ItemTemplate is used.

SeparatorTemplate

If defined, is rendered between items (and alternating items). If not defined, a separator is not rendered.

SelectedItemTemplate

If defined, determines the content and layout of the selected item. If not defined, ItemTemplate (AlternatingItemTemplate) is used.

EditItemTemplate

If defined, determines the content and layout of the item being edited. If not defined, ItemTemplate (AlternatingItemTemplate, SelectedItemTemplate) is used.

HeaderTemplate

If defined, determines the content and layout of the list header. If not defined, the header is not rendered.

FooterTemplate

If defined, determines the content and layout of the list footer. If not defined, the footer is not rendered.

Templates define the HTML elements and controls that should be displayed for an item, as well as the layout of these
elements. Style formatting -- font, color, and border attributes -- is set via styles. Each template has its
own style property. For example, styles for the EditItemTemplate are set through the EditItemStyle property.

A third set of properties affect the overall rendering of DataList. By default, DataList items render within a
table as a single vertical column. Setting the RepeatLayout property to Flow removes the HTML table
structure from the rendering of the list.

DataList supports directional rendering through the RepeatDirection property,
meaning it can render its items horizontally or vertically. Since page width is the dimension that the developer
must control in Web user interface, DataList permits the developer to control the number of "columns" that are rendered
(RepeatColumns), regardless of whether the items are rendered horizontally or vertically.

If RepeatDirection is Horizontal and RepeatColumns is five, the items are rendered in rows containing five columns.

1

2

3

4

5

6

7

8

9

10

11

12

13

If RepeatDirection is Vertical, and RepeatColumns remains set to five, the items are rendered
in five columns, each equal in length to the total number of items divided by five.

1

4

7

10

13

2

5

8

11

3

6

9

12

The following sample illustrates using a simple DataList control.

VB Simple DataList

Selecting Items in DataList

You can customize the content and appearance of the selected item through the SelectedItemTemplate
property. The SelectedItemTemplate is controlled by the SelectedIndex property. By default the value of
SelectedIndex is -1, meaning none of the items in the list is selected. When SelectedIndex is set to a
particular item, that item is displayed using the SelectedItemTemplate.

The following sample illustrates using a SelectedItemTemplate in DataList.

VB DataList SelectedItemTemplate

Editing DataList Items

The DataList control supports in-place editing of the data in an item through its EditItemTemplate
property. The EditItemTemplate defines the content and appearance of the item when it is being edited. For
example, the following template includes a text box, an "Update" button and a "Cancel" button.

The EditItemTemplate interacts with another property: EditItemIndex. By default, the value of
EditItemIndex is -1, meaning none of the items in the list is being edited. When EditItemIndex is set to a
particular item, that item is displayed using the EditItemTemplate.

The DataList also supplies three events that can be used to support editing. EditCommand is thrown
when an "edit" command button control is clicked within the list's ItemTemplate. It's up to you to handle this event
in your code. The typical logic sets EditItemIndex to the selected item, and then rebinds the data to the DataList as shown in the following example.

The EditItemTemplate typically contains "update" and "cancel" command buttons. These buttons cause the
UpdateCommand and CancelCommand events to be thrown, respectively. It's up to you to handle these events
in your code. The typical logic for "cancel" sets EditItemIndex to -1, and then rebinds the data to the DataList as shown in the following example.

The typical logic for "update" updates the data source, sets EditItemIndex to -1, and then rebinds the data to the
DataList. The following sample illustrates editing items in DataList.

VB DataList Editing

DataList renders additional elements, like table rows and cells and spans containing style attributes, outside of the template definition to enable
layout formatting. For example, DataList supports RepeatColumns and RepeatDirection properties that specify whether
data should be rendered in multiple columns, and in which direction (vertical or horizontal) the data items should be rendered. DataList also
supports style attributes, as shown in the following example.

The following sample demonstrates the DataList control with the RepeatDirection and RepeatColumns
properties set to determine how the ItemTemplates are laid out.

VB DataList RepeatDirection and RepeatColumns

The following example further demonstrates the flexibility of templates by changing the ItemTemplate yet again.
This time, one of the DataItem values has been substituted for the "src" attribute of an <img> tag. The formatString parameter of DataBinder.Eval has also been used to substitute a DataItem value in the query string for a URL.

VB DataList ItemTemplate Customization

You can fire a command from inside a DataList template that is passed to an event handler wired to the
DataList itself. For example, a LinkButton inside the ItemTemplate might fire a Select command. By setting the
OnSelectedIndexChanged property of the DataList, you can call an event handler in response to this command. The following example demonstrates this process.
The following sample demonstrates this code in action. In the MyDataList_Select event handler, you populate several other server controls
with the details about the particular selected item.

VB DataList Selection

Note that while the DataList recognizes a few special commands such as Select and Edit/Update/Cancel, the command string fired inside a template
can be any arbitrary string. For all commands, the DataList's OnItemCommand is fired. You can wire this event to a handler
as in the previous example; the following example shows how to do this.

Note that because more than one command can fire this event handler, you must employ a switch statement to determine the
particular command that was fired. The following sample demonstrates this code in action.

VB DataList ItemCommand Event

In addition to handling the Select command using a page-level event handler, the DataList can respond to this event internally. If a
SelectedItemTemplate is defined for the DataList, the DataList renders this template for the item that fired the Select
command. The following example uses the SelectedItemTemplate to make the title of the selected book bold.

VB DataList SelectedItemTemplate (2)

DataList also supports an EditItemTemplate for rendering an item whose index is equal to the DataList's EditItemIndex
property. Note that DataList does not support automatically updating and deleting using a data source control, so you need to write code to handle the
edit, update, and delete commands yourself (using the same model as was supported in ASP.NET v1.x).

VB DataList Editing (2)

Sometimes it is necessary to locate a control contained inside a template. If a control is given an ID in a template, that control can be
retrieved from its container (the first control in the parent hierarchy that supports INamingContainer). In this case, the
container is the DataListItem control. Note that even though there are several controls with the same ID (by virtue of the DataList's
repetition), each is contained logically in the namespace of the DataListItem container control.

You can go through the DataList's Items collection to retrieve the DataListItem for a given index, and then call
the DataListItem's FindControl method (inherited from the base Control class) to retrieve a control with a particular ID.