<%@ Page Language="C#" MasterPageFile="~/aspnet/section.master" %> <%@ Register TagPrefix=Acme Namespace=Acme %> <%@ Register TagPrefix="Acme" TagName="SourceRef" Src="~/util/SrcRef.ascx"%>

DataList

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 12
2 5 8 11 13
3 6 9

The following sample illustrates using a simple DataList control.

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.

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.

<EditItemTemplate>
    Item: <asp:TextBox id="Text1" runat="server"
    Text='<%# ((DataRowView)Container.DataItem)["Item"]  %>'
    /><br>
<asp:LinkButton id="button1" runat="server"
    Text="Update"
    CommandName="update"
    />
<asp:LinkButton id="button2" runat="server"
    Text="Cancel"
    CommandName="cancel"
    />
</EditItemTemplate>

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.

protected void DataList_EditCommand(object Source, DataListCommandEventArgs e) { DataList1.EditItemIndex = (int)e.Item.ItemIndex; BindList(); } Protected Sub DataList_EditCommand(Source As Object, e As DataListCommandEventArgs) DataList1.EditItemIndex = CType(e.Item.ItemIndex, Integer) BindList() End Sub

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.

protected void DataList_CancelCommand(object Source, DataListCommandEventArgs e) { DataList1.EditItemIndex = -1; BindList(); } Protected Sub DataList_CancelCommand(Source As Object, e As DataListCommandEventArgs) DataList1.EditItemIndex = -1 BindList() End Sub
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.

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.

<ASP:DataList runat="server" DataSource="<%#MyData%>"
    RepeatColumns="2"
    RepeatDirection="Horizontal"
    ItemStyle-Font-Size="10pt"
    ItemStyle-Font-Name="Verdana"
>
    ...
</ASP:DataList>

The following sample demonstrates the DataList control with the RepeatDirection and RepeatColumns properties set to determine how the ItemTemplates are laid out.
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 format String parameter of DataBinder.Eval has also been used to substitute a DataItem value in the query string for a URL.

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.

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.

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.

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).

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.

<script runat="server"> public void Page_Load(Object sender, EventArgs E)) { // set datasource and call databind here for (int i=0; i<MyDataList.Items.Count; i++) { String isChecked = ((CheckBox) MyDataList.Items[i].FindControl("Save")).Checked.ToString(); If (isChecked == "True") { ... } } } </script> <ASP:DataList id="MyDataList" runat="server"> <ItemTemplate> <asp:CheckBox id="Save" runat="server"/> <b>Save to Favorites</b> </ItemTemplate> </ASP:DataList> <script runat="server"> Public Sub Page_Load(sender As Object, E As EventArgs)) ' set datasource and call databind here For I=0 To MyDataList.Items.Count-1 Dim IsChecked As String = MyDataList.Items(i).FindControl("Save").Checked.ToString() If IsChecked = "True" Then ... End If Next End Sub </script> <ASP:DataList id="MyDataList" runat="server"> <ItemTemplate> <asp:CheckBox id="Save" runat="server"/> <b>Save to Favorites</b> </ItemTemplate> </ASP:DataList>
The following sample demonstrates this code in action.