Class TDataList

Description

Implements interfaces:

TDataList class

TDataList represents a data bound and updatable list control.

The HeaderTemplate property specifies the content template that will be displayed at the beginning, while 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 ItemTemplate will be generated and displayed once. If AlternatingItemTemplate is not empty, then the corresponding content will be displayed alternatively with that in ItemTemplate. The content in SeparatorTemplate, if not empty, will be displayed between items. Besides the above templates, there are two additional templates, EditItemTemplate and 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, AlternatingItemStyle will be applied to every alternating item in the data list.

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.

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 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 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', CellPadding and CellSpacing can be used to adjust the cellpadding and cellpadding of the table, 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 items is specified via RepeatColumns property, while the RepeatDirection governs the order of the items being rendered.

You can retrive the repeated contents by the Items property. The header and footer items can be accessed by Header and Footer properties, respectively.

When TDataList creates an item, it will raise an OnItemCreated so that you may customize the newly created item. When databinding is performed by TDataList, for each item once it has finished databinding, an OnItemDataBound event will be raised.

When an item is selected by an end-user, a OnSelectedIndexChanged 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.

TDataList raises an OnItemCommand whenever a button control 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 OnEditCommand.

Located in /Web/UI/WebControls/TDataList.php (line 99)

TComponent
   |
   --TApplicationComponent
      |
      --TControl
         |
         --TWebControl
            |
            --TDataBoundControl
               |
               --TBaseDataList
                  |
                  --TDataList
Class Constant Summary
 CMD_CANCEL = 'Cancel'
 CMD_DELETE = 'Delete'
 CMD_EDIT = 'Edit'
 CMD_SELECT = 'Select'
 CMD_UPDATE = 'Update'
Method Summary
void applyItemStyles ()
boolean bubbleEvent (TControl $sender, TEventParameter $param)
TDataListItem createItem (integer $itemIndex, string $itemType)
TStyle generateItemStyle (string $itemType, integer $index)
string getCaption ()
string getCaptionAlign ()
integer getEditItemIndex ()
boolean getHasFooter ()
boolean getHasHeader ()
boolean getHasSeparators ()
integer getItemCount ()
integer getRepeatColumns ()
string getRepeatDirection ()
string getRepeatLayout ()
boolean getShowFooter ()
boolean getShowHeader ()
void loadState ()
void performDataBinding (Traversable $data)
void render (THtmlWriter $writer)
void renderItem (THtmlWriter $writer, TRepeatInfo $repeatInfo, string $itemType, integer $index)
void reset ()
void saveState ()
void setCaption (string $value)
string setCaptionAlign (mixed $value)
void setEditItemIndex (integer $value)
void setFooterTemplate (ITemplate $value)
void setHeaderTemplate (ITemplate $value)
void setItemTemplate (ITemplate $value)
void setRepeatColumns (integer $value)
void setRepeatDirection (string $value)
void setRepeatLayout (string $value)
void setSelectedItemIndex (integer $value)
void setShowFooter (boolean $value)
void setShowHeader (boolean $value)
Methods
applyItemStyles (line 912)

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.

  • access: protected
void applyItemStyles ()
bubbleEvent (line 650)

This method overrides parent's implementation to handle onItemCommand event which is bubbled from TDataListItem 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.

  • return: whether the event bubbling should stop here.
  • access: public
boolean bubbleEvent (TControl $sender, TEventParameter $param)

Redefinition of:
TControl::bubbleEvent()
This method responds to a bubbled event.
createItem (line 896)

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

  • return: created data list item
  • access: protected
TDataListItem createItem (integer $itemIndex, string $itemType)
  • integer $itemIndex: zero-based item index
  • string $itemType: item type, may be 'Header', 'Footer', 'Item', 'Separator', 'AlternatingItem', 'SelectedItem', 'EditItem'.
generateItemStyle (line 808)

Returns a style used for rendering items.

This method is required by IRepeatInfoUser interface.

  • return: item style
  • access: public
TStyle generateItemStyle (string $itemType, integer $index)
  • string $itemType: item type (Header,Footer,Item,AlternatingItem,SelectedItem,EditItem,Separator,Pager)
  • integer $index: index of the item being rendered
getAlternatingItemStyle (line 207)
  • return: the style for each alternating item
  • access: public
TTableItemStyle getAlternatingItemStyle ()
getAlternatingItemTemplate (line 187)
  • return: the template for each alternating item
  • access: public
ITemplate getAlternatingItemTemplate ()
getCaption (line 559)
  • return: caption of the table layout
  • access: public
string getCaption ()

Redefinition of:
TBaseDataList::getCaption()
getCaptionAlign (line 575)
  • return: alignment of the caption of the table layout. Defaults to 'NotSet'.
  • access: public
string getCaptionAlign ()

