• Home
• Prado
• Web
• UI
• WebControls
• TDataList

PHP Class 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. Datei anzeigen Open project: pradosoft/prado Class Usage Examples

Public Methods

Method	Description
bubbleEvent ( $sender, $param ) : boolean	This method overrides parent's implementation to handle {@link onItemCommand OnItemCommand} event which is bubbled from datalist items and their child controls.
generateItemStyle ( $itemType, $index ) : TStyle	Returns a style used for rendering items.
getAlternatingItemRenderer ( ) : string
getAlternatingItemStyle ( ) : TTableItemStyle
getAlternatingItemTemplate ( ) : Prado\Web\UI\ITemplate
getCaption ( ) : string
getCaptionAlign ( ) : TTableCaptionAlign
getEditItem ( ) : TControl
getEditItemIndex ( ) : integer
getEditItemRenderer ( ) : string
getEditItemStyle ( ) : TTableItemStyle
getEditItemTemplate ( ) : Prado\Web\UI\ITemplate
getEmptyRenderer ( ) : string
getEmptyTemplate ( ) : Prado\Web\UI\ITemplate
getFooter ( ) : TControl
getFooterRenderer ( ) : string
getFooterStyle ( ) : TTableItemStyle
getFooterTemplate ( ) : Prado\Web\UI\ITemplate
getHasFooter ( ) : boolean	Returns a value indicating whether this control contains footer item.
getHasHeader ( ) : boolean	Returns a value indicating whether this control contains header item.
getHasSeparators ( ) : boolean	Returns a value indicating whether this control contains separator items.
getHeader ( ) : TControl
getHeaderRenderer ( ) : string
getHeaderStyle ( ) : TTableItemStyle
getHeaderTemplate ( ) : Prado\Web\UI\ITemplate
getItemCount ( ) : integer
getItemRenderer ( ) : string
getItemStyle ( ) : TTableItemStyle
getItemTemplate ( ) : Prado\Web\UI\ITemplate
getItems ( ) : TDataListItemCollection
getRepeatColumns ( ) : integer
getRepeatDirection ( ) : TRepeatDirection
getRepeatLayout ( ) : TRepeatLayout
getSelectedDataKey ( ) : mixed
getSelectedItem ( ) : TControl
getSelectedItemIndex ( ) : integer
getSelectedItemRenderer ( ) : string
getSelectedItemStyle ( ) : TTableItemStyle
getSelectedItemTemplate ( ) : Prado\Web\UI\ITemplate
getSeparatorRenderer ( ) : string
getSeparatorStyle ( ) : TTableItemStyle
getSeparatorTemplate ( ) : Prado\Web\UI\ITemplate
getShowFooter ( ) : boolean
getShowHeader ( ) : boolean
loadState ( )	Loads item count information from viewstate.
onCancelCommand ( $param )	Raises OnCancelCommand event.
onDeleteCommand ( $param )	Raises OnDeleteCommand event.
onEditCommand ( $param )	Raises OnEditCommand event.
onItemCommand ( $param )	Raises OnItemCommand event.
onItemCreated ( $param )	Raises OnItemCreated event.
onItemDataBound ( $param )	Raises OnItemDataBound event.
onUpdateCommand ( $param )	Raises OnUpdateCommand event.
render ( $writer )	Renders the data list control.
renderItem ( $writer, $repeatInfo, $itemType, $index )	Renders an item in the list.
reset ( )	Clears up all items in the data list.
saveState ( )	Saves item count in viewstate.
setAlternatingItemRenderer ( $value )	Sets the alternative item renderer class.
setAlternatingItemTemplate ( $value )
setCaption ( $value )
setCaptionAlign ( $value ) : TTableCaptionAlign
setEditItemIndex ( $value )	Edits an item by its index in {@link getItems Items}.
setEditItemRenderer ( $value )	Sets the renderer class for the datalist item being editted.
setEditItemTemplate ( $value )
setEmptyRenderer ( $value )	Sets the datalist empty renderer class.
setEmptyTemplate ( $value )
setFooterRenderer ( $value )	Sets the datalist footer renderer class.
setFooterTemplate ( $value )
setHeaderRenderer ( $value )	Sets the datalist header renderer class.
setHeaderTemplate ( $value )
setItemRenderer ( $value )	Sets the item renderer class.
setItemTemplate ( $value )
setRepeatColumns ( $value )
setRepeatDirection ( $value )
setRepeatLayout ( $value )
setSelectedItemIndex ( $value )	Selects an item by its index in {@link getItems Items}.
setSelectedItemRenderer ( $value )	Sets the renderer class for the datalist item being selected.
setSelectedItemTemplate ( $value )
setSeparatorRenderer ( $value )	Sets the datalist item separator renderer class.
setSeparatorTemplate ( $value )
setShowFooter ( $value )
setShowHeader ( $value )

Protected Methods

Method	Description
applyItemStyles ( )	Applies styles to items, header, footer and separators.
createEmptyContent ( )	Creates empty datalist content.
createItem ( $itemIndex, $itemType ) : TControl	Creates a datalist item instance based on the item type and index.
getRepeatInfo ( ) : TRepeatInfo
performDataBinding ( $data )	Performs databinding to populate data list items from data source.
restoreItemsFromViewState ( )	Creates data list items based on viewstate information.

Private Methods

Method	Description
createItemInternal ( $itemIndex, $itemType ) : TControl	Creates a datalist item.
createItemWithDataInternal ( $itemIndex, $itemType, $dataItem ) : TControl	Creates a datalist item and performs databinding.
getAlternatingItemDisplay ( )
getEditItemDisplay ( $itemIndex )
getItem ( $itemType, $index ) : TControl
getSelectedItemDisplay ( $itemIndex )

Method Details