Class TDataGrid

TDataGrid class

TDataGrid represents a data bound and updatable grid control.

To populate data into the datagrid, sets its DataSource to a tabular data source and call dataBind(). Each row of data will be represented by an item in the Items collection of the datagrid.

An item can be at one of three states: browsing, selected and edit. The state determines how the item will be displayed. For example, if an item is in edit state, it may be displayed as a table row with input text boxes if the columns are of type TBoundColumn; and if in browsing state, they are displayed as static text.

To change the state of an item, set EditItemIndex or SelectedItemIndex property.

Each datagrid item has a TDataGridItem::getItemType which tells the position and state of the item in the datalist. An item in the header of the repeater is of type Header. A body item may be of either Item, AlternatingItem, SelectedItem or EditItem, depending whether the item index is odd or even, whether it is being selected or edited.

A datagrid is specified with a list of columns. Each column specifies how the corresponding table column will be displayed. For example, the header/footer text of that column, the cells in that column, and so on. The following column types are currently provided by the framework,

• TBoundColumn, associated with a specific field in datasource and displays the corresponding data.
• TEditCommandColumn, displaying edit/update/cancel command buttons
• TButtonColumn, displaying generic command buttons that may be bound to specific field in datasource.
• TDropDownListColumn, displaying a dropdown list when the item is in edit state
• THyperLinkColumn, displaying a hyperlink that may be bound to specific field in datasource.
• TCheckBoxColumn, displaying a checkbox that may be bound to specific field in datasource.
• TTemplateColumn, displaying content based on templates.

• Automatically generated based on data source. By setting AutoGenerateColumns to true, a list of columns will be automatically generated based on the schema of the data source. Each column corresponds to a column of the data.
• Specified in template. For example,

       <com:TDataGrid ...>
          <com:TBoundColumn .../>
          <com:TEditCommandColumn .../>
       </com:TDataGrid>
  

• Manually created in code. Columns can be manipulated via the setColumns property of the datagrid. For example,

      $column=new TBoundColumn;
      $datagrid->Columns[]=$column;
  

TDataGrid supports sorting. If the AllowSorting is set to true, a column with nonempty setSortExpression will have its header text displayed as a clickable link button. Clicking on the link button will raise OnSortCommand event. You can respond to this event, sort the data source according to the event parameter, and then invoke databind() on the datagrid to show to end users the sorted data.

TDataGrid supports paging. If the AllowPaging is set to true, a pager will be displayed on top and/or bottom of the table. How the pager will be displayed is determined by the PagerStyle property. Clicking on a pager button will raise an OnPageIndexChanged event. You can respond to this event, specify the page to be displayed by setting CurrentPageIndex</b> property, and then invoke databind() on the datagrid to show to end users a new page of data.

TDataGrid supports two kinds of paging. The first one is based on the number of data items in datasource. The number of pages PageCount is calculated based the item number and the PageSize property. The datagrid will manage which section of the data source to be displayed based on the CurrentPageIndex property. The second approach calculates the page number based on the VirtualItemCount property and the PageSize property. The datagrid will always display from the beginning of the datasource up to the number of PageSize data items. This approach is especially useful when the datasource may contain too many data items to be managed by the datagrid efficiently.

When the datagrid contains a button control that raises an onCommand event, the event will be bubbled up to the datagrid control. If the event's command name is recognizable by the datagrid control, a corresponding item event will be raised. The following item events will be raised upon a specific command:

• OnEditCommand, if CommandName=edit
• OnCancelCommand, if CommandName=cancel
• OnSelectCommand, if CommandName=select
• OnDeleteCommand, if CommandName=delete
• OnUpdateCommand, if CommandName=update
• onPageIndexChanged, if CommandName=page
• OnSortCommand, if CommandName=sort

TDataGrid also raises an OnItemCreated event for every newly created datagrid item. You can respond to this event to customize the content or style of the newly created item.

Note, the data bound to the datagrid are reset to null after databinding. There are several ways to access the data associated with a datagrid row:

• Access the data in OnItemDataBound event
• Use DataKeys to obtain the data key associated with

• Save the data in viewstate and get it back during postbacks.