PHP Класс Prado\Web\UI\WebControls\TDataList
TDataList represents a data bound and updatable list control.
Like {@link TRepeater}, TDataList displays its content repeatedly based on
the data fetched from {@link setDataSource DataSource}.
The repeated contents in TDataList are called items, which are controls and
can be accessed through {@link getItems Items}. When {@link dataBind()} is
invoked, TDataList creates an item for each row of data and binds the data
row to the item. Optionally, a TDataList can have a header, a footer and/or
separators between items.
TDataList differs from {@link TRepeater} in that it supports tiling the items
in different manners and it maintains status of items to handle data update.
The layout of the repeated contents are specified by inline templates.
TDataList items, header, footer, etc. are being instantiated with the corresponding
templates when data is being bound to the repeater.
Since v3.1.0, the layout can also be by renderers. A renderer is a control class
that can be instantiated as datalist items, header, etc. A renderer can thus be viewed
as an external template (in fact, it can also be non-templated controls).
A renderer can be any control class.
- If the class implements {@link \Prado\IDataRenderer}, the
Data
property will be set as the data row during databinding. Many PRADO controls
implement this interface, such as {@link TLabel}, {@link TTextBox}, etc.
- If the class implements {@link IItemDataRenderer}, the
ItemIndex property will be set
as the zero-based index of the item in the datalist item collection, and
the
ItemType property as the item's type (such as TListItemType::Item).
{@link TDataListItemRenderer} may be used as the convenient base class which
already implements {@link IDataItemRenderer}.
The following properties are used to specify different types of template and renderer
for a datalist:
- {@link setItemTemplate ItemTemplate}, {@link setItemRenderer ItemRenderer}:
for each repeated row of data
- {@link setAlternatingItemTemplate AlternatingItemTemplate}, {@link setAlternatingItemRenderer AlternatingItemRenderer}:
for each alternating row of data. If not set, {@link setItemTemplate ItemTemplate} or {@link setItemRenderer ItemRenderer}
will be used instead.
- {@link setHeaderTemplate HeaderTemplate}, {@link setHeaderRenderer HeaderRenderer}:
for the datalist header.
- {@link setFooterTemplate FooterTemplate}, {@link setFooterRenderer FooterRenderer}:
for the datalist footer.
- {@link setSeparatorTemplate SeparatorTemplate}, {@link setSeparatorRenderer SeparatorRenderer}:
for content to be displayed between items.
- {@link setEmptyTemplate EmptyTemplate}, {@link setEmptyRenderer EmptyRenderer}:
used when data bound to the datalist is empty.
- {@link setEditItemTemplate EditItemTemplate}, {@link setEditItemRenderer EditItemRenderer}:
for the row being editted.
- {@link setSelectedItemTemplate SelectedItemTemplate}, {@link setSelectedItemRenderer SelectedItemRenderer}:
for the row being selected.
If a content type is defined with both a template and a renderer, the latter takes precedence.
When {@link dataBind()} is being called, TDataList undergoes the following lifecycles for each row of data:
- create item based on templates or renderers
- set the row of data to the item
- raise {@link onItemCreated OnItemCreated}:
- add the item as a child control
- call dataBind() of the item
- raise {@link onItemDataBound OnItemDataBound}:
TDataList raises an {@link onItemCommand OnItemCommand} whenever a button control
within some datalist item raises a
OnCommand event. Therefore,
you can handle all sorts of
OnCommand event in a central place by
writing an event handler for {@link onItemCommand OnItemCommand}.
An additional event is raised if the
OnCommand event has one of the following
command names:
- edit: user wants to edit an item.
OnEditCommand event will be raised.
- update: user wants to save the change to an item.
OnUpdateCommand event will be raised.
- select: user selects an item.
OnSelectedIndexChanged event will be raised.
- delete: user deletes an item.
OnDeleteCommand event will be raised.
- cancel: user cancels previously editting action.
OnCancelCommand event will be raised.
TDataList provides a few properties to support tiling the items.
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.
The layout of the data items in the list is specified via {@link setRepeatLayout RepeatLayout},
which can take one of the following values:
- Table (default): items are organized using HTML table and cells.
When using this layout, one can set {@link setCellPadding CellPadding} and
{@link setCellSpacing CellSpacing} to adjust the cellpadding and cellpadding
of the table, and {@link setCaption Caption} and {@link setCaptionAlign CaptionAlign}
to add a table caption with the specified alignment.
- Flow: items are organized using HTML spans and breaks.
- Raw: TDataList does not generate any HTML tags to do the tiling.
Items in TDataList can be in one of the three status: normal browsing,
being editted and being selected. 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} or
{@link setSelectedItemRenderer SelectedItemRenderer} for presentation.
The latter will change the indicated item to edit mode and to use corresponding
template or renderer.
Note, if an item is in edit mode, then selecting this item will have no effect.
Different styles may be applied to items in different status. The style
application is performed 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
- {@link getItemStyle ItemStyle}
- {@link getAlternatingItemStyle AlternatingItemStyle}
- {@link getSelectedItemStyle SelectedItemStyle}
- {@link getEditItemStyle EditItemStyle}.
Therefore, if background color is set as red in {@link getItemStyle ItemStyle},
{@link getEditItemStyle EditItemStyle} will also have red background color
unless it is set to a different value explicitly.
When a page containing a datalist is post back, the datalist will restore automatically
all its contents, including items, header, footer and separators.
However, the data row associated with each item will not be recovered and become null.
To access the data, use one of the following ways:
- Use {@link getDataKeys DataKeys} to obtain the data key associated with
the specified datalist item and use the key to fetch the corresponding data
from some persistent storage such as DB.
- Save the whole dataset in viewstate, which will restore the dataset automatically upon postback.
Be aware though, if the size of your dataset is big, your page size will become big. Some
complex data may also have serializing problem if saved in viewstate.
Показать файл
Открыть проект
Примеры использования класса
Открытые методы
Защищенные методы
Приватные методы
Описание методов
applyItemStyles()
защищенный Метод
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, {@link getItemStyle ItemStyle}, {@link getAlternatingItemStyle AlternatingItemStyle},
{@link getSelectedItemStyle SelectedItemStyle}, and {@link getEditItemStyle EditItemStyle}.
Therefore, if background color is set as red in {@link getItemStyle ItemStyle},
{@link getEditItemStyle EditItemStyle} will also have red background color
unless it is set to a different value explicitly.
bubbleEvent()
публичный Метод
If the event parameter is {@link TDataListCommandEventParameter} and
the command name is a recognized one, which includes 'select', 'edit',
'delete', 'update', and 'cancel' (case-insensitive), then a
corresponding command event is also raised (such as {@link onEditCommand OnEditCommand}).
This method should only be used by control developers.
createEmptyContent()
защищенный Метод
Creates empty datalist content.
createItem()
защищенный Метод
Creates a datalist item instance based on the item type and index.
protected createItem ( $itemIndex, $itemType ) : TControl |
Результат |
TControl |
created datalist item |
generateItemStyle()
публичный Метод
This method is required by {@link IRepeatInfoUser} interface.
getAlternatingItemRenderer()
публичный Метод
getAlternatingItemStyle()
публичный Метод
getAlternatingItemTemplate()
публичный Метод
public getAlternatingItemTemplate ( ) : Prado\Web\UI\ITemplate |
Результат |
Prado\Web\UI\ITemplate |
the template for each alternating item |
getCaption()
публичный Метод
getCaptionAlign()
публичный Метод
public getCaptionAlign ( ) : TTableCaptionAlign |
Результат |
TTableCaptionAlign |
alignment of the caption of the table layout. Defaults to TTableCaptionAlign::NotSet. |
getEditItem()
публичный Метод
public getEditItem ( ) : TControl |
Результат |
TControl |
the edit item |
getEditItemIndex()
публичный Метод
public getEditItemIndex ( ) : integer |
Результат |
integer |
the zero-based index of the edit item in {@link getItems Items}.
A value -1 means no item is in edit mode. |
getEditItemRenderer()
публичный Метод
getEditItemStyle()
публичный Метод
public getEditItemStyle ( ) : TTableItemStyle |
Результат |
TTableItemStyle |
the style for edit item |
getEditItemTemplate()
публичный Метод
public getEditItemTemplate ( ) : Prado\Web\UI\ITemplate |
Результат |
Prado\Web\UI\ITemplate |
the edit item template |
getEmptyRenderer()
публичный Метод
getEmptyTemplate()
публичный Метод
public getEmptyTemplate ( ) : Prado\Web\UI\ITemplate |
Результат |
Prado\Web\UI\ITemplate |
the template applied when no data is bound to the datalist |
getHasSeparators()
публичный Метод
This method is required by {@link IRepeatInfoUser} interface.
getItemCount()
публичный Метод
getItemRenderer()
публичный Метод
getItemStyle()
публичный Метод
public getItemStyle ( ) : TTableItemStyle |
Результат |
TTableItemStyle |
the style for item |
getItemTemplate()
публичный Метод
public getItemTemplate ( ) : Prado\Web\UI\ITemplate |
Результат |
Prado\Web\UI\ITemplate |
the template for item |
getItems()
публичный Метод
public getItems ( ) : TDataListItemCollection |
Результат |
TDataListItemCollection |
item list |
getRepeatColumns()
публичный Метод
getRepeatDirection()
публичный Метод
public getRepeatDirection ( ) : TRepeatDirection |
Результат |
TRepeatDirection |
the direction of traversing the list, defaults to TRepeatDirection::Vertical |
getRepeatInfo()
защищенный Метод
protected getRepeatInfo ( ) : TRepeatInfo |
Результат |
TRepeatInfo |
repeat information (primarily used by control developers) |
getRepeatLayout()
публичный Метод
public getRepeatLayout ( ) : TRepeatLayout |
Результат |
TRepeatLayout |
how the list should be displayed, using table or using line breaks. Defaults to TRepeatLayout::Table. |
getSelectedDataKey()
публичный Метод
getSelectedItem()
публичный Метод
public getSelectedItem ( ) : TControl |
Результат |
TControl |
the selected item, null if no item is selected. |
getSelectedItemIndex()
публичный Метод
getSelectedItemRenderer()
публичный Метод
getSelectedItemStyle()
публичный Метод
public getSelectedItemStyle ( ) : TTableItemStyle |
Результат |
TTableItemStyle |
the style for selected item |
getSelectedItemTemplate()
публичный Метод
public getSelectedItemTemplate ( ) : Prado\Web\UI\ITemplate |
Результат |
Prado\Web\UI\ITemplate |
the selected item template |
getSeparatorRenderer()
публичный Метод
getSeparatorStyle()
публичный Метод
public getSeparatorStyle ( ) : TTableItemStyle |
Результат |
TTableItemStyle |
the style for separator |
getSeparatorTemplate()
публичный Метод
public getSeparatorTemplate ( ) : Prado\Web\UI\ITemplate |
Результат |
Prado\Web\UI\ITemplate |
the separator template |
loadState()
публичный Метод
This method is invoked right after control state is loaded.
onCancelCommand()
публичный Метод
This method is invoked when a child control of the data list
raises an OnCommand event and the command name is 'cancel' (case-insensitive).
onDeleteCommand()
публичный Метод
This method is invoked when a child control of the data list
raises an OnCommand event and the command name is 'delete' (case-insensitive).
onEditCommand()
публичный Метод
This method is invoked when a child control of the data list
raises an OnCommand event and the command name is 'edit' (case-insensitive).
onItemCommand()
публичный Метод
This method is invoked when a child control of the data list
raises an OnCommand event.
onItemCreated()
публичный Метод
This method is invoked after a data list item is created and instantiated with
template, but before added to the page hierarchy.
The datalist item control responsible for the event
can be determined from the event parameter.
If you override this method, be sure to call parent's implementation
so that event handlers have chance to respond to the event.
onItemDataBound()
публичный Метод
This method is invoked right after an item is data bound.
The datalist item control responsible for the event
can be determined from the event parameter.
If you override this method, be sure to call parent's implementation
so that event handlers have chance to respond to the event.
onUpdateCommand()
публичный Метод
This method is invoked when a child control of the data list
raises an OnCommand event and the command name is 'update' (case-insensitive).
This method overrides the parent implementation.
renderItem()
публичный Метод
This method is required by {@link IRepeatInfoUser} interface.
public renderItem ( $writer, $repeatInfo, $itemType, $index ) |
Clears up all items in the data list.
restoreItemsFromViewState()
защищенный Метод
Creates data list items based on viewstate information.
saveState()
публичный Метод
This method is invoked right before control state is to be saved.
setAlternatingItemRenderer()
публичный Метод
If not empty, the class will be used to instantiate as alternative datalist items.
This property takes precedence over {@link getAlternatingItemTemplate AlternatingItemTemplate}.
setAlternatingItemTemplate()
публичный Метод
setCaption()
публичный Метод
setCaptionAlign()
публичный Метод
public setCaptionAlign ( $value ) : TTableCaptionAlign |
Результат |
TTableCaptionAlign |
alignment of the caption of the table layout. |
setEditItemIndex()
публичный Метод
Previously editting item will change to normal item state.
If the index is less than 0, any existing edit item will be cleared up.
setEditItemRenderer()
публичный Метод
If not empty, the class will be used to instantiate as the datalist item.
This property takes precedence over {@link getEditItemTemplate EditItemTemplate}.
setEditItemTemplate()
публичный Метод
setEmptyRenderer()
публичный Метод
The empty renderer is created as the child of the datalist
if data bound to the datalist is empty.
This property takes precedence over {@link getEmptyTemplate EmptyTemplate}.
setEmptyTemplate()
публичный Метод
setItemRenderer()
публичный Метод
If not empty, the class will be used to instantiate as datalist items.
This property takes precedence over {@link getItemTemplate ItemTemplate}.
setItemTemplate()
публичный Метод
setRepeatColumns()
публичный Метод
setRepeatDirection()
публичный Метод
setRepeatLayout()
публичный Метод
setSelectedItemIndex()
публичный Метод
Previously selected item will be un-selected.
If the item to be selected is already in edit mode, it will remain in edit mode.
If the index is less than 0, any existing selection will be cleared up.
setSelectedItemRenderer()
публичный Метод
If not empty, the class will be used to instantiate as the datalist item.
This property takes precedence over {@link getSelectedItemTemplate SelectedItemTemplate}.
setSelectedItemTemplate()
публичный Метод
setSeparatorRenderer()
публичный Метод
If not empty, the class will be used to instantiate as datalist item separators.
This property takes precedence over {@link getSeparatorTemplate SeparatorTemplate}.
setSeparatorTemplate()
публичный Метод