The DataList control displays a data-bound list. You can manipulate the control's layout by defining templates.
Note The DataList control differs from the Repeater control by providing supporting directional rendering (via the RepeatColumns and RepeatDirection properties) and the option to render within an HTML table.
Required properties are noted in boldface type.
<asp:DataList id="DataList1" runat="server" CellPadding="pixels" CellSpacing="pixels" DataKeyField="DataSourceKeyField" DataSource='<% databindingexpression %>' ExtractTemplateRows="To be supplied" GridLines="None|Columns|Rows|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" <template name="Header"> Header template HTML </template > <template name="Item"> Item template HTML </template > <template name="AlternatingItem"> Alternating item template HTML </template > <template name="EditItem"> Edited item template HTML </template > <template name="SelectedItem"> Selected item template HTML </template > <template name="Separator"> Separator template HTML </template > <template name="Footer"> Footer template HTML </template > AlternatingItemStyle-property="value" EditItemStyle-property="value" FooterStyle-property="value" HeaderStyle-property="value" ItemStyle-property="value" SelectedItemStyle-property="value" SeparatorStyle-property="value" />
Property | Description |
---|---|
(Base control properties) | The properties defined in Base Web Control Properties. |
CellPadding | The amount of space, in pixels, between cells. This property has no effect unless RepeatLayout is set to Table.
When programming, this property is set using Units. |
CellSpacing | The amount of space, in pixels, between the contents of a cell and the cell's border. This property has no effect unless RepeatLayout is set to Table.
When programming, this property is set using Units. |
DataKeyField | The name of the field in the data source referenced by DataSource that holds the primary key. |
DataKeys | A collection of DataKey objects created by evaluating the DataKeyField expression against the data source. One DataKey object is stored per item in the Items collection.
This property is only used when programming; it cannot be set when declaring the control. |
DataSource | A data-binding expression that references any object that supports the ICollection interface.
Note In ASP+ syntax, it is preferable to include the data-binding expression in single quotation marks to accommodate quoted expressions. |
EditItemIndex | The ordinal index of item to be edited (zero-based). Setting this property to -1 cancels editing.
This property is only used when programming; it cannot be set when declaring the control. |
ExtractTemplateRows | True if [to be supplied]; otherwise false. |
GridLines | How grid lines are displayed between items. The default is None. This property has no effect unless RepeatLayout is set to Table.
Note Gridlines can be displayed only in browsers that support CSS stylesheets. When programming, this property is set using the GridLinesRule enumeration. |
Items | A collection of DataListItem objects representing individual items within the control. The Items collection contains only items bound to the data model; header, footer and separators are not available via the collection.
This property is only used when programming. At design time, you set this property by declaring ListItem elements. |
RepeatColumns | The number of columns to use to display the items. The default is 1. |
RepeatDirection | The direction in which items are displayed in the list. If Vertical, the itme are ordered top to bottom, like text in a newspaper. If Horizontal, items are ordered left-to-right, like days in a calendar. This property has no effect if RepeatColumns is set to 1. The default is Vertical.
When programming, this property is set using the RepeatDirection enumeration. |
RepeatLayout | Indicates whether the control renders in-line (Flow) or in a table (Table). The default is Table.
When programming, this property is set using the RepeatLayout enumeration. |
SelectedIndex | The ordinal index of currently selected row (referenced by the SelectedItem property) in the control (zero-based).
This property is only used when programming. |
SelectedItem | A reference to the currently-selected row in the list.
This property is only used when programming. |
ShowFooter | True if the footer should be rendered, false otherwise. |
ShowHeader | True if the header should be rendered, false otherwise. |
AlternatingItemTemplate | Like the ItemTemplate element, but rendered for every other row in the DataList control. You can specify a different look for the AlternatingItemTemplate element by setting its style properties. |
EditItemTemplate | The layout of an item when it has been set into 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 after all items have been rendered.
The FooterTemplate item cannot be data bound. |
HeaderTemplate | The text and controls to render before all items have been rendered.
The HeaderTemplate item 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 beign displayed and to visually mark the row using a highlight. |
SeparatorTemplate | The elements to render between each item.
The SeparatorTemplate item cannot be data bound. |
For information about the properties supported for each style class, see Style Object Properties.
Style object | Description | Style class |
---|---|---|
AlternatingItemStyle | Every other item. | TableItemStyle |
EditItemStyle | The item currently being edited. | TableItemStyle |
FooterStyle | The footer at the end of the list (if any) | TableItemStyle |
HeaderStyle | The header at the top of the list (if any). | TableItemStyle |
ItemStyle | Individual items. | Style |
SelectedItemStyle | The currently-selected item. | TableItemStyle |
SeparatorStyle | The elements between each item. | TableItemStyle |
Event (and paramters) | Description |
---|---|
OnCancelCommand(Object sender, DataListCommandEventArgs e) | Raised when an event is bubbled to the DataList control that was raised by a control whose Command property is cancel. Typically, this is a Button or LinkButton control declared in the EditItemTemplate.
The following are properties of the e events argument object:
|
OnDeleteCommand(Object sender, DataListCommandEventArgs e) | Raised when an event is bubbled to the DataListt control that was raised by a control whose Command property is delete. Typically, this is a Button or LinkButton control declared in the ItemTemplate.
For details about the properties of the event argument e, see OnCancelCommand above. |
OnEditCommand(Object sender, DataListCommandEventArgs e) | Raised when an event is bubbled to the DataList control that was raised by a control whose Command property is edit. Typically, this is a Button or LinkButton control declared in the ItemTemplate.
For details about the properties of the event argument e, see OnCancelCommand above. |
OnItemCommand(Object sender, DataListCommandEventArgs e) | Raised in the DataList control when an embedded control raises an event that is not already covered by edit, cancel, delete, or update.
For details about the properties of the event argument e, see OnCancelCommand above. |
OnItemCreated(Object sender, DataListItemCreatedEventArgs e) | Raised on the server each time a control is created.
The following are properties of the e events argument object:
|
OnUpdateCommand(Object sender, DataListCommandEventArgs e) | Raised when an event is bubbled to the DataList control that was raised by a control whose Command property is update. Typically, this is a Button or LinkButton control declared in the EditItemTemplate.
For details about the properties of the event argument e, see OnCancelCommand above. |
The Items collection contains the databound members of the DataList control. The collection is populated when the Bind 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 any add or remove methods. However, you can modify the contents within an Item by handling the OnItemCreated event.
Example
To be supplied.
See Also