This documentation is archived and is not being maintained.

Introduction to the DataGrid Web Server Control

Visual Studio .NET 2003

The DataGrid Web server control displays data in a tabular layout. By default, the DataGrid displays data in read-only mode, but the DataGrid is also capable of automatically displaying the data in editable controls at run-time. The DataGrid control can also create the Select, Edit, Update, and Cancel buttons and programming structure for you through the Property Builder dialog box. Additionally, the DataGrid supports paging, though you may also use the custom navigation features of the control to improve performance by controlling the amount of data sent to the client browser.

Note   To have complete control over the HTML rendered by the list, use the Repeater Web server control. Use the DataList control to display data in a non-tabular layout. For more information, see Controls for Displaying Lists On Web Pages.

The following sections introduce the features of the DataGrid control.

Binding Data to the Control

The DataGrid Web server control must be bound to a data source via its DataSource property or it will not be rendered on the page. Typical data sources for the DataGrid are the DataSet and data readers. You can use data sources available from the Toolbox, such as the DataSet or DataView class. You can also bind to data sources in code, such as a data reader or an array. The control can use as a data source any class that supports the IEnumerable interface.

When data binding, you specify a data source for the DataGrid control as a whole. The grid displays one row — one item — for every row in the data source. By default, the DataGrid control generates a bound column for each field in the data source. However, you can pick which fields in the data source generate columns in the grid. For more information on data binding, see Introduction to Data Access in Web Forms Pages.

When the Web page runs, your code must call the control's DataBind method to load the grid with data. You call the method again if the data changes (for example, in an event handler) to refresh the grid.

As part of the data binding, you can specify a DataKeyField property. This property allows you to specify information that uniquely identifies each item in the grid. The information does not have to be part of the information displayed in the grid. It can consist of the name of a field in the data source (such as a primary key). You can use this information to update a specific item in the data source. For example, if you set the DataKeyField to be customerId, you could later update the record where customerID=DataGrid1.DataKeys[DataGrid1.SelectedIndex].

As with other server controls, data binding in the DataGrid control is one-way; that is, data binding is read-only. If you are using the grid to allow users to edit the data, you must create your own code to update the data source. After updating the data source, you again bind the data to the data source. The update logic often takes advantage of the DataKeyField to locate the correct record using the key value.

For more details about updating data using the DataGrid control, see "Editing Items" below. For general information about data binding in server controls, see Data Access in Web Forms Pages.

Format Items

The Format tab of the Property Builder dialog box controls the layout of the rows of the DataGrid. These settings specify the color, font, and alignment of the rows. The actual control, text, and data contents of the row are specified in the Columns tab of the Property Builder. The following items can be configured:

  • DataGrid   These settings are applied to the entire grid. Other item formats override these settings.
  • Header   The Header is the top row of the DataGrid, and does not display the row data of the data source. You must indicate in the General tab of the Property Builderwhether you want the Header row to be displayed. It is displayed by default.
  • Footer   The Footer is the bottom row of the DataGrid and does not display the row data of the data source. You must indicate in the General tab of the Property Builderwhether you want the Footer row to be displayed. It is not displayed by default.
  • Pager   If you are displaying only a few rows of your data source at a time, using the paging abilities of the DataGrid, use this item to control the appearance of the paging controls.
  • Items   These four items specify how the data rows will appear. They are:
    • Normal Items   This format is applied to all the data rows of the table, unless overridden by another item.
    • Alternating Items   This format is applied to alternating items in the control.
    • Selected Items   This format is applied to the selected item in the control.
    • Edit Mode Items   This format is applied to the item being edited.
  • Columns   This item allows you to specify the format of the columns you create in the Columns tab of the Property Builder.

For more information on using item formats, see Specifying Grid Item Format in a DataGrid Web Server Control and Specifying Paging Behavior in a DataGrid Web Server Control.

Columns

The DataGrid control allows you to specify the columns it displays in a variety of ways. By default, the columns are generated automatically based on fields in the data source. However, in order to control the content and layout of columns more precisely, you can define the following types of columns:

