DataList Web Server Control
Displays the items from a data source by using templates. You can customize the appearance and contents of the control by manipulating the templates that make up the different components of the DataList control, such as the ItemTemplate and HeaderTemplate.
<asp:DataList id="DataList1"
CellPadding="pixels"
CellSpacing="pixels"
DataKeyField="DataSourceKeyField"
DataSource='<% databindingexpression %>'
ExtractTemplateRows="True|False"
GridLines="None|Horizontal|Vertical|Both"
RepeatColumns="ColumnCount"
RepeatDirection="Vertical|Horizontal"
RepeatLayout="Flow|Table"
ShowFooter="True|False"
ShowHeader="True|False"
OnCancelCommand="OnCancelCommandMethod"
OnDeleteCommand="OnDeleteCommandMethod"
OnEditCommand="OnEditCommandMethod"
OnItemCommand="OnItemCommandMethod"
OnItemCreated="OnItemCreatedMethod"
OnUpdateCommand="OnUpdateCommandMethod"
runat="server">
<AlternatingItemStyle ForeColor="Blue"/>
<EditItemStyle BackColor="Yellow"/>
<FooterStyle BorderColor="Gray"/>
<HeaderStyle BorderColor="Gray"/>
<ItemStyle Font-Bold="True"/>
<PagerStyle Font-Name="Ariel"/>
<SelectedItemStyle BackColor="Blue"/>
<HeaderTemplate>
Header template HTML
</HeaderTemplate>
<ItemTemplate>
Item template HTML
</ItemTemplate>
<AlternatingItemTemplate>
Alternating item template HTML
</AlternatingItemTemplate>
<EditItemTemplate>
Edited item template HTML
</EditItemTemplate>
<SelectedItemTemplate>
Selected item template HTML
</SelectedItemTemplate>
<SeparatorTemplate>
Separator template HTML
</SeparatorTemplate>
<FooterTemplate>
Footer template HTML
</FooterTemplate>
</asp:DataList>
Remarks
You can manipulate the control's layout and content by defining templates. The following table lists the different templates for the DataList control.
| AlternatingItemTemplate | Similar to the ItemTemplate element, but rendered for every other row (alternating rows) in the DataList control. You can specify a different appearance for the AlternatingItemTemplate element by setting its style properties. |
| EditItemTemplate | The layout of an item when it has been set to edit mode. This template typically contains editing controls (such as TextBox controls). The EditItemTemplate is invoked for a row in the DataList control when the EditItemIndex is set to the ordinal number of that row. |
| FooterTemplate | The text and controls to render at the bottom (footer) of the DataList control.
The FooterTemplate cannot be data bound. |
| HeaderTemplate | The text and controls to render at the top (header) of the DataList control.
The HeaderTemplate cannot be data bound. |
| ItemTemplate | The elements to render once for each row in the data source. |
| SelectedItemTemplate | The elements to render when the user selects an item in the DataList control. Typical uses are to expand the number of data fields displayed and to visually mark the row with a highlight. |
| SeparatorTemplate | The elements to render between each item.
The SeparatorTemplate item cannot be data bound. |
You can customize the appearance of the DataList control by specifying a style for the different parts of the control. The following table lists the style properties that control the appearance of the different parts of the DataList control.
| Style property | Description | Style class |
|---|---|---|
| AlternatingItemStyle | The style for every other item (alternating item). | TableItemStyle |
| EditItemStyle | The style for the item being edited. | TableItemStyle |
| FooterStyle | The style for the footer at the end of the list (if any). | TableItemStyle |
| HeaderStyle | The style for the header at the beginning of the list (if any). | TableItemStyle |
| ItemStyle | The style for individual items. | Style |
| SelectedItemStyle | The style for the selected item. | TableItemStyle |
| SeparatorStyle | The style for the separator between each item. | TableItemStyle |
Note The DataList control differs from the Repeater control by supporting directional rendering (by use of the RepeatColumns and RepeatDirection properties) and the option to render within an HTML table.
The Items collection contains the data-bound members of the DataList control. The collection is populated when the DataBind method is called on the DataList control. The header (if any) is added first, then one Item object for each data row. If a SeparatorTemplate exists, Separators are created and added between each item, but these are not added to the Items collection.
After all items have been created for the rows in the DataSource, the Footer is added to the control (but not to the Items collection). Finally, the control raises the ItemCreated event for each item, including the header, footer, and separators. Unlike most collections, the Items collection does not expose Add or Remove methods. However, you can modify the contents within an item by providing a handler for the ItemCreated event.
CAUTION Text is not HTML encoded before it is displayed in the DataList control. This makes it possible to embed script within HTML tags in the text. If the values for the control come from user input, be sure to validate the values to help prevent security vulnerabilities.
For detailed information on the DataList Web server control's properties and events, see the DataList Class documentation.
Example
The following example demonstrates how to use a DataList control to display the items of a data source.
<%@ Page Language="VB" AutoEventWireup="True" %>
<%@ Import Namespace="System.Data" %>
<html>
<script runat="server">
Function CreateDataSource() As ICollection
Dim dt As New DataTable()
Dim dr As DataRow
dt.Columns.Add(New DataColumn("StringValue", GetType(String)))
Dim i As Integer
For i = 0 To 9
dr = dt.NewRow()
dr(0) = "Item " & i.ToString()
dt.Rows.Add(dr)
Next i
Dim dv As New DataView(dt)
Return dv
End Function 'CreateDataSource
Sub Page_Load(sender As Object, e As EventArgs)
If Not IsPostBack Then
DataList1.DataSource = CreateDataSource()
DataList1.DataBind()
End If
End Sub 'Page_Load
Sub Button1_Click(sender As Object, e As EventArgs)
If DropDown1.SelectedIndex = 0 Then
DataList1.RepeatDirection = RepeatDirection.Horizontal
Else
DataList1.RepeatDirection = RepeatDirection.Vertical
End If
If DropDown2.SelectedIndex = 0 Then
DataList1.RepeatLayout = RepeatLayout.Table
Else
DataList1.RepeatLayout = RepeatLayout.Flow
End If
DataList1.RepeatColumns = DropDown3.SelectedIndex + 1
If Check1.Checked = True And DataList1.RepeatLayout = RepeatLayout.Table Then
DataList1.BorderWidth = Unit.Pixel(1)
DataList1.GridLines = GridLines.Both
Else
DataList1.BorderWidth = Unit.Pixel(0)
DataList1.GridLines = GridLines.None
End If
End Sub 'Button1_Click
</script>
<body>
<form runat="server">
<h3>DataList Example</h3>
<asp:DataList id="DataList1" runat="server"
BorderColor="black"
CellPadding="3"
Font-Name="Verdana"
Font-Size="8pt">
<HeaderStyle BackColor="#aaaadd">
</HeaderStyle>
<AlternatingItemStyle BackColor="Gainsboro">
</AlternatingItemStyle>
<HeaderTemplate>
Items
</HeaderTemplate>
<ItemTemplate>
<%# DataBinder.Eval(Container.DataItem, "StringValue") %>
</ItemTemplate>
</asp:DataList>
<p>
<hr noshade align="left" width="300px">
RepeatDirection:
<asp:DropDownList id=DropDown1 runat="server">
<asp:ListItem>Horizontal</asp:ListItem>
<asp:ListItem>Vertical</asp:ListItem>
</asp:DropDownList><br>
RepeatLayout:
<asp:DropDownList id=DropDown2 runat="server">
<asp:ListItem>Table</asp:ListItem>
<asp:ListItem>Flow</asp:ListItem>
</asp:DropDownList><br>
RepeatColumns:
<asp:DropDownList id=DropDown3 runat="server">
<asp:ListItem>1</asp:ListItem>
<asp:ListItem>2</asp:ListItem>
<asp:ListItem>3</asp:ListItem>
<asp:ListItem>4</asp:ListItem>
<asp:ListItem>5</asp:ListItem>
</asp:DropDownList><br>
Show Borders:
<asp:CheckBox id=Check1 runat="server" /><p>
<asp:LinkButton id=Button1
Text="Refresh DataList"
OnClick="Button1_Click"
runat="server"/>
</form>
</body>
</html>
[C#]
<%@ Page Language="C#" AutoEventWireup="True" %>
<%@ Import Namespace="System.Data" %>
<html>
<script runat="server">
ICollection CreateDataSource()
{
DataTable dt = new DataTable();
DataRow dr;
dt.Columns.Add(new DataColumn("StringValue", typeof(string)));
for (int i = 0; i < 10; i++)
{
dr = dt.NewRow();
dr[0] = "Item " + i.ToString();
dt.Rows.Add(dr);
}
DataView dv = new DataView(dt);
return dv;
}
void Page_Load(Object Sender, EventArgs e)
{
if (!IsPostBack)
{
DataList1.DataSource = CreateDataSource();
DataList1.DataBind();
}
}
void Button1_Click(Object Sender, EventArgs e)
{
if (DropDown1.SelectedIndex == 0)
DataList1.RepeatDirection = RepeatDirection.Horizontal;
else
DataList1.RepeatDirection = RepeatDirection.Vertical;
if (DropDown2.SelectedIndex == 0)
DataList1.RepeatLayout = RepeatLayout.Table;
else
DataList1.RepeatLayout = RepeatLayout.Flow;
DataList1.RepeatColumns=DropDown3.SelectedIndex+1;
if ((Check1.Checked ==true) &&
(DataList1.RepeatLayout == RepeatLayout.Table))
{
DataList1.BorderWidth = Unit.Pixel(1);
DataList1.GridLines = GridLines.Both;
}
else
{
DataList1.BorderWidth = Unit.Pixel(0);
DataList1.GridLines = GridLines.None;
}
}
</script>
<body>
<form runat="server">
<h3>DataList Sample</h3>
<asp:DataList id="DataList1"
BorderColor="black"
CellPadding="3"
Font-Name="Verdana"
Font-Size="8pt"
runat="server">
<HeaderStyle BackColor="#aaaadd"/>
<AlternatingItemStyle BackColor="Gainsboro"/>
<HeaderTemplate>
Items
</HeaderTemplate>
<ItemTemplate>
<%# DataBinder.Eval(Container.DataItem, "StringValue") %>
</ItemTemplate>
</asp:DataList>
<p>
<hr noshade align="left" width="300px">
RepeatDirection:
<asp:DropDownList id=DropDown1 runat="server">
<asp:ListItem>Horizontal</asp:ListItem>
<asp:ListItem>Vertical</asp:ListItem>
</asp:DropDownList><br>
RepeatLayout:
<asp:DropDownList id=DropDown2 runat="server">
<asp:ListItem>Table</asp:ListItem>
<asp:ListItem>Flow</asp:ListItem>
</asp:DropDownList><br>
RepeatColumns:
<asp:DropDownList id=DropDown3 runat="server">
<asp:ListItem>1</asp:ListItem>
<asp:ListItem>2</asp:ListItem>
<asp:ListItem>3</asp:ListItem>
<asp:ListItem>4</asp:ListItem>
<asp:ListItem>5</asp:ListItem>
</asp:DropDownList><br>
Show Borders:
<asp:CheckBox id=Check1 runat="server" />
<p>
<asp:LinkButton id=Button1
Text="Refresh DataList"
OnClick="Button1_Click"
runat="server"/>
</font>
</form>
</body>
</html>