Completed TDataGrid documentation.

9 files changed, 412 insertions, 214 deletions

diff --git a/framework/Exceptions/messages.txt b/framework/Exceptions/messages.txt
index 8b739623..b4a91adb 100644
--- a/framework/Exceptions/messages.txt
+++ b/framework/Exceptions/messages.txt
@@ -195,6 +195,14 @@ repeater_template_required				= TRepeater.%s requires a template instance implem
 datalist_template_required				= TDataList.%s requires a template instance implementing ITemplate interface.

 templatecolumn_template_required		= TTemplateColumn.%s requires a template instance implementing ITemplate interface.

 

+datagrid_currentpageindex_invalid		= TDataGrid.CurrentPageIndex must be no less than 0.

+datagrid_pagesize_invalid				= TDataGrid.PageSize must be greater than 0.

+datagrid_virtualitemcount_invalid		= TDataGrid.VirtualItemCount must be no less than 0.

+

+datagridpagerstyle_pagebuttoncount_invalid = TDataGridPagerStyle.PageButtonCount must be greater than 0.

+

+datagridcolumn_data_invalid				= %s is unable to evaluate the value of data field %s. The data must be an array, TList, TMap, or component that contains the field.

+

 repeateritemcollection_repeateritem_required = TRepeaterItemCollection can only accept TRepeaterItem objects.

 

 datagriditemcollection_datagriditem_required = TDataGridItemCollection can only accept TDataGridItem objects.

diff --git a/framework/Web/UI/WebControls/TBoundColumn.php b/framework/Web/UI/WebControls/TBoundColumn.php
index 6ad578d7..f5b5517c 100644
--- a/framework/Web/UI/WebControls/TBoundColumn.php
+++ b/framework/Web/UI/WebControls/TBoundColumn.php
@@ -20,9 +20,10 @@ Prado::using('System.Web.UI.WebControls.TDataGridColumn');
  *

  * TBoundColumn represents a column that is bound to a field in a data source.

  * The cells in the column will be displayed using the data indexed by

- * <b>DataField</b>. You can customize the display by setting <b>DataFormatString</b>.

+ * {@link setDataField DataField}. You can customize the display by

+ * setting {@link setDataFormatString DataFormatString}.

  *

- * If <b>ReadOnly</b> is false, TBoundColumn will display cells in edit mode

+ * If {@link setReadOnly ReadOnly} is false, TBoundColumn will display cells in edit mode

  * with textboxes. Otherwise, a static text is displayed.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

