- Home
- About
- Testimonials
- Demos
- Download
- Documentation
- Blogs
- Forum
- Support

Packages:
default
System
System.Caching
System.Collections
System.Data
System.Data.ActiveRecord
System.Data.ActiveRecord.Relations
System.Data.ActiveRecord.Scaffold
System.Data.ActiveReecord.Scaffold.InputBuilder
System.Data.Commom.Sqlite
System.Data.Common
System.Data.Common.Mssql
System.Data.Common.Mysql
System.Data.Common.Oracle
System.Data.Common.Pgsql
System.Data.Common.Sqlite
System.Data.DataGateway
System.Data.SqlMap
System.Data.SqlMap.Configuration
System.Data.SqlMap.Statements
System.Exceptions
System.I18N
System.IO
System.Security
System.Util
System.Web
System.Web.Services
System.Web.UI
System.Web.UI.ActiveControls
System.Web.UI.WebControls
System.Web.UI.WebControls.assets
System.Xml
Classes:
IDataSource
IItemDataRenderer
IRepeatInfoUser
TActiveFileUpload
TBaseDataList
TBaseValidator
TBoundColumn
TBulletedList
TBulletedListDisplayMode
TBulletedListEventParameter
TBulletStyle
TButton
TButtonColumn
TButtonColumnType
TButtonType
TCaptcha
TCaptchaValidator
TCheckBox
TCheckBoxColumn
TCheckBoxList
TCircleHotSpot
TClientScript
TClientScriptLoader
TClientSideValidationSummaryOptions
TColorPicker
TColorPickerClientSide
TColorPickerMode
TCompareValidator
TCompleteWizardStep
TConditional
TContent
TContentDirection
TContentPlaceHolder
TCustomValidator
TDataBoundControl
TDataGrid
TDataGridColumn
TDataGridColumnCollection
TDataGridCommandEventParameter
TDataGridItem
TDataGridItemCollection
TDataGridItemEventParameter
TDataGridItemRenderer
TDataGridPageChangedEventParameter
TDataGridPager
TDataGridPagerButtonType
TDataGridPagerEventParameter
TDataGridPagerMode
TDataGridPagerPosition
TDataGridPagerStyle
TDataGridSortCommandEventParameter
TDataList
TDataListCommandEventParameter
TDataListItem
TDataListItemCollection
TDataListItemEventParameter
TDataListItemRenderer
TDataRenderer
TDataSourceControl
TDataSourceSelectParameters
TDataSourceView
TDataTypeValidator
TDatePicker
TDatePickerClientScript
TDatePickerInputMode
TDatePickerMode
TDatePickerPositionMode
TDisplayStyle
TDraggable
TDropContainer
TDropDownList
TDropDownListColumn
TEditCommandColumn
TEmailAddressValidator
TExpression
TFileUpload
TFont
THiddenField
THorizontalAlign
THotSpot
THotSpotCollection
THotSpotMode
THtmlArea
THtmlElement
THyperLink
THyperLinkColumn
TImage
TImageButton
TImageClickEventParameter
TImageMap
TImageMapEventParameter
TInlineFrame
TInlineFrameAlign
TInlineFrameScrollBars
TItemDataRenderer
TJavascriptLogger
TKeyboard
TLabel
TLinkButton
TListBox
TListControl
TListControlValidator
TListItem
TListItemCollection
TListItemType
TListSelectionMode
TLiteral
TLiteralColumn
TMarkdown
TMetaTag
TMetaTagCollection
TMultiView
TOutputCache
TOutputCacheCalculateKeyEventParameter
TOutputCacheCheckDependencyEventParameter
TPager
TPagerButtonType
TPagerMode
TPagerPageChangedEventParameter
TPanel
TPanelStyle
TPlaceHolder
TPolygonHotSpot
TRadioButton
TRadioButtonList
TRangeValidationDataType
TRangeValidator
TRatingList
TReadOnlyDataSource
TReadOnlyDataSourceView
TRectangleHotSpot
TRegularExpressionValidator
TRepeatDirection
TRepeater
TRepeaterCommandEventParameter
TRepeaterItem
TRepeaterItemCollection
TRepeaterItemEventParameter
TRepeaterItemRenderer
TRepeatInfo
TRepeatLayout
TRequiredFieldValidator
TSafeHtml
TScrollBars
TServerValidateEventParameter
TSlider
TSliderClientScript
TSliderDirection
TStatements
TStyle
TStyleSheet
TTable
TTableCaptionAlign
TTableCell
TTableCellCollection
TTableFooterRow
TTableGridLines
TTableHeaderCell
TTableHeaderRow
TTableHeaderScope
TTableItemStyle
TTableRow
TTableRowCollection
TTableRowSection
TTableStyle
TTabPanel
TTabView
TTabViewCollection
TTemplateColumn
TTemplatedWizardStep
TTextAlign
TTextBox
TTextBoxAutoCompleteType
TTextBoxMode
TTextHighlighter
TTextHighlighterLineNumberStyle
TValidationCompareOperator
TValidationDataType
TValidationSummary
TValidationSummaryDisplayMode
TValidationSummaryDisplayStyle
TValidatorClientSide
TValidatorDisplayStyle
TVerticalAlign
TView
TViewCollection
TWebControl
TWebControlAdapter
TWizard
TWizardFinishNavigationTemplate
TWizardNavigationButtonStyle
TWizardNavigationButtonType
TWizardNavigationContainer
TWizardNavigationEventParameter
TWizardNavigationTemplate
TWizardSideBarListItemTemplate
TWizardSideBarTemplate
TWizardStartNavigationTemplate
TWizardStep
TWizardStepCollection
TWizardStepNavigationTemplate
TWizardStepType
TXmlTransform

