TDataList completed. A preliminary demo added.

4 files changed, 535 insertions, 242 deletions

diff --git a/framework/Web/UI/WebControls/TDataList.php b/framework/Web/UI/WebControls/TDataList.php
index 666a344a..a9d23b9c 100644
--- a/framework/Web/UI/WebControls/TDataList.php
+++ b/framework/Web/UI/WebControls/TDataList.php
@@ -14,48 +14,68 @@
  * Includes TBaseDataList class

  */

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

-

+/**

+ * Includes TRepeatInfo class

+ */

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

 

 /**

  * TDataList class

  *

  * TDataList represents a data bound and updatable list control.

  *

- * It can be used to display and maintain a list of data items (rows, records).

- * There are three kinds of layout determined by the <b>RepeatLayout</b>

- * property. The <b>Table</b> layout displays a table and each table cell

- * contains a data item. The <b>Flow</b> layout uses the span tag to organize

- * the presentation of data items. The <b>Raw</b> layout displays all templated

- * content without any additional decorations (therefore, you can use arbitrary

- * complex UI layout). In case when the layout is Table or Flow,

- * the number of table/flow columns is determined by the <b>RepeatColumns</b>

- * property, and the data items are enumerated according to the <b>RepeatDirection</b> property.

+ * The {@link setHeaderTemplate HeaderTemplate} property specifies the content

+ * template that will be displayed at the beginning, while

+ * {@link setFooterTemplate FooterTemplate} at the end.

+ * If present, these two templates will only be rendered when the data list is

+ * given non-empty data. In this case, for each data item the content defined

+ * by {@link setItemTemplate ItemTemplate} will be generated and displayed once.

+ * If {@link setAlternatingItemTemplate AlternatingItemTemplate} is not empty,

+ * then the corresponding content will be displayed alternatively with that

+ * in {@link setItemTemplate ItemTemplate}. The content in

+ * {@link setSeparatorTemplate SeparatorTemplate}, if not empty, will be

+ * displayed between items. All these templates are associated with styles that

+ * may be applied to the corresponding generated items. For example,

+ * {@link getAlternatingItemStyle AlternatingItemStyle} will be applied to

+ * every alternating item in the data list.

+ *

+ * To change the status of a particular item, set {@link setSelectedItemIndex SelectedItemIndex}

+ * or {@link setEditItemIndex EditItemIndex}. The former will change the indicated

+ * item to selected mode, which will cause the item to use {@link setSelectedItemTemplate SelectedItemTemplate}

+ * for presentation. The latter will change the indicated item to edit mode.

+ * Note, if an item is in edit mode, then selecting this item will have no effect.

+ *

+ * The layout of the data items in the 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 data items while

+ * a flow layout uses line breaks to organize the data items.

+ * 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, and {@link setCaption Caption} and {@link setCaptionAlign CaptionAlign}

+ * can be used to add a table caption with the specified alignment.

+ *

+ * The number of columns used to display the data items is specified via

+ * {@link setRepeatColumns RepeatColumns} property, while the {@link setRepeatDirection RepeatDirection}

+ * governs the order of the items being rendered.

+ *

+ * You can retrive the repeated contents by the {@link getItems Items} property.

+ * The header and footer items can be accessed by {@link getHeader Header}

+ * and {@link getFooter Footer} properties, respectively.

  *

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

- * afterwards. The data will be populated into the TDataList and saved as data items.

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

- * The state determines which template is used to display the item.

- * In particular, data items are displayed using the following templates,

- * <b>ItemTemplate</b>, <b>AlternatingItemTemplate</b>,

- * <b>SelectedItemTemplate</b>, <b>EditItemTemplate</b>. In addition, the

- * <b>HeaderTemplate</b>, <b>FooterTemplate</b>, and <b>SeparatorTemplate</b>

- * can be used to decorate the overall presentation.

+ * When TDataList creates an item, it will raise an {@link onItemCreated ItemCreated}

+ * so that you may customize the newly created item.

+ * When databinding is performed by TDataList, for each item once it has finished

+ * databinding, an {@link onItemDataBound ItemDataBound} event will be raised.

  *

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

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

+ * When an item is selected by an end-user, a {@link onSelectedIndexChanged SelectedIndexChanged}

+ * event will be raised. Note, the selected index may not be actually changed.

+ * The event mainly informs the server side that the end-user has made a selection.

  *

- * When an item template contains a button control that raises an <b>OnCommand</b>

- * event, the event will be bubbled up to the data list control.

- * If the event's command name is recognizable by the data list 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

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

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

+ * TDataList raises an {@link onItemCommand ItemCommand} whenever a button control

+ * within some TDataList item raises a <b>Command</b> event. If the command name

+ * is one of the followings: 'edit', 'update', 'select', 'delete', 'cancel' (case-insensitive),

+ * another event will also be raised. For example, if the command name is 'select',

+ * then the new event is {@link onSelectCommand SelectCommand}.

  *

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

  * @version $Revision: $  $Date: $

@@ -86,6 +106,14 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 	private $_headerTemplate='';

 	private $_footerTemplate='';

 	private $_separatorTemplate='';

+	/**

+	 * @var TDatListItem header item

+	 */

+	private $_header=null;

+	/**

+	 * @var TDatListItem footer item

+	 */

+	private $_footer=null;

 

 	/**

 	 * @return TDataListItemCollection item list

@@ -251,6 +279,14 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 	}

 

 	/**

+	 * @return TDataListItem the header item

+	 */

+	public function getHeader()

+	{

+		return $this->_header;

+	}

+

+	/**

 	 * @return string the footer template string

 	 */

 	public function getFooterTemplate()

@@ -280,6 +316,14 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 	}

 

 	/**

+	 * @return TDataListItem the footer item

+	 */

+	public function getFooter()

+	{

+		return $this->_footer;

+	}

+

+	/**

 	 * @return TTableItemStyle the separator template string

 	 */

 	public function getSeparatorTemplate()

@@ -451,6 +495,39 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 	}

 

 	/**

+	 * @return string caption of the table layout

+	 */

+	public function getCaption()

+	{

+		return $this->getRepeatInfo()->getCaption();

+	}

+

+	/**

+	 * @param string caption of the table layout

+	 */

+	public function setCaption($value)

+	{

+		$this->getRepeatInfo()->setCaption($value);

+	}

+

+	/**

+	 * @return string alignment of the caption of the table layout. Defaults to 'NotSet'.

+	 */

+	public function getCaptionAlign()

+	{

+		return $this->getRepeatInfo()->getCaptionAlign();

+	}

+

+	/**

+	 * @return string alignment of the caption of the table layout.

+	 * Valid values include 'NotSet','Top','Bottom','Left','Right'.

+	 */

+	public function setCaptionAlign($value)

+	{

+		$this->getRepeatInfo()->setCaptionAlign($value);

+	}

+

+	/**

 	 * @return integer the number of columns that the list should be displayed with. Defaults to 0 meaning not set.

 	 */

 	public function getRepeatColumns()

@@ -651,7 +728,7 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 	 */

 	public function getHasHeader()

 	{

-		return ($this->getShowHeader() && $this->_headerTemplate!=='')

+		return ($this->getShowHeader() && $this->_headerTemplate!=='');

 	}

 

 	/**

@@ -661,7 +738,7 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 	 */

 	public function getHasFooter()

 	{

-		return ($this->getShowFooter() && $this->_footerTemplate!=='')

+		return ($this->getShowFooter() && $this->_footerTemplate!=='');

 	}

 

 	/**

@@ -689,6 +766,28 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 			return null;

 	}

 

+	/**

+	 * 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->getItem($itemType,$index);

+		if($repeatInfo->getRepeatLayout()==='Table')

+			$item->renderContents($writer);

+		else

+			$item->renderControl($writer);

+	}

+

+	/**

+	 * @param string item type

+	 * @param integer item index

+	 * @return TDataListItem data list item with the specified item type and index

+	 */

 	private function getItem($itemType,$index)

 	{

 		switch($itemType)

@@ -706,59 +805,126 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 					$i++;

 				return $this->getControls->itemAt($i);

 		}

-		return null

+		return null;

+	}

+

+	/**

+	 * Creates a data list item and does databinding if needed.

+	 * This method invokes {@link createItem} to create a new data list item.

+	 * @param integer zero-based item index.

+	 * @param string item type, may be 'Header', 'Footer', 'Item', 'Separator', 'AlternatingItem', 'SelectedItem', 'EditItem'.

+	 * @param boolean whether to do databinding for the item

+	 * @param mixed data to be associated with the item

+	 * @return TDataListItem the created item

+	 */

+	private function createItemInternal($itemIndex,$itemType,$dataBind,$dataItem)

+	{

+		$item=$this->createItem($itemIndex,$itemType);

+		$this->initializeItem($item);

+		$param=new TDataListItemEventParameter($item);

+		if($dataBind)

+		{

+			$item->setDataItem($dataItem);

+			$this->onItemCreated($param);

+			$this->getControls()->add($item);

+			$item->dataBind();

+			$this->onItemDataBound($param);

+			$item->setDataItem(null);

+		}

+		else

+		{

+			$this->onItemCreated($param);

+			$this->getControls()->add($item);

+		}

+		return $item;

+	}

