From df96feedc019e531ea165681b837f6a3595f702d Mon Sep 17 00:00:00 2001 From: xue <> Date: Sat, 11 Feb 2006 04:49:58 +0000 Subject: Completed TDataGrid documentation. --- framework/Web/UI/WebControls/TBoundColumn.php | 13 +- framework/Web/UI/WebControls/TButtonColumn.php | 38 ++- framework/Web/UI/WebControls/TCheckBoxColumn.php | 28 +- framework/Web/UI/WebControls/TDataGrid.php | 348 +++++++++++++++------ framework/Web/UI/WebControls/TDataGridColumn.php | 99 +++--- .../Web/UI/WebControls/TEditCommandColumn.php | 49 +-- framework/Web/UI/WebControls/THyperLinkColumn.php | 33 +- framework/Web/UI/WebControls/TTemplateColumn.php | 10 +- 8 files changed, 404 insertions(+), 214 deletions(-) (limited to 'framework/Web/UI') 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 - * DataField. You can customize the display by setting DataFormatString. + * {@link setDataField DataField}. You can customize the display by + * setting {@link setDataFormatString DataFormatString}. * - * If ReadOnly 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 @@ -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 Text - * and DataTextField properties. If both are present, the latter takes - * precedence. The DataTextField refers to the name of the field in datasource - * whose value will be used as the button caption. If DataTextFormatString - * 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 ButtonType property. - * The CommandName will assign its value to all button's CommandName - * 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 CommandName property. The datagrid will capture + * the command event where you can write event handlers based on different command names. + * The buttons' CausesValidation and ValidationGroup property values + * are determined by the column's corresponding properties. * * @author Qiang Xue * @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 Command event. + * @return string the command name associated with the OnCommand 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 - * DataField. You can customize the display by setting DataFormatString. - * - * If ReadOnly 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 * @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 @@ * @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 DataSource property and invokes dataBind() - * afterwards. The data will be populated into the TDataGrid and saved in the Items 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 EditItemIndex property - * or the SelectedItemIndex 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. *
    - *
  • Automatically generated based on data source. By setting AutoGenerateColumns - * to true, a list of columns will be automatically generated based on the schema of the data source. + *
  • 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.
    • *
  • Specified in template. For example, * @@ -53,53 +67,65 @@ Prado::using('System.Web.UI.WebControls.TTable'); * * *
    • - *
  • Manually created in code. Columns can be manipulated via the Columns property of - * the datagrid. For example, - * - * $column=$datagrid->createComponent('TBoundColumn'); - * $datagrid->Columns->add($column); - * + *
  • Manually created in code. Columns can be manipulated via + * the {@link setColumns Columns} property of the datagrid. For example, + * + * $column=new TBoundColumn; + * $datagrid->Columns[]=$column; + * *
    • *
- * Note, automatically generated columns cannot be accessed via Columns property. + * Note, automatically generated columns cannot be accessed via + * the {@link getColumns Columns} property. * - * TDataGrid supports sorting. If the AllowSorting is set to true, a column - * whose SortExpression is not empty will have its header text displayed as a link button. - * Clicking on the link button will raise OnSortCommand 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 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 PagerDisplay - * and PagerButtonCount 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 onPageIndexChanged event. You can respond to this event, specify the page to be displayed by - * setting CurrentPageIndex 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} 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 PageCount is calculated based the item number and the - * PageSize property. The datagrid will manage which section of the data source to be displayed - * based on the CurrentPageIndex property. - * The second approach calculates the page number based on the VirtualItemCount property and - * the PageSize property. The datagrid will always display from the beginning of the datasource - * upto the number of 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 OnCommand + * 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 OnItemCommand - * upon its receiving a bubbled OnCommand 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 OnItemCreated 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 * @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; } @@ -245,14 +302,6 @@ class TDataGrid extends TBaseDataList implements INamingContainer return $style; } - /** - * @return TDataGridItem the header item - */ - public function getHeader() - { - return $this->_header; - } - /** * @return TTableItemStyle the style for footer */ @@ -266,14 +315,6 @@ class TDataGrid extends TBaseDataList implements INamingContainer return $style; } - /** - * @return TDataGridItem the footer item - */ - public function getFooter() - { - return $this->_footer; - } - /** * @return TDataGridPagerStyle the style for pager */ @@ -287,6 +328,22 @@ class TDataGrid extends TBaseDataList implements INamingContainer return $style; } + /** + * @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. */ @@ -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 BubbleEvent. + * Handles OnBubbleEvent. * 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 OnCancelCommand event. - * This method is invoked when a button control raisesCommand event - * withcancel command name. + * This method is invoked when a button control raises OnCommand event + * with cancel command name. * @param TDataGridCommandEventParameter event parameter */ public function onCancelCommand($param) @@ -622,7 +685,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer /** * Raises OnDeleteCommand event. - * This method is invoked when a button control raises Command event + * This method is invoked when a button control raises OnCommand event * with delete command name. * @param TDataGridCommandEventParameter event parameter */ @@ -633,7 +696,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer /** * Raises OnEditCommand event. - * This method is invoked when a button control raises Command event + * This method is invoked when a button control raises OnCommand event * with edit command name. * @param TDataGridCommandEventParameter event parameter */ @@ -644,7 +707,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer /** * Raises OnItemCommand event. - * This method is invoked when a button control raises Command event. + * This method is invoked when a button control raises OnCommand event. * @param TDataGridItemCommandEventParameter event parameter */ public function onItemCommand($param) @@ -654,7 +717,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer /** * Raises OnSortCommand event. - * This method is invoked when a button control raises Command event + * This method is invoked when a button control raises OnCommand event * with sort command name. * @param TDataGridSortCommandEventParameter event parameter */ @@ -665,7 +728,7 @@ class TDataGrid extends TBaseDataList implements INamingContainer /** * Raises OnUpdateCommand event. - * This method is invoked when a button control raises Command event + * This method is invoked when a button control raises OnCommand event * with update 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 + * @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 - * HeaderText, HeaderStyle, FooterText, and FooterStyle. - * If HeaderImageUrl is specified, the image will be displayed instead in the header cell. - * The ItemStyle 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 SortExpression 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 EditText, UpdateText - * and CancelText. + * 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 ButtonType property. + * by setting the {@link setButtonType ButtonType} property. * - * When an edit button is clicked, the datagrid will generate an OnEditCommand - * event. When an update/cancel button is clicked, the datagrid will generate an - * OnUpdateCommand or an OnCancelCommand. 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 * @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 Text and NavigateUrl - * properties, respectively. You can also bind the text and url to specific - * data field in datasource by setting DataTextField and DataNavigateUrlField. - * Both can be formatted before rendering according to the DataTextFormatString - * and DataNavigateUrlFormatString properties, respectively. - * If both Text and DataTextField are present, the latter takes precedence. - * The same rule applies to NavigateUrl and DataNavigateUrlField 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 * @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 ItemTemplate, EditItemTemplate - * HeaderTemplate and FooterTemplate 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 * @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) -- cgit v1.2.3