Keyword

# Class TDataList

    TComponent
       |
       --TApplicationComponent
          |
          --TControl
             |
             --TWebControl
                |
                --TDataBoundControl
                   |
                   --TBaseDataList
                      |
                      --TDataList

TDataList class

TDataList represents a data bound and updatable list control.

Like TRepeater, TDataList displays its content repeatedly based on the data fetched from DataSource. The repeated contents in TDataList are called items, which are controls and can be accessed through Items. When 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 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 IDataRenderer, the Data

property will be set as the data row during databinding. Many PRADO controls implement this interface, such as TLabel, TTextBox, etc.

- If the class implements 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). TDataListItemRenderer may be used as the convenient base class which already implements IDataItemRenderer.

The following properties are used to specify different types of template and renderer for a datalist:

- ItemTemplate, ItemRenderer:

for each repeated row of data

- AlternatingItemTemplate, AlternatingItemRenderer:

for each alternating row of data. If not set, ItemTemplate or ItemRenderer will be used instead.

- HeaderTemplate, HeaderRenderer:

for the datalist header.

- FooterTemplate, FooterRenderer:

for the datalist footer.

- SeparatorTemplate, SeparatorRenderer:

for content to be displayed between items.

- EmptyTemplate, EmptyRenderer:

used when data bound to the datalist is empty.

- EditItemTemplate, EditItemRenderer:

for the row being editted.

- SelectedItemTemplate, SelectedItemRenderer:

for the row being selected.

If a content type is defined with both a template and a renderer, the latter takes precedence.

When 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 OnItemCreated:
- add the item as a child control
- call dataBind() of the item
- raise OnItemDataBound:

TDataList raises an 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 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 RepeatColumns property, while the RepeatDirection governs the order of the items being rendered. The layout of the data items in the list is specified via 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 CellPadding and CellSpacing to adjust the cellpadding and cellpadding of the table, and Caption and 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 SelectedItemIndex or EditItemIndex. The former will change the indicated item to selected mode, which will cause the item to use SelectedItemTemplate or 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
- ItemStyle
- AlternatingItemStyle
- SelectedItemStyle
- EditItemStyle.

Therefore, if background color is set as red in ItemStyle, 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 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.
Since: 3.0
Author: Qiang Xue <qiang.xue@gmail.com>

Constants Inherited From TControl

AUTOMATIC_ID_PREFIX, CLIENT_ID_SEPARATOR, CS_CHILD_INITIALIZED, CS_CONSTRUCTED, CS_INITIALIZED, CS_LOADED, CS_PRERENDERED, CS_STATE_LOADED, ID_FORMAT, ID_SEPARATOR, IS_CHILD_CREATED, IS_CREATING_CHILD, IS_DISABLE_THEMING, IS_DISABLE_VIEWSTATE, IS_ID_SET, IS_SKIN_APPLIED, IS_STYLESHEET_APPLIED, RF_ADAPTER, RF_AUTO_BINDINGS, RF_CHILD_STATE, RF_CONTROLS, RF_CONTROLSTATE, RF_DATA_BINDINGS, RF_EVENTS, RF_NAMED_CONTROLS, RF_NAMED_CONTROLS_ID, RF_NAMED_OBJECTS, RF_SKIN_ID,

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

Methods Inherited From TBaseDataList

TBaseDataList::createStyle(), TBaseDataList::getCellPadding(), TBaseDataList::getCellSpacing(), TBaseDataList::getDataFieldValue(), TBaseDataList::getDataKeyField(), TBaseDataList::getDataKeys(), TBaseDataList::getGridLines(), TBaseDataList::getHorizontalAlign(), TBaseDataList::onSelectedIndexChanged(), TBaseDataList::setCellPadding(), TBaseDataList::setCellSpacing(), TBaseDataList::setDataKeyField(), TBaseDataList::setGridLines(), TBaseDataList::setHorizontalAlign()

Methods Inherited From TDataBoundControl

TDataBoundControl::createPagedDataSource(), TDataBoundControl::dataBind(), TDataBoundControl::dataSourceViewChanged(), TDataBoundControl::determineDataSource(), TDataBoundControl::ensureDataBound(), TDataBoundControl::getAllowCustomPaging(), TDataBoundControl::getAllowPaging(), TDataBoundControl::getCurrentPageIndex(), TDataBoundControl::getDataMember(), TDataBoundControl::getDataSource(), TDataBoundControl::getDataSourceID(), TDataBoundControl::getDataSourceView(), TDataBoundControl::getInitialized(), TDataBoundControl::getIsDataBound(), TDataBoundControl::getPageCount(), TDataBoundControl::getPageSize(), TDataBoundControl::getRequiresDataBinding(), TDataBoundControl::getSelectParameters(), TDataBoundControl::getUsingDataSourceID(), TDataBoundControl::getVirtualItemCount(), TDataBoundControl::onDataBound(), TDataBoundControl::onDataSourceChanged(), TDataBoundControl::onInit(), TDataBoundControl::onPreRender(), TDataBoundControl::pagePreLoad(), TDataBoundControl::setAllowCustomPaging(), TDataBoundControl::setAllowPaging(), TDataBoundControl::setCurrentPageIndex(), TDataBoundControl::setDataMember(), TDataBoundControl::setDataSource(), TDataBoundControl::setDataSourceID(), TDataBoundControl::setInitialized(), TDataBoundControl::setIsDataBound(), TDataBoundControl::setPageSize(), TDataBoundControl::setRequiresDataBinding(), TDataBoundControl::setVirtualItemCount(), TDataBoundControl::validateDataSource()

Methods Inherited From TWebControl

TWebControl::addAttributesToRender(), TWebControl::clearStyle(), TWebControl::copyBaseAttributes(), TWebControl::createStyle(), TWebControl::getAccessKey(), TWebControl::getBackColor(), TWebControl::getBorderColor(), TWebControl::getBorderStyle(), TWebControl::getBorderWidth(), TWebControl::getCssClass(), TWebControl::getDisplay(), TWebControl::getFont(), TWebControl::getForeColor(), TWebControl::getHasStyle(), TWebControl::getHeight(), TWebControl::getStyle(), TWebControl::getTabIndex(), TWebControl::getTagName(), TWebControl::getToolTip(), TWebControl::getWidth(), TWebControl::render(), TWebControl::renderBeginTag(), TWebControl::renderContents(), TWebControl::renderEndTag(), TWebControl::setAccessKey(), TWebControl::setBackColor(), TWebControl::setBorderColor(), TWebControl::setBorderStyle(), TWebControl::setBorderWidth(), TWebControl::setCssClass(), TWebControl::setDisplay(), TWebControl::setForeColor(), TWebControl::setHeight(), TWebControl::setStyle(), TWebControl::setTabIndex(), TWebControl::setToolTip(), TWebControl::setWidth()

Methods Inherited From TControl

TControl::addedControl(), TControl::addParsedObject(), TControl::addToPostDataLoader(), TControl::applyStyleSheetSkin(), TControl::autoBindProperty(), TControl::autoDataBindProperties(), TControl::bindProperty(), TControl::broadcastEvent(), TControl::bubbleEvent(), TControl::clearChildState(), TControl::clearControlState(), TControl::clearNamingContainer(), TControl::clearViewState(), TControl::convertUniqueIdToClientId(), TControl::createChildControls(), TControl::createControlCollection(), TControl::dataBind(), TControl::dataBindChildren(), TControl::dataBindProperties(), TControl::ensureChildControls(), TControl::findControl(), TControl::findControlsByID(), TControl::findControlsByType(), TControl::focus(), TControl::getAdapter(), TControl::getAllowChildControls(), TControl::getAttribute(), TControl::getAttributes(), TControl::getChildControlsCreated(), TControl::getClientID(), TControl::getControls(), TControl::getControlStage(), TControl::getControlState(), TControl::getCustomData(), TControl::getEnabled(), TControl::getEnableTheming(), TControl::getEnableViewState(), TControl::getHasAdapter(), TControl::getHasAttributes(), TControl::getHasChildInitialized(), TControl::getHasControls(), TControl::getHasInitialized(), TControl::getHasLoaded(), TControl::getHasLoadedPostData(), TControl::getHasPreRendered(), TControl::getID(), TControl::getNamingContainer(), TControl::getPage(), TControl::getParent(), TControl::getRegisteredObject(), TControl::getSkinID(), TControl::getSourceTemplateControl(), TControl::getTemplateControl(), TControl::getUniqueID(), TControl::getViewState(), TControl::getVisible(), TControl::hasAttribute(), TControl::initRecursive(), TControl::isDescendentOf(), TControl::isObjectRegistered(), TControl::loadRecursive(), TControl::loadState(), TControl::loadStateRecursive(), TControl::onDataBinding(), TControl::onInit(), TControl::onLoad(), TControl::onPreRender(), TControl::onUnload(), TControl::preRenderRecursive(), TControl::raiseBubbleEvent(), TControl::registerObject(), TControl::removeAttribute(), TControl::removedControl(), TControl::render(), TControl::renderChildren(), TControl::renderControl(), TControl::saveState(), TControl::saveStateRecursive(), TControl::setAdapter(), TControl::setAttribute(), TControl::setChildControlsCreated(), TControl::setControlStage(), TControl::setControlState(), TControl::setCustomData(), TControl::setEnabled(), TControl::setEnableTheming(), TControl::setEnableViewState(), TControl::setID(), TControl::setPage(), TControl::setSkinID(), TControl::setTemplateControl(), TControl::setViewState(), TControl::setVisible(), TControl::trackViewState(), TControl::traverseChildControls(), TControl::unbindProperty(), TControl::unloadRecursive(), TControl::unregisterObject(), TControl::__get()

Methods Inherited From TApplicationComponent
TApplicationComponent::getApplication(), TApplicationComponent::getRequest(), TApplicationComponent::getResponse(), TApplicationComponent::getService(), TApplicationComponent::getSession(), TApplicationComponent::getUser(), TApplicationComponent::publishAsset(), TApplicationComponent::publishFilePath()

Methods Inherited From TComponent

TComponent::addParsedObject(), TComponent::attachEventHandler(), TComponent::canGetProperty(), TComponent::canSetProperty(), TComponent::createdOnTemplate(), TComponent::detachEventHandler(), TComponent::evaluateExpression(), TComponent::evaluateStatements(), TComponent::getEventHandlers(), TComponent::getSubProperty(), TComponent::hasEvent(), TComponent::hasEventHandler(), TComponent::hasProperty(), TComponent::raiseEvent(), TComponent::setSubProperty(), TComponent::__get(), TComponent::__set()

Constant Summary
string | CMD_CANCEL |
string | CMD_DELETE |
string | CMD_EDIT |
string | CMD_SELECT | Command name that TDataList understands. They are case-insensitive.
string | CMD_UPDATE |

Method Details

## applyItemStyles

protected void applyItemStyles | ()

Applies styles to items, header, footer and separators.

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 set to a different value explicitly.

Output
Exception

## bubbleEvent

public boolean bubbleEvent | (TControl $sender , TEventParameter $param )

This method overrides parent's implementation to handle onItemCommand event which is bubbled from datalist items and their child controls.

If the event parameter is 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 OnEditCommand). This method should only be used by control developers.

Input
TControl | $sender | the sender of the event
TEventParameter | $param | event parameter
Output
boolean | whether the event bubbling should stop here.
Exception

## createEmptyContent

protected void createEmptyContent | ()

Creates empty datalist content.

Output
Exception

## createItem

protected TControl createItem | (integer $itemIndex , TListItemType $itemType )

Creates a datalist item instance based on the item type and index.

Input
integer | $itemIndex | zero-based item index
TListItemType | $itemType | item type
Output
TControl | created datalist item
Exception

## generateItemStyle

public TStyle generateItemStyle | (string $itemType , integer $index )

Returns a style used for rendering items.

This method is required by IRepeatInfoUser interface.

Input
string | $itemType | item type (Header,Footer,Item,AlternatingItem,SelectedItem,EditItem,Separator,Pager)
integer | $index | index of the item being rendered
Output
TStyle | item style
Exception

## getAlternatingItemRenderer

public string getAlternatingItemRenderer | ()

Output
string | the class name for alternative datalist items. Defaults to empty, meaning not set.
Exception

## getAlternatingItemStyle

public TTableItemStyle getAlternatingItemStyle | ()

Output
TTableItemStyle | the style for each alternating item
Exception

## getAlternatingItemTemplate

public ITemplate getAlternatingItemTemplate | ()

Output
ITemplate | the template for each alternating item
Exception

## getCaption

public string getCaption | ()

Output
string | caption of the table layout
Exception

## getCaptionAlign

public TTableCaptionAlign getCaptionAlign | ()

Output
TTableCaptionAlign | alignment of the caption of the table layout. Defaults to TTableCaptionAlign::NotSet.
Exception

## getEditItem

public TControl getEditItem | ()

Output
TControl | the edit item
Exception

## getEditItemIndex

public integer getEditItemIndex | ()

Output
integer | the zero-based index of the edit item in Items. A value -1 means no item is in edit mode.
Exception

## getEditItemRenderer

public string getEditItemRenderer | ()

Output
string | the class name for the datalist item being editted. Defaults to empty, meaning not set.
Exception

## getEditItemStyle

public TTableItemStyle getEditItemStyle | ()

Output
TTableItemStyle | the style for edit item
Exception

## getEditItemTemplate

public ITemplate getEditItemTemplate | ()

Output
ITemplate | the edit item template
Exception

## getEmptyRenderer

public string getEmptyRenderer | ()

Output
string | the class name for empty datalist item. Defaults to empty, meaning not set.
Exception

## getEmptyTemplate

public ITemplate getEmptyTemplate | ()

Output
ITemplate | the template applied when no data is bound to the datalist
Exception

## getFooter

public TControl getFooter | ()

Output
TControl | the footer item
Exception

## getFooterRenderer

public string getFooterRenderer | ()

Output
string | the class name for datalist footer item. Defaults to empty, meaning not set.
Exception

## getFooterStyle

public TTableItemStyle getFooterStyle | ()

Output
TTableItemStyle | the style for footer
Exception

## getFooterTemplate

public ITemplate getFooterTemplate | ()

Output
ITemplate | the footer template
Exception

## getHasFooter

public boolean getHasFooter | ()

Returns a value indicating whether this control contains footer item.

This method is required by IRepeatInfoUser interface.

Output
boolean | whether the datalist has footer
Exception

## getHasHeader

public boolean getHasHeader | ()

Returns a value indicating whether this control contains header item.

This method is required by IRepeatInfoUser interface.

Output
boolean | whether the datalist has header
Exception

## getHasSeparators

public boolean getHasSeparators | ()

Returns a value indicating whether this control contains separator items.

This method is required by IRepeatInfoUser interface.

Output
boolean | always false.
Exception

## getHeader

public TControl getHeader | ()