+

+	/**

+	 * Creates a DataList item instance based on the item type and index.

+	 * @param integer zero-based item index

+	 * @param string item type, may be 'Header', 'Footer', 'Item', 'Separator', 'AlternatingItem', 'SelectedItem', 'EditItem'.

+	 * @return TDataListItem created data list item

+	 */

+	protected function createItem($itemIndex,$itemType)

+	{

+		return new TDataListItem($itemIndex,$itemType);

 	}

 

 	/**

 	 * Initializes a data list item.

 	 * The item is added as a child of the data list and the corresponding

 	 * template is instantiated within the item.

-	 * @param TRepeaterItem item to be initialized

+	 * @param TDataListItem item to be initialized

 	 */

 	protected function initializeItem($item)

 	{

 		$tplContent='';

+		$style=null;

 		switch($item->getItemType())

 		{

-			case 'Header': $tplContent=$this->_headerTemplate; break;

-			case 'Footer': $tplContent=$this->_footerTemplate; break;

-			case 'Item': $tplContent=$this->_itemTemplate; break;

+			case 'Header':

+				$tplContent=$this->_headerTemplate;

+				$style=$this->getViewState('HeaderStyle',null);

+				break;

+			case 'Footer':

+				$tplContent=$this->_footerTemplate;

+				$style=$this->getViewState('FooterStyle',null);

+				break;

+			case 'Item':

+				$tplContent=$this->_itemTemplate;

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

+				break;

 			case 'AlternatingItem':

-				if($this->_alternatingItemTemplate!=='')

-					$tplContent=$this->_alternatingItemTemplate;

-				else

+				if(($tplContent=$this->_alternatingItemTemplate)==='')

 					$tplContent=$this->_itemTemplate;

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

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

+				break;

+			case 'Separator':

+				$tplContent=$this->_separatorTemplate;

+				$style=$this->getViewState('SeparatorStyle',null);

 				break;

-			case 'Separator': $tplContent=$this->_separatorTemplate; break;

 			case 'SelectedItem':

-				if($this->_selectedItemTemplate==='')

+				if(($tplContent=$this->_selectedItemTemplate)==='')

 				{

-					if($item->getItemIndex()%2 && $this->_alternatingItemTemplate!=='')

-						$tplContent=$this->_alternatingItemTemplate;

-					else

+					if(!($item->getItemIndex()%2) || ($tplContent=$this->_alternatingItemTemplate)==='')

 						$tplContent=$this->_itemTemplate;

 				}

-				else

-					$tplContent=$this->_selectedItemTemplate;

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

+				{

+					if(!($item->getItemIndex()%2) || ($style=$this->getViewState('AlternatingItemStyle',null))===null)

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

+				}

 				break;

 			case 'EditItem':

-				if($this->_editItemTemplate==='')

+				if(($tplContent=$this->_editItemTemplate)==='')

 				{

-					if($item->getItemIndex()===$this->getSelectedIndex() && $this->_selectedItemTemplate!=='')

-						$tplContent=$this->_selectedItemTemplate;

-					else if($item->getItemIndex()%2 && $this->_alternatingItemTemplate!=='')

-						$tplContent=$this->_alternatingItemTemplate;

-					else

-						$tplContent=$this->_itemTemplate;

+					if($item->getItemIndex()!==$this->getSelectedItemIndex() || ($tplContent=$this->_selectedItemTemplate)==='')

+						if(!($item->getItemIndex()%2) || ($tplContent=$this->_alternatingItemTemplate)==='')

+							$tplContent=$this->_itemTemplate;

 				}

-				else

-					$tplContent=$this->_editItemTemplate;

-			default: break;

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

+				{

+					if($item->getItemIndex()!==$this->getSelectedItemIndex() || ($style=$this->getViewState('SelectedItemStyle',null))===null)

+						if(!($item->getItemIndex()%2) || ($style=$this->getViewState('AlternatingItemStyle',null))===null)

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

+				}

+				break;

+			default:

+				break;

 		}

 		if($tplContent!=='')

 			$this->createTemplate($tplContent)->instantiateIn($item);

+		if($style!==null)

+			$item->getStyle()->copyFrom($style);

 	}

 

+	/**

+	 * Parses item template.

+	 * This method uses caching technique to accelerate template parsing.

+	 * @param string template string

+	 * @return ITemplate parsed template object

+	 */

 	protected function createTemplate($str)

 	{

 		$key=md5($str);

@@ -785,51 +951,133 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 	}

 

 	/**

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

+	 * Saves item count in viewstate.

+	 * This method is invoked right before control state is to be saved.

+	 * @param mixed event parameter

 	 */

-	public function renderItem($writer,$repeatInfo,$itemType,$index)