Type of ColumnDescription
Bound columnAllows you to specify which data source field to display. Allows you to specify the format of that field, using a .NET formatting expression. For details see Adding Bound Columns to a DataGrid Web Server Control.
Hyperlink columnDisplays information as hyperlinks. A typical use is to display data (such as a customer number or product name) as a hyperlink that users can click to navigate to a separate page that provides details about that item. For details see Adding Hyperlink Columns to a DataGrid Web Server Control.
Button columnAllows you to add a button for each item in the grid and define custom functionality for that button. For example, you might create a button labeled "Add to Shopping Cart" that runs your custom logic when a user clicks it. You can also add predefined buttons for Select, Edit, Update, Cancel, and Delete functions. For details see Adding Button Columns to a DataGrid Web Server Control.
Edit, Update, Cancel columnAllows you to create in-place editing. For more details, see "Editing Items" below.
Template columnAllows you to create combinations of HTML text and server controls to design a custom layout for a column. The controls within a template column can be data-bound. Template columns give you great flexibility in defining the layout and functionality of the grid contents, because you have complete control over how the data is displayed and what happens when users interact with rows in the grid. For details see Adding Template Columns to a DataGrid Web Server Control.

For more information about columns, see DataGrid Columns.

Events

The DataGrid control supports several events. One of them, the ItemCreated event, gives you a way to customize the item-creation process. The ItemDataBound event also gives you the ability to customize the DataGrid items, but after the data is available for inspection. For example, if you were using the DataGrid control to display a to-do list, you could display overdue items in red text, completed items in black text, and other tasks in green text.

The remaining events are raised in response to button or LinkButton clicks in grid items. They are designed to help you implement common data manipulation tasks. Four events of this type are supported:

  • EditCommand
  • DeleteCommand
  • UpdateCommand
  • CancelCommand

The Property Builder dialog box of the DataGrid control will build the buttons needed to raise these events at run time. When the user clicks one of the buttons (labeled by default Edit, Delete, Update, or Cancel, respectively), the corresponding event is raised.

The DataGrid control also supports the ItemCommand event that is raised when a user clicks a button that is not one of the predefined buttons above. You can use this event for custom functionality by setting a button's CommandName property to a value you need and then testing for it in the ItemCommand event handler. (For example, you could use this approach when selecting an item, as documented in Allowing Users to Select Items in a DataList Web Server Control.)

For a complete list of the events supported by the DataGrid control, see DataList Events. For more information about events, see ASP.NET Server Control Event Model. For information on supporting these events with the DataGrid, see Allowing Users to Select Items in a DataGrid Web Server Control, Allowing Users to Edit Items in a DataGrid Web Server Control, and Allowing Users to Delete Items in a DataGrid Web Server Control.

Editing Items

You can allow users to edit the contents of individual rows in a grid item. There are two ways to do this:

  • Allow in-place editing. This is the easier way to implement editing. Using the Property Builder, you include a special column in the grid known as an Edit, Update, Cancel column. At run time, each row of the column contains a button labeled "Edit". When a user clicks this edit button, the control automatically redisplays the current row with TextBox controls for all columns. The column with the edit button is redisplayed with Update and Cancel buttons. You add code to the UpdateCommand and CancelCommand events to propagate the changes in the editing controls back to your data source.

    For details, see Allowing Users to Edit Items in a DataGrid Web Server Control.

  • Create a custom-editing layout with a template column. You can create columns that display the data in editable controls. This approach allows you to choose which columns can be edited and how the user can edit the data. For example, instead of using a TextBox control for true-false data, you might prefer a ListBox control with "True" and "False" entries. A template column allows you to put more than one control in a DataGrid cell.

    The template column supports four templates:

    • HeaderTemplate
    • ItemTemplate
    • EditItemTemplate
    • FooterTemplate

    For more information, see Allowing Users to Edit Items in a DataGrid Web Server Control and Allowing Users to Delete Items in a DataGrid Web Server Control.

Sorting

The DataGrid Web server control provides a way for you to add sorting to the grid. The grid does not directly support sorting — that is, it doesn't sort the contents of the grid for you. Instead, it provides a way for you to add sort options to the grid, such as hyperlinks in the column heads that users click to sort. The grid then notifies you when a user has requested sorting. You then sort the data source and rebind the data source to the DataGrid.

The DataGrid control provides two levels of sorting support:

  • Default sorting   You specify that you want the grid to support sorting. The column headings are all link buttons; when the user clicks one, you are notified of the sort. This solution is easy, but does not allow you to pick which columns support sorting — they all do.
  • Custom sorting   You define which columns support sorting. This is a more complex option, because you must define the columns using either bound columns or template columns. However, not only does this allow you to specify which columns can be sorted, but you can use whatever control you want in the column header as the sort button. For example, you might use a graphic that you create using an ImageButton Web server control.

For details, see Adding Sorting to a DataGrid Web Server Control.

See Also

DataGrid Web Server Control | Adding DataGrid Web Server Controls to a Web Forms Page | DataGrid Class

Show: