NGWS SDK Documentation  

This is preliminary documentation and subject to change.
To comment on this topic, please send us email at ngwssdk@microsoft.com. Thanks!

DataGrid Web Control

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.

ASP+ Syntax

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>

Properties

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.

DataGrid Style Objects

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

DataGridColumns

The following tables provide information about the columns you can declare for the DataGrid control.

Column Base Properties

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.

Column Base Style Objects

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.

BoundColumn Properties

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.

ButtonColumn Properties

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.

TemplateColumn Properties

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.

HyperlinkColumn Properties

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.

EditCommandColumn Properties

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.

Events

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:

  • e.CommandSource   (Object)
  • e.Item   (DataGridItem)
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:

  • e.Item   (DataGridItem)
OnPageIndexChanged(Object sender, DataGridPageChangedEventArgs e) Raised when

The following are properties of the e events argument object:

  • e.CommandSource   (Object)
  • e.NewPageIndex   (Integer)
  • e.OldPageIndex   (Integer)
OnSortCommand(Object sender, DataGridSortCommandEventArgs e) Raised when

The following are properties of the e events argument object:

  • e.CommandSource   (Object)
  • e.SortField   (String)
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.

Remarks

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

Web Forms Controls by Function |