Output
TControl | the header item
Exception

## getHeaderRenderer

public string getHeaderRenderer | ()

Output
string | the class name for datalist header item. Defaults to empty, meaning not set.
Exception

## getHeaderStyle

public TTableItemStyle getHeaderStyle | ()

Output
TTableItemStyle | the style for header
Exception

## getHeaderTemplate

public ITemplate getHeaderTemplate | ()

Output
ITemplate | the header template
Exception

## getItemCount

public integer getItemCount | ()

Output
integer | number of items
Exception

## getItemRenderer

public string getItemRenderer | ()

Output
string | the class name for datalist items. Defaults to empty, meaning not set.
Exception

## getItems

public TDataListItemCollection getItems | ()

Output
TDataListItemCollection | item list
Exception

## getItemStyle

public TTableItemStyle getItemStyle | ()

Output
TTableItemStyle | the style for item
Exception

## getItemTemplate

public ITemplate getItemTemplate | ()

Output
ITemplate | the template for item
Exception

## getRepeatColumns

public integer getRepeatColumns | ()

Output
integer | the number of columns that the list should be displayed with. Defaults to 0 meaning not set.
Exception

## getRepeatDirection

public TRepeatDirection getRepeatDirection | ()

Output
TRepeatDirection | the direction of traversing the list, defaults to TRepeatDirection::Vertical
Exception

## getRepeatInfo

protected TRepeatInfo getRepeatInfo | ()

Output
TRepeatInfo | repeat information (primarily used by control developers)
Exception

## getRepeatLayout

public TRepeatLayout getRepeatLayout | ()

Output
TRepeatLayout | how the list should be displayed, using table or using line breaks. Defaults to TRepeatLayout::Table.
Exception

## getSelectedDataKey

public mixed getSelectedDataKey | ()

Output
mixed | the key value of the currently selected item
Exception
throws | TInvalidOperationException if DataKeyField is empty.

## getSelectedItem

public TControl getSelectedItem | ()

Output
TControl | the selected item, null if no item is selected.
Exception

## getSelectedItemIndex

public integer getSelectedItemIndex | ()

Output
integer | the zero-based index of the selected item in Items. A value -1 means no item selected.
Exception

## getSelectedItemRenderer

public string getSelectedItemRenderer | ()

Output
string | the class name for the datalist item being selected. Defaults to empty, meaning not set.
Exception

## getSelectedItemStyle

public TTableItemStyle getSelectedItemStyle | ()

Output
TTableItemStyle | the style for selected item
Exception

## getSelectedItemTemplate

public ITemplate getSelectedItemTemplate | ()

Output
ITemplate | the selected item template
Exception

## getSeparatorRenderer

public string getSeparatorRenderer | ()

Output
string | the class name for datalist item separators. Defaults to empty, meaning not set.
Exception

## getSeparatorStyle

public TTableItemStyle getSeparatorStyle | ()

Output
TTableItemStyle | the style for separator
Exception

## getSeparatorTemplate

public ITemplate getSeparatorTemplate | ()

Output
ITemplate | the separator template
Exception

## getShowFooter

public boolean getShowFooter | ()

Output
boolean | whether the footer should be shown. Defaults to true.
Exception

## getShowHeader

public boolean getShowHeader | ()

Output
boolean | whether the header should be shown. Defaults to true.
Exception

## loadState

public void loadState | ()

Loads item count information from viewstate.

This method is invoked right after control state is loaded.

Output
Exception

## onCancelCommand

public void onCancelCommand | (TDataListCommandEventParameter $param )

Raises OnCancelCommand event.

This method is invoked when a child control of the data list raises an OnCommand event and the command name is 'cancel' (case-insensitive).

Input
TDataListCommandEventParameter | $param | event parameter
Output
Exception

## onDeleteCommand

public void onDeleteCommand | (TDataListCommandEventParameter $param )

Raises OnDeleteCommand event.

This method is invoked when a child control of the data list raises an OnCommand event and the command name is 'delete' (case-insensitive).

Input
TDataListCommandEventParameter | $param | event parameter
Output
Exception

## onEditCommand

public void onEditCommand | (TDataListCommandEventParameter $param )