Redefinition of:
TBaseDataList::getCaptionAlign()
getEditItem (line 501)
  • return: the edit item
  • access: public
TDataListItem getEditItem ()
getEditItemIndex (line 471)
  • return: the zero-based index of the edit item in Items. A value -1 means no item is in edit mode.
  • access: public
integer getEditItemIndex ()
getEditItemStyle (line 273)
  • return: the style for edit item
  • access: public
TTableItemStyle getEditItemStyle ()
getEditItemTemplate (line 253)
  • return: the edit item template
  • access: public
ITemplate getEditItemTemplate ()
getFooter (line 360)
  • return: the footer item
  • access: public
TDataListItem getFooter ()
getFooterStyle (line 347)
  • return: the style for footer
  • access: public
TTableItemStyle getFooterStyle ()
getFooterTemplate (line 327)
  • return: the footer template
  • access: public
ITemplate getFooterTemplate ()
getHasFooter (line 786)

Returns a value indicating whether this control contains footer item.

This method is required by IRepeatInfoUser interface.

  • return: always false.
  • access: public
boolean getHasFooter ()
getHasHeader (line 776)

Returns a value indicating whether this control contains header item.

This method is required by IRepeatInfoUser interface.

  • return: always false.
  • access: public
boolean getHasHeader ()
getHasSeparators (line 796)

Returns a value indicating whether this control contains separator items.

This method is required by IRepeatInfoUser interface.

  • return: always false.
  • access: public
boolean getHasSeparators ()
getHeader (line 319)
  • return: the header item
  • access: public
TDataListItem getHeader ()
getHeaderStyle (line 306)
  • return: the style for header
  • access: public
TTableItemStyle getHeaderStyle ()
getHeaderTemplate (line 286)
  • return: the header template
  • access: public
ITemplate getHeaderTemplate ()
getItemCount (line 146)
  • return: number of items
  • access: public
integer getItemCount ()
getItems (line 136)
  • return: item list
  • access: public
getItemStyle (line 174)
  • return: the style for item
  • access: public
TTableItemStyle getItemStyle ()
getItemTemplate (line 154)
  • return: the template for item
  • access: public
ITemplate getItemTemplate ()
getRepeatColumns (line 592)
  • return: the number of columns that the list should be displayed with. Defaults to 0 meaning not set.
  • access: public
integer getRepeatColumns ()
getRepeatDirection (line 608)
  • return: the direction of traversing the list, defaults to 'Vertical'
  • access: public
string getRepeatDirection ()
getRepeatInfo (line 546)
  • return: repeat information (primarily used by control developers)
  • access: protected
TRepeatInfo getRepeatInfo ()
getRepeatLayout (line 624)
  • return: how the list should be displayed, using table or using line breaks. Defaults to 'Table'.
  • access: public
string getRepeatLayout ()
getSelectedDataKey (line 455)
  • return: the key value of the currently selected item
  • access: public
  • throws: TInvalidOperationException if DataKeyField is empty.
mixed getSelectedDataKey ()
getSelectedItem (line 441)
  • return: the selected item, null if no item is selected.
  • access: public
TDataListItem getSelectedItem ()
getSelectedItemIndex (line 402)
  • return: the zero-based index of the selected item in Items. A value -1 means no item selected.
  • access: public
integer getSelectedItemIndex ()
getSelectedItemStyle (line 240)
  • return: the style for selected item
  • access: public
TTableItemStyle getSelectedItemStyle ()
getSelectedItemTemplate (line 220)
  • return: the selected item template
  • access: public
ITemplate getSelectedItemTemplate ()
getSeparatorStyle (line 388)
  • return: the style for separator
  • access: public
TTableItemStyle getSeparatorStyle ()
getSeparatorTemplate (line 368)
  • return: the separator template
  • access: public
ITemplate getSeparatorTemplate ()
getShowFooter (line 530)
  • return: whether the footer should be shown. Defaults to true.
  • access: public
boolean getShowFooter ()
getShowHeader (line 514)
  • return: whether the header should be shown. Defaults to true.
  • access: public
boolean getShowHeader ()
initializeItem (line 1004)

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.

  • access: protected
void initializeItem (TDataListItem $item)
loadState (line 1064)

Loads item count information from viewstate.

This method is invoked right after control state is loaded.

  • access: public
void loadState ()

Redefinition of:
TControl::loadState()
This method is invoked right after the control has loaded its state.
onCancelCommand (line 766)

Raises OnCancelCommand event.

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

  • access: public
void onCancelCommand (TDataListCommandEventParameter $param)
onDeleteCommand (line 744)

Raises OnDeleteCommand event.

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

  • access: public
void onDeleteCommand (TDataListCommandEventParameter $param)
onEditCommand (line 733)

Raises OnEditCommand event.

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

  • access: public