+	protected function onSaveState($param)

 	{

-		$item=$this->getItems()->itemAt($index);

-		if($item->getHasAttributes())

-			$this->_repeatedControl->getAttributes()->copyFrom($item->getAttributes());

-		else if($this->_repeatedControl->getHasAttributes())

-			$this->_repeatedControl->getAttributes()->clear();

-		$this->_repeatedControl->setID("$index");

-		$this->_repeatedControl->setText($item->getText());

-		$this->_repeatedControl->setChecked($item->getSelected());

-		$this->_repeatedControl->setAttribute('value',$item->getValue());

-		$this->_repeatedControl->setEnabled($this->_isEnabled && $item->getEnabled());

-		$this->_repeatedControl->renderControl($writer);

+		if($this->_items)

+			$this->setViewState('ItemCount',$this->_items->getCount(),0);

+		else

+			$this->clearViewState('ItemCount');

 	}

 

-	// how to save item state??? c.f. TRepeater

+	/**

+	 * Loads item count information from viewstate.

+	 * This method is invoked right after control state is loaded.

+	 * @param mixed event parameter

+	 */

+	protected function onLoadState($param)

+	{

+		if(!$this->getIsDataBound())

+			$this->restoreItemsFromViewState();

+		$this->clearViewState('ItemCount');

+	}

 

 	/**

-	 * Renders the checkbox list control.

+	 * Clears up all items in the data list.

+	 */

+	public function reset()

+	{

+		$this->getControls()->clear();

+		$this->getItems()->clear();

+		$this->_header=null;

+		$this->_footer=null;

+	}

+

+	/**

+	 * Creates data list items based on viewstate information.

+	 */

+	protected function restoreItemsFromViewState()

+	{

+		$this->reset();

+		if(($itemCount=$this->getViewState('ItemCount',0))>0)

+		{

+			$items=$this->getItems();

+			$selectedIndex=$this->getSelectedItemIndex();

+			$editIndex=$this->getEditItemIndex();

+			if($this->_headerTemplate!=='')

+				$this->_header=$this->createItemInternal(-1,'Header',false,null);

+			$hasSeparator=$this->_separatorTemplate!=='';

+			for($i=0;$i<$itemCount;++$i)

+			{

+				if($hasSeparator && $i>0)

+					$this->createItemInternal($i-1,'Separator',false,null);

+				if($i===$editIndex)

+					$itemType='EditItem';

+				else if($i===$selectedIndex)

+					$itemType='SelectedItem';

+				else

+					$itemType=$i%2?'AlternatingItem':'Item';

+				$items->add($this->createItemInternal($i,$itemType,false,null));

+			}

+			if($this->_footerTemplate!=='')

+				$this->_footer=$this->createItemInternal(-1,'Footer',false,null);

+		}

+		$this->clearChildState();

+	}

+

+	/**

+	 * Performs databinding to populate data 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)

+	{

+		$this->reset();

+		$keys=$this->getDataKeys();

+		$keys->clear();

+		$keyField=$this->getDataKeyField();

+		$itemIndex=0;

+		$items=$this->getItems();

+		$hasSeparator=$this->_separatorTemplate!=='';

+		$selectedIndex=$this->getSelectedItemIndex();

+		$editIndex=$this->getEditItemIndex();

+		foreach($data as $dataItem)

+		{

+			if($keyField!=='')

+			{

+				if(is_array($dataItem) || ($dataItem instanceof TMap))

+					$keys->add($dataItem[$keyField]);

+				else if(($dataItem instanceof TComponent) && $dataItem->canGetProperty($keyField))

+				{

+					$getter='get'.$keyField;

+					$keys->add($dataItem->$getter());

+				}

+				else

+					throw new TInvalidDataValueException('datalist_keyfield_invalid',$keyField);

+			}

+			if($itemIndex===0 && $this->_headerTemplate!=='')

+				$this->_header=$this->createItemInternal(-1,'Header',true,null);

+			if($hasSeparator && $itemIndex>0)

+				$this->createItemInternal($itemIndex-1,'Separator',true,null);

+			if($itemIndex===$editIndex)

+				$itemType='EditItem';

+			else if($itemIndex===$selectedIndex)

+				$itemType='SelectedItem';

+			else

+				$itemType=$itemIndex%2?'AlternatingItem':'Item';

+			$items->add($this->createItemInternal($itemIndex,$itemType,true,$dataItem));

+			$itemIndex++;

+		}

+		if($itemIndex>0 && $this->_footerTemplate!=='')

+			$this->_footer=$this->createItemInternal(-1,'Footer',true,null);

+		$this->setViewState('ItemCount',$itemIndex,0);

+	}

+

+	/**

+	 * Renders the data list control.

 	 * This method overrides the parent implementation.

 	 * @param THtmlWriter writer for rendering purpose.

 	 */

 	protected function render($writer)

 	{

-		if($this->getItemCount()>0)

+		if($this->getHasControls())

 		{

-			$this->_isEnabled=$this->getEnabled(true);

 			$repeatInfo=$this->getRepeatInfo();

-			$accessKey=$this->getAccessKey();

-			$tabIndex=$this->getTabIndex();

-			$this->_repeatedControl->setTextAlign($this->getTextAlign());

-			$this->_repeatedControl->setAccessKey($accessKey);

-			$this->_repeatedControl->setTabIndex($tabIndex);

-			$this->setAccessKey('');

-			$this->setTabIndex(0);

 			$repeatInfo->renderRepeater($writer,$this);

-			$this->setAccessKey($accessKey);

-			$this->setTabIndex($tabIndex);

 		}

 	}

 }

