From d1384deb9b3ac872defd08fd01fbf8cf11442b45 Mon Sep 17 00:00:00 2001 From: xue <> Date: Wed, 4 Jan 2006 04:59:01 +0000 Subject: Added documentation. --- framework/Exceptions/messages.txt | 7 +- framework/Web/UI/TPageStatePersister.php | 67 +++- framework/Web/UI/TTemplateManager.php | 16 +- framework/Web/UI/WebControls/TBulletedList.php | 20 +- framework/Web/UI/WebControls/TCheckBoxList.php | 127 +++++++- framework/Web/UI/WebControls/TDataBoundControl.php | 38 ++- .../Web/UI/WebControls/TDataSourceControl.php | 19 ++ framework/Web/UI/WebControls/TDataSourceView.php | 19 ++ framework/Web/UI/WebControls/TDropDownList.php | 46 ++- framework/Web/UI/WebControls/TListBox.php | 65 +++- framework/Web/UI/WebControls/TListControl.php | 344 +++++++++++++++++---- framework/Web/UI/WebControls/TRadioButtonList.php | 38 +++ framework/Web/UI/WebControls/TRepeatInfo.php | 25 +- framework/Web/UI/WebControls/TTextBox.php | 3 +- 14 files changed, 736 insertions(+), 98 deletions(-) (limited to 'framework') diff --git a/framework/Exceptions/messages.txt b/framework/Exceptions/messages.txt index c260255d..9869cc8c 100644 --- a/framework/Exceptions/messages.txt +++ b/framework/Exceptions/messages.txt @@ -149,4 +149,9 @@ hiddenfield_skinid_unsupported = THiddenField does not support control skin. panel_defaultbutton_invalid = TPanel.DefaultButton '%s' does not refer to an existing button control. tablestyle_cellpadding_invalid = TTableStyle.CellPadding must take an integer equal to or greater than -1. -tablestyle_cellspacing_invalid = TTableStyle.CellSpacing must take an integer equal to or greater than -1. \ No newline at end of file +tablestyle_cellspacing_invalid = TTableStyle.CellSpacing must take an integer equal to or greater than -1. + +pagestatepersister_pagestate_corrupted = Page state is corrupted. +pagestatepersister_privatekey_invalid = TPageStatePersister.PrivateKey must take a string no shorter than 8 characters. + +listitemcollection_item_invalid = TListItemCollection can only take strings or TListItem objects. \ No newline at end of file diff --git a/framework/Web/UI/TPageStatePersister.php b/framework/Web/UI/TPageStatePersister.php index 9c9954de..d312ed84 100644 --- a/framework/Web/UI/TPageStatePersister.php +++ b/framework/Web/UI/TPageStatePersister.php @@ -1,12 +1,44 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI + */ +/** + * TPageStatePersister class + * + * TPageStatePersister implements a page state persistent method based on + * form hidden fields. It is the default way of storing page state. + * Should you need to access this module, you may get it via + * {@link TPageService::getPageStatePersister}. + * + * TPageStatePersister uses a private key to generate a private unique hash + * code to prevent the page state from being tampered. + * By default, the private key is a randomly generated string. + * You may specify it explicitly by setting the {@link setPrivateKey PrivateKey} property. + * This may be useful if your application is running on a server farm. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI + * @since 3.0 + */ class TPageStatePersister extends TModule implements IStatePersister { + /** + * @var string private key + */ private $_privateKey=null; /** - * Initializes the service. - * This method is required by IModule interface. + * Registers the module with the page service. + * This method is required by IModule interface and is invoked when the module is initialized. * @param TXmlElement module configuration */ public function init($config) @@ -14,6 +46,10 @@ class TPageStatePersister extends TModule implements IStatePersister $this->getService()->setPageStatePersister($this); } + /** + * Saves state in hidden fields. + * @param mixed state to be stored + */ public function save($state) { $data=Prado::serialize($state); @@ -25,6 +61,11 @@ class TPageStatePersister extends TModule implements IStatePersister $this->getService()->getRequestedPage()->getClientScript()->registerHiddenField(TPage::FIELD_PAGESTATE,base64_encode($data)); } + /** + * Loads page state from hidden fields. + * @return mixed the restored state + * @throws THttpException if page state is corrupted + */ public function load() { $str=base64_decode($this->getApplication()->getRequest()->getItems()->itemAt(TPage::FIELD_PAGESTATE)); @@ -41,9 +82,14 @@ class TPageStatePersister extends TModule implements IStatePersister if($hmac===$this->computeHMAC($state,$this->getPrivateKey())) return Prado::unserialize($state); } - throw new TInvalidDataValueException('pagestatepersister_viewstate_corrupted.'); + throw new THttpException(400,'pagestatepersister_pagestate_corrupted'); } + /** + * Generates a random private key used for hashing the state. + * You may override this method to provide your own way of private key generation. + * @return string the rondomly generated private key + */ protected function generatePrivateKey() { $v1=rand(); @@ -52,6 +98,9 @@ class TPageStatePersister extends TModule implements IStatePersister return md5("$v1$v2$v3"); } + /** + * @return string private key used for hashing the state. + */ public function getPrivateKey() { if(empty($this->_privateKey)) @@ -65,13 +114,23 @@ class TPageStatePersister extends TModule implements IStatePersister return $this->_privateKey; } + /** + * @param string private key used for hashing the state. + * @throws TInvalidDataValueException if the length of the private key is shorter than 8. + */ public function setPrivateKey($value) { if(strlen($value)<8) - throw new TConfigurationException('pagestatepersister_privatekey_invalid'); + throw new TInvalidDataValueException('pagestatepersister_privatekey_invalid'); $this->_privateKey=$value; } + /** + * Computes a hashing code based on the input data and the private key. + * @param string input data + * @param string the private key + * @return string the hashing code + */ private function computeHMAC($data,$key) { if (strlen($key) > 64) diff --git a/framework/Web/UI/TTemplateManager.php b/framework/Web/UI/TTemplateManager.php index 0187dfd9..cb44b81d 100644 --- a/framework/Web/UI/TTemplateManager.php +++ b/framework/Web/UI/TTemplateManager.php @@ -15,9 +15,13 @@ * * TTemplateManager manages the loading and parsing of control templates. * - * Given a class name, TTemplateManager tries to locate the corresponding template - * file under the directory containing the class file. The name of the template file - * is the class name with the extension '.tpl'. + * There are two ways of loading a template, either by the associated template + * control class name, or the template file name. + * The former is via calling {@link getTemplateByClassName}, which tries to + * locate the corresponding template file under the directory containing + * the class file. The name of the template file is the class name with + * the extension '.tpl'. To load a template from a template file path, + * call {@link getTemplateByFileName}. * * By default, TTemplateManager is registered with {@link TPageService} as the * template manager module that can be accessed via {@link TPageService::getTemplateManager()}. @@ -115,7 +119,7 @@ class TTemplateManager extends TModule * A TTemplate object represents a parsed PRADO template. To instantiate the template * for a particular control, call {@link instantiateIn($control)}, which * will create and intialize all components specified in the template and - * set their parent as the control. + * set their parent as $control. * * @author Qiang Xue * @version $Revision: $ $Date: $ @@ -129,8 +133,8 @@ class TTemplate extends TComponent implements ITemplate * '' - HTML comments * '<\/?com:([\w\.]+)((?:\s*[\w\.]+=\'.*?\'|\s*[\w\.]+=".*?"|\s*[\w\.]+=<%.*?%>)*)\s*\/?>' - component tags * '<\/?prop:([\w\.]+)\s*>' - property tags - * '<%@\s*(\w+)((?:\s*[\w\.]+=\'.*?\'|\s*[\w\.]+=".*?")*)\s*%>' - directives - * '<%=?(.*?)%> | <%#(.*?)%>' - expressions + * '<%@\s*((?:\s*[\w\.]+=\'.*?\'|\s*[\w\.]+=".*?")*)\s*%>' - directives + * '<%[%#~\\$=](.*?)%>' - expressions */ const REGEX_RULES='/||<\/?com:([\w\.]+)((?:\s*[\w\.]+=\'.*?\'|\s*[\w\.]+=".*?"|\s*[\w\.]+=<%.*?%>)*)\s*\/?>|<\/?prop:([\w\.]+)\s*>|<%@\s*((?:\s*[\w\.]+=\'.*?\'|\s*[\w\.]+=".*?")*)\s*%>|<%[%#~\\$=](.*?)%>/msS'; diff --git a/framework/Web/UI/WebControls/TBulletedList.php b/framework/Web/UI/WebControls/TBulletedList.php index f2540644..8190f9ec 100644 --- a/framework/Web/UI/WebControls/TBulletedList.php +++ b/framework/Web/UI/WebControls/TBulletedList.php @@ -1,5 +1,23 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ + +/** + * TBulletedList class + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TBulletedList extends TListControl implements IPostBackEventHandler { private $_isEnabled; diff --git a/framework/Web/UI/WebControls/TCheckBoxList.php b/framework/Web/UI/WebControls/TCheckBoxList.php index f351acba..cceb217e 100644 --- a/framework/Web/UI/WebControls/TCheckBoxList.php +++ b/framework/Web/UI/WebControls/TCheckBoxList.php @@ -1,7 +1,44 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ +/** + * Includes TRepeatInfo class + */ Prado::using('System.Web.UI.WebControls.TRepeatInfo'); +/** + * TCheckBoxList class + * + * TCheckBoxList displays a list of checkboxes on a Web page. + * + * The layout of the checkbox list is specified via {@link setRepeatLayout RepeatLayout}, + * which can be either 'Table' (default) or 'Flow'. + * A table layout uses HTML table cells to organize the checkboxes while + * a flow layout uses line breaks to organize the checkboxes. + * When the layout is using 'Table', {@link setCellPadding CellPadding} and + * {@link setCellSpacing CellSpacing} can be used to adjust the cellpadding and + * cellpadding of the table. + * + * The number of columns used to display the checkboxes is specified via + * {@link setRepeatColumns RepeatColumns} property, while the {@link setRepeatDirection RepeatDirection} + * governs the order of the items being rendered. + * + * The alignment of the text besides each checkbox can be specified via {@link setTextAlign TextAlign}. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TCheckBoxList extends TListControl implements IRepeatInfoUser, INamingContainer, IPostBackDataHandler { private $_repeatedControl; @@ -17,26 +54,48 @@ class TCheckBoxList extends TListControl implements IRepeatInfoUser, INamingCont $this->getControls()->add($this->_repeatedControl); } + /** + * Creates a control used for repetition (used as a template). + * @return TControl the control to be repeated + */ protected function createRepeatedControl() { return new TCheckBox; } + /** + * Finds a control by ID. + * This method overrides the parent implementation so that it always returns + * the checkbox list itself (because the checkbox list does not have child controls.) + * @param string control ID + * @return TControl control being found + */ public function findControl($id) { return $this; } + /** + * @return boolean whether this control supports multiple selection. Always true for checkbox list. + */ protected function getIsMultiSelect() { return true; } + /** + * Creates a style object for the control. + * This method creates a {@link TTableStyle} to be used by checkbox list. + * @return TStyle control style to be used + */ protected function createStyle() { return new TTableStyle; } + /** + * @return TRepeatInfo repeat information (primarily used by control developers) + */ protected function getRepeatInfo() { if(($repeatInfo=$this->getViewState('RepeatInfo',null))===null) @@ -155,34 +214,56 @@ class TCheckBoxList extends TListControl implements IRepeatInfoUser, INamingCont $this->getStyle()->setCellPadding($value); } + /** + * Returns a value indicating whether this control contains header item. + * This method is required by {@link IRepeatInfoUser} interface. + * @return boolean always false. + */ public function getHasHeader() { return false; } + /** + * Returns a value indicating whether this control contains footer item. + * This method is required by {@link IRepeatInfoUser} interface. + * @return boolean always false. + */ public function getHasFooter() { return false; } + /** + * Returns a value indicating whether this control contains separator items. + * This method is required by {@link IRepeatInfoUser} interface. + * @return boolean always false. + */ public function getHasSeparators() { return false; } + /** + * Returns a style used for rendering items. + * This method is required by {@link IRepeatInfoUser} interface. + * @param string item type + * @param integer index of the item being rendered + * @return null + */ public function getItemStyle($itemType,$index) { return null; } - public function getRepeatedItemCount() - { - if($this->getHasItems()) - return $this->getItems()->getCount(); - else - return 0; - } - + /** + * Renders an item in the list. + * This method is required by {@link IRepeatInfoUser} interface. + * @param THtmlWriter writer for rendering purpose + * @param TRepeatInfo repeat information + * @param string item type (Header,Footer,Item,AlternatingItem,SelectedItem,EditItem,Separator,Pager) + * @param integer zero-based index of the item in the item list + */ public function renderItem($writer,$repeatInfo,$itemType,$index) { $item=$this->getItems()->itemAt($index); @@ -198,13 +279,20 @@ class TCheckBoxList extends TListControl implements IRepeatInfoUser, INamingCont $this->_repeatedControl->renderControl($writer); } + /** + * Loads user input data. + * This method is primarly used by framework developers. + * @param string the key that can be used to retrieve data from the input data collection + * @param array the input data collection + * @return boolean whether the data of the control has been changed + */ public function loadPostData($key,$values) { if($this->getEnabled(true)) { $index=(int)substr($key,strlen($this->getUniqueID())+1); $this->ensureDataBound(); - if($index>=0 && $index<$this->getRepeatedItemCount()) + if($index>=0 && $index<$this->getItemCount()) { $item=$this->getItems()->itemAt($index); if($item->getEnabled()) @@ -225,6 +313,13 @@ class TCheckBoxList extends TListControl implements IRepeatInfoUser, INamingCont return false; } + /** + * Raises postdata changed event. + * This method is required by {@link IPostBackDataHandler} interface. + * It is invoked by the framework when {@link getSelectedIndices SelectedIndices} property + * is changed on postback. + * This method is primarly used by framework developers. + */ public function raisePostDataChangedEvent() { $page=$this->getPage(); @@ -237,6 +332,11 @@ class TCheckBoxList extends TListControl implements IRepeatInfoUser, INamingCont $this->onSelectedIndexChanged(null); } + /** + * Registers for post data on postback. + * This method overrides the parent implementation. + * @param mixed event parameter + */ protected function onPreRender($param) { parent::onPreRender($param); @@ -244,7 +344,7 @@ class TCheckBoxList extends TListControl implements IRepeatInfoUser, INamingCont $this->_repeatedControl->setCausesValidation($this->getCausesValidation()); $this->_repeatedControl->setValidationGroup($this->getValidationGroup()); $page=$this->getPage(); - $n=$this->getRepeatedItemCount(); + $n=$this->getItemCount(); for($i=0;$i<$n;++$i) { $this->_repeatedControl->setID("$i"); @@ -252,9 +352,14 @@ class TCheckBoxList extends TListControl implements IRepeatInfoUser, INamingCont } } + /** + * Renders the checkbox list control. + * This method overrides the parent implementation. + * @param THtmlWriter writer for rendering purpose. + */ protected function render($writer) { - if($this->getRepeatedItemCount()>0) + if($this->getItemCount()>0) { $this->_isEnabled=$this->getEnabled(true); $repeatInfo=$this->getRepeatInfo(); diff --git a/framework/Web/UI/WebControls/TDataBoundControl.php b/framework/Web/UI/WebControls/TDataBoundControl.php index 8f447607..9eca4434 100644 --- a/framework/Web/UI/WebControls/TDataBoundControl.php +++ b/framework/Web/UI/WebControls/TDataBoundControl.php @@ -1,4 +1,23 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ + +/** + * TBulletedList class + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ abstract class TDataBoundControl extends TWebControl { @@ -280,11 +299,24 @@ abstract class TDataBoundControl extends TWebControl */ protected function validateDataSource($value) { - if(is_array($value)) + if(is_string($value)) + { + $list=new TList; + foreach(TPropertyValue::ensureArray($value) as $key=>$value) + { + if(is_array($value)) + $list->add($value); + else + $list->add(array($value,is_string($key)?$key:$value)); + } + return $list; + } + else if(is_array($value)) $value=new TList($value); - else if($value!==null && !($value instanceof Traversable)) + else if(($value instanceof Traversable) || $value===null) + return $value; + else throw new TInvalidDataTypeException('databoundcontrol_datasource_invalid'); - return $value; } public function getDataMember() diff --git a/framework/Web/UI/WebControls/TDataSourceControl.php b/framework/Web/UI/WebControls/TDataSourceControl.php index 6814e872..b46338b1 100644 --- a/framework/Web/UI/WebControls/TDataSourceControl.php +++ b/framework/Web/UI/WebControls/TDataSourceControl.php @@ -1,4 +1,23 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ + +/** + * TBulletedList class + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ interface IDataSource { diff --git a/framework/Web/UI/WebControls/TDataSourceView.php b/framework/Web/UI/WebControls/TDataSourceView.php index e988af15..36b4ef2d 100644 --- a/framework/Web/UI/WebControls/TDataSourceView.php +++ b/framework/Web/UI/WebControls/TDataSourceView.php @@ -1,4 +1,23 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ + +/** + * TBulletedList class + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TDataSourceSelectParameters extends TComponent { diff --git a/framework/Web/UI/WebControls/TDropDownList.php b/framework/Web/UI/WebControls/TDropDownList.php index 9b9b1b92..d56e3e7e 100644 --- a/framework/Web/UI/WebControls/TDropDownList.php +++ b/framework/Web/UI/WebControls/TDropDownList.php @@ -1,13 +1,45 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ +/** + * TDropDownList class + * + * TDropDownList displays a dropdown list on a Web page. + * It inherits all properties and events from {@link TListControl}. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TDropDownList extends TListControl implements IPostBackDataHandler { + /** + * Adds attributes to renderer. + * @param THtmlWriter the renderer + */ protected function addAttributesToRender($writer) { $writer->addAttribute('name',$this->getUniqueID()); parent::addAttributesToRender($writer); } + /** + * Loads user input data. + * This method is primarly used by framework developers. + * @param string the key that can be used to retrieve data from the input data collection + * @param array the input data collection + * @return boolean whether the data of the component has been changed + */ public function loadPostData($key,$values) { if(!$this->getEnabled(true)) @@ -26,6 +58,13 @@ class TDropDownList extends TListControl implements IPostBackDataHandler return false; } + /** + * Raises postdata changed event. + * This method is required by {@link IPostBackDataHandler} interface. + * It is invoked by the framework when {@link getSelectedIndex SelectedIndex} property + * is changed on postback. + * This method is primarly used by framework developers. + */ public function raisePostDataChangedEvent() { $page=$this->getPage(); @@ -38,10 +77,15 @@ class TDropDownList extends TListControl implements IPostBackDataHandler $this->onSelectedIndexChanged(null); } + /** + * @return integer the index (zero-based) of the item being selected. + * If none is selected, the return value is 0 meaning the first item is selected. + * If there is no items, it returns -1. + */ public function getSelectedIndex() { $index=parent::getSelectedIndex(); - if($index<0 && $this->getItems()->getCount()>0) + if($index<0 && $this->getHasItems()) { $this->setSelectedIndex(0); return 0; diff --git a/framework/Web/UI/WebControls/TListBox.php b/framework/Web/UI/WebControls/TListBox.php index 02e07013..db99edc5 100644 --- a/framework/Web/UI/WebControls/TListBox.php +++ b/framework/Web/UI/WebControls/TListBox.php @@ -1,7 +1,36 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ +/** + * TListBox class + * + * TListBox displays a list box on a Web page that allows single or multiple selection. + * The list box allows multiple selections if {@link setSelectionMode SelectionMode} + * is 'Multiple'. It takes single selection only if 'Single'. + * The property {@link setRows Rows} specifies how many rows of options are visible + * at a time. See {@link TListControl} for inherited properties. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TListBox extends TListControl implements IPostBackDataHandler { + /** + * Adds attribute name-value pairs to renderer. + * This method overrides the parent implementation with additional list box specific attributes. + * @param THtmlWriter the writer used for the rendering purpose + */ protected function addAttributesToRender($writer) { $rows=$this->getRows(); @@ -13,6 +42,11 @@ class TListBox extends TListControl implements IPostBackDataHandler parent::addAttributesToRender($writer); } + /** + * Registers the list control to load post data on postback. + * This method overrides the parent implementation. + * @param mixed event parameter + */ protected function onPreRender($param) { parent::onPreRender($param); @@ -20,6 +54,13 @@ class TListBox extends TListControl implements IPostBackDataHandler $this->getPage()->registerRequiresPostData($this); } + /** + * Loads user input data. + * This method is primarly used by framework developers. + * @param string the key that can be used to retrieve data from the input data collection + * @param array the input data collection + * @return boolean whether the data of the component has been changed + */ public function loadPostData($key,$values) { if(!$this->getEnabled(true)) @@ -76,6 +117,13 @@ class TListBox extends TListControl implements IPostBackDataHandler return false; } + /** + * Raises postdata changed event. + * This method is required by {@link IPostBackDataHandler} interface. + * It is invoked by the framework when {@link getSelectedIndices SelectedIndices} property + * is changed on postback. + * This method is primarly used by framework developers. + */ public function raisePostDataChangedEvent() { $page=$this->getPage(); @@ -88,18 +136,16 @@ class TListBox extends TListControl implements IPostBackDataHandler $this->onSelectedIndexChanged(null); } + /** + * @return boolean whether this control allows multiple selection + */ protected function getIsMultiSelect() { return $this->getSelectionMode()==='Multiple'; } - public function getSelectedIndices() - { - return parent::getSelectedIndices(); - } - /** - * @return integer the number of rows to be displayed in the component + * @return integer the number of rows to be displayed in the list control */ public function getRows() { @@ -107,8 +153,7 @@ class TListBox extends TListControl implements IPostBackDataHandler } /** - * Sets the number of rows to be displayed in the component - * @param integer the number of rows + * @param integer the number of rows to be displayed in the list control */ public function setRows($value) { @@ -119,7 +164,7 @@ class TListBox extends TListControl implements IPostBackDataHandler } /** - * @return string the selection mode (Single, Multiple ) + * @return string the selection mode (Single, Multiple). Defaults to 'Single'. */ public function getSelectionMode() { @@ -127,7 +172,7 @@ class TListBox extends TListControl implements IPostBackDataHandler } /** - * Sets the selection mode of the component (Single, Multiple) + * Sets the selection mode of the list control (Single, Multiple) * @param string the selection mode */ public function setSelectionMode($value) diff --git a/framework/Web/UI/WebControls/TListControl.php b/framework/Web/UI/WebControls/TListControl.php index 860cbc48..582e03bd 100644 --- a/framework/Web/UI/WebControls/TListControl.php +++ b/framework/Web/UI/WebControls/TListControl.php @@ -1,11 +1,83 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ + +/** + * TListControl class + * + * TListControl is a base class for list controls, such as {@link TListBox}, + * {@link TDropDownList}, {@link TCheckBoxList}, etc. + * It manages the items and their status in a list control. + * It also implements how the items can be populated from template and + * data source. + * + * The property {@link getItems} returns a list of the items in the control. + * To specify or determine which item is selected, use the + * {@link getSelectedIndex SelectedIndex} property that indicates the zero-based + * index of the selected item in the item list. You may also use + * {@link getSelectedItem SelectedItem} and {@link getSelectedValue SelectedValue} + * to get the selected item and its value. For multiple selection lists + * (such as {@link TCheckBoxList} and {@link TListBox}), property + * {@link getSelectedIndices SelectedIndices} is useful. + * + * TListControl implements {@link setAutoPostBack AutoPostBack} which allows + * a list control to postback the page if the selections of the list items are changed. + * The {@link setCausesValidation CausesValidation} and {@link setValidationGroup ValidationGroup} + * properties may be used to specify that validation be performed when auto postback occurs. + * + * There are three ways to populate the items in a list control: from template, + * using {@link setDataSource DataSource} and using {@link setDataSourceID DataSourceID}. + * The latter two are covered in {@link TDataBoundControl}. To specify items via + * template, using the following template syntax: + * + * <com:TListControl> + * <com:TListItem Value="xxx" Text="yyy" > + * <com:TListItem Value="xxx" Text="yyy" Selected="true" > + * <com:TListItem Value="xxx" Text="yyy" > + * </com:TListControl> + * + * + * When {@link setDataSource DataSource} or {@link setDataSourceID DataSourceID} + * is used to populate list items, the {@link setDataTextField DataTextField} and + * {@link setDataValueField DataValueField} properties are used to specify which + * columns of the data will be used to populate the text and value of the items. + * For example, if a data source is as follows, + * + * $dataSource=array( + * array('name'=>'John', 'age'=>31), + * array('name'=>'Cary', 'age'=>28), + * array('name'=>'Rose', 'age'=>35), + * ); + * + * setting {@link setDataTextField DataTextField} and {@link setDataValueField DataValueField} + * to 'name' and 'age' will make the first item's text be 'John', value be 31, + * the second item's text be 'Cary', value be 28, and so on. + * The {@link setDataTextFormatString DataTextFormatString} property may be further + * used to format how the item should be displayed. The formatting function is + * the sprintf() PHP function. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ abstract class TListControl extends TDataBoundControl { + /** + * @var TListItemCollection item list + */ private $_items=null; /** - * @return string tag name of the textbox + * @return string tag name of the list control */ protected function getTagName() { @@ -35,6 +107,9 @@ abstract class TListControl extends TDataBoundControl parent::addAttributesToRender($writer); } + /** + * @return TPostBackOptions postback options for JS postback code + */ protected function getAutoPostBackOptions() { $option=new TPostBackOptions(); @@ -49,28 +124,28 @@ abstract class TListControl extends TDataBoundControl return $option; } + /** + * Adds object parsed from template to the control. + * This method adds only {@link TListItem} objects into the {@link getItems Items} collection. + * All other objects are ignored. + * @param mixed object parsed from template + */ public function addParsedObject($object) { if($object instanceof TListItem) $this->getItems()->add($object); } - protected function validateDataSource($value) - { - if(is_string($value)) - { - $list=new TList; - foreach(TPropertyValue::ensureArray($value) as $key=>$value) - $list->add(array($value,is_string($key)?$key:$value)); - return $list; - } - else - return parent::validateDataSource($value); - return $value; - } - + /** + * Performs databinding to populate list items from data source. + * This method is invoked by dataBind(). + * You may override this function to provide your own way of data population. + * @param Traversable the data + */ protected function performDataBinding($data) { + if(!$this->getAppendDataBoundItems()) + $items->clear(); if($data instanceof Traversable) { $textField=$this->getDataTextField(); @@ -81,8 +156,6 @@ abstract class TListControl extends TDataBoundControl $valueField=1; $textFormat=$this->getDataTextFormatString(); $items=$this->getItems(); - if(!$this->getAppendDataBoundItems()) - $items->clear(); foreach($data as $object) { $item=new TListItem; @@ -98,6 +171,11 @@ abstract class TListControl extends TDataBoundControl } } + /** + * Saves items into viewstate. + * This method is invoked right before control state is to be saved. + * @param mixed event parameter + */ protected function onSaveState($param) { if($this->_items) @@ -106,22 +184,36 @@ abstract class TListControl extends TDataBoundControl $this->clearViewState('Items'); } + /** + * Loads items into from viewstate. + * This method is invoked right after control state is loaded. + * @param mixed event parameter + */ protected function onLoadState($param) { $this->_items=new TListItemCollection; $this->_items->loadState($this->getViewState('Items',null)); } + /** + * @return boolean whether this is a multiselect control. Defaults to false. + */ protected function getIsMultiSelect() { return false; } + /** + * @return boolean whether performing databind should append items or clear the existing ones. Defaults to false. + */ public function getAppendDataBoundItems() { return $this->getViewState('AppendDataBoundItems',false); } + /** + * @param boolean whether performing databind should append items or clear the existing ones. + */ public function setAppendDataBoundItems($value) { $this->setViewState('AppendDataBoundItems',TPropertyValue::ensureBoolean($value),false); @@ -129,8 +221,8 @@ abstract class TListControl extends TDataBoundControl /** * @return boolean a value indicating whether an automatic postback to the server - * will occur whenever the user modifies the text in the TTextBox control and - * then tabs out of the component. Defaults to false. + * will occur whenever the user makes change to the list control and then tabs out of it. + * Defaults to false. */ public function getAutoPostBack() { @@ -140,7 +232,7 @@ abstract class TListControl extends TDataBoundControl /** * Sets the value indicating if postback automatically. * An automatic postback to the server will occur whenever the user - * modifies the text in the TTextBox control and then tabs out of the component. + * makes change to the list control and then tabs out of it. * @param boolean the value indicating if postback automatically */ public function setAutoPostBack($value) @@ -149,7 +241,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @return boolean whether postback event trigger by this text box will cause input validation, default is true. + * @return boolean whether postback event trigger by this list control will cause input validation, default is true. */ public function getCausesValidation() { @@ -157,8 +249,7 @@ abstract class TListControl extends TDataBoundControl } /** - * Sets the value indicating whether postback event trigger by this text box will cause input validation. - * @param boolean whether postback event trigger by this button will cause input validation. + * @param boolean whether postback event trigger by this list control will cause input validation. */ public function setCausesValidation($value) { @@ -190,6 +281,9 @@ abstract class TListControl extends TDataBoundControl } /** + * Sets data text format string. + * The format string is used in sprintf() to format the Text property value + * of each item in the list control. * @param string the formatting string used to control how data bound to the list control is displayed. */ public function setDataTextFormatString($value) @@ -213,11 +307,25 @@ abstract class TListControl extends TDataBoundControl $this->setViewState('DataValueField',$value,''); } + /** + * @return integer the number of items in the list control + */ + public function getItemCount() + { + return $this->_items?$this->_items->getCount():0; + } + + /** + * @return boolean whether the list control contains any items. + */ public function getHasItems() { return ($this->_items && $this->_items->getCount()>0); } + /** + * @return TListItemCollection the item collection + */ public function getItems() { if(!$this->_items) @@ -226,7 +334,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @return integer the index of the item being selected, -1 if no selection + * @return integer the index (zero-based) of the item being selected, -1 if no item is selected. */ public function getSelectedIndex() { @@ -241,7 +349,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @param integer the index of the item to be selected + * @param integer the index (zero-based) of the item to be selected */ public function setSelectedIndex($index) { @@ -254,6 +362,9 @@ abstract class TListControl extends TDataBoundControl } } + /** + * @return array list of index of items that are selected + */ public function getSelectedIndices() { $selections=array(); @@ -267,6 +378,9 @@ abstract class TListControl extends TDataBoundControl return $selections; } + /** + * @param array list of index of items to be selected + */ public function setSelectedIndices($indices) { if($this->_items) @@ -282,7 +396,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @return TListItem|null the selected item with the lowest cardinal index, null if no selection. + * @return TListItem|null the selected item with the lowest cardinal index, null if no item is selected. */ public function getSelectedItem() { @@ -303,6 +417,8 @@ abstract class TListControl extends TDataBoundControl /** * Sets selection by item value. + * Existing selections will be cleared if the item value is found in the item collection. + * Note, if the value is null, existing selections will also be cleared. * @param string the value of the item to be selected. */ public function setSelectedValue($value) @@ -319,6 +435,9 @@ abstract class TListControl extends TDataBoundControl } } + /** + * Clears all existing selections. + */ public function clearSelection() { if($this->_items) @@ -329,24 +448,7 @@ abstract class TListControl extends TDataBoundControl } /** - * @return string the text content of the TTextBox control. - */ - public function getText() - { - return $this->getSelectedValue(); - } - - /** - * Sets the text content of the TTextBox control. - * @param string the text content - */ - public function setText($value) - { - $this->setSelectedValue($value); - } - - /** - * @return string the group of validators which the text box causes validation upon postback + * @return string the group of validators which the list control causes validation upon postback */ public function getValidationGroup() { @@ -354,24 +456,29 @@ abstract class TListControl extends TDataBoundControl } /** - * @param string the group of validators which the text box causes validation upon postback + * @param string the group of validators which the list control causes validation upon postback */ public function setValidationGroup($value) { $this->setViewState('ValidationGroup',$value,''); } + /** + * Raises SelectedIndexChanged event when selection is changed. + * This method is invoked when the list control has its selection changed + * by end-users. + * @param TEventParameter event parameter + */ public function onSelectedIndexChanged($param) { $this->raiseEvent('SelectedIndexChanged',$this,$param); } - // ???? - public function onTextChanged($param) - { - $this->raiseEvent('TextChanged',$this,$param); - } - + /** + * Renders body content of the list control. + * This method renders items contained in the list control as the body content. + * @param THtmlWriter writer + */ protected function renderContents($writer) { if($this->_items) @@ -399,10 +506,23 @@ abstract class TListControl extends TDataBoundControl } } +/** + * TListItemCollection class. + * + * TListItemCollection maintains a list of {@link TListItem} for {@link TListControl}. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TListItemCollection extends TList { - private $_items=null; - + /** + * Appends an item to the collection. + * @param TListItem the item to be appended. + * @throws TInvalidDataTypeException if the item being appended is neither a string nor a TListItem + */ public function add($item) { if(is_string($item)) @@ -413,6 +533,13 @@ class TListItemCollection extends TList throw new TInvalidDataTypeException('listitemcollection_item_invalid'); } + /** + * Inserts an item into the collection. + * @param integer the location where the item will be inserted. + * The current item at the place and the following ones will be moved backward. + * @param TListItem the item to be inserted. + * @throws TInvalidDataTypeException if the item being inserted is neither a string nor TListItem + */ public function insert($index,$item) { if(is_string($item)) @@ -423,6 +550,12 @@ class TListItemCollection extends TList throw new TInvalidDataTypeException('listitemcollection_item_invalid'); } + /** + * Finds the lowest cardinal index of the item whose value is the one being looked for. + * @param string the value to be looked for + * @param boolean whether to look for disabled items also + * @return integer the index of the item found, -1 if not found. + */ public function findIndexByValue($value,$includeDisabled=true) { $value=TPropertyValue::ensureString($value); @@ -436,6 +569,12 @@ class TListItemCollection extends TList return -1; } + /** + * Finds the lowest cardinal index of the item whose text is the one being looked for. + * @param string the text to be looked for + * @param boolean whether to look for disabled items also + * @return integer the index of the item found, -1 if not found. + */ public function findIndexByText($text,$includeDisabled=true) { $text=TPropertyValue::ensureString($text); @@ -449,6 +588,12 @@ class TListItemCollection extends TList return -1; } + /** + * Finds the item whose value is the one being looked for. + * @param string the value to be looked for + * @param boolean whether to look for disabled items also + * @return TListItem the item found, null if not found. + */ public function findItemByValue($value,$includeDisabled=true) { if(($index=$this->findIndexByValue($value,$includeDisabled))>=0) @@ -457,6 +602,12 @@ class TListItemCollection extends TList return null; } + /** + * Finds the item whose text is the one being looked for. + * @param string the text to be looked for + * @param boolean whether to look for disabled items also + * @return TListItem the item found, null if not found. + */ public function findItemByText($text,$includeDisabled=true) { if(($index=$this->findIndexByText($text,$includeDisabled))>=0) @@ -465,6 +616,11 @@ class TListItemCollection extends TList return null; } + /** + * Loads state into every item in the collection. + * This method should only be used by framework and control developers. + * @param array|null state to be loaded. + */ public function loadState($state) { $this->clear(); @@ -475,6 +631,11 @@ class TListItemCollection extends TList } } + /** + * Saves state of items. + * This method should only be used by framework and control developers. + * @return array|null the saved state + */ public function saveState() { if($this->getCount()>0) @@ -489,14 +650,51 @@ class TListItemCollection extends TList } } +/** + * TListItem class. + * + * TListItem represents an item in a list control. Each item has a {@link setText Text} + * property and a {@link setValue Value} property. If either one of them is not set, + * it will take the value of the other property. + * An item can be {@link setSelected Selected} or {@link setEnabled Enabled}, + * and it can have additional {@link getAttributes Attributes} which may be rendered + * if the list control supports so. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TListItem extends TComponent { + /** + * @var TMap list of custom attributes + */ private $_attributes=null; + /** + * @var string text of the item + */ private $_text; + /** + * @var string value of the item + */ private $_value; + /** + * @var boolean whether the item is enabled + */ private $_enabled; + /** + * @var boolean whether the item is selected + */ private $_selected; + /** + * Constructor. + * @param string text of the item + * @param string value of the item + * @param boolean whether the item is enabled + * @param boolean whether the item is selected + */ public function __construct($text='',$value='',$enabled=true,$selected=false) { $this->setText($text); @@ -505,46 +703,73 @@ class TListItem extends TComponent $this->setSelected($selected); } + /** + * @return boolean whether the item is enabled + */ public function getEnabled() { return $this->_enabled; } + /** + * @param boolean whether the item is enabled + */ public function setEnabled($value) { $this->_enabled=TPropertyValue::ensureBoolean($value); } + /** + * @return boolean whether the item is selected + */ public function getSelected() { return $this->_selected; } + /** + * @param boolean whether the item is selected + */ public function setSelected($value) { $this->_selected=TPropertyValue::ensureBoolean($value); } + /** + * @return string text of the item + */ public function getText() { return $this->_text===''?$this->_value:$this->_text; } + /** + * @param string text of the item + */ public function setText($value) { $this->_text=TPropertyValue::ensureString($value); } + /** + * @return string value of the item + */ public function getValue() { return $this->_value===''?$this->_text:$this->_value; } + /** + * @param string value of the item + */ public function setValue($value) { $this->_value=TPropertyValue::ensureString($value); } + /** + * @return TMap custom attributes + */ public function getAttributes() { if(!$this->_attributes) @@ -552,18 +777,25 @@ class TListItem extends TComponent return $this->_attributes; } + /** + * @return boolean whether the item has any custom attribute + */ public function getHasAttributes() { - return $this->_attributes!==null; + return $this->_attributes && $this->_attributes->getCount()>0; } + /** + * @param string name of the attribute + * @return boolean whether the named attribute exists + */ public function hasAttribute($name) { return $this->_attributes?$this->_attributes->contains($name):false; } /** - * @return string attribute value, '' if attribute does not exist + * @return string the named attribute value, null if attribute does not exist */ public function getAttribute($name) { diff --git a/framework/Web/UI/WebControls/TRadioButtonList.php b/framework/Web/UI/WebControls/TRadioButtonList.php index e434e709..2f12369b 100644 --- a/framework/Web/UI/WebControls/TRadioButtonList.php +++ b/framework/Web/UI/WebControls/TRadioButtonList.php @@ -1,17 +1,55 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ +/** + * TRadioButtonList class + * + * TRadioButtonList displays a list of radiobuttons on a Web page. + * + * TRadioButtonList inherits all properties and events of {@link TCheckBoxList}. + * Each TRadioButtonList displays one group of radiobuttons, i.e., at most + * one radiobutton can be selected at a time. + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ class TRadioButtonList extends TCheckBoxList { + /** + * @return boolean whether this control supports multiple selection. Always false for radiobutton list. + */ protected function getIsMultiSelect() { return false; } + /** + * Creates a control used for repetition (used as a template). + * @return TControl the control to be repeated + */ protected function createRepeatedControl() { return new TRadioButton; } + /** + * Loads user input data. + * This method is primarly used by framework developers. + * @param string the key that can be used to retrieve data from the input data collection + * @param array the input data collection + * @return boolean whether the data of the control has been changed + */ public function loadPostData($key,$values) { $value=isset($values[$key])?$values[$key]:''; diff --git a/framework/Web/UI/WebControls/TRepeatInfo.php b/framework/Web/UI/WebControls/TRepeatInfo.php index d3178c0c..389d09d5 100644 --- a/framework/Web/UI/WebControls/TRepeatInfo.php +++ b/framework/Web/UI/WebControls/TRepeatInfo.php @@ -1,11 +1,30 @@ + * @link http://www.pradosoft.com/ + * @copyright Copyright © 2005 PradoSoft + * @license http://www.pradosoft.com/license/ + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + */ + +/** + * TBulletedList class + * + * @author Qiang Xue + * @version $Revision: $ $Date: $ + * @package System.Web.UI.WebControls + * @since 3.0 + */ interface IRepeatInfoUser { public function getHasFooter(); public function getHasHeader(); public function getHasSeparators(); - public function getRepeatedItemCount(); + public function getItemCount(); public function getItemStyle($itemType,$index); public function renderItem($writer,$repeatInfo,$itemType,$index); } @@ -100,7 +119,7 @@ class TRepeatInfo extends TComponent { $tableLayout=($this->_repeatLayout==='Table'); $hasSeparators=$user->getHasSeparators(); - $itemCount=$user->getRepeatedItemCount(); + $itemCount=$user->getItemCount(); $columns=$this->_repeatColumns===0?$itemCount:$this->_repeatColumns; $totalColumns=$hasSeparators?$columns+$columns:$columns; $needBreak=$columns<$itemCount; @@ -175,7 +194,7 @@ class TRepeatInfo extends TComponent { $tableLayout=($this->_repeatLayout==='Table'); $hasSeparators=$user->getHasSeparators(); - $itemCount=$user->getRepeatedItemCount(); + $itemCount=$user->getItemCount(); if($this->_repeatColumns<=1) { $rows=$itemCount; diff --git a/framework/Web/UI/WebControls/TTextBox.php b/framework/Web/UI/WebControls/TTextBox.php index 00d75e75..e37b98b8 100644 --- a/framework/Web/UI/WebControls/TTextBox.php +++ b/framework/Web/UI/WebControls/TTextBox.php @@ -283,8 +283,7 @@ class TTextBox extends TWebControl implements IPostBackDataHandler, IValidatable } /** - * Sets the value indicating whether postback event trigger by this text box will cause input validation. - * @param boolean whether postback event trigger by this button will cause input validation. + * @param boolean whether postback event trigger by this text box will cause input validation. */ public function setCausesValidation($value) { -- cgit v1.2.3