TDataGrid : Part I

TDatagrid is an important control in building complex Web applications. It displays data in a tabular format with rows (also called items) and columns. A row is composed by cells, while columns govern how cells should be displayed according to their association with the columns. Data specified via DataSource or DataSourceID are bound to the rows and feed contents to cells.

TDataGrid is highly interactive. Users can sort the data along specified columns, navigate through different pages of the data, and perform actions, such as editting and deleting, on rows of the data.

Rows of TDataGrid can be accessed via its Items property. A row (item) can be in one of several modes: browsing, editting and selecting, which affects how cells in the row are displayed. To change an item's mode, modify EditItemIndex or SelectedItemIndex. Note, if an item is in edit mode, then selecting this item will have no effect.

Columns

Columns of a data grid determine how the associated cells are displayed. For example, cells associated with a TBoundColumn are displayed differently according to their modes. A cell is displayed as a static text if the cell is in browsing mode, a text box if it is in editting mode, and so on.

PRADO provides five types of columns:

TBoundColumn associates cells with a specific field of data and displays the cells according to their modes.
TCheckBoxColumn associates cells with a specific field of data and displays in each cell a checkbox whose check state is determined by the data field value.
THyperLinkColumn displays in the cells a hyperlink whose caption and URL can be either statically specified or bound to some fields of data.
TEditCommandColumn displays in the cells edit/update/cancel command buttons according to the state of the item that a cell resides in.
TButtonColumn displays in the cells a command button.
TTemplateColumn displays the cells according to different templates defined for it.

Item Styles

TDataGrid defines different styles applied to its items. For example, AlternatingItemStyle is applied to alternating items (item 2, 4, 6, etc.) Through these properties, one can set CSS style fields or CSS classes for the items.

Item styles are applied in a hierarchical way. Styles in higher hierarchy will inherit from styles in lower hierarchy. Starting from the lowest hierarchy, the item styles include item's own style, ItemStyle, AlternatingItemStyle, SelectedItemStyle, and EditItemStyle. Therefore, if background color is set as red in ItemStyle, EditItemStyle will also have red background color, unless it is explicitly set to a different value.

Events

TDataGrid provides several events to facilitate manipulation of its items,

OnItemCreated - raised each time an item is newly created. When the event is raised, data and child controls are both available for the new item.
OnItemDataBound - raised each time an item just completes databinding. When the event is raised, data and child controls are both available for the item, and the item has finished databindings of itself and all its child controls.
OnItemCommand - raised when a child control of some item (such as a TButton) raises an OnCommand event.
command events - raised when a child control's OnCommand event has a specific command name,
- OnSelectedIndexChanged - if the command name is select.
- OnEditCommand - if the command name is edit.
- OnDeleteCommand - if the command name is delete.
- OnUpdateCommand - if the command name is update.
- OnCancelCommand - if the command name is cancel.
- OnSortCommand - if the command name is sort.
- OnPageIndexChanged - if the command name is page.

Using TDataGrid

Automatically Generated Columns

TDataGrid by default will create a list of columns based on the structure of the bound data. TDataGrid will read the first row of the data, extract the field names of the row, and construct a column for each field. Each column is of type TBoundColumn.

The following example displays a list of computer product information using a TDataGrid. Columns are automatically generated. Pay attention to how item styles are specified and inherited. The data are populated into the datagrid using the follow code, which is common among most datagrid applications,

public function onLoad($param) { parent::onLoad($param); if(!$this->IsPostBack) { $this->DataGrid->DataSource=$this->Data; $this->DataGrid->dataBind(); } }

Manually Specified Columns

Using automatically generated columns gives a quick way of browsing tabular data. In real applications, however, automatically generated columns are often not sufficient because developers have no way customizing their appearance. Manually specified columns are thus more desirable.

To manually specify columns, set AutoGenerateColumns to false, and specify the columns in a template like the following,

<com:TDataGrid ...> <com:TBoundColumn DataField="name" .../> <com:TBoundColumn DataField="price" .../> <com:TEditCommandColumn ...> ... </com:TDataGrid>

Note, if AutoGenerateColumns is true and there are manually specified columns, the automatically generated columns will be appended to the manually specified columns. Also note, the datagrid's Columns property contains only manually specified columns and no automatically generated ones.

The following example uses manually specified columns to show a list of book information,

Book title - displayed as a hyperlink pointing to the corresponding amazon.com book page. THyperLinkColumn is used.
Publisher - displayed as a piece of text using TBoundColumn.
Price - displayed as a piece of text using TBoundColumn with output formatting string and customized styles.
In-stock or not - displayed as a checkbox using TCheckBoxColumn.
Rating - displayed as an image using TTemplateColumn which allows maximum freedom in specifiying cell contents.

Pay attention to how item (row) styles and column styles cooperate together to affect the appearance of the cells in the datagrid.