@@ -838,12 +1086,14 @@ class TDataList extends TBaseDataList implements INamingContainer, IRepeatInfoUs
 /**

  * TDataListItemEventParameter class

  *

- * TDataListItemEventParameter encapsulates the parameter data for <b>OnItemCreated</b>

- * event of TDataList controls.

+ * TDataListItemEventParameter encapsulates the parameter data for

+ * {@link TDataList::onItemCreated ItemCreated} event of {@link TDataList} controls.

+ * The {@link getItem Item} property indicates the DataList item related with the event.

  *

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

- * @version v1.0, last update on 2004/08/13 21:44:52

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

  * @package System.Web.UI.WebControls

+ * @since 3.0

  */

 class TDataListItemEventParameter extends TEventParameter

 {

@@ -851,202 +1101,178 @@ class TDataListItemEventParameter extends TEventParameter
 	 * The TDataListItem control responsible for the event.

 	 * @var TDataListItem

 	 */

-	public $item=null;

+	private $_item=null;

+

+	/**

+	 * Constructor.

+	 * @param TDataListItem DataList item related with the corresponding event

+	 */

+	public function __construct(TDataListItem $item)

+	{

+		$this->_item=$item;

+	}

+

+	/**

+	 * @return TDataListItem DataList item related with the corresponding event

+	 */

+	public function getItem()

+	{

+		return $this->_item;

+	}

 }

 

 /**

  * TDataListCommandEventParameter class

  *

- * TDataListCommandEventParameter encapsulates the parameter data for <b>OnItemCommand</b>

- * event of TDataList controls.

+ * TDataListCommandEventParameter encapsulates the parameter data for

+ * {@link TDataList::onItemCommand ItemCommand} event of {@link TDataList} controls.

+ *

+ * The {@link getItem Item} property indicates the DataList item related with the event.

+ * The {@link getCommandSource CommandSource} refers to the control that originally

+ * raises the Command event.

  *

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

- * @version v1.0, last update on 2004/08/13 21:44:52

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

  * @package System.Web.UI.WebControls

+ * @since 3.0

  */

 class TDataListCommandEventParameter extends TCommandEventParameter

 {

 	/**

-	 * The TDataListItem control responsible for the event.

-	 * @var TDataListItem

+	 * @var TDataListItem the TDataListItem control responsible for the event.

 	 */

-	public $item=null;

+	private $_item=null;

 	/**

-	 * The control originally raises the <b>OnCommand</b> event.

-	 * @var TControl

+	 * @var TControl the control originally raises the <b>Command</b> event.

 	 */

-	public $source=null;

-}

+	private $_source=null;

 

-

-class TDataListItemCollection extends TCollection

-{

-	protected $list=null;

-

-	public function __construct($list)

+	/**

+	 * Constructor.

+	 * @param TDataListItem DataList item responsible for the event

+	 * @param TControl original event sender

+	 * @param TCommandEventParameter original event parameter

+	 */

+	public function __construct($item,$source,TCommandEventParameter $param)

 	{

-		parent::__construct();

-		$this->list=$list;

+		$this->_item=$item;

+		$this->_source=$source;

+		parent::__construct($param->getCommandName(),$param->getCommandParameter());

 	}

 

-	protected function onAddItem($item)

+	/**

+	 * @return TDataListItem the TDataListItem control responsible for the event.

+	 */

+	public function getItem()

 	{

-		if($item instanceof TDataListItem)

-		{

-			$this->list->addBody($item);

-			return true;

-		}

-		else

-			return false;

+		return $this->_item;

 	}

 

-	protected function onRemoveItem($item)

+	/**

+	 * @return TControl the control originally raises the <b>Command</b> event.

+	 */

+	public function getCommandSource()

 	{

-		$this->list->getBodies()->remove($item);

+		return $this->_source;

 	}

 }

 