void onEditCommand (TDataListCommandEventParameter $param)
onItemCommand (line 722)

Raises OnItemCommand event.

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

  • access: public
void onItemCommand (TDataListCommandEventParameter $param)
onItemCreated (line 697)

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 TDataListItem 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.

  • access: public
void onItemCreated (TDataListItemEventParameter $param)
onItemDataBound (line 711)

Raises OnItemDataBound event.

This method is invoked right after an item is data bound. The TDataListItem 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.

  • access: public
void onItemDataBound (TDataListItemEventParameter $param)
onUpdateCommand (line 755)

Raises OnUpdateCommand event.

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

  • access: public
void onUpdateCommand (TDataListCommandEventParameter $param)
performDataBinding (line 1121)

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.

  • access: protected
void performDataBinding (Traversable $data)
  • Traversable $data: the data

Redefinition of:
TDataBoundControl::performDataBinding()
render (line 1159)

Renders the data list control.

This method overrides the parent implementation.

  • access: public
void render (THtmlWriter $writer)

Redefinition of:
TWebControl::render()
Renders the control.
renderItem (line 824)

Renders an item in the list.

This method is required by IRepeatInfoUser interface.

  • access: public
void renderItem (THtmlWriter $writer, TRepeatInfo $repeatInfo, string $itemType, integer $index)
  • 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
reset (line 1075)

Clears up all items in the data list.

  • access: public
void reset ()
restoreItemsFromViewState (line 1086)

Creates data list items based on viewstate information.

  • access: protected
void restoreItemsFromViewState ()
saveState (line 1051)

Saves item count in viewstate.

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

  • access: public
void saveState ()

Redefinition of:
TControl::saveState()
This method is invoked when control state is to be saved.
setAlternatingItemTemplate (line 196)
  • access: public
  • throws: TInvalidDataTypeException if the input is not an ITemplate or not null.
void setAlternatingItemTemplate (ITemplate $value)
  • ITemplate $value: the template for each alternating item
setCaption (line 567)
  • access: public
void setCaption (string $value)
  • string $value: caption of the table layout

Redefinition of:
TBaseDataList::setCaption()
setCaptionAlign (line 584)
  • return: alignment of the caption of the table layout. Valid values include 'NotSet','Top','Bottom','Left','Right'.
  • access: public
string setCaptionAlign (mixed $value)

Redefinition of:
TBaseDataList::setCaptionAlign()
setEditItemIndex (line 482)

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.

  • access: public
void setEditItemIndex (integer $value)
  • integer $value: the edit item index
setEditItemTemplate (line 262)
  • access: public
  • throws: TInvalidDataTypeException if the input is not an ITemplate or not null.
void setEditItemTemplate (ITemplate $value)
setFooterTemplate (line 336)
  • access: public
  • throws: TInvalidDataTypeException if the input is not an ITemplate or not null.
void setFooterTemplate (ITemplate $value)
setHeaderTemplate (line 295)
  • access: public
  • throws: TInvalidDataTypeException if the input is not an ITemplate or not null.
void setHeaderTemplate (ITemplate $value)
setItemTemplate (line 163)
  • access: public
  • throws: TInvalidDataTypeException if the input is not an ITemplate or not null.
void setItemTemplate (ITemplate $value)
setRepeatColumns (line 600)
  • access: public
void setRepeatColumns (integer $value)
  • integer $value: the number of columns that the list should be displayed with.
setRepeatDirection (line 616)
  • access: public
void setRepeatDirection (string $value)
  • string $value: the direction (Vertical, Horizontal) of traversing the list
setRepeatLayout (line 632)
  • access: public
void setRepeatLayout (string $value)
  • string $value: how the list should be displayed, using table or using line breaks (Table, Flow, Raw)
setSelectedItemIndex (line 414)

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.

  • access: public
void setSelectedItemIndex (integer $value)
  • integer $value: the selected item index
setSelectedItemTemplate (line 229)
  • access: public
  • throws: TInvalidDataTypeException if the input is not an ITemplate or not null.
void setSelectedItemTemplate (ITemplate $value)
  • ITemplate $value: the selected item template
setSeparatorTemplate (line 377)
  • access: public
  • throws: TInvalidDataTypeException if the input is not an ITemplate or not null.
void setSeparatorTemplate (ITemplate $value)
setShowFooter (line 538)
  • access: public
void setShowFooter (boolean $value)
  • boolean $value: whether to show footer
setShowHeader (line 522)
  • access: public
void setShowHeader (boolean $value)
  • boolean $value: whether to show header

Inherited Methods

Inherited From TBaseDataList

