TDataGridColumn serves as the base class for the different column types of
the {@link 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 {@link setHeaderText HeaderText} and {@link getHeaderStyle HeaderStyle}
{@link setFooterText FooterText} and {@link getFooterStyle FooterStyle} properties.
If {@link setHeaderImageUrl HeaderImageUrl} is specified, the image
will be displayed instead in the header cell.
The {@link getItemStyle ItemStyle} is applied to cells that belong to
non-header and -footer datagrid items.
When the datagrid enables sorting, if the {@link setSortExpression 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 {@link setHeaderRenderer HeaderRenderer}
and {@link setFooterRenderer 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 {@link TRepeater} and {@link TDataList}.
Since v3.1.1, TDataGridColumn has introduced {@link setEnableCellGrouping 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 {@link TTableCell::getText Text} property. If the text is empty and the cell has
some child controls, we will pick up the first control who implements {@link \Prado\IDataRenderer}
and obtain its {@link \Prado\IDataRenderer::getData Data} property.
The following datagrid column types are provided by the framework currently,
- {@link TBoundColumn}, associated with a specific field in datasource and displays the corresponding data.
- {@link TEditCommandColumn}, displaying edit/update/cancel command buttons
- {@link TDropDownListColumn}, displaying a dropdown list when the item is in edit state
- {@link TButtonColumn}, displaying generic command buttons that may be bound to specific field in datasource.
- {@link THyperLinkColumn}, displaying a hyperlink that may be bound to specific field in datasource.
- {@link TCheckBoxColumn}, displaying a checkbox that may be bound to specific field in datasource.
- {@link TTemplateColumn}, displaying content based on templates.
To create your own column class, simply override {@link initializeCell()} method,
which is the major logic for managing the data and presentation of cells in the column.
/**
* Initializes the specified cell to its initial values.
* This method overrides the parent implementation.
* It creates a textbox for item in edit mode and the column is not read-only.
* Otherwise it displays a static text.
* The caption of the button and the static text are retrieved
* from the datasource.
* @param TTableCell the cell to be initialized.
* @param integer the index to the Columns property that the cell resides in.
* @param string the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)
*/
public function initializeCell($cell, $columnIndex, $itemType)
{
if (!$this->_dataBound && $this->_listControl->getDataSource() !== null) {
$this->_listControl->setDataTextField($this->getListTextField());
$this->_listControl->setDataValueField($this->getListValueField());
$this->_listControl->setDataTextFormatString($this->getListTextFormatString());
$this->_listControl->dataBind();
$this->_dataBound = true;
}
switch ($itemType) {
case TListItemType::EditItem:
if (!$this->getReadOnly()) {
$listControl = clone $this->_listControl;
$cell->getControls()->add($listControl);
$cell->registerObject('DropDownList', $listControl);
$control = $listControl;
} else {
$control = $cell;
}
$control->attachEventHandler('OnDataBinding', array($this, 'dataBindColumn'));
break;
case TListItemType::Item:
case TListItemType::AlternatingItem:
case TListItemType::SelectedItem:
if ($this->getDataTextField() !== '' || $this->getDataValueField() !== '') {
$cell->attachEventHandler('OnDataBinding', array($this, 'dataBindColumn'));
}
break;
default:
parent::initializeCell($cell, $columnIndex, $itemType);
break;
}
}
/**
* Initializes the specified cell to its initial values.
* This method overrides the parent implementation.
* It creates a textbox for item in edit mode and the column is not read-only.
* Otherwise it displays a static text.
* The caption of the button and the static text are retrieved
* from the datasource.
* @param TTableCell the cell to be initialized.
* @param integer the index to the Columns property that the cell resides in.
* @param string the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)
*/
public function initializeCell($cell, $columnIndex, $itemType)
{
$item = $cell->getParent();
switch ($itemType) {
case TListItemType::Item:
case TListItemType::AlternatingItem:
case TListItemType::SelectedItem:
if (($classPath = $this->getItemRenderer()) !== '') {
$control = Prado::createComponent($classPath);
if ($control instanceof IItemDataRenderer) {
$control->setItemIndex($item->getItemIndex());
$control->setItemType($item->getItemType());
}
$cell->getControls()->add($control);
} else {
$control = $cell;
}
$control->attachEventHandler('OnDataBinding', array($this, 'dataBindColumn'));
break;
case TListItemType::EditItem:
if (!$this->getReadOnly()) {
if (($classPath = $this->getEditItemRenderer()) !== '') {
$control = Prado::createComponent($classPath);
if ($control instanceof IItemDataRenderer) {
$control->setItemIndex($item->getItemIndex());
$control->setItemType($item->getItemType());
}
$cell->getControls()->add($control);
$cell->registerObject('EditControl', $control);
} else {
$control = new TTextBox();
$cell->getControls()->add($control);
$cell->registerObject('TextBox', $control);
}
} else {
if (($classPath = $this->getItemRenderer()) !== '') {
$control = Prado::createComponent($classPath);
if ($control instanceof IItemDataRenderer) {
$control->setItemIndex($item->getItemIndex());
$control->setItemType($item->getItemType());
}
$cell->getControls()->add($control);
} else {
$control = $cell;
}
}
$control->attachEventHandler('OnDataBinding', array($this, 'dataBindColumn'));
break;
default:
parent::initializeCell($cell, $columnIndex, $itemType);
break;
}
}
/**
* Initializes the specified cell to its initial values.
* This method overrides the parent implementation.
* It creates a command button within the cell.
* @param TTableCell the cell to be initialized.
* @param integer the index to the Columns property that the cell resides in.
* @param string the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)
*/
public function initializeCell($cell, $columnIndex, $itemType)
{
if ($itemType === TListItemType::Item || $itemType === TListItemType::AlternatingItem || $itemType === TListItemType::SelectedItem || $itemType === TListItemType::EditItem) {
$buttonType = $this->getButtonType();
if ($buttonType === TButtonColumnType::LinkButton) {
$button = new TLinkButton();
} else {
if ($buttonType === TButtonColumnType::PushButton) {
$button = new TButton();
} else {
$button = new TImageButton();
$button->setImageUrl($this->getImageUrl());
$button->setToolTip($this->getText());
}
}
$button->setText($this->getText());
$button->setCommandName($this->getCommandName());
$button->setCausesValidation($this->getCausesValidation());
$button->setValidationGroup($this->getValidationGroup());
if ($this->getDataTextField() !== '' || $buttonType === TButtonColumnType::ImageButton && $this->getDataImageUrlField() !== '') {
$button->attachEventHandler('OnDataBinding', array($this, 'dataBindColumn'));
}
$cell->getControls()->add($button);
$cell->registerObject('Button', $button);
} else {
parent::initializeCell($cell, $columnIndex, $itemType);
}
}
/**
* Initializes the specified cell to its initial values.
* This method overrides the parent implementation.
* It creates a checkbox inside the cell.
* If the column is read-only or if the item is not in edit mode,
* the checkbox will be set disabled.
* @param TTableCell the cell to be initialized.
* @param integer the index to the Columns property that the cell resides in.
* @param string the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)
*/
public function initializeCell($cell, $columnIndex, $itemType)
{
if ($itemType === TListItemType::Item || $itemType === TListItemType::AlternatingItem || $itemType === TListItemType::SelectedItem || $itemType === TListItemType::EditItem) {
$checkBox = new TCheckBox();
if ($this->getReadOnly() || $itemType !== TListItemType::EditItem) {
$checkBox->setEnabled(false);
}
$cell->setHorizontalAlign('Center');
$cell->getControls()->add($checkBox);
$cell->registerObject('CheckBox', $checkBox);
if ($this->getDataField() !== '') {
$checkBox->attachEventHandler('OnDataBinding', array($this, 'dataBindColumn'));
}
} else {
parent::initializeCell($cell, $columnIndex, $itemType);
}
}
/**
* Initializes the specified cell to its initial values.
* This method overrides the parent implementation.
* @param TTableCell the cell to be initialized.
* @param integer the index to the Columns property that the cell resides in.
* @param string the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)
*/
public function initializeCell($cell, $columnIndex, $itemType)
{
if ($itemType === TListItemType::Item || $itemType === TListItemType::AlternatingItem || $itemType === TListItemType::EditItem || $itemType === TListItemType::SelectedItem) {
if ($this->getDataField() !== '') {
$cell->attachEventHandler('OnDataBinding', array($this, 'dataBindColumn'));
} else {
$text = $this->getText();
if ($this->getEncode()) {
$text = THttpUtility::htmlEncode($text);
}
$cell->setText($text);
}
} else {
parent::initializeCell($cell, $columnIndex, $itemType);
}
}
/**
* Initializes the specified cell to its initial values.
* This method overrides the parent implementation.
* It creates an update and a cancel button for cell in edit mode.
* Otherwise it creates an edit button.
* @param TTableCell the cell to be initialized.
* @param integer the index to the Columns property that the cell resides in.
* @param string the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)
*/
public function initializeCell($cell, $columnIndex, $itemType)
{
if ($itemType === TListItemType::Item || $itemType === TListItemType::AlternatingItem || $itemType === TListItemType::SelectedItem) {
$button = $this->createButton('Edit', $this->getEditText(), false, '');
$cell->getControls()->add($button);
$cell->registerObject('EditButton', $button);
} else {
if ($itemType === TListItemType::EditItem) {
$controls = $cell->getControls();
$button = $this->createButton('Update', $this->getUpdateText(), $this->getCausesValidation(), $this->getValidationGroup());
$controls->add($button);
$cell->registerObject('UpdateButton', $button);
$controls->add(' ');
$button = $this->createButton('Cancel', $this->getCancelText(), false, '');
$controls->add($button);
$cell->registerObject('CancelButton', $button);
} else {
parent::initializeCell($cell, $columnIndex, $itemType);
}
}
}