-

 /**

- * TDataGridItem class

- *

- * A TDataGridItem control represents an item in the TDataGrid control, such

- * as heading section, footer section, data item, or pager section. The

- * item type can be determined by <b>Type</b> property.

- * The data items are stored in the <b>Items</b> property of TDataGrid control.

- * The index and data value of the item can be accessed via <b>Index</b>

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

- *

- * Since TDataGridItem inherits from TTableRow, you can also access

- * the <b>Cells</b> property to get the table cells in the item.

- *

- * Namespace: System.Web.UI.WebControls

+ * TDataListItem class

  *

- * Properties

- * - <b>ItemIndex</b>, mixed

- *   <br>Gets or sets the index of the data item in the Items collection of datagrid.

- * - <b>Data</b>, mixed

- *   <br>Gets or sets the value of the data item.

- * - <b>Type</b>, mixed

- *   <br>Gets or sets the type of the item (Header, Footer, Item, AlternatingItem, EditItem, SelectedItem, Separator)

+ * A TDataListItem control represents an item in the {@link TDataList} control,

+ * such as heading section, footer section, or a data item.

+ * The index and data value of the item can be accessed via {@link getItemIndex ItemIndex}>

+ * and {@link getDataItem DataItem} properties, respectively. The type of the item

+ * is given by {@link getItemType ItemType} property.

  *

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

- * @version v1.0, last update on 2004/08/13 21:44:52

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

  * @package System.Web.UI.WebControls

+ * @since 3.0

  */

-class TDataGridItem extends TTableRow

