Class TDataGrid
TDataGrid class
TDataGrid represents a data bound and updatable grid control.
To populate data into the datagrid, sets its setDataSource DataSource
to a tabular data source and call TDataBoundControl::dataBind()
. Each row of data will be
represented by an item in the getItems 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 setEditItemIndex EditItemIndex or setSelectedItemIndex SelectedItemIndex property.
Each datagrid item has a TDataGridItem::getItemType type 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 buttonsTButtonColumn
, displaying generic command buttons that may be bound to specific field in datasource.TDropDownListColumn
, displaying a dropdown list when the item is in edit stateTHyperLinkColumn
, 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 setAutoGenerateColumns 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 Columns property of the datagrid. For example,
$column=new TBoundColumn; $datagrid->Columns[]=$column;
TDataGrid supports sorting. If the setAllowSorting AllowSorting is set to true, a column with nonempty setSortExpression SortExpression will have its header text displayed as a clickable link button. Clicking on the link button will raise onSortCommand 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 setAllowPaging 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 getPagerStyle PagerStyle property. Clicking on a pager button will raise an onPageIndexChanged OnPageIndexChanged event. You can respond to this event, specify the page to be displayed by setting setCurrentPageIndex CurrentPageIndex 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 getPageCount PageCount is calculated based the item number and the setPageSize PageSize property. The datagrid will manage which section of the data source to be displayed based on the setCurrentPageIndex CurrentPageIndex property. The second approach calculates the page number based on the setVirtualItemCount VirtualItemCount property and the setPageSize PageSize property. The datagrid will always display from the beginning of the datasource up to the number of setPageSize 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 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
Note, an onItemCommand OnItemCommand event is raised in addition to the above specific command events.
TDataGrid also raises an onItemCreated 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 OnItemDataBound event
- Use getDataKeys DataKeys to obtain the data key associated with
the specified datagrid row and use the key to fetch the corresponding data from some persistent storage such as DB.
- Save the data in viewstate and get it back during postbacks.
- TComponent
-
TApplicationComponent
-
TControl implements IRenderable, IBindable
-
TWebControl implements IStyleable
-
TDataBoundControl
-
TBaseDataList
-
TDataGrid implements INamingContainer
Direct known subclasses
TActiveDataGridCopyright: Copyright © 2005-2014 PradoSoft
License: http://www.pradosoft.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 3.0
Located at Web/UI/WebControls/TDataGrid.php
protected
string
|
|
protected
string
|
|
public
|
#
addParsedObject( mixed $object )
Adds objects parsed in template to datagrid. Datagrid columns are added into getColumns Columns collection. |
public
|
|
public
|
|
public
|
|
public
integer
|
|
protected
|
#
createStyle( )
Creates a style object for the control. This method creates a |
public
string
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
string
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
integer
|
|
public
|
#
setSelectedItemIndex( integer $value )
Selects an item by its index in getItems Items. Previously selected item will be un-selected. If the item to be selected is already in edit mode, it will remain in edit mode. If the index is less than 0, any existing selection will be cleared up. |
public
|
|
public
integer
|
|
public
|
#
setEditItemIndex( integer $value )
Edits an item by its index in getItems Items. Previously editting item will change to normal item state. If the index is less than 0, any existing edit item will be cleared up. |
public
boolean
|
|
public
|
|
public
boolean
|
|
public
|
|
public
boolean
|
|
public
|
|
public
boolean
|
|
public
|
|
public
|
|
public
|
|
public
boolean
|
#
bubbleEvent(
This method overrides parent's implementation to handle onItemCommand
OnItemCommand event which is bubbled from |
public
|
#
onCancelCommand(
Raises OnCancelCommand event. This method is invoked when a button control raises OnCommand event with cancel command name. |
public
|
#
onDeleteCommand(
Raises OnDeleteCommand event. This method is invoked when a button control raises OnCommand event with delete command name. |
public
|
#
onEditCommand(
Raises OnEditCommand event. This method is invoked when a button control raises OnCommand event with edit command name. |
public
|
#
onItemCommand(
Raises OnItemCommand event. This method is invoked when a button control raises OnCommand event. |
public
|
#
onSortCommand(
Raises OnSortCommand event. This method is invoked when a button control raises OnCommand event with sort command name. |
public
|
#
onUpdateCommand(
Raises OnUpdateCommand event. This method is invoked when a button control raises OnCommand event with update command name. |
public
|
#
onItemCreated(
Raises OnItemCreated event. This method is invoked right after a datagrid item is created and before added to page hierarchy. |
public
|
#
onPagerCreated(
Raises OnPagerCreated event. This method is invoked right after a datagrid pager is created and before added to page hierarchy. |
public
|
#
onItemDataBound(
Raises OnItemDataBound event. This method is invoked for each datagrid item after it performs databinding. |
public
|
#
onPageIndexChanged(
Raises OnPageIndexChanged event. This method is invoked when current page is changed. |
public
|
#
saveState( )
Saves item count in viewstate. This method is invoked right before control state is to be saved. |
public
|
#
loadState( )
Loads item count information from viewstate. This method is invoked right after control state is loaded. |
public
|
|
protected
|
|
protected
|
#
performDataBinding( Traversable $data )
Performs databinding to populate datagrid items from data source. This method
is invoked by |
protected
|
#
createItem( integer $itemIndex,
Creates a datagrid item instance based on the item type and index. |
protected
|
#
initializeItem(
Initializes a datagrid item and cells inside it |
protected
|
|
protected
|
|
protected
mixed
|
#
createPagerButton( mixed $pager, string $buttonType, boolean $enabled, string $text, string $commandName, string $commandParameter )
Creates a pager button. Depending on the button type, a TLinkButton or a TButton may be created. If it is enabled (clickable), its command name and parameter will also be set. Derived classes may override this method to create additional types of buttons, such as TImageButton. |
protected
|
|
protected
|
|
protected
|
#
createAutoColumns( Traversable $dataSource )
Automatically generates datagrid columns based on datasource schema |
protected
|
#
applyItemStyles( )
Applies styles to items, header, footer and separators. Item styles are applied in a hierarchical way. Style in higher hierarchy will inherit from styles in lower hierarchy. Starting from the lowest hierarchy, the item styles include item's own style, getItemStyle ItemStyle, getAlternatingItemStyle AlternatingItemStyle, getSelectedItemStyle SelectedItemStyle, and getEditItemStyle EditItemStyle. Therefore, if background color is set as red in getItemStyle ItemStyle, getEditItemStyle EditItemStyle will also have red background color unless it is set to a different value explicitly. |
public
|
#
renderBeginTag(
Renders the openning tag for the datagrid control which will render table caption if present. |
public
|
|
protected
|
getApplication(),
getRequest(),
getResponse(),
getService(),
getSession(),
getUser(),
publishAsset(),
publishFilePath()
|
string |
IT_HEADER |
'Header' |
#
datagrid item types |
string |
IT_FOOTER |
'Footer' |
|
string |
IT_ITEM |
'Item' |
|
string |
IT_SEPARATOR |
'Separator' |
|
string |
IT_ALTERNATINGITEM |
'AlternatingItem' |
|
string |
IT_EDITITEM |
'EditItem' |
|
string |
IT_SELECTEDITEM |
'SelectedItem' |
|
string |
IT_PAGER |
'Pager' |
|
string |
CMD_SELECT |
'Select' |
#
Command name that TDataGrid understands. |
string |
CMD_EDIT |
'Edit' |
|
string |
CMD_UPDATE |
'Update' |
|
string |
CMD_DELETE |
'Delete' |
|
string |
CMD_CANCEL |
'Cancel' |
|
string |
CMD_SORT |
'Sort' |
|
string |
CMD_PAGE |
'Page' |
|
string |
CMD_PAGE_NEXT |
'Next' |
|
string |
CMD_PAGE_PREV |
'Previous' |
|
string |
CMD_PAGE_FIRST |
'First' |
|
string |
CMD_PAGE_LAST |
'Last' |
GLOBAL_RAISE_EVENT_LISTENER
|
$_decorator
|