-TBC +TDataList is used to display or modify a list of data items specified by its DataSource or DataSourceID property. Each data item is displayed by a data list item which is a child control of the data list. The Items property contains the list of all data list items. +
++TDataList displays its items in either a Table or Flow layout, which is specified by the RepeatLayout property. A table layout uses HTML table cells to organize the items while a flow layout uses line breaks to organize the items. When the layout is Table, the table's cellpadding and cellspacing can be adjusted by CellPadding and CellSpacing properties, respectively. And Caption and CaptionAlign can be used to add a table caption with the specified alignment. The number of columns used to display the data list items is specified via RepeatColumns property, while the RepeatDirection governs the order of the items being rendered. +
++Each data list item is created according to one of the seven kinds of templates that developers may specified for a TDataList, +
++Each of the above templates is associated with a style property that is applied to the items using the template. For example, ItemTemplate is associated with a property named AlternatingItemStyle. Through this property, one can set CSS style fields or CSS classes for the data list items. +
++Item styles are applied in a hierarchical way. Style in higher hierarchy will inherit from styles in lower hierarchy. Starting from the lowest hierarchy, the item styles include item's own style, ItemStyle, AlternatingItemStyle, SelectedItemStyle, and EditItemStyle. Therefore, if background color is set as red in ItemStyle, EditItemStyle will also have red background color, unless it is explicitly set to a different value. +
++A data list item can be in normal mode, edit mode or selected mode. Different templates will apply to items of different modes. To change an item's mode, modify EditItemIndex or SelectedItemIndex. Note, if an item is in edit mode, then selecting this item will have no effect. +
++TDataList provides several events to facilitate manipulation of its items, +
++The following example shows how to use TDataList to display tabular data, with different layout and styles.
+An important use of TDataList is for maintaining tabular data, including browsing, editting, deleting data items. This is enabled by the command events and various item templates of TDataList. The following example displays a computer product information. Users can add new products, modify or delete existing ones. +
+-TRepeater displays its content defined in templates repeatedly based on the given data specified by the DataSource or DataSourceID property. The repeated contents can be retrieved from the Items property. Each item is created by instantiating a template and each is a child control of the repeater. TRepeater provides the OnItemCommand event that serves as a central place to process all OnCommand events raised by child controls of the repeater items. And an OnItemCreated event is raised each time when a new item is created based on a template. +TRepeater displays its content defined in templates repeatedly based on the given data specified by the DataSource or DataSourceID property. The repeated contents can be retrieved from the Items property. Each item is created by instantiating a template and each is a child control of the repeater.
Like normal control templates, the repeater templates can contain static text, controls and special tags, which after instantiation, become child contents of the corresponding item. TRepeater defiens five templates for different purposes, @@ -31,6 +31,17 @@ class MyPage extends TPage {
Normally, you only need to do this when the page containing the repeater is initially requested. In postbacks, TRepeater is smart enough to remember the previous state, i.e., contents populated with datasource information.The following sample displays tabular data using TRepeater.
++TRepeater provides several events to facilitate manipulation of its items, +
++The following example shows how to use TRepeater to display tabular data. +
TRepeater can be used in more complex situations. As an example, we show in the following how to use nested repeaters, i.e., repeater in repeater. This is commonly seen in presenting master-detail data. To use a repeater within another repeater, for an item for the outer repeater is created, we need to set the detail data source for the inner repeater. This can be achieved by responding to the OnItemDataBound event of the outer repeater. An OnItemDataBound event is raised each time an outer repeater item completes databinding. In the following example, we exploit another event of repeater called OnItemCreated, which is raised each time a repeater item (and its content) is newly created. We respond to this event by setting different background colors for repeater items to achieve alternating item background display. This saves us from writing an AlternatingItemTemplate for the repeaters.
diff --git a/framework/Web/UI/WebControls/TDataList.php b/framework/Web/UI/WebControls/TDataList.php
index 819febd6..e3748d22 100644
--- a/framework/Web/UI/WebControls/TDataList.php
+++ b/framework/Web/UI/WebControls/TDataList.php
@@ -34,8 +34,13 @@ Prado::using('System.Web.UI.WebControls.TRepeatInfo');
* 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,
+ * displayed between items. Besides the above templates, there are two additional
+ * templates, {@link setEditItemTemplate EditItemTemplate} and
+ * {@link setSelectedItemTemplate SelectedItemTemplate}, which are used to display
+ * items that are in edit and selected mode, respectively.
+ *
+ * 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.
*
@@ -81,10 +86,10 @@ Prado::using('System.Web.UI.WebControls.TRepeatInfo');
* The event mainly informs the server side that the end-user has made a selection.
*
* TDataList raises an {@link onItemCommand OnItemCommand} whenever a button control
- * within some TDataList item raises a Command event. If the command name
+ * within some TDataList item raises a OnCommand 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 'edit',
- * then the new event is {@link onEditCommand OnSelectCommand}.
+ * then the new event is {@link onEditCommand OnEditCommand}.
*
* @author Qiang Xue