+class TDataListItem extends TWebControl implements INamingContainer

 {

 	/**

-	 * Header

-	 */

-	const TYPE_HEADER='Header';

-	/**

-	 * Footer

+	 * index of the data item in the Items collection of DataList

 	 */

-	const TYPE_FOOTER='Footer';

+	private $_itemIndex='';

 	/**

-	 * Data item

-	 */

-	const TYPE_ITEM='Item';

-	/**

-	 * Alternating data item

-	 */

-	const TYPE_ALTERNATING_ITEM='AlternatingItem';

-	/**

-	 * Selected item

-	 */

-	const TYPE_SELECTED_ITEM='SelectedItem';

-	/**

-	 * Edit item

-	 */

-	const TYPE_EDIT_ITEM='EditItem';

-	/**

-	 * Pager

-	 */

-	const TYPE_PAGER='Pager';

-	/**

-	 * index of the data item

-	 * @var mixed

+	 * type of the TDataListItem

+	 * @var string

 	 */

-	private $index='';

+	private $_itemType='';

 	/**

 	 * value of the data item

 	 * @var mixed

 	 */

-	private $data=null;

-	/**

-	 * type of the TDataGridItem

-	 * @var string

-	 */

-	private $type='';

+	private $_dataItem=null;

 

 	/**

 	 * Constructor.

-	 * Initializes the type to 'Item'.

+	 * @param integer zero-based index of the item in the item collection of DataList

+	 * @param string item type, can be 'Header','Footer','Item','AlternatingItem','SelectedItem','EditItem','Separator','Pager'.

 	 */

-	public function __construct()

+	public function __construct($itemIndex,$itemType)

 	{

-		$this->type=self::TYPE_ITEM;

-		parent::__construct();

+		$this->_itemIndex=$itemIndex;

+		$this->setItemType($itemType);

 	}

 

 	/**

-	 * @return mixed the index of the data item

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

 	 */

-	public function getItemIndex()

+	protected function createStyle()

 	{

-		return $this->index;

+		return new TTableItemStyle;

 	}

 

 	/**

-	 * Sets the index of the data item

-	 * @param mixed the data item index

+	 * @return string item type, can be 'Header','Footer','Item','AlternatingItem','SelectedItem','EditItem','Separator','Pager'

 	 */

-	public function setItemIndex($value)

+	public function getItemType()

 	{

-		$this->index=$value;

+		return $this->_itemType;

 	}

 

 	/**

-	 * @return mixed the value of the data item

+	 * @param mixed data to be associated with the item

 	 */

-	public function getData()

+	public function setItemType($value)

 	{

-		return $this->data;

+		$this->_itemType=TPropertyValue::ensureEnum($value,'Header','Footer','Item','AlternatingItem','SelectedItem','EditItem','Separator','Pager');

 	}

 

 	/**

-	 * Sets the value of the data item

-	 * @param mixed the value of the data item

+	 * @return integer zero-based index of the item in the item collection of DataList

 	 */

-	public function setData($value)

+	public function getItemIndex()

 	{

-		$this->data=$value;

+		return $this->_itemIndex;

 	}

 

 	/**

-	 * @return string the item type

+	 * @return mixed data associated with the item

 	 */

-	public function getType()

+	public function getDataItem()

 	{

-		return $this->type;

+		return $this->_dataItem;

 	}

 

 	/**

-	 * Sets the item type

-	 * @param string the item type

+	 * @param mixed data to be associated with the item

 	 */

-	public function setType($value)

+	public function setDataItem($value)

 	{

-		$this->type=$value;

+		$this->_dataItem=$value;

 	}

 

 	/**

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

-	 * This method overrides parent's implementation to bubble

-	 * <b>OnItemCommand</b> event if an <b>OnCommand</b>

-	 * event is bubbled from a child control.

-	 * This method should only be used by control developers.

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

+	 * This method overrides parent's implementation by wrapping event parameter

+	 * for <b>Command</b> event with item information.

 	 * @param TControl the sender of the event

 	 * @param TEventParameter event parameter

 	 * @return boolean whether the event bubbling should stop here.

@@ -1055,36 +1281,37 @@ class TDataGridItem extends TTableRow
 	{

 		if($param instanceof TCommandEventParameter)

 		{

-			$ce=new TDataGridCommandEventParameter;

-			$ce->name=$param->name;

-			$ce->parameter=$param->parameter;

-			$ce->source=$sender;

-			$ce->item=$this;

-			$this->raiseBubbleEvent($this,$ce);

+			$this->raiseBubbleEvent($this,new TDataListCommandEventParameter($this,$sender,$param));

 			return true;

 		}

 		else

 			return false;

 	}

+}

+

 

+/**

+ * TDataListItemCollection class.

+ *

+ * TDataListItemCollection represents a collection of data list items.

+ *

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

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

+ * @package System.Web.UI.WebControls

+ * @since 3.0

+ */

+class TDataListItemCollection extends TList

+{

 	/**

-	 * Renders the body content of this table.

-	 * @return string the rendering result

+	 * Returns true only when the item to be added is a {@link TDataListItem}.

+	 * This method is invoked before adding an item to the list.

+	 * If it returns true, the item will be added to the list, otherwise not.

+	 * @param mixed item to be added

+	 * @return boolean whether the item can be added to the list

 	 */

-	protected function renderBody()

+	protected function canAddItem($item)

 	{

-		$content="\n";

-		$cols=$this->getParent()->getColumns();

-		$n=$cols->length();

-		foreach($this->getCells() as $index=>$cell)

-		{

-			if($cell->isVisible())

-			{

-				if(!isset($cols[$index]) || $cols[$index]->isVisible() || $this->getType()===self::TYPE_PAGER)

-					$content.=$cell->render()."\n";

-			}

-		}

-		return $content;

+		return ($item instanceof TDataListItem);

 	}

 }

 

diff --git a/framework/Web/UI/WebControls/TFont.php b/framework/Web/UI/WebControls/TFont.php
index 75917b6c..37a08546 100644
--- a/framework/Web/UI/WebControls/TFont.php
+++ b/framework/Web/UI/WebControls/TFont.php
@@ -228,7 +228,7 @@ class TFont extends TComponent
 			$this->setUnderline($font->getUnderline());

 		if($font->_flags & self::IS_SET_SIZE)

 			$this->setSize($font->getSize());

-		if($font->_flags & self::IS_SET_NAMES)

+		if($font->_flags & self::IS_SET_NAME)

 			$this->setName($font->getName());

 	}

 

