## Class TDataGridColumn

Description

TDataGridColumn class

TDataGridColumn serves as the base class for the different column types of the TDataGrid control. TDataGridColumn defines the properties and methods that are common among all datagrid column types. In particular, it initializes header and footer cells according to HeaderText and HeaderStyle FooterText and FooterStyle properties. If HeaderImageUrl is specified, the image will be displayed instead in the header cell. The ItemStyle is applied to cells that belong to non-header and -footer datagrid items.

When the datagrid enables sorting, if the SortExpression is not empty, the header cell will display a button (linkbutton or imagebutton) that will bubble the sort command event to the datagrid.

Since v3.1.0, TDataGridColumn has introduced two new properties HeaderRenderer and FooterRenderer which can be used to specify the layout of header and footer column cells. A renderer refers to a control class that is to be instantiated as a control. For more details, see TRepeater and TDataList.

Since v3.1.1, TDataGridColumn has introduced EnableCellGrouping. If a column has this property set true, consecutive cells having the same content in this column will be grouped into one cell. Note, there are some limitations to cell grouping. We determine the cell content according to the cell's TTableCell::getText property. If the text is empty and the cell has some child controls, we will pick up the first control who implements IDataRenderer and obtain its IDataRenderer::getData property.

The following datagrid column types are provided by the framework currently,

- TBoundColumn, associated with a specific field in datasource and displays the corresponding data.
- TEditCommandColumn, displaying edit/update/cancel command buttons
- TDropDownListColumn, displaying a dropdown list when the item is in edit state
- TButtonColumn, displaying generic command buttons that may be bound to specific field in datasource.
- 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.

To create your own column class, simply override initializeCell() method, which is the major logic for managing the data and presentation of cells in the column.

- abstract:
- since: 3.0
- version: $Id: TDataGridColumn.php 2756 2010-01-14 13:12:27Z Christophe.Boulain $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TDataGridColumn.php (line 65)

    TComponent
       |
       --TApplicationComponent
          |
          --TDataGridColumn

Direct descendents

Class | Description
--- | ---
TBoundColumn | TBoundColumn class
TButtonColumn | TButtonColumn class
TCheckBoxColumn | TCheckBoxColumn class
TDropDownListColumn | TDropDownListColumn class
TEditCommandColumn | TEditCommandColumn class
THyperLinkColumn | THyperLinkColumn class
TLiteralColumn | TLiteralColumn class
TTemplateColumn | TTemplateColumn class

Method Summary
string formatDataValue (string $formatString, mixed $value)
boolean getAllowSorting ()
mixed getDataFieldValue (mixed $data, string $field)
boolean getEnableCellGrouping ()
string getFooterRenderer ()
TTableItemStyle getFooterStyle ([boolean $createStyle = true])
string getFooterText ()
string getHeaderImageUrl ()
string getHeaderRenderer ()
TTableItemStyle getHeaderStyle ([boolean $createStyle = true])
string getHeaderText ()
string getID ()
TTableItemStyle getItemStyle ([boolean $createStyle = true])
TDataGrid getOwner ()
string getSortExpression ()
mixed getViewState (string $key, [mixed $defaultValue = null])
boolean getVisible ([mixed $checkParents = true])
void initialize ()
void initializeCell (TTableCell $cell, integer $columnIndex, string $itemType)
void initializeFooterCell (TTableCell $cell, integer $columnIndex)
void initializeHeaderCell (TTableCell $cell, integer $columnIndex)
void loadState (mixed $state)
mixed saveState ()
void setEnableCellGrouping (boolean $value)
void setFooterRenderer (string $value)
void setFooterText (string $value)
void setHeaderImageUrl (string $value)
void setHeaderRenderer (string $value)
void setHeaderText (string $value)
void setID (string $value)
void setOwner (TDataGrid $value)
void setSortExpression (string $value)
void setViewState (string $key, mixed $value, [mixed $defaultValue = null])
void setVisible (boolean $value)
Methods
formatDataValue (line 522)

Formats the text value according to a format string.

If the format string is empty, the original value is converted into a string and returned. If the format string starts with '#', the string is treated as a PHP expression within which the token '{0}' is translated with the data value to be formated. Otherwise, the format string and the data value are passed as the first and second parameters in http://www.php.net/sprintf.

- return: the formatted result
- access: protected

string formatDataValue (string $formatString, mixed $value)

- string $formatString: format string
- mixed $value: the data to be formatted

getAllowSorting (line 395)

Returns a value indicating whether this column allows sorting.

The column allows sorting only when SortExpression is not empty and the datagrid allows sorting.

- return: whether this column allows sorting
- access: public

boolean getAllowSorting ()
getDataFieldValue (line 364)

Fetches the value of the data at the specified field.

If the data is an array, the field is used as an array key. If the data is an of TMap, TList or their derived class, the field is used as a key value. If the data is a component, the field is used as the name of a property.

- return: data value at the specified field
- access: protected
- throws: TInvalidDataValueException if the data or the field is invalid.

mixed getDataFieldValue (mixed $data, string $field)

- mixed $data: data containing the field of value
- string $field: the data field

getEnableCellGrouping (line 251)

- return: whether cells having the same content should be grouped together. Defaults to false.
- access: public
- since: 3.1.1

boolean getEnableCellGrouping ()
getFooterRenderer (line 183)

- return: the class name for the column footer cell renderer. Defaults to empty, meaning not set.
- access: public
- since: 3.1.0

string getFooterRenderer ()
getFooterStyle (line 207)

- return: the style for footer
- access: public

TTableItemStyle getFooterStyle ([boolean $createStyle = true])

- boolean $createStyle: whether to create a style if previously not existing

getFooterText (line 166)

- return: the text to be displayed in the footer of this column
- access: public

string getFooterText ()
getHeaderImageUrl (line 112)

- return: the url of the image to be displayed in header
- access: public

string getHeaderImageUrl ()
getHeaderRenderer (line 129)

- return: the class name for the column header cell renderer. Defaults to empty, meaning not set.
- access: public
- since: 3.1.0

string getHeaderRenderer ()
getHeaderStyle (line 153)

- return: the style for header
- access: public

TTableItemStyle getHeaderStyle ([boolean $createStyle = true])

- boolean $createStyle: whether to create a style if previously not existing

getHeaderText (line 96)

- return: the text to be displayed in the header of this column
- access: public

string getHeaderText ()
getID (line 74)

- return: the ID of the column.
- access: public

string getID ()
getItemStyle (line 221)

- return: the style for item
- access: public

TTableItemStyle getItemStyle ([boolean $createStyle = true])

- boolean $createStyle: whether to create a style if previously not existing

getOwner (line 330)

- return: datagrid that owns this column
- access: public

TDataGrid getOwner ()
getSortExpression (line 234)

- return: the name of the field or expression for sorting
- access: public

string getSortExpression ()
getViewState (line 288)

Returns a viewstate value.

- return: the viewstate value corresponding to $key
- access: protected

mixed getViewState (string $key, [mixed $defaultValue = null])

- string $key: the name of the viewstate value to be returned
- mixed $defaultValue: the default value. If $key is not found in viewstate, $defaultValue will be returned

getVisible (line 268)

- return: whether the column is visible. Defaults to true.
- access: public

boolean getVisible ([mixed $checkParents = true])
initialize (line 349)

Initializes the column.

This method is invoked by TDataGrid when the column is about to be used to initialize datagrid items. Derived classes may override this method to do additional initialization.

- access: public

void initialize ()
initializeCell (line 381)

Initializes the specified cell to its initial values.

The default implementation sets the content of header and footer cells. If sorting is enabled by the grid and sort expression is specified in the column, the header cell will show a link/image button. Otherwise, the header/footer cell will only show static text/image. This method can be overriden to provide customized intialization to column cells.

- access: public

void initializeCell (TTableCell $cell, integer $columnIndex, string $itemType)

- TTableCell $cell: the cell to be initialized.
- integer $columnIndex: the index to the Columns property that the cell resides in.
- string $itemType: the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)

Redefined in descendants as:

- TBoundColumn::initializeCell() : Initializes the specified cell to its initial values.
- TButtonColumn::initializeCell() : Initializes the specified cell to its initial values.
- TCheckBoxColumn::initializeCell() : Initializes the specified cell to its initial values.
- TDropDownListColumn::initializeCell() : Initializes the specified cell to its initial values.
- TEditCommandColumn::initializeCell() : Initializes the specified cell to its initial values.
- THyperLinkColumn::initializeCell() : Initializes the specified cell to its initial values.
- TLiteralColumn::initializeCell() : Initializes the specified cell to its initial values.
- TTemplateColumn::initializeCell() : Initializes the specified cell to its initial values.

initializeFooterCell (line 486)

Initializes the footer cell.

This method attempts to use FooterRenderer to instantiate the footer cell. If that is not available, it will populate the cell with a text string specified by getFooterImageUrl

- access: protected

void initializeFooterCell (TTableCell $cell, integer $columnIndex)

- TTableCell $cell: the cell to be initialized
- integer $columnIndex: the index to the Columns property that the cell resides in.

initializeHeaderCell (line 414)

Initializes the header cell.

This method attempts to use HeaderRenderer to instantiate the header cell. If that is not available, it will populate the cell with an image or a text string, depending on HeaderImageUrl and HeaderText property values.

If the column allows sorting, image or text will be created as a button which issues Sort command upon user click.

- access: protected

void initializeHeaderCell (TTableCell $cell, integer $columnIndex)

- TTableCell $cell: the cell to be initialized
- integer $columnIndex: the index to the Columns property that the cell resides in.

loadState (line 313)

Loads persistent state values.

- access: public

void loadState (mixed $state)

- mixed $state: state values

Redefined in descendants as:

- TDropDownListColumn::loadState() : Loads items from viewstate.

saveState (line 322)

Saves persistent state values.

- return: values to be saved
- access: public

mixed saveState ()

Redefined in descendants as:

- TDropDownListColumn::saveState() : Saves items into viewstate.

setEnableCellGrouping (line 260)

- access: public
- since: 3.1.1

void setEnableCellGrouping (boolean $value)

- boolean $value: whether cells having the same content should be grouped together.

setFooterRenderer (line 198)

Sets the column footer cell renderer class.

If not empty, the class will be used to instantiate as a child control in the column footer cell. If the class implements IDataRenderer, the Data property will be set as the FooterText.

- access: public
- since: 3.1.0

void setFooterRenderer (string $value)

- string $value: the renderer class name in namespace format.

setFooterText (line 174)

- access: public

void setFooterText (string $value)

- string $value: text to be displayed in the footer of this column

setHeaderImageUrl (line 120)

- access: public

void setHeaderImageUrl (string $value)

- string $value: the url of the image to be displayed in header

setHeaderRenderer (line 144)

Sets the column header cell renderer class.

If not empty, the class will be used to instantiate as a child control in the column header cell. If the class implements IDataRenderer, the Data property will be set as the FooterText.

- access: public
- since: 3.1.0

void setHeaderRenderer (string $value)

- string $value: the renderer class name in namespace format.

setHeaderText (line 104)

- access: public

void setHeaderText (string $value)

- string $value: text to be displayed in the header of this column

setID (line 86)

Sets the ID of the column.

By explicitly specifying the column ID, one can access the column by $templateControl->ColumnID.

- access: public
- throws: TInvalidDataValueException if the ID is of bad format

void setID (string $value)

- string $value: the ID of the column.

setOwner (line 338)

- access: public

void setOwner (TDataGrid $value)

- TDataGrid $value: datagrid object that owns this column

setSortExpression (line 242)

- access: public

void setSortExpression (string $value)

- string $value: the name of the field or expression for sorting

setViewState (line 301)

Sets a viewstate value.

Make sure that the viewstate value must be serializable and unserializable.

- access: protected

void setViewState (string $key, mixed $value, [mixed $defaultValue = null])

- string $key: the name of the viewstate value
- mixed $value: the viewstate value to be set
- mixed $defaultValue: default value. If $value===$defaultValue, the item will be cleared from the viewstate.

setVisible (line 276)

- access: public

void setVisible (boolean $value)

- boolean $value: whether the column is visible

#### Inherited Methods

Inherited From TApplicationComponent

> TApplicationComponent::getApplication()
> TApplicationComponent::getRequest()
> TApplicationComponent::getResponse()
> TApplicationComponent::getService()
> TApplicationComponent::getSession()
> TApplicationComponent::getUser()
> TApplicationComponent::publishAsset()
> TApplicationComponent::publishFilePath()

Inherited From TComponent

> TComponent::addParsedObject()
> TComponent::attachEventHandler()
> TComponent::canGetProperty()
> TComponent::canSetProperty()
> TComponent::createdOnTemplate()
> TComponent::detachEventHandler()
> TComponent::evaluateExpression()
> TComponent::evaluateStatements()
> TComponent::getEventHandlers()
> TComponent::getSubProperty()
> TComponent::hasEvent()
> TComponent::hasEventHandler()
> TComponent::hasProperty()
> TComponent::raiseEvent()
> TComponent::setSubProperty()
> TComponent::__get()
> TComponent::__set()

Documentation generated on Mon, 22 Feb 2010 12:17:24 +0000 by phpDocumentor 1.3.0RC4