Raises OnEditCommand event.

This method is invoked when a child control of the data list raises an OnCommand event and the command name is 'edit' (case-insensitive).

Input
TDataListCommandEventParameter | $param | event parameter
Output
Exception

## onItemCommand

public void onItemCommand | (TDataListCommandEventParameter $param )

Raises OnItemCommand event.

This method is invoked when a child control of the data list raises an OnCommand event.

Input
TDataListCommandEventParameter | $param | event parameter
Output
Exception

## onItemCreated

public void onItemCreated | (TDataListItemEventParameter $param )

Raises OnItemCreated event.

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.

Input
TDataListItemEventParameter | $param | event parameter
Output
Exception

## onItemDataBound

public void onItemDataBound | (TDataListItemEventParameter $param )

Raises OnItemDataBound event.

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.

Input
TDataListItemEventParameter | $param | event parameter
Output
Exception

## onUpdateCommand

public void onUpdateCommand | (TDataListCommandEventParameter $param )

Raises OnUpdateCommand event.

This method is invoked when a child control of the data list raises an OnCommand event and the command name is 'update' (case-insensitive).

Input
TDataListCommandEventParameter | $param | event parameter
Output
Exception

## performDataBinding

protected void performDataBinding | (Traversable $data )

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.

Input
Traversable | $data | the data
Output
Exception

## render

public void render | (THtmlWriter $writer )

Renders the data list control.

This method overrides the parent implementation.

Input
THtmlWriter | $writer | writer for rendering purpose.
Output
Exception

## renderItem

public void renderItem | (THtmlWriter $writer , TRepeatInfo $repeatInfo , string $itemType , integer $index )

Renders an item in the list.

This method is required by IRepeatInfoUser interface.

Input
THtmlWriter | $writer | writer for rendering purpose
TRepeatInfo | $repeatInfo | repeat information
string | $itemType | item type (Header,Footer,Item,AlternatingItem,SelectedItem,EditItem,Separator,Pager)
integer | $index | zero-based index of the item in the item list
Output
Exception

## reset

public void reset | ()

Clears up all items in the data list.

Output
Exception

## restoreItemsFromViewState

protected void restoreItemsFromViewState | ()

Creates data list items based on viewstate information.

Output
Exception

## saveState

public void saveState | ()

Saves item count in viewstate.

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

Output
Exception

## setAlternatingItemRenderer

public void setAlternatingItemRenderer | (string $value )

Sets the alternative item renderer class.

If not empty, the class will be used to instantiate as alternative datalist items. This property takes precedence over AlternatingItemTemplate.

Input
string | $value | the renderer class name in namespace format.
Output
Exception

## setAlternatingItemTemplate

public void setAlternatingItemTemplate | (ITemplate $value )

Input
ITemplate | $value | the template for each alternating item
Output
Exception
throws | TInvalidDataTypeException if the input is not an ITemplate or not null.

## setCaption

public void setCaption | (string $value )

Input
string | $value | caption of the table layout
Output
Exception

## setCaptionAlign

public TTableCaptionAlign setCaptionAlign | (mixed $value )

Input
mixed | $value |
Output
TTableCaptionAlign | alignment of the caption of the table layout.
Exception

## setEditItemIndex

public void setEditItemIndex | (integer $value )

Edits an item by its index in getItems.

Previously editting item will change to normal item state. If the index is less than 0, any existing edit item will be cleared up.

Input
integer | $value | the edit item index
Output
Exception

## setEditItemRenderer

public void setEditItemRenderer | (string $value )

Sets the renderer class for the datalist item being editted.

If not empty, the class will be used to instantiate as the datalist item. This property takes precedence over EditItemTemplate.

Input
string | $value | the renderer class name in namespace format.
Output
Exception

## setEditItemTemplate

public void setEditItemTemplate | (ITemplate $value )

Input
ITemplate | $value | the edit item template
Output
Exception
throws | TInvalidDataTypeException if the input is not an ITemplate or not null.

## setEmptyRenderer

public void setEmptyRenderer | (string $value )

Sets the datalist empty renderer class.

The empty renderer is created as the child of the datalist if data bound to the datalist is empty. This property takes precedence over EmptyTemplate.