diff --git a/framework/Web/UI/WebControls/TRepeatInfo.php b/framework/Web/UI/WebControls/TRepeatInfo.php
index ce6efe8d..5f4fb825 100644
--- a/framework/Web/UI/WebControls/TRepeatInfo.php
+++ b/framework/Web/UI/WebControls/TRepeatInfo.php
@@ -72,6 +72,14 @@ interface IRepeatInfoUser
 class TRepeatInfo extends TComponent

 {

 	/**

+	 * @var string caption of the table used to organize the repeated items

+	 */

+	private $_caption='';

+	/**

+	 * @var string alignment of the caption of the table used to organize the repeated items

+	 */

+	private $_captionAlign='NotSet';

+	/**

 	 * @var integer number of columns that the items should be arranged in

 	 */

 	private $_repeatColumns=0;

@@ -85,6 +93,39 @@ class TRepeatInfo extends TComponent
 	private $_repeatLayout='Table';

 

 	/**

+	 * @return string caption of the table layout

+	 */

+	public function getCaption()

+	{

+		return $this->_caption;

+	}

+

+	/**

+	 * @param string caption of the table layout

+	 */

+	public function setCaption($value)

+	{

+		$this->_caption=$value;

+	}

+

+	/**

+	 * @return string alignment of the caption of the table layout. Defaults to 'NotSet'.

+	 */

+	public function getCaptionAlign()

+	{

+		return $this->_captionAlign;

+	}

+

+	/**

+	 * @return string alignment of the caption of the table layout.

+	 * Valid values include 'NotSet','Top','Bottom','Left','Right'.

+	 */

+	public function setCaptionAlign($value)

+	{

+		$this->_captionAlign=TPropertyValue::ensureEnum($value,array('NotSet','Top','Bottom','Left','Right'));

+	}

+

+	/**

 	 * @return integer the number of columns that the repeated items should be displayed in. Defaults to 0, meaning not set.

 	 */

 	public function getRepeatColumns()

diff --git a/framework/Web/UI/WebControls/TRepeater.php b/framework/Web/UI/WebControls/TRepeater.php
index 664faa68..c71f6590 100644
--- a/framework/Web/UI/WebControls/TRepeater.php
+++ b/framework/Web/UI/WebControls/TRepeater.php
@@ -36,6 +36,18 @@ Prado::using('System.Web.UI.WebControls.TDataBoundControl');
  * displayed between items.

  *

  * You can retrive the repeated contents by the {@link getItems Items} property.

+ * The header and footer items can be accessed by {@link getHeader Header}

+ * and {@link getFooter Footer} properties, respectively.

+ *

+ * When TRepeater creates an item, it will raise an {@link onItemCreated ItemCreated}

+ * so that you may customize the newly created item.

+ * When databinding is performed by TRepeater, for each item once it has finished

+ * databinding, an {@link onItemDataBound ItemDataBound} event will be raised.

+ *

+ * TRepeater raises an {@link onItemCommand ItemCommand} whenever a button control

+ * within some repeater item raises a <b>Command</b> event. Therefore,

+ * you can handle all sorts of <b>Command</b> event in a central place by

+ * writing an event handler for {@link onItemCommand ItemCommand}.

  *

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

  * @version $Revision: $  $Date: $

@@ -223,6 +235,7 @@ class TRepeater extends TDataBoundControl implements INamingContainer
 	 * @param string item type, may be 'Header', 'Footer', 'Item', 'Separator', 'AlternatingItem', 'SelectedItem', 'EditItem'.

 	 * @param boolean whether to do databinding for the item

 	 * @param mixed data to be associated with the item

+	 * @return TRepeaterItem the created item

 	 */

 	private function createItemInternal($itemIndex,$itemType,$dataBind,$dataItem)

 	{

@@ -271,6 +284,12 @@ class TRepeater extends TDataBoundControl implements INamingContainer
 			$this->createTemplate($tplContent)->instantiateIn($item);

 	}

 

+	/**

+	 * Parses item template.

+	 * This method uses caching technique to accelerate template parsing.

+	 * @param string template string

+	 * @return ITemplate parsed template object

+	 */

 	protected function createTemplate($str)

 	{

 		$key=md5($str);

@@ -333,20 +352,28 @@ class TRepeater extends TDataBoundControl implements INamingContainer
 	}

 

 	/**

-	 * Creates repeater items based on viewstate information.

+	 * Clears up all items in the repeater.

 	 */

-	protected function restoreItemsFromViewState()

+	public function reset()

 	{

 		$this->getControls()->clear();

-		$items=$this->getItems();

-		$items->clear();

+		$this->getItems()->clear();

 		$this->_header=null;

 		$this->_footer=null;

+	}

+

+	/**

+	 * Creates repeater items based on viewstate information.

+	 */

+	protected function restoreItemsFromViewState()

+	{

+		$this->reset();

 		if(($itemCount=$this->getViewState('ItemCount',0))>0)

 		{

+			$items=$this->getItems();

+			$hasSeparator=$this->_separatorTemplate!=='';

 			if($this->_headerTemplate!=='')

 				$this->_header=$this->createItemInternal(-1,'Header',false,null);

-			$hasSeparator=$this->_separatorTemplate!=='';

 			for($i=0;$i<$itemCount;++$i)

 			{

 				if($hasSeparator && $i>0)

@@ -368,11 +395,9 @@ class TRepeater extends TDataBoundControl implements INamingContainer
 	 */

 	protected function performDataBinding($data)

 	{

-		$this->getControls()->clear();

-		$this->clearChildState();

-		$items=$this->getItems();

-		$items->clear();

+		$this->reset();

 		$itemIndex=0;

+		$items=$this->getItems();

 		$hasSeparator=$this->_separatorTemplate!=='';

 		foreach($data as $dataItem)

 		{