TBaseDataList::addParsedObject()
TBaseDataList::createStyle()
TBaseDataList::getCaption()
TBaseDataList::getCaptionAlign()
TBaseDataList::getCellPadding()
TBaseDataList::getCellSpacing()
TBaseDataList::getDataFieldValue()
TBaseDataList::getDataKeyField()
TBaseDataList::getDataKeys()
TBaseDataList::getGridLines()
TBaseDataList::getHorizontalAlign()
TBaseDataList::onSelectedIndexChanged()
TBaseDataList::setCaption()
TBaseDataList::setCaptionAlign()
TBaseDataList::setCellPadding()
TBaseDataList::setCellSpacing()
TBaseDataList::setDataKeyField()
TBaseDataList::setGridLines()
TBaseDataList::setHorizontalAlign()

Inherited From TDataBoundControl

TDataBoundControl::dataBind()
TDataBoundControl::dataSourceViewChanged()
TDataBoundControl::determineDataSource()
TDataBoundControl::ensureDataBound()
TDataBoundControl::getData()
TDataBoundControl::getDataMember()
TDataBoundControl::getDataSource()
TDataBoundControl::getDataSourceID()
TDataBoundControl::getDataSourceView()
TDataBoundControl::getInitialized()
TDataBoundControl::getIsDataBound()
TDataBoundControl::getRequiresDataBinding()
TDataBoundControl::getSelectParameters()
TDataBoundControl::getUsingDataSourceID()
TDataBoundControl::onDataBound()
TDataBoundControl::onDataSourceChanged()
TDataBoundControl::onInit()
TDataBoundControl::onPreRender()
TDataBoundControl::pagePreLoad()
TDataBoundControl::performDataBinding()
TDataBoundControl::setDataMember()
TDataBoundControl::setDataSource()
TDataBoundControl::setDataSourceID()
TDataBoundControl::setInitialized()
TDataBoundControl::setIsDataBound()
TDataBoundControl::setRequiresDataBinding()
TDataBoundControl::validateDataSource()

Inherited From TWebControl

TWebControl::addAttributesToRender()
TWebControl::copyBaseAttributes()
TWebControl::createStyle()
TWebControl::getAccessKey()
TWebControl::getBackColor()
TWebControl::getBorderColor()
TWebControl::getBorderStyle()
TWebControl::getBorderWidth()
TWebControl::getCssClass()
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::setForeColor()
TWebControl::setHeight()
TWebControl::setStyle()
TWebControl::setTabIndex()
TWebControl::setToolTip()
TWebControl::setWidth()

Inherited From TControl

TControl::__construct()
TControl::addedControl()
TControl::addParsedObject()
TControl::applyStyleSheetSkin()
TControl::autoBindProperty()
TControl::autoDataBindProperties()
TControl::bindProperty()
TControl::broadcastEvent()
TControl::broadcastEventInternal()
TControl::bubbleEvent()
TControl::clearChildState()
TControl::clearControlState()
TControl::clearNamingContainer()
TControl::clearViewState()
TControl::createChildControls()
TControl::createControlCollection()
TControl::createdOnTemplate()
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::getEnabled()
TControl::getEnableTheming()
TControl::getEnableViewState()
TControl::getHasAdapter()
TControl::getHasAttributes()
TControl::getHasControls()
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::setEnabled()
TControl::setEnableTheming()
TControl::setEnableViewState()
TControl::setID()
TControl::setPage()
TControl::setSkinID()
TControl::setTemplateControl()
TControl::setViewState()
TControl::setVisible()
TControl::traverseChildControls()
TControl::unbindProperty()
TControl::unloadRecursive()
TControl::unregisterObject()
TControl::__get()

Inherited From TApplicationComponent

TApplicationComponent::getApplication()
TApplicationComponent::getRequest()
TApplicationComponent::getResponse()
TApplicationComponent::getService()
TApplicationComponent::getSession()
TApplicationComponent::getUser()
TApplicationComponent::publishAsset()
TApplicationComponent::publishFilePath()

Inherited From TComponent

TComponent::attachEventHandler()
TComponent::canGetProperty()
TComponent::canSetProperty()
TComponent::detachEventHandler()
TComponent::evaluateExpression()
TComponent::evaluateStatements()
TComponent::getEventHandlers()
TComponent::getSubProperty()
TComponent::hasEvent()
TComponent::hasEventHandler()
TComponent::hasProperty()
TComponent::raiseEvent()
TComponent::setSubProperty()
TComponent::__get()
TComponent::__set()
Class Constants
CMD_CANCEL = 'Cancel' (line 108)
CMD_DELETE = 'Delete' (line 107)
CMD_EDIT = 'Edit' (line 105)
CMD_SELECT = 'Select' (line 104)

Command name that TDataList understands.

CMD_UPDATE = 'Update' (line 106)

Inherited Constants

Inherited from TControl

Documentation generated on Sun, 04 Jun 2006 18:59:08 -0400 by phpDocumentor 1.3.0RC4