@@ -46,7 +47,6 @@ class TBoundColumn extends TDataGridColumn
 	public function setDataField($value)

 	{

 		$this->setViewState('DataField',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -63,7 +63,6 @@ class TBoundColumn extends TDataGridColumn
 	public function setDataFormatString($value)

 	{

 		$this->setViewState('DataFormatString',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -80,7 +79,6 @@ class TBoundColumn extends TDataGridColumn
 	public function setReadOnly($value)

 	{

 		$this->setViewState('ReadOnly',TPropertyValue::ensureBoolean($value),false);

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -119,6 +117,11 @@ class TBoundColumn extends TDataGridColumn
 		}

 	}

 

+	/**

+	 * Databinds a cell in the column.

+	 * This method is invoked when datagrid performs databinding.

+	 * It populates the content of the cell with the relevant data from data source.

+	 */

 	public function dataBindColumn($sender,$param)

 	{

 		$item=$sender->getNamingContainer();

diff --git a/framework/Web/UI/WebControls/TButtonColumn.php b/framework/Web/UI/WebControls/TButtonColumn.php
index 4555aa24..dc506b0a 100644
--- a/framework/Web/UI/WebControls/TButtonColumn.php
+++ b/framework/Web/UI/WebControls/TButtonColumn.php
@@ -21,20 +21,20 @@ Prado::using('System.Web.UI.WebControls.TDataGridColumn');
  * TButtonColumn contains a user-defined command button, such as Add or Remove,

  * that corresponds with each row in the column.

  *

- * The caption of the buttons in the column is determined by <b>Text</b>

- * and <b>DataTextField</b> properties. If both are present, the latter takes

- * precedence. The <b>DataTextField</b> refers to the name of the field in datasource

- * whose value will be used as the button caption. If <b>DataTextFormatString</b>

- * is not empty, the value will be formatted before rendering.

+ * The caption of the buttons in the column is determined by {@link setText Text}

+ * and {@link setDataTextField DataTextField} properties. If both are present,

+ * the latter takes precedence. The {@link setDataTextField DataTextField} property

+ * refers to the name of the field in datasource whose value will be used as the button caption.

+ * If {@link setDataTextFormatString DataTextFormatString} is not empty,

+ * the value will be formatted before rendering.

  *

  * The buttons in the column can be set to display as hyperlinks or push buttons

- * by setting the <b>ButtonType</b> property.

- * The <b>CommandName</b> will assign its value to all button's <b>CommandName</b>

- * property. The datagrid will capture the command event where you can write event handlers

- * based on different command names.

- *

- * Note, the command buttons created in the column will not cause validation.

- * To enable validation, please use TTemplateColumn instead.

+ * by setting the {@link setButtonType ButtonType} property.

+ * The {@link setCommandName CommandName} will assign its value to

+ * all button's <b>CommandName</b> property. The datagrid will capture

+ * the command event where you can write event handlers based on different command names.

+ * The buttons' <b>CausesValidation</b> and <b>ValidationGroup</b> property values

+ * are determined by the column's corresponding properties.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -58,7 +58,6 @@ class TButtonColumn extends TDataGridColumn
 	public function setText($value)

 	{

 		$this->setViewState('Text',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -75,7 +74,6 @@ class TButtonColumn extends TDataGridColumn
 	public function setDataTextField($value)

 	{

 		$this->setViewState('DataTextField',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -92,7 +90,6 @@ class TButtonColumn extends TDataGridColumn
 	public function setDataTextFormatString($value)

 	{

 		$this->setViewState('DataTextFormatString',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -109,11 +106,10 @@ class TButtonColumn extends TDataGridColumn
 	public function setButtonType($value)

 	{

 		$this->setViewState('ButtonType',TPropertyValue::ensureEnum($value,'LinkButton','PushButton'),'LinkButton');

-		$this->onColumnChanged();

 	}

 

 	/**

-	 * @return string the command name associated with the <b>Command</b> event.

+	 * @return string the command name associated with the <b>OnCommand</b> event.

 	 */

 	public function getCommandName()

 	{

@@ -127,7 +123,6 @@ class TButtonColumn extends TDataGridColumn
 	public function setCommandName($value)

 	{

 		$this->setViewState('CommandName',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -144,7 +139,6 @@ class TButtonColumn extends TDataGridColumn
 	public function setCausesValidation($value)

 	{

 		$this->setViewState('CausesValidation',TPropertyValue::ensureBoolean($value),true);

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -161,7 +155,6 @@ class TButtonColumn extends TDataGridColumn
 	public function setValidationGroup($value)

 	{

 		$this->setViewState('ValidationGroup',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -191,6 +184,11 @@ class TButtonColumn extends TDataGridColumn
 		}

 	}

 

+	/**

+	 * Databinds a cell in the column.

+	 * This method is invoked when datagrid performs databinding.

+	 * It populates the content of the cell with the relevant data from data source.

+	 */

 	public function dataBindColumn($sender,$param)

 	{

 		if(($field=$this->getDataTextField())!=='')

diff --git a/framework/Web/UI/WebControls/TCheckBoxColumn.php b/framework/Web/UI/WebControls/TCheckBoxColumn.php
index 4f8c5ff3..4b13a171 100644
--- a/framework/Web/UI/WebControls/TCheckBoxColumn.php
+++ b/framework/Web/UI/WebControls/TCheckBoxColumn.php
@@ -18,12 +18,11 @@ Prado::using('System.Web.UI.WebControls.TDataGridColumn');
 /**

  * TCheckBoxColumn class

  *

- * TCheckBoxColumn represents a column that is bound to a field in a data source.

- * The cells in the column will be displayed using the data indexed by

- * <b>DataField</b>. You can customize the display by setting <b>DataFormatString</b>.

- *

- * If <b>ReadOnly</b> is false, TCheckBoxColumn will display cells in edit mode

- * with textboxes. Otherwise, a static text is displayed.

+ * TCheckBoxColumn represents a checkbox column that is bound to a field in a data source.

+ * The checked state of the checkboxes are determiend by the bound data at

+ * {@link setDataField DataField}. If {@link setReadOnly ReadOnly} is false,

+ * TCheckBoxColumn will display an enabled checkbox provided the cells are

+ * in edit mode. Otherwise, the checkboxes will be disabled to prevent from editting.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -46,7 +45,6 @@ class TCheckBoxColumn extends TDataGridColumn
 	public function setDataField($value)

 	{

 		$this->setViewState('DataField',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -63,16 +61,14 @@ class TCheckBoxColumn extends TDataGridColumn
 	public function setReadOnly($value)

 	{

 		$this->setViewState('ReadOnly',TPropertyValue::ensureBoolean($value),false);

-		$this->onColumnChanged();

 	}

 

 	/**

 	 * 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.

+	 * 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)

@@ -80,8 +76,7 @@ class TCheckBoxColumn extends TDataGridColumn
 	public function initializeCell($cell,$columnIndex,$itemType)

 	{

 		parent::initializeCell($cell,$columnIndex,$itemType);

-		if($itemType==='EditItem' || $itemType==='Item'

-				|| $itemType==='AlternatingItem' || $itemType==='SelectedItem')

+		if($itemType==='EditItem' || $itemType==='Item' || $itemType==='AlternatingItem' || $itemType==='SelectedItem')

 		{

 			$checkBox=Prado::createComponent('System.Web.UI.WebControls.TCheckBox');

 			if($this->getReadOnly() || $itemType!=='EditItem')

@@ -93,6 +88,11 @@ class TCheckBoxColumn extends TDataGridColumn
 		}

 	}

 

+	/**

+	 * Databinds a cell in the column.

+	 * This method is invoked when datagrid performs databinding.

+	 * It populates the content of the cell with the relevant data from data source.

+	 */

 	public function dataBindColumn($sender,$param)

 	{

 		$item=$sender->getNamingContainer();

diff --git a/framework/Web/UI/WebControls/TDataGrid.php b/framework/Web/UI/WebControls/TDataGrid.php
index 9cf467bf..4741b56e 100644
--- a/framework/Web/UI/WebControls/TDataGrid.php
+++ b/framework/Web/UI/WebControls/TDataGrid.php
@@ -1,6 +1,11 @@
 <?php

 /**

- * TDataGrid class file

+ * TDataGrid related class files.

+ * This file contains the definition of the following classes:

+ * TDataGrid, TDataGridItem, TDataGridItemCollection, TDataGridColumnCollection,

+ * TDataGridPagerStyle, TDataGridItemEventParameter,

+ * TDataGridCommandEventParameter, TDataGridSortCommandEventParameter,

+ * TDataGridPageChangedEventParameter

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @link http://www.pradosoft.com/

@@ -10,6 +15,9 @@
  * @package System.Web.UI.WebControls

  */

 

+/**

+ * Includes TBaseList, TPagedDataSource, TDummyDataSource and TTable classes

+ */

 Prado::using('System.Web.UI.WebControls.TBaseDataList');

 Prado::using('System.Collections.TPagedDataSource');

 Prado::using('System.Collections.TDummyDataSource');

@@ -20,30 +28,36 @@ Prado::using('System.Web.UI.WebControls.TTable');
  *

  * TDataGrid represents a data bound and updatable grid control.

  *

- * To use TDataGrid, sets its <b>DataSource</b> property and invokes dataBind()

- * afterwards. The data will be populated into the TDataGrid and saved in the <b>Items</b> property.

+ * To populate data into the datagrid, sets its {@link setDataSource DataSource}

+ * to a tabular data source and call {@link dataBind()}.

+ * Each row of data will be represented by an item in the {@link getItems Items}

+ * collection of the datagrid.

  *

- * Each item is associated with a row of data and will be displayed as a row in table.

- * A data item can be at one of three states: normal, selected and edit.

+ * 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 instead

- * static text as in normal state.

- * To change the state of a data item, set either the <b>EditItemIndex</b> property

- * or the <b>SelectedItemIndex</b> property.

+ * is in edit state, it may be displayed as a table row with input text boxes

+ * if the columns are of type {@link TBoundColumn}; and if in browsing state,

+ * they are displayed as static text.

+ *

+ * To change the state of an item, set {@link setEditItemIndex EditItemIndex}

+ * or {@link setSelectedItemIndex SelectedItemIndex} property.

  *

  * 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 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.

- * - THyperLinkColumn, displaying a hyperlink that may be boudn to specific field in datasource.

- * - TTemplateColumn, displaying content based on templates.

+ * the cells in that column, and so on. The following column types are currently

+ * provided by the framework,

+ * - {@link TBoundColumn}, associated with a specific field in datasource and displays the corresponding data.

+ * - {@link TEditCommandColumn}, displaying edit/update/cancel command buttons

+ * - {@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.

  *

  * There are three ways to specify columns for a datagrid.

  * <ul>

- *  <li>Automatically generated based on data source. By setting <b>AutoGenerateColumns</b>

- *  to true, a list of columns will be automatically generated based on the schema of the data source.

+ *  <li>Automatically generated based on data source.

+ *  By setting {@link 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.</li>

  *  <li>Specified in template. For example,

  *    <code>

@@ -53,53 +67,65 @@ Prado::using('System.Web.UI.WebControls.TTable');
  *     </com:TDataGrid>

  *    </code>

  *  </li>

- *  <li>Manually created in code. Columns can be manipulated via the <b>Columns</b> property of

- *  the datagrid. For example,

- *    <code>

- *    $column=$datagrid->createComponent('TBoundColumn');

- *    $datagrid->Columns->add($column);

- *    </code>

+ *  <li>Manually created in code. Columns can be manipulated via

+ *  the {@link setColumns Columns} property of the datagrid. For example,

+ *  <code>

+ *    $column=new TBoundColumn;

+ *    $datagrid->Columns[]=$column;

+ *  </code>

  *  </li>

  * </ul>

- * Note, automatically generated columns cannot be accessed via <b>Columns</b> property.

+ * Note, automatically generated columns cannot be accessed via

+ * the {@link getColumns Columns} property.

  *

- * TDataGrid supports sorting. If the <b>AllowSorting</b> is set to true, a column

- * whose <b>SortExpression</b> is not empty will have its header text displayed as a link button.

- * Clicking on the link button will raise <b>OnSortCommand</b> event. You can respond to this event,

- * sort the data source according to the event parameter, and then invoke databind on the datagrid.

+ * TDataGrid supports sorting. If the {@link setAllowSorting AllowSorting}

+ * is set to true, a column with nonempty {@link setSortExpression SortExpression}

+ * will have its header text displayed as a clickable link button.

+ * Clicking on the link button will raise {@link onSortCommand OnSortCommand}

+ * event. You can respond to this event, sort the data source according

+ * to the event parameter, and then invoke {@link databind()} on the datagrid

+ * to show to end users the sorted data.

  *

- * TDataGrid supports paging. If the <b>AllowPaging</b> 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 <b>PagerDisplay</b>

- * and <b>PagerButtonCount</b> properties. The former decides the position of the pager and latter

- * specifies how many buttons are to be used for paging purpose. Clicking on a pager button will raise

- * an <b>onPageIndexChanged</b> event. You can respond to this event, specify the page to be displayed by

- * setting <b>CurrentPageIndex</b> property, and then invoke databind on the datagrid.

+ * TDataGrid supports paging. If the {@link 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 {@link getPagerStyle PagerStyle}

+ * property. Clicking on a pager button will raise an {@link onPageIndexChanged OnPageIndexChanged}

+ * event. You can respond to this event, specify the page to be displayed by

+ * setting {@link setCurrentPageIndex CurrentPageIndex}</b> property,

+ * and then invoke {@link 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 <b>PageCount</b> is calculated based the item number and the

- * <b>PageSize</b> property. The datagrid will manage which section of the data source to be displayed

- * based on the <b>CurrentPageIndex</b> property.

- * The second approach calculates the page number based on the <b>VirtualItemCount</b> property and

- * the <b>PageSize</b> property. The datagrid will always display from the beginning of the datasource

- * upto the number of <b>PageSize> data items. This approach is especially useful when the datasource may

- * contain too many data items to be managed by the datagrid efficiently.

+ * datasource. The number of pages {@link getPageCount PageCount} is calculated based

+ * the item number and the {@link setPageSize PageSize} property.

+ * The datagrid will manage which section of the data source to be displayed

+ * based on the {@link setCurrentPageIndex CurrentPageIndex} property.

+ * The second approach calculates the page number based on the

+ * {@link setVirtualItemCount VirtualItemCount} property and

+ * the {@link setPageSize PageSize} property. The datagrid will always

+ * display from the beginning of the datasource up to the number of

+ * {@link 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 <b>OnCommand</b>

+ * When the datagrid contains a button control that raises an {@link 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, edit

- * - OnCancelCommand, cancel

- * - OnSelectCommand, select

- * - OnDeleteCommand, delete

- * - OnUpdateCommand, update

- * - onPageIndexChanged, page

- * - OnSortCommand, sort

- * The data list will always raise an <b>OnItemCommand</b>

- * upon its receiving a bubbled <b>OnCommand</b> event.

+ * - 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 {@link onItemCommand OnItemCommand} event is raised in addition to

+ * the above specific command events.

  *

- * An <b>OnItemCreated</b> event will be raised right after each item is created in the datagrid.

+ * TDataGrid also raises an {@link 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.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -108,27 +134,53 @@ Prado::using('System.Web.UI.WebControls.TTable');
  */

 class TDataGrid extends TBaseDataList implements INamingContainer

 {

+	/**

+	 * @var TDataGridColumnCollection manually created column collection

+	 */

 	private $_columns=null;

+	/**

+	 * @var TDataGridColumnCollection automatically created column collection

+	 */

 	private $_autoColumns=null;

+	/**

+	 * @var TDataGridItemCollection datagrid item collection

+	 */

 	private $_items=null;

+	/**

+	 * @var TDataGridItem header item

+	 */

 	private $_header=null;

+	/**

+	 * @var TDataGridItem footer item

+	 */

 	private $_footer=null;

+	/**

+	 * @var TPagedDataSource paged data source object

+	 */

 	private $_pagedDataSource=null;

 

 	/**

-	 * @return string tag name of the datagrid

+	 * @return string tag name (table) of the datagrid

 	 */

 	protected function getTagName()

 	{

 		return 'table';

 	}

 

+	/**

+	 * Adds objects parsed in template to datagrid.

+	 * Only datagrid columns are added into {@link getColumns Columns} collection.

+	 * @param mixed object parsed in template

+	 */

 	public function addParsedObject($object)

 	{

 		if($object instanceof TDataGridColumn)

 			$this->getColumns()->add($object);

 	}

 

+	/**

+	 * @return TDataGridColumnCollection manually specified datagrid columns

+	 */

 	public function getColumns()

 	{

 		if(!$this->_columns)

@@ -136,6 +188,9 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		return $this->_columns;

 	}

 

+	/**

+	 * @return TDataGridColumnCollection automatically specified datagrid columns

+	 */

 	public function getAutoColumns()

 	{

 		if(!$this->_autoColumns)

@@ -143,6 +198,9 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		return $this->_autoColumns;

 	}

 

+	/**

+	 * @return TDataGridItemCollection datagrid item collection

+	 */

 	public function getItems()

 	{

 		if(!$this->_items)

@@ -153,7 +211,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	/**

 	 * Creates a style object for the control.

 	 * This method creates a {@link TTableStyle} to be used by datagrid.

-	 * @return TStyle control style to be used

+	 * @return TTableStyle control style to be used

 	 */

 	protected function createStyle()

 	{

@@ -172,8 +230,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * Sets the URL of the background image for the datagrid

-	 * @param string the URL

+	 * @param string the URL of the background image for the datagrid

 	 */

 	public function setBackImageUrl($value)

 	{

@@ -181,27 +238,27 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * @return TTableItemStyle the style for each alternating item

+	 * @return TTableItemStyle the style for every item

 	 */

-	public function getAlternatingItemStyle()

+	public function getItemStyle()

 	{

-		if(($style=$this->getViewState('AlternatingItemStyle',null))===null)

+		if(($style=$this->getViewState('ItemStyle',null))===null)

 		{

 			$style=new TTableItemStyle;

-			$this->setViewState('AlternatingItemStyle',$style,null);

+			$this->setViewState('ItemStyle',$style,null);

 		}

 		return $style;

 	}

 

 	/**

-	 * @return TTableItemStyle the style for item

+	 * @return TTableItemStyle the style for each alternating item

 	 */

-	public function getItemStyle()

+	public function getAlternatingItemStyle()

 	{

-		if(($style=$this->getViewState('ItemStyle',null))===null)

+		if(($style=$this->getViewState('AlternatingItemStyle',null))===null)

 		{

 			$style=new TTableItemStyle;

-			$this->setViewState('ItemStyle',$style,null);

+			$this->setViewState('AlternatingItemStyle',$style,null);

 		}

 		return $style;

 	}

@@ -246,14 +303,6 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * @return TDataGridItem the header item

-	 */

-	public function getHeader()

-	{

-		return $this->_header;

-	}

-

-	/**

 	 * @return TTableItemStyle the style for footer

 	 */

 	public function getFooterStyle()

@@ -267,14 +316,6 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * @return TDataGridItem the footer item

-	 */

-	public function getFooter()

-	{

-		return $this->_footer;

-	}

-

-	/**

 	 * @return TDataGridPagerStyle the style for pager

 	 */

 	public function getPagerStyle()

@@ -288,6 +329,22 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

+	 * @return TDataGridItem the header item

+	 */

+	public function getHeader()

+	{

+		return $this->_header;

+	}

+

+	/**

+	 * @return TDataGridItem the footer item

+	 */

+	public function getFooter()

+	{

+		return $this->_footer;

+	}

+

+	/**

 	 * @return TDataGridItem the selected item, null if no item is selected.

 	 */

 	public function getSelectedItem()

@@ -385,7 +442,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * @return boolean whether the custom paging is enabled Defaults to false.

+	 * @return boolean whether the custom paging is enabled. Defaults to false.

 	 */

 	public function getAllowCustomPaging()

 	{

@@ -449,7 +506,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * @return integer the index of the current page. Defaults to 0.

+	 * @return integer the zero-based index of the current page. Defaults to 0.

 	 */

 	public function getCurrentPageIndex()

 	{

@@ -457,7 +514,8 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * @param integer the index of the current page

+	 * @param integer the zero-based index of the current page

+	 * @throws TInvalidDataValueException if the value is less than 0

 	 */

 	public function setCurrentPageIndex($value)

 	{

@@ -467,7 +525,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * @return integer the number of rows displayed within a page. Defaults to 10.

+	 * @return integer the number of rows displayed each page. Defaults to 10.

 	 */

 	public function getPageSize()

 	{

@@ -476,6 +534,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * @param integer the number of rows displayed within a page

+	 * @throws TInvalidDataValueException if the value is less than 1

 	 */

 	public function setPageSize($value)

 	{

@@ -484,12 +543,15 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		$this->setViewState('PageSize',TPropertyValue::ensureInteger($value),10);

 	}

 

-

+	/**

+	 * @return integer number of pages of items available

+	 */

 	public function getPageCount()

 	{

 		if($this->_pagedDataSource)

 			return $this->_pagedDataSource->getPageCount();

-		return $this->getViewState('PageCount',0);

+		else

+			return $this->getViewState('PageCount',0);

 	}

 

 	/**

@@ -502,6 +564,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * @param integer virtual number of items in the grid

+	 * @throws TInvalidDataValueException if the value is less than 0

 	 */

 	public function setVirtualItemCount($value)

 	{

@@ -511,7 +574,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * @return boolean whether the header should be displayed Defaults to true.

+	 * @return boolean whether the header should be displayed. Defaults to true.

 	 */

 	public function getShowHeader()

 	{

@@ -543,7 +606,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * Handles <b>BubbleEvent</b>.

+	 * Handles <b>OnBubbleEvent</b>.

 	 * This method overrides parent's implementation to handle

 	 * {@link onItemCommand OnItemCommand} event which is bubbled from

 	 * {@link TDataGridItem} child controls.

@@ -611,8 +674,8 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * Raises <b>OnCancelCommand</b> event.

-	 * This method is invoked when a button control raises<b>Command</b> event

-	 * with<b>cancel</b> command name.

+	 * This method is invoked when a button control raises <b>OnCommand</b> event

+	 * with <b>cancel</b> command name.

 	 * @param TDataGridCommandEventParameter event parameter

 	 */

 	public function onCancelCommand($param)

@@ -622,7 +685,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * Raises <b>OnDeleteCommand</b> event.

-	 * This method is invoked when a button control raises <b>Command</b> event

+	 * This method is invoked when a button control raises <b>OnCommand</b> event

 	 * with <b>delete</b> command name.

 	 * @param TDataGridCommandEventParameter event parameter

 	 */

@@ -633,7 +696,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * Raises <b>OnEditCommand</b> event.

-	 * This method is invoked when a button control raises <b>Command</b> event

+	 * This method is invoked when a button control raises <b>OnCommand</b> event

 	 * with <b>edit</b> command name.

 	 * @param TDataGridCommandEventParameter event parameter

 	 */

@@ -644,7 +707,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * Raises <b>OnItemCommand</b> event.

-	 * This method is invoked when a button control raises <b>Command</b> event.

+	 * This method is invoked when a button control raises <b>OnCommand</b> event.

 	 * @param TDataGridItemCommandEventParameter event parameter

 	 */

 	public function onItemCommand($param)

@@ -654,7 +717,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * Raises <b>OnSortCommand</b> event.

-	 * This method is invoked when a button control raises <b>Command</b> event

+	 * This method is invoked when a button control raises <b>OnCommand</b> event

 	 * with <b>sort</b> command name.

 	 * @param TDataGridSortCommandEventParameter event parameter

 	 */

@@ -665,7 +728,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * Raises <b>OnUpdateCommand</b> event.

-	 * This method is invoked when a button control raises <b>Command</b> event

+	 * This method is invoked when a button control raises <b>OnCommand</b> event

 	 * with <b>update</b> command name.

 	 * @param TDataGridCommandEventParameter event parameter

 	 */

@@ -778,6 +841,9 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		$this->clearViewState('ItemCount');

 	}

 

+	/**

+	 * @return TPagedDataSource creates a paged data source

+	 */

 	private function createPagedDataSource()

 	{

 		$ds=new TPagedDataSource;

@@ -790,7 +856,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 	}

 

 	/**

-	 * Clears up all items in the data list.

+	 * Clears up all items in the datagrid.

 	 */

 	public function reset()

 	{

@@ -800,6 +866,9 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		$this->_footer=null;

 	}

 

+	/**

+	 * Restores datagrid content from viewstate.

+	 */

 	protected function restoreGridFromViewState()

 	{

 		$this->reset();

@@ -850,9 +919,9 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 

 	/**

 	 * Performs databinding to populate data list items from data source.

-	 * This method is invoked by dataBind().

+	 * This method is invoked by {@link dataBind()}.

 	 * You may override this function to provide your own way of data population.

-	 * @param Traversable the data

+	 * @param Traversable the bound data

 	 */

 	protected function performDataBinding($data)

 	{

@@ -954,6 +1023,11 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		return $item;

 	}

 

+	/**

+	 * Initializes a datagrid item and cells inside it

+	 * @param TDataGrid datagrid item to be initialized

+	 * @param TDataGridColumnCollection datagrid columns to be used to initialize the cells in the item

+	 */

 	protected function initializeItem($item,$columns)

 	{

 		$cells=$item->getCells();

@@ -980,6 +1054,12 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		return $item;

 	}

 

+	/**

+	 * Initializes the pager.

+	 * @param TDataGridItem the pager to be initialized

+	 * @param integer columnspan for the pager

+	 * @param TPagedDataSource data source bound to the datagrid

+	 */

 	protected function initializePager($pager,$columnSpan,$pagedDataSource)

 	{

 		$cell=new TTableCell;

@@ -989,6 +1069,11 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		$pager->getCells()->add($cell);

 	}

 

+	/**

+	 * Builds the pager content based on pager style.

+	 * @param TTableCell table cell for the pager

+	 * @param TPagedDataSource data source bound to the datagrid

+	 */

 	protected function buildPager($cell,$dataSource)

 	{

 		switch($this->getPagerStyle()->getMode())

@@ -1002,6 +1087,11 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		}

 	}

 

+	/**

+	 * Builds a next-prev pager

+	 * @param TTableCell table cell for the pager

+	 * @param TPagedDataSource data source bound to the datagrid

+	 */

 	protected function buildNextPrevPager($cell,$dataSource)

 	{

 		$style=$this->getPagerStyle();

@@ -1039,6 +1129,11 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		}

 	}

 

+	/**

+	 * Builds a numeric pager

+	 * @param TTableCell table cell for the pager

+	 * @param TPagedDataSource data source bound to the datagrid

+	 */

 	protected function buildNumericPager($cell,$dataSource)

 	{

 		$style=$this->getPagerStyle();

@@ -1105,6 +1200,11 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		}

 	}

 

+	/**

+	 * Automatically generates datagrid columns based on datasource schema

+	 * @param TPagedDataSource data source bound to the datagrid

+	 * @return TDataGridColumnCollection

+	 */

 	protected function createAutoColumns($dataSource)

 	{

 		if(!$dataSource)

@@ -1283,6 +1383,10 @@ class TDataGrid extends TBaseDataList implements INamingContainer
 		}

 	}

 

+	/**

+	 * Renders the content in the datagrid.

+	 * @param THtmlWriter writer for the rendering purpose

+	 */

 	public function renderContents($writer)

 	{

 		if($this->getHasControls())

@@ -1668,7 +1772,16 @@ class TDataGridColumnCollection extends TList
 	}

 }

 

-

+/**

+ * TDataGridPagerStyle class.

+ *

+ * TDataGridPagerStyle specifies the styles available for a datagrid pager.

+ *

+ * @author Qiang Xue <qiang.xue@gmail.com>

+ * @version $Revision: $  $Date: $

+ * @package System.Web.UI.WebControls

+ * @since 3.0

+ */

 class TDataGridPagerStyle extends TTableItemStyle

 {

 	private $_mode=null;

@@ -1678,41 +1791,66 @@ class TDataGridPagerStyle extends TTableItemStyle
 	private $_position=null;

 	private $_visible=null;

 

+	/**

+	 * @return string pager mode. Defaults to 'NextPrev'.

+	 */

 	public function getMode()

 	{

 		return $this->_mode===null?'NextPrev':$this->_mode;

 	}

 

+	/**

+	 * @param string pager mode. Valid values include 'NextPrev' and 'Numeric'.

+	 */

 	public function setMode($value)

 	{

 		$this->_mode=TPropertyValue::ensureEnum($value,'NextPrev','Numeric');

 	}

 

+	/**

+	 * @return string text for the next page button. Defaults to '>'.

+	 */

 	public function getNextPageText()

 	{

 		return $this->_nextText===null?'>':$this->_nextText;

 	}

 

+	/**

+	 * @param string text for the next page button.

+	 */

 	public function setNextPageText($value)

 	{

 		$this->_nextText=$value;

 	}

 

+	/**

+	 * @return string text for the previous page button. Defaults to '<'.

+	 */

 	public function getPrevPageText()

 	{

 		return $this->_prevText===null?'<':$this->_prevText;

 	}

 

+	/**

+	 * @param string text for the next page button.

+	 */

 	public function setPrevPageText($value)

 	{

 		$this->_prevText=$value;

 	}

 

+	/**

+	 * @return integer maximum number of pager buttons to be displayed. Defaults to 10.

+	 */

 	public function getPageButtonCount()

 	{

 		return $this->_buttonCount===null?10:$this->_buttonCount;

 	}

 

+	/**

+	 * @param integer maximum number of pager buttons to be displayed

+	 * @throws TInvalidDataValueException if the value is less than 1.

+	 */

 	public function setPageButtonCount($value)

 	{

 		if(($value=TPropertyValue::ensureInteger($value))<1)

@@ -1720,21 +1858,33 @@ class TDataGridPagerStyle extends TTableItemStyle
 		$this->_buttonCount=$value;

 	}

 

+	/**

+	 * @return string where the pager is to be displayed. Defaults to 'Bottom'.

+	 */

 	public function getPosition()

 	{

 		return $this->_position===null?'Bottom':$this->_position;

 	}

 

+	/**

+	 * @param string where the pager is to be displayed. Valid values include 'Bottom', 'Top', 'TopAndBottom'

+	 */

 	public function setPosition($value)

 	{

 		$this->_position=TPropertyValue::ensureEnum($value,'Bottom','Top','TopAndBottom');

 	}

 

+	/**

+	 * @return boolean whether the pager is visible. Defaults to true.

+	 */

 	public function getVisible()

 	{

 		return $this->_visible===null?true:$this->_visible;

 	}

 

+	/**

+	 * @param boolean whether the pager is visible.

+	 */

 	public function setVisible($value)

 	{

 		$this->_visible=TPropertyValue::ensureBoolean($value);

diff --git a/framework/Web/UI/WebControls/TDataGridColumn.php b/framework/Web/UI/WebControls/TDataGridColumn.php
index 41d11946..925fa90b 100644
--- a/framework/Web/UI/WebControls/TDataGridColumn.php
+++ b/framework/Web/UI/WebControls/TDataGridColumn.php
@@ -13,23 +13,28 @@
 /**

  * 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 to all column types.

- * In particular, it initializes header and footer cells according to

- * <b>HeaderText</b>, <b>HeaderStyle</b>, <b>FooterText</b>, and <b>FooterStyle</b>.

- * If <b>HeaderImageUrl</b> is specified, the image will be displayed instead in the header cell.

- * The <b>ItemStyle</b> is applied to non-header and -footer items.

+ * 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 <b>SortExpression</b> is not empty,

- * the header cell will display a button (linkbutton or imagebutton) that will

- * bubble sort command event to the datagrid.

+ * 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.

  *

- * The framework provides the following TDataGridColumn descendant classes,

- * - 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.

- * - THyperLinkColumn, displaying a hyperlink that may be boudn to specific field in datasource.

- * - TTemplateColumn, displaying content based on templates.

+ * 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 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.

@@ -58,7 +63,6 @@ abstract class TDataGridColumn extends TComponent
 	public function setHeaderText($value)

 	{

 		$this->setViewState('HeaderText',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -75,7 +79,6 @@ abstract class TDataGridColumn extends TComponent
 	public function setHeaderImageUrl($value)

 	{

 		$this->setViewState('HeaderImageUrl',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -106,7 +109,6 @@ abstract class TDataGridColumn extends TComponent
 	public function setFooterText($value)

 	{

 		$this->setViewState('FooterText',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -138,20 +140,19 @@ abstract class TDataGridColumn extends TComponent
 	}

 

 	/**

-	 * @param string the name of the field or expression for sorting

+	 * @return string the name of the field or expression for sorting

 	 */

-	public function setSortExpression($value)

+	public function getSortExpression()

 	{

-		$this->setViewState('SortExpression',$value,'');

-		$this->onColumnChanged();

+		return $this->getViewState('SortExpression','');

 	}

 

 	/**

-	 * @return string the name of the field or expression for sorting

+	 * @param string the name of the field or expression for sorting

 	 */

-	public function getSortExpression()

+	public function setSortExpression($value)

 	{

-		return $this->getViewState('SortExpression','');

+		$this->setViewState('SortExpression',$value,'');

 	}

 

 	/**

@@ -168,7 +169,6 @@ abstract class TDataGridColumn extends TComponent
 	public function setVisible($value)

 	{

 		$this->setViewState('Visible',TPropertyValue::ensureBoolean($value),true);

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -199,41 +199,66 @@ abstract class TDataGridColumn extends TComponent
 			$this->_viewState[$key]=$value;

 	}

 

+	/**

+	 * Loads persistent state values.

+	 * @param mixed state values

+	 */

 	public function loadState($state)

 	{

 		$this->_viewState=$state;

 	}

 

+	/**

+	 * Saves persistent state values.

+	 * @return mixed values to be saved

+	 */

 	public function saveState()

 	{

 		return $this->_viewState;

 	}

 

+	/**

+	 * @return TDataGrid datagrid that owns this column

+	 */

 	public function getOwner()

 	{

 		return $this->_owner;

 	}

 

+	/**

+	 * @param TDataGrid datagrid object that owns this column

+	 */

 	public function setOwner(TDataGrid $value)

 	{

 		$this->_owner=$value;

 	}

 

-	public function onColumnChanged()

-	{

-		if($this->_owner)

-			$this->_owner->onColumnsChanged();

-	}

-

+	/**

+	 * Initializes the column.

+	 * This method is invoked by {@link TDataGrid} when the column

+	 * is about to be used to initialize datagrid items.

+	 * Derived classes may override this method to do additional initialization.

+	 */

 	public function initialize()

 	{

 	}

 

+	/**

+	 * 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 {@link TMap}, {@link 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.

+	 * @param mixed data containing the field of value

+	 * @param string the data field

+	 * @return mixed data value at the specified field

+	 * @throws TInvalidDataValueException if the data or the field is invalid.

+	 */

 	protected function getDataFieldValue($data,$field)

 	{

 		if(is_array($data))

 			return $data[$field];

-		else if($data instanceof TMap)

+		else if(($data instanceof TMap) || ($data instanceof TList))

 			return $data->itemAt($field);

 		else if(($data instanceof TComponent) && $data->canGetProperty($field))

 		{

@@ -241,7 +266,7 @@ abstract class TDataGridColumn extends TComponent
 			return $data->$getter();

 		}

 		else

-			throw new TInvalidDataValueException('datagridcolumn_data_invalid');

+			throw new TInvalidDataValueException('datagridcolumn_data_invalid',get_class($this),$field);

 	}

 

 	/**

@@ -311,8 +336,10 @@ abstract class TDataGridColumn extends TComponent
 

 	/**

 	 * Formats the text value according to format string.

-	 * This method is invoked when setting the text to a cell.

-	 * This method can be overriden.

+	 * This method invokes the {@link sprintf} to do string formatting.

+	 * If the format string is empty, the original value is converted into

+	 * a string and returned.

+	 * @param string format string

 	 * @param mixed the data associated with the cell

 	 * @return string the formatted result

 	 */

diff --git a/framework/Web/UI/WebControls/TEditCommandColumn.php b/framework/Web/UI/WebControls/TEditCommandColumn.php
index 8244981b..6cb93a39 100644
--- a/framework/Web/UI/WebControls/TEditCommandColumn.php
+++ b/framework/Web/UI/WebControls/TEditCommandColumn.php
@@ -22,16 +22,21 @@ Prado::using('System.Web.UI.WebControls.TDataGridColumn');
  *

  * TEditCommandColumn will create an edit button if a cell is not in edit mode.

  * Otherwise an update button and a cancel button will be created within the cell.

- * The button captions are specified using <b>EditText</b>, <b>UpdateText</b>

- * and <b>CancelText</b>.

+ * The button captions are specified using {@link setEditText EditText},

+ * {@link setUpdateText UpdateText}, and {@link setCancelText CancelText}.

  *

  * The buttons in the column can be set to display as hyperlinks or push buttons

- * by setting the <b>ButtonType</b> property.

+ * by setting the {@link setButtonType ButtonType} property.

  *

- * When an edit button is clicked, the datagrid will generate an <b>OnEditCommand</b>

- * event. When an update/cancel button is clicked, the datagrid will generate an

- * <b>OnUpdateCommand</b> or an <b>OnCancelCommand</b>. You can write these event handlers

- * to change the state of specific datagrid item.

+ * When an edit button is clicked, the datagrid will generate an

+ * {@link onEditCommand OnEditCommand} event. When an update/cancel button

+ * is clicked, the datagrid will generate an

+ * {@link onUpdateCommand OnUpdateCommand} or an {@link onCancelCommand OnCancelCommand}

+ * You can write these event handlers to change the state of specific datagrid item.

+ *

+ * The {@link setCausesValidation CausesValidation} and {@link setValidationGroup ValidationGroup}

+ * properties affect the corresponding properties of the edit and update buttons.

+ * The cancel button does not cause validation by default.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -54,11 +59,10 @@ class TEditCommandColumn extends TDataGridColumn
 	public function setButtonType($value)

 	{

 		$this->setViewState('ButtonType',TPropertyValue::ensureEnum($value,'LinkButton','PushButton'),'LinkButton');

-		$this->onColumnChanged();

 	}

 

 	/**

-	 * @return string the caption of the edit button

+	 * @return string the caption of the edit button. Defaults to 'Edit'.

 	 */

 	public function getEditText()

 	{

@@ -71,11 +75,10 @@ class TEditCommandColumn extends TDataGridColumn
 	public function setEditText($value)

 	{

 		$this->setViewState('EditText',$value,'Edit');

-		$this->onColumnChanged();

 	}

 

 	/**

-	 * @return string the caption of the update button

+	 * @return string the caption of the update button. Defaults to 'Update'.

 	 */

 	public function getUpdateText()

 	{

@@ -88,11 +91,10 @@ class TEditCommandColumn extends TDataGridColumn
 	public function setUpdateText($value)

 	{

 		$this->setViewState('UpdateText',$value,'Update');

-		$this->onColumnChanged();

 	}

 

 	/**

-	 * @return string the caption of the cancel button

+	 * @return string the caption of the cancel button. Defaults to 'Cancel'.

 	 */

 	public function getCancelText()

 	{

@@ -105,11 +107,10 @@ class TEditCommandColumn extends TDataGridColumn
 	public function setCancelText($value)

 	{

 		$this->setViewState('CancelText',$value,'Cancel');

-		$this->onColumnChanged();

 	}

 

 	/**

-	 * @return boolean whether postback event trigger by this button will cause input validation, default is true

+	 * @return boolean whether postback event trigger by edit or update button will cause input validation, default is true

 	 */

 	public function getCausesValidation()

 	{

@@ -117,16 +118,15 @@ class TEditCommandColumn extends TDataGridColumn
 	}

 

 	/**

-	 * @param boolean whether postback event trigger by this button will cause input validation

+	 * @param boolean whether postback event trigger by edit or update button will cause input validation

 	 */

 	public function setCausesValidation($value)

 	{

 		$this->setViewState('CausesValidation',TPropertyValue::ensureBoolean($value),true);

-		$this->onColumnChanged();

 	}

 

 	/**

-	 * @return string the group of validators which the button causes validation upon postback

+	 * @return string the group of validators which the edit or update button causes validation upon postback

 	 */

 	public function getValidationGroup()

 	{

@@ -134,12 +134,11 @@ class TEditCommandColumn extends TDataGridColumn
 	}

 

 	/**

-	 * @param string the group of validators which the button causes validation upon postback

+	 * @param string the group of validators which the edit or update button causes validation upon postback

 	 */

 	public function setValidationGroup($value)

 	{

 		$this->setViewState('ValidationGroup',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -165,7 +164,15 @@ class TEditCommandColumn extends TDataGridColumn
 		}

 	}

 

-	private function addButtonToCell($cell,$commandName,$text,$causesValidation,$validationGroup)

+	/**

+	 * Creates a button and adds it to the cell.

+	 * @param TTableCell the cell that the button is created within

+	 * @param string command name associated with the button

+	 * @param string button caption

+	 * @param boolean whether the button should cause validation

+	 * @param string the validation group that the button belongs to

+	 */

+	protected function addButtonToCell($cell,$commandName,$text,$causesValidation,$validationGroup)

 	{

 		if($this->getButtonType()==='LinkButton')

 			$button=Prado::createComponent('System.Web.UI.WebControls.TLinkButton');

diff --git a/framework/Web/UI/WebControls/THyperLinkColumn.php b/framework/Web/UI/WebControls/THyperLinkColumn.php
index 6a14ea5b..96e905cd 100644
--- a/framework/Web/UI/WebControls/THyperLinkColumn.php
+++ b/framework/Web/UI/WebControls/THyperLinkColumn.php
@@ -19,15 +19,18 @@ Prado::using('System.Web.UI.WebControls.TDataGridColumn');
  * THyperLinkColumn class

  *

  * THyperLinkColumn contains a hyperlink for each item in the column.

- * You can set the text and the url of the hyperlink by <b>Text</b> and <b>NavigateUrl</b>

- * properties, respectively. You can also bind the text and url to specific

- * data field in datasource by setting <b>DataTextField</b> and <b>DataNavigateUrlField</b>.

- * Both can be formatted before rendering according to the <b>DataTextFormatString</b>

- * and <b>DataNavigateUrlFormatString</b> properties, respectively.

- * If both <b>Text</b> and <b>DataTextField</b> are present, the latter takes precedence.

- * The same rule applies to <b>NavigateUrl</b> and <b>DataNavigateUrlField</b> properties.

- *

- * Namespace: System.Web.UI.WebControls

+ * You can set the text and the url of the hyperlink by {@link setText Text}

+ * and {@link setNavigateUrl NavigateUrl} properties, respectively.

+ * You can also bind the text and url to specific data field in datasource

+ * by setting {@link setDataTextField DataTextField} and

+ * {@link setDataNavigateUrlField DataNavigateUrlField}.

+ * Both can be formatted before rendering according to the

+ * {@link setDataTextFormatString DataTextFormatString} and

+ * and {@link setDataNavigateUrlFormatString DataNavigateUrlFormatString}

+ * properties, respectively. If both {@link setText Text} and {@link setDataTextField DataTextField}

+ * are present, the latter takes precedence.

+ * The same rule applies to {@link setNavigateUrl NavigateUrl} and

+ * {@link setDataNavigateUrlField DataNavigateUrlField} properties.

  *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

@@ -51,7 +54,6 @@ class THyperLinkColumn extends TDataGridColumn
 	public function setText($value)

 	{

 		$this->setViewState('Text',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -68,7 +70,6 @@ class THyperLinkColumn extends TDataGridColumn
 	public function setDataTextField($value)

 	{

 		$this->setViewState('DataTextField',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -85,7 +86,6 @@ class THyperLinkColumn extends TDataGridColumn
 	public function setDataTextFormatString($value)

 	{

 		$this->setViewState('DataTextFormatString',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -103,7 +103,6 @@ class THyperLinkColumn extends TDataGridColumn
 	public function setNavigateUrl($value)

 	{

 		$this->setViewState('NavigateUrl',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -120,7 +119,6 @@ class THyperLinkColumn extends TDataGridColumn
 	public function setDataNavigateUrlField($value)

 	{

 		$this->setViewState('DataNavigateUrlField',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -137,7 +135,6 @@ class THyperLinkColumn extends TDataGridColumn
 	public function setDataNavigateUrlFormatString($value)

 	{

 		$this->setViewState('DataNavigateUrlFormatString',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -155,7 +152,6 @@ class THyperLinkColumn extends TDataGridColumn
 	public function setTarget($value)

 	{

 		$this->setViewState('Target',$value,'');

-		$this->onColumnChanged();

 	}

 

 	/**

@@ -181,6 +177,11 @@ class THyperLinkColumn extends TDataGridColumn
 		}

 	}

 

+	/**

+	 * Databinds a cell in the column.

+	 * This method is invoked when datagrid performs databinding.

+	 * It populates the content of the cell with the relevant data from data source.

+	 */

 	public function dataBindColumn($sender,$param)

 	{

 		$item=$sender->getNamingContainer();

diff --git a/framework/Web/UI/WebControls/TTemplateColumn.php b/framework/Web/UI/WebControls/TTemplateColumn.php
index 350f0f92..08c4e2c6 100644
--- a/framework/Web/UI/WebControls/TTemplateColumn.php
+++ b/framework/Web/UI/WebControls/TTemplateColumn.php
@@ -19,10 +19,14 @@ Prado::using('System.Web.UI.WebControls.TDataGridColumn');
  * TTemplateColumn class

  *

  * TTemplateColumn customizes the layout of controls in the column with templates.

- * In particular, you can specify <b>ItemTemplate</b>, <b>EditItemTemplate</b>

- * <b>HeaderTemplate</b> and <b>FooterTemplate</b> to customize specific

+ * In particular, you can specify {@link setItemTemplate ItemTemplate},

+ * {@link setEditItemTemplate EditItemTemplate}, {@link setHeaderTemplate HeaderTemplate}

+ * and {@link setFooterTemplate FooterTemplate} to customize specific

  * type of cells in the column.

  *

+ * Note, if {@link setHeaderTemplate HeaderTemplate} is not set, the column

+ * header will be displayed with {@link setHeaderText HeaderText}.

+ *

  * @author Qiang Xue <qiang.xue@gmail.com>

  * @version $Revision: $  $Date: $

  * @package System.Web.UI.WebControls

@@ -88,7 +92,7 @@ class TTemplateColumn extends TDataGridColumn
 	}

 

 	/**

-	 * @param ITemplate the header template

+	 * @param ITemplate the header template.

 	 * @throws TInvalidDataTypeException if the input is not an {@link ITemplate} or not null.

 	 */

 	public function setHeaderTemplate($value)