The DataGrid Web control is multi-column, data-bound grid. The control allows you to define various types of columns, both to lay out the contents of the grid (template columns) and to add specific functionality (edit button columns, hyperlink columns, and so on). The control also supports a variety of options for including paging.
Required properties are noted in boldface type.
<asp:DataGrid id="DataGrid1" runat=server DataSource='<%# DataBindingExpression %>' AllowPaging="True|False" AllowSorting="True|False" AutoGenerateColumns="True|False" BackImageUrl="url" CellPadding="pixels" CellSpacing="pixels" DataKeyField="DataSourceKeyField" GridLines="None|Columns|Rows|Both" HorizontalAlign="Center|Justify|Left|NotSet|Right" PagedDataSource PageSize="ItemCount" ShowFooter="True|False" ShowHeader="True|False" VirtualItemCount="ItemCount" AlternatingItemStyle-property="value" EditItemStyle-property="value" FooterStyle-property="value" HeaderStyle-property="value" ItemStyle-property="value" PagerStyle-property="value" SelectedItemStyle-property="value" OnCancelCommand="OnCancelCommandMethod" OnDeleteCommand="OnDeleteCommandMethod" OnEditCommand="OnEditCommandMethod" OnItemCommand="OnItemCommandMethod" OnItemCreated="OnItemCreatedMethod" OnPageIndexChanged="OnPageIndexChangedMethod" OnSortCommand="OnSortCommandMethod" OnUpdateCommand="OnUpdateCommandMethod" </asp:DataGrid> or <asp:DataGrid id="DataGrid1" runat=server DataSource='<%# DataBindingExpression %>' AutoGenerateColumns="False" (other properties) <property name="Columns"> <asp:BoundColumn DataField="DataSourceField" DataFormatString="FormatString" FooterText="FooterText" HeaderImageUrl="url" HeaderText="HeaderText" ReadOnly="True|False" SortField="DataSourceFieldToSortBy" Visible="True|False" FooterStyle-property="value" HeaderStyle-property="value" ItemStyle-property="value" /> <asp:ButtonColumn ButtonType="LinkButton|PushButton" Command="BubbleText" DataTextField="DataSourceField" DataTextFormatString="FormatString" FooterText="FooterText" HeaderImageUrl="url" HeaderText="HeaderText" ReadOnly="True|False" SortField="DataSourceFieldToSortBy" Text="ButtonCaption" Visible="True|False" /> <asp:EditCommandColumn ButtonType="LinkButton|PushButton" CancelText="CancelButtonCaption" EditText="EditButtonCaption" FooterText="FooterText" HeaderImageUrl="url" HeaderText="HeaderText" ReadOnly="True|False" SortField="DataSourceFieldToSortBy" UpdateText="UpdateButtonCaption" Visible="True|False" /> <asp:HyperlinkColumn DataNavigateUrlField="DataSourceField" DataNavigateUrlFormatString="FormatExpression" DataTextField="DataSourceField" DataTextFormatString="FormatExpression" FooterText="FooterText" HeaderImageUrl="url" HeaderText="HeaderText" NavigateUrl="url" ReadOnly="True|False" SortField="DataSourceFieldToSortBy" Target="window" Text="HyperlinkText" Visible="True|False" /> <asp:TemplateColumn> FooterText="FooterText" HeaderImageUrl="url" HeaderText="HeaderText" ReadOnly="True|False" SortField="DataSourceFieldToSortBy" Visible="True|False" <template name="HeaderTemplate"> Header template HTML </template> <template name="ItemTemplate"> ItemTemplate HTML </template> <template name="EditItemTemplate"> EditItem template HTML </template> <template name="FooterTemplate"> Footer template HTML </template> </asp:TemplateColumn> </property> </asp:DataGrid>
Property | Description |
---|---|
(Base control properties) | The properties defined in Base Web Control Properties. |
AllowCustomPaging | True if the control does not calcuate a starting position in the data model based on PageIndex. Instead, the DataGrid control displays rows 0 through PageSize. This allows you to implement a "chunked" paging behavior. The default is true. |
AllowPaging | True if paging is enabled. The default is true. |
AllowSorting | True if sorting is enabled on the DataGrid, false otherwise. The default is false. If true, the headers of columns whose SortExpression is set will be rendered as LinkButton controls with the command sort. |
AutoGenerateColumns | True if columns will be generated for each bound data field, false otherwise. If other columns are explicitly declared, the auto-generated columns will be appended to the end of the columns collection. The default is true. |
BackImageUrl | The URL of an image to display behind the control. |
CellPadding | The amount of space, in pixels, between cells.
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.
When programming, this property is set using Units. |
Columns | (Read-only) A collection of the columns in the control.
This property is only used when programming; it is not used when declaring the control. |
CurrentPageIndex | The current page number.
This property is only used when programming; it cannot be set when declaring the control. |
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. |
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. |
HorizontalAlign | The alignment of the rows with respect to surrounding text.
When programming, you set this property using the HorizontalAlign 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. |
PageCount | (Read-only) The total number of pages to be displayed, calculated as a function of the PageSize and the total number of records to be displayed.
This property is only used when programming. |
PagedDataSource | To be supplied. |
PageSize | Number of items (records) to display per page. |
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. |
VirtualItemCount | A user-settable count of the number of rows to display (rather than an actual count based on the rows in the data source). If AllowCustomPaging is true, this property determines the number of pages that will be displayed. In that case, the DataGrid control does not calcuate a starting position based on PageIndex. Instead, the control displays rows 0 through PageSize of the data, while its Pager object reports the current position as page PageIndex of (VirtualItemCount+PageSize-1)/PageSize.
If AllowCustomPaging is false, the control will calculate the total page count from the data. |
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 |
PagerStyle | The pager buttons. | DataGridPagerStyle |
SelectedItemStyle | The currently-selected item. | TableItemStyle |
The following tables provide information about the columns you can declare for the DataGrid control.
These properties are available on all DataGrid column types.
Property | Description |
---|---|
FooterText | Text to display at the bottom of the column. |
HeaderImageUrl | The URL of an image that will render instead of HeaderText text in the column header. |
HeaderText | Text to display at the top of the column. |
Owner | (Read-only) A reference to the DataGrid to which the bound column belongs.
This property is only used when programming. |
SortField | The name of the field to sort the data source by when the user specifies sorting by the contents of this column. |
State | (Read-only) A reference to a StateBag object for this column.
This property is only used when programming. |
Visible | true if the column should be displayed, false otherwise. |
All style objects for DataGrid columns are of type TableItemStyle. For details, see Style Object Properties.
Style object | Description |
---|---|
FooterStyle | To be supplied. |
HeaderStyle | To be supplied. |
ItemStyle | To be supplied. |
Property | Description |
---|---|
DataField | The field or property of the object in DataSource that will be the source of data for the column. |
DataFormatString | A format expression. |
ReadOnly | True if the column cannot be edited when the row is put into edit mode, false otherwise. |
Property | Description |
---|---|
ButtonType | What type of button to render. The default is LinkButton.
When programming, this property is set using the ButtonColumnType enumeration. |
Command | A string indicating the command that should be bubbled when a button in the column is clicked. This string is available in the event-handling method via the Command property of the e events argument object. |
DataTextField | The field name from DataSource that is bound to the Text property of the button in this column. |
DataTextFormatString | A format expression. |
Text | The caption to display on the face of the button in this column. If DataTextField is set, it overrides this value. |
Property | Description |
---|---|
EditItemTemplate | The HTML elements and controls that define the column when it is in edit mode. |
FooterTemplate | The HTML elements and controls that define the column footing. |
HeaderTemplate | The HTML elements and controls that define the column heading. |
ItemTemplate | The HTML elements and controls that define the column when it is being displayed. |
Property | Description |
---|---|
DataNavigateUrlField | The field or property of the object in DataSource that will provide the URL of the page to go to. |
DataNavigateUrlFormatString | A format expression to be used with the Text property. |
DataTextField | The field or property of the object in DataSource that will be the source of data for the Text property of the columns. |
DataTextFormatString | |
NavigateUrl | The URL of the page to go to. If DataNavigateUrlField is set, it overrides this property. |
Target | The target window in which the hyperlink will display the page. This can be the name of a window or a frame reference such as _TOP. |
Text | The text of the hyperlink. |
Property | Description |
---|---|
ButtonType | What type of button to render. The default is LinkButton.
When programming, this property is set using the ButtonColumnType enumeration. |
EditText | The string to display on the face of the edit button. |
UpdateText | The string to display on the face of the update button. |
CancelText | The string to display on the face of the cancel button. |
Event (and paramters) | Description |
---|---|
OnCancelCommand(Object sender, DataGridCommandEventArgs e) | Raised when an event is bubbled to the DataGrid 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, DataGridCommandEventArgs e) | Raised when an event is bubbled to the DataGrid 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, DataGridCommandEventArgs e) | Raised when an event is bubbled to the DataGrid 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, DataGridCommandEventArgs e) | Raised in the DataGrid 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, DataGridItemCreatedEventArgs e) | Raised on the server each time a control is created.
The following are properties of the e events argument object:
|
OnPageIndexChanged(Object sender, DataGridPageChangedEventArgs e) | Raised when
The following are properties of the e events argument object:
|
OnSortCommand(Object sender, DataGridSortCommandEventArgs e) | Raised when
The following are properties of the e events argument object:
|
OnUpdateCommand(Object sender, DataGridCommandEventArgs e) | Raised when an event is bubbled to the DataGrid 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 DataGrid control allows you to define the following types of columns:
Column type | Description |
---|---|
EditCommandColumn | Encapsulates the most common Edit commands (edit, update, cancel) into a predefined column type. |
HyperlinkColumn | Creates a column with a set of hyperlinks that are bound to the value of a data field. For example, a grid that displays a list of orders could include a hyperlink column where the OrderID is rendered as a hyperlink to a page that displays the details for the order. |
BoundColumn | A column bound to a field in the data source and rendered into a table cell using styles. This is the default column type for the DataGrid control. |
TemplatedColumn | Allows you to define the layout of controls using templates for custom HTML elements and controls. |
Note By default, the DataGrid control recreates the data set each time the user navigates to a new page and then calculates which rows to display for the requested page. If this is not efficient in your application, you can turn off automatic paging. To do this, set the AllowCustomPaging property to true. The grid will now only display the rows provided in the data set. If you are using built-in navigation controls, the grid will still set the CurrentPageIndex property.
If you haven't already, you will need to provide built-in or custom navigation controls, and in the event handling method for these controls, request a page worth of rows from the data source. The number of rows to retrieve is set by the grid's PageSize property and the page number to go to the value of the CurrentPageIndex property. You can calculate the starting row number this way:
[C#]
StartRowIndex=(MyDataGrid.CurrentPageIndex*MyDataGrid.PageSize);
.
Example
To be supplied.
See Also