Share via


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>

See Also

Web Server Controls | DataList Class