Input
string | $value | the renderer class name in namespace format.
Output
Exception

## setEmptyTemplate

public void setEmptyTemplate | (ITemplate $value )

Input
ITemplate | $value | the template applied when no data is bound to the datalist
Output
Exception
throws | TInvalidDataTypeException if the input is not an ITemplate or not null.

## setFooterRenderer

public void setFooterRenderer | (string $value )

Sets the datalist footer renderer class.

If not empty, the class will be used to instantiate as datalist footer item. This property takes precedence over FooterTemplate.

Input
string | $value | the renderer class name in namespace format.
Output
Exception

## setFooterTemplate

public void setFooterTemplate | (ITemplate $value )

Input
ITemplate | $value | the footer template
Output
Exception
throws | TInvalidDataTypeException if the input is not an ITemplate or not null.

## setHeaderRenderer

public void setHeaderRenderer | (string $value )

Sets the datalist header renderer class.

If not empty, the class will be used to instantiate as datalist header item. This property takes precedence over HeaderTemplate.

Input
string | $value | the renderer class name in namespace format.
Output
Exception

## setHeaderTemplate

public void setHeaderTemplate | (ITemplate $value )

Input
ITemplate | $value | the header template
Output
Exception
throws | TInvalidDataTypeException if the input is not an ITemplate or not null.

## setItemRenderer

public void setItemRenderer | (string $value )

Sets the item renderer class.

If not empty, the class will be used to instantiate as datalist items. This property takes precedence over ItemTemplate.

Input
string | $value | the renderer class name in namespace format.
Output
Exception

## setItemTemplate

public void setItemTemplate | (ITemplate $value )

Input
ITemplate | $value | the template for item
Output
Exception
throws | TInvalidDataTypeException if the input is not an ITemplate or not null.

## setRepeatColumns

public void setRepeatColumns | (integer $value )

Input
integer | $value | the number of columns that the list should be displayed with.
Output
Exception

## setRepeatDirection

public void setRepeatDirection | (TRepeatDirection $value )

Input
TRepeatDirection | $value | the direction of traversing the list
Output
Exception

## setRepeatLayout

public void setRepeatLayout | (TRepeatLayout $value )

Input
TRepeatLayout | $value | how the list should be displayed, using table or using line breaks
Output
Exception

## setSelectedItemIndex

public void setSelectedItemIndex | (integer $value )

Selects an item by its index in getItems.

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.

Input
integer | $value | the selected item index
Output
Exception

## setSelectedItemRenderer

public void setSelectedItemRenderer | (string $value )

Sets the renderer class for the datalist item being selected.

If not empty, the class will be used to instantiate as the datalist item. This property takes precedence over SelectedItemTemplate.

Input
string | $value | the renderer class name in namespace format.
Output
Exception

## setSelectedItemTemplate

public void setSelectedItemTemplate | (ITemplate $value )

Input
ITemplate | $value | the selected item template
Output
Exception
throws | TInvalidDataTypeException if the input is not an ITemplate or not null.

## setSeparatorRenderer

public void setSeparatorRenderer | (string $value )

Sets the datalist item separator renderer class.

If not empty, the class will be used to instantiate as datalist item separators. This property takes precedence over SeparatorTemplate.

Input
string | $value | the renderer class name in namespace format.
Output
Exception

## setSeparatorTemplate

public void setSeparatorTemplate | (ITemplate $value )

Input
ITemplate | $value | the separator template
Output
Exception
throws | TInvalidDataTypeException if the input is not an ITemplate or not null.

## setShowFooter

public void setShowFooter | (boolean $value )

Input
boolean | $value | whether to show footer
Output
Exception

## setShowHeader

public void setShowHeader | (boolean $value )

Input
boolean | $value | whether to show header
Output
Exception

Constant Details

### CMD_CANCEL

#### Type:

string

#### Value:

'Cancel'

### CMD_DELETE

#### Type:

string

#### Value:

'Delete'

### CMD_EDIT

#### Type:

string

#### Value:

'Edit'

### CMD_SELECT

Command name that TDataList understands. They are case-insensitive.

#### Type:

string

#### Value:

'Select'

### CMD_UPDATE

#### Type:

string

#### Value:

'Update'