Class: TDataList

Source Location: /Web/UI/WebControls/TDataList.php

Class Overview

TComponent
   |
   --TControl
      |
      --TWebControl
         |
         --TBaseDataList
            |
            --TDataList

TDataList class

Class Details

[line 137]
TDataList class

TDataList represents a data bound and updatable list control.

It can be used to display and maintain a list of data items (rows, records). There are three kinds of layout determined by the RepeatLayout property. The Table layout displays a table and each table cell contains a data item. The Flow layout uses the span tag to organize the presentation of data items. The Raw layout displays all templated content without any additional decorations (therefore, you can use arbitrary complex UI layout). In case when the layout is Table or Flow, the number of table/flow columns is determined by the RepeatColumns property, and the data items are enumerated according to the RepeatDirection property.

To use TDataList, sets its DataSource property and invokes dataBind() afterwards. The data will be populated into the TDataList and saved as data items. A data item can be at one of three states: normal, selected and edit. The state determines which template is used to display the item. In particular, data items are displayed using the following templates, ItemTemplate, AlternatingItemTemplate, SelectedItemTemplate, EditItemTemplate. In addition, the HeaderTemplate, FooterTemplate, and SeparatorTemplate can be used to decorate the overall presentation.

To change the state of a data item, set either the EditItemIndex property or the SelectedItemIndex property.

When an item template contains a button control that raises an OnCommand event, the event will be bubbled up to the data list control. If the event's command name is recognizable by the data list control, a corresponding item event will be raised. The following item events will be raised upon a specific command:

OnEditCommand, edit
OnCancelCommand, cancel
OnSelectCommand, select
OnDeleteCommand, delete
OnUpdateCommand, update

The data list will always raise an OnItemCommand upon its receiving a bubbled OnCommand event.

Namespace: System.Web.UI.WebControls

Properties

RepeatColumns, integer, default=1, kept in viewstate
Gets or sets the number of columns that the list should be displayed with.
RepeatDirection, string (Vertical, Horizontal), default='Vertical', kept in viewstate
Gets or sets the direction of traversing the list
RepeatLayout, string (Table, Flow, Raw), default=Table, kept in viewstate
Gets or sets how the list should be displayed, using table or using line breaks.
ItemTemplate, string
Gets or sets the template for each data item.
AlternatingItemTemplate, string
Gets or sets the template for alternating data item.
HeaderTemplate, string
Gets or sets the template displayed at the beginning of the list.
FooterTemplate, string
Gets or sets the template displayed at the end of the list.
SeparatorTemplate, string
Gets or sets the template displayed between two items.
SelectedItemTemplate, string
Gets or sets the template displayed for selected item if any.
EditItemTemplate, string
Gets or sets the template displayed for editting item if any.
Items, array, read-only
Gets the list of TDataListItem controls that correspond to each data item.
ItemCount, integer, read-only
Gets the number of TDataListItem controls for data items.
EditItemIndex, integer, default=-1, stored in viewstate
Gets or sets the index for edit item.
EditItem, TDataListItem, read-only
Gets the edit item, null if none
SelectedItemIndex, integer, default=-1, stored in viewstate
Gets or sets the index for selected item.
SelectedItem, TDataListItem, read-only
Gets the selected item, null if none
ItemStyle, string, stored in viewstate
Gets or sets the css style for each item
AlternatingItemStyle, string, stored in viewstate
Gets or sets the css style for each alternating item
EditItemStyle, string, stored in viewstate
Gets or sets the css style for the edit item
SelectedItemStyle, string, stored in viewstate
Gets or sets the css style for the selected item
HeaderStyle, string, stored in viewstate
Gets or sets the css style for the header
FooterStyle, string, stored in viewstate
Gets or sets the css style for the footer
SeparatorStyle, string, stored in viewstate
Gets or sets the css style for each separator
ShowHeader, boolean, default=true, stored in viewstate
Gets or sets the value whether to show header
ShowFooter, boolean, default=true, stored in viewstate
Gets or sets the value whether to show footer

Events

OnEditCommand, raised when a button control raises an OnCommand event with 'edit' command.
OnSelectCommand, raised when a button control raises an OnCommand event with 'select' command.
OnUpdateCommand, raised when a button control raises an OnCommand event with 'update' command.
OnCancelCommand, raised when a button control raises an OnCommand event with 'cancel' command.
OnDeleteCommand, raised when a button control raises an OnCommand event with 'delete' command.
OnItemCommand, raised when a button control raises an OnCommand event.
OnItemCreatedCommand, raised right after an item is created.

version:	$Revision: 1.19 $ $Date: 2005/04/03 21:18:33 $
author:	Qiang Xue <qiang.xue@gmail.com>

[ Top ]

Constants

Methods

Inherited Variables

Class: TBaseDataList

TBaseDataList::$datasource

Class: TComponent

TComponent::$children

Inherited Methods

Class: TBaseDataList

TBaseDataList::getCellPadding()
TBaseDataList::getCellSpacing()
TBaseDataList::getDataKeyField()
TBaseDataList::getDataKeys()
TBaseDataList::getDataSource()
TBaseDataList::getGridLines()
TBaseDataList::getHorizontalAlign()
TBaseDataList::setCellPadding(): Sets the cellpadding for the table keeping the data listing items.
TBaseDataList::setCellSpacing(): Sets the cellspacing for the table keeping the data listing items.
TBaseDataList::setDataKeyField()
TBaseDataList::setDataSource(): Sets the data source that populates the items of the data listing control.
TBaseDataList::setGridLines(): Sets the value specifying whether the border between the cells is displayed.
TBaseDataList::setHorizontalAlign(): Sets the horizontal alignment of a data listing control within its container.

Class: TWebControl

TWebControl::appendJavascriptEvent(): Append a javascript statement to a particular attribute, e.g. "onclick".
TWebControl::getAccessKey()
TWebControl::getAttributesToRender(): This overrides the parent implementation by rendering more TWebControl-specific attributes.
TWebControl::getBackColor()
TWebControl::getBorderColor()
TWebControl::getBorderStyle()
TWebControl::getBorderWidth()
TWebControl::getCssClass()
TWebControl::getForeColor()
TWebControl::getHeight()
TWebControl::getJavascriptEvents(): Get the list of all the javascript statements.
TWebControl::getStyle()
TWebControl::getTabIndex()
TWebControl::getToolTip()
TWebControl::getWidth()
TWebControl::isEnabled()
TWebControl::parseStyle(): Parses a CSS style string into an array representation.
TWebControl::removeJavascriptEvent(): Remove all or a particular javascript statements.
TWebControl::setAccessKey(): Sets the access key of the control.
TWebControl::setBackColor(): Sets the background color of the control
TWebControl::setBorderColor(): Sets the border color of the control
TWebControl::setBorderStyle(): Sets the border style of the control
TWebControl::setBorderWidth(): Sets the border width of the control
TWebControl::setCssClass(): Sets the CSS class name of the control
TWebControl::setEnabled(): Enables or disables a control.
TWebControl::setForeColor(): Sets the foreground color of the control
TWebControl::setHeight(): Sets the height of the control
TWebControl::setStyle(): Sets the CSS style of the control.
TWebControl::setTabIndex(): Sets the tab index of the control.
TWebControl::setToolTip(): Sets the tooltip of the control.
TWebControl::setWidth(): Sets the width of the control

Class: TControl

TControl::__construct(): Constructor.
TControl::addBody(): Appends an object into the body collection of this control.
TControl::addParsedObject(): Adds the object parsed in template as a body of the component.
TControl::allowBody(): Determines whether the control can add the object as a body.
TControl::clearViewState(): Clears viewstate
TControl::findBodyControl()
TControl::getAttribute()
TControl::getAttributes(): Returns the attribute list object.
TControl::getAttributesToRender(): Returns attributes to be rendered.
TControl::getBodies()
TControl::getClientID(): Returns the client ID of the component.
TControl::getContainer(): Returns the container of this component.
TControl::getSkinName()
TControl::getTagName()
TControl::getViewState(): Returns a viewstate value.
TControl::initSkin(): Initializes a skin for the control. If a skin name is provided then that skin will be loaded.
TControl::isViewStateEnabled()
TControl::isVisible(): This method checks whether a control is visible.
TControl::loadViewState(): Loads viewstate into this component and its children.
TControl::onBubbleEvent(): This method responds to a bubbled event.
TControl::onInit(): This method is invoked when the control enters 'Init' stage.
TControl::onInitRecursive(): Calls onInit of this control and its children recursively.
TControl::onLoad(): This method is invoked when the control enters 'Load' stage.
TControl::onLoadRecursive(): Calls onLoad of this control and its children recursively.
TControl::onPreRender(): This method is invoked when the control enters 'PreRender' stage.
TControl::onPreRenderRecursive(): Calls onPreRender of this control and its children recursively.
TControl::onUnload(): This method is invoked when the control enters 'Unload' stage.
TControl::onUnloadRecursive(): Calls onUnload of this control and its children recursively.
TControl::raiseBubbleEvent(): Invokes the parent's onBubbleEvent method.
TControl::removeBodies(): Removes all body content.
TControl::render(): Renders this control.
TControl::renderAttributes(): Renders the attributes.
TControl::renderBody(): Renders the body content.
TControl::saveViewState(): Returns the viewstate of this component and its children.
TControl::setAttribute(): Sets an attribute.
TControl::setContainer(): Sets the container of this component
TControl::setEnableViewState()
TControl::setSkinName(): Sets the skin to use for this control
TControl::setTagName(): Sets the tag name.
TControl::setViewState(): Sets a viewstate value.
TControl::setVisible()
TControl::synchronizeControl(): This method should only be used by framework developer.

Class: TComponent

TComponent::__construct(): Constructor.
TComponent::addChild(): Adds a child component.
TComponent::addParsedObject(): Handles a component or string met in template.
TComponent::attachEventHandler(): Attaches a handler function to an event.
TComponent::bindProperty(): Sets up the binding between a property and an expression.
TComponent::canGetProperty(): Determines whether a property can be read.
TComponent::canSetProperty(): Determines whether a property can be written.
TComponent::createComponent(): Creates a child component.
TComponent::dataBind(): Performs the databinding for this component.
TComponent::evaluateExpression(): Evaluates a PHP expression.
TComponent::evaluateStatements(): Evaluates a list of PHP statements.
TComponent::findObject(): Finds an object by its ID path.
TComponent::getApplication()
TComponent::getChild()
TComponent::getChildren()
TComponent::getDefinition(): Returns or builds a component definition.
TComponent::getGlobalization(): Returns the Globalization instance for the application.
TComponent::getID()
TComponent::getModule(): Returns the module object that contains the component or the page containing the component.
TComponent::getPage()
TComponent::getParent()
TComponent::getPropertyInitValue(): Gets the initial value of a property.
TComponent::getPropertyType(): Returns the type of a property
TComponent::getRequest(): Returns the request object associated with application.
TComponent::getServiceManager(): Returns the service manager for this application.
TComponent::getSession(): Returns the session object associated with the application.
TComponent::getSessionState(): Returns a session variable.
TComponent::getUniqueID(): Returns the unique ID of the component.
TComponent::getUser(): Returns the user object associated with the application.
TComponent::hasChildren()
TComponent::hasEvent(): Determines whether an event is defined.
TComponent::hasProperty(): Determines whether a property is defined.
TComponent::initProperties(): Initializes the property values.
TComponent::instantiateTemplate(): Parses a template string and instantiates the content.
TComponent::onDataBinding(): This method is invoked when dataBind is invoked for the component.
TComponent::raiseEvent(): Invokes all attached event handler functions for a particular event.
TComponent::removeChild(): Removes a child component.
TComponent::removeChildren(): Removes all child components.
TComponent::setAttribute(): Sets an attribute.
TComponent::setDefinition(): Sets a component definition.
TComponent::setID(): Sets a component ID.
TComponent::setParent(): Sets the parent of this component.
TComponent::setPropertyInitValue(): Sets the initial value of a property.
TComponent::setRoot(): Sets the root component in the component hierarchy.
TComponent::setSessionState(): Sets a session variable.
TComponent::unbindProperty(): Breaks the binding between a property and an expression.
TComponent::__get(): Returns a property value by name or a child component by ID.
TComponent::__set(): Sets value of a component property.

Class Methods

method addParsedObject [line 208]

void addParsedObject(
TComponent|string
$object, TComponent
$context)

This method overrides the parent implementation so that no body content is added from template.

access:

public

Overrides TControl::addParsedObject() (Adds the object parsed in template as a body of the component.)

Parameters:

TComponent\|string	$object	the newly parsed object
TComponent	$context	the template owner

[ Top ]

method allowBody [line 217]

boolean allowBody(
mixed
$object)

Overrides parent implementation to disable body addition.

access:

public

Overrides TControl::allowBody() (Determines whether the control can add the object as a body.)

Parameters:

mixed

$object

the object to be added

[ Top ]

constructor __construct [line 196]

TDataList __construct(
)

Initializes the item list

access:

public

Overrides TControl::__construct() (Constructor.)

[ Top ]

method getAlternatingItemStyle [line 428]

string getAlternatingItemStyle(
)

return:	the style for each alternating item
access:	public

[ Top ]

method getAlternatingItemTemplate [line 307]

string getAlternatingItemTemplate(
)

return:	the alternative template string for the item
access:	public

[ Top ]

method getAttributesToRender [line 867]

ArrayObject getAttributesToRender(
)

Returns the attributes to be rendered.

return:	attributes to be rendered
access:	protected

Overrides TWebControl::getAttributesToRender() (This overrides the parent implementation by rendering more TWebControl-specific attributes.)

[ Top ]

method getDataKeys [line 693]

array getDataKeys(
)

return:	the keys used in the data listing control.
access:	public

Overrides TBaseDataList::getDataKeys() (parent method not documented)

[ Top ]

method getDataSource [line 564]

Iterator getDataSource(
)

return:	the data source
access:	public

Overrides TBaseDataList::getDataSource() (parent method not documented)

[ Top ]

method getEditItem [line 278]

TDataListItem getEditItem(
)

return:	the edit item
access:	public

[ Top ]

method getEditItemIndex [line 259]

integer getEditItemIndex(
)

return:	the index of the edit item in Items array
access:	public

[ Top ]

method getEditItemStyle [line 445]

string getEditItemStyle(
)

return:	the style for edit item
access:	public

[ Top ]

method getEditItemTemplate [line 394]

string getEditItemTemplate(
)

return:	the edit item template string
access:	public

[ Top ]

method getFooterStyle [line 496]

string getFooterStyle(
)

return:	the style for footer
access:	public

[ Top ]

method getFooterTemplate [line 342]

string getFooterTemplate(
)

return:	the footer template string
access:	public

[ Top ]

method getHeaderStyle [line 479]

string getHeaderStyle(
)

return:	the style for header
access:	public

[ Top ]

method getHeaderTemplate [line 324]

string getHeaderTemplate(
)

return:	the header template string
access:	public

[ Top ]

method getItemCount [line 594]

integer getItemCount(
)

return:	number of TDataListItem control
access:	public

[ Top ]

method getItems [line 586]

array getItems(
)

return:	list of TDataListItem control
access:	public

[ Top ]

method getItemStyle [line 411]

string getItemStyle(
)

return:	the style for each item
access:	public

[ Top ]

method getItemTemplate [line 290]

string getItemTemplate(
)

return:	the template string for the item
access:	public

[ Top ]

method getRepeatColumns [line 602]

integer getRepeatColumns(
)

return:	the number of columns that the list should be displayed with.
access:	public

[ Top ]

method getRepeatDirection [line 620]

string getRepeatDirection(
)

return:	the direction of traversing the list (Vertical, Horizontal)
access:	public

[ Top ]

method getRepeatLayout [line 639]

string getRepeatLayout(
)

return:	how the list should be displayed, using table or using line breaks (Table, Flow, Raw)
access:	public

[ Top ]

method getSelectedItem [line 247]

TDataListItem getSelectedItem(
)

return:	the selected item
access:	public

[ Top ]

method getSelectedItemIndex [line 225]

integer getSelectedItemIndex(
)

return:	the index of the selected item in Items array
access:	public

[ Top ]

method getSelectedItemStyle [line 462]

string getSelectedItemStyle(
)

return:	the style for selected item
access:	public

[ Top ]

method getSelectedItemTemplate [line 377]

string getSelectedItemTemplate(
)

return:	the selected item template string
access:	public

[ Top ]

method getSeparatorStyle [line 513]

string getSeparatorStyle(
)

return:	the style for separator
access:	public

[ Top ]

method getSeparatorTemplate [line 360]

string getSeparatorTemplate(
)

return:	the separator template string
access:	public

[ Top ]

method isShowFooter [line 547]

boolean isShowFooter(
)

return:	whether the footer should be shown
access:	public

[ Top ]

method isShowHeader [line 530]

boolean isShowHeader(
)

return:	whether the header should be shown
access:	public

[ Top ]

method loadViewState [line 662]

void loadViewState(
array
$viewState)

Loads viewstate into this control and its children.

This method is overriden to load the items data from view state. If the items data is not empty, it will be used to populate the data list (to restore the previous view).

access:

public

Overrides TControl::loadViewState() (Loads viewstate into this component and its children.)

Parameters:

array

$viewState

viewstate to be loaded

[ Top ]

method onBubbleEvent [line 807]

boolean onBubbleEvent(
TControl
$sender, TEventParameter
$param)

Handles OnBubbleEvent.

This method overrides parent's implementation to handle OnItemCommand event that is bubbled from TDataListItem child controls. This method should only be used by control developers.

return:	whether the event bubbling should stop here.
access:	protected

Overrides TControl::onBubbleEvent() (This method responds to a bubbled event.)

Parameters:

TControl	$sender	the sender of the event
TEventParameter	$param	event parameter

[ Top ]

method onDataBinding [line 714]

void onDataBinding(
TEventParameter
$param)

Parses and intantiates templates.

This method is invoked when OnDataBinding event is raised. It parses and instantiates all assoicated templates for the data listing control and raises related events. This method should only used by control developers.

access:

protected

Overrides TComponent::onDataBinding() (This method is invoked when dataBind is invoked for the component.)

Parameters:

TEventParameter

$param

event parameter

[ Top ]

method onItemCommand [line 848]

void onItemCommand(
TDataListCommandEventParameter
$param)

Raises OnItemCommand and other related events.

This method is invoked after a button control in a template raises OnCommand event. You may override this method to provide customized event handling. Be sure to call parent's implementation so that event handlers have chance to respond to the event. The TDataListItem control responsible for the event can be determined from the event parameter's item field. The initial sender of the OnCommand event is in source field. The command name and parameter are in name and parameter fields, respectively.

access:

protected

Parameters:

TDataListCommandEventParameter

$param

event parameter

[ Top ]

method onItemCreated [line 829]

void onItemCreated(
TDataListItemEventParameter
$param)

Raises OnItemCreated event.

This method is invoked after a data list item is created. You may override this method to provide customized event handling. Be sure to call parent's implementation so that event handlers have chance to respond to the event. The TDataListItem control responsible for the event can be determined from the event parameter's item field.

access:

protected

Parameters:

TDataListItemEventParameter

$param

event parameter

[ Top ]

method render [line 903]

string render(
)

Displays the data list.

return:	the rendering result.
access:	public

Overrides TControl::render() (Renders this control.)

[ Top ]

method saveViewState [line 678]

array|null saveViewState(
)

Returns the viewstate of this control and its children.

This method is overriden to save the items data in view state.

return:	viewstate to be saved
access:	public

Overrides TControl::saveViewState() (Returns the viewstate of this component and its children.)

[ Top ]

method setAlternatingItemStyle [line 437]

void setAlternatingItemStyle(
string
$value)

Sets the style for each alternating item

access:

public

Parameters:

string

$value

the style for each alternating item

[ Top ]

method setAlternatingItemTemplate [line 316]

void setAlternatingItemTemplate(
string
$value)

Sets the alternative template string for the item

access:

public

Parameters:

string

$value

the alternative item template

[ Top ]

method setDataSource [line 573]

void setDataSource(
Iterator
$value)

Sets the data source.

access:

public

Overrides TBaseDataList::setDataSource() (Sets the data source that populates the items of the data listing control.)

Parameters:

Iterator

$value

the data source.

[ Top ]

method setEditItemIndex [line 268]

void setEditItemIndex(
string
$value)

Sets the index of the edit item in Items array

access:

public

Parameters:

string

$value

the edit item index

[ Top ]

method setEditItemStyle [line 454]

void setEditItemStyle(
string
$value)

Sets the style for edit item

access:

public

Parameters:

string

$value

the style for edit item

[ Top ]

method setEditItemTemplate [line 403]

void setEditItemTemplate(
string
$value)

Sets the edit item template string

access:

public

Parameters:

string

$value

the edit item template

[ Top ]

method setFooterStyle [line 505]

void setFooterStyle(
string
$value)

Sets the style for footer

access:

public

Parameters:

string

$value

the style for footer

[ Top ]

method setFooterTemplate [line 352]

void setFooterTemplate(
string
$value)

Sets the footer template.

The template will be parsed immediately.

access:

public

Parameters:

string

$value

the footer template

[ Top ]

method setHeaderStyle [line 488]

void setHeaderStyle(
string
$value)

Sets the style for header

access:

public

Parameters:

string

$value

the style for header

[ Top ]

method setHeaderTemplate [line 334]

void setHeaderTemplate(
string
$value)

Sets the header template.

The template will be parsed immediately.

access:

public

Parameters:

string

$value

the header template

[ Top ]

method setItemStyle [line 420]

void setItemStyle(
string
$value)

Sets the style for each item

access:

public

Parameters:

string

$value

the style for each item

[ Top ]

method setItemTemplate [line 299]

void setItemTemplate(
string
$value)

Sets the template string for the item

access:

public

Parameters:

string

$value

the item template

[ Top ]

method setRepeatColumns [line 611]

void setRepeatColumns(
integer
$value)

Sets the number of columns that the list should be displayed with.

access:

public

Parameters:

integer

$value

the number of columns that the list should be displayed with.

[ Top ]

method setRepeatDirection [line 629]

void setRepeatDirection(
string
$value)

Sets the direction of traversing the list (Vertical, Horizontal)

access:

public

Parameters:

string

$value

the direction of traversing the list

[ Top ]

method setRepeatLayout [line 648]

void setRepeatLayout(
string
$value)

Sets how the list should be displayed, using table or using line breaks (Table, Flow, Raw)

access:

public

Parameters:

string

$value

how the list should be displayed, using table or using line breaks (Table, Flow, Raw)

[ Top ]

method setSelectedItemIndex [line 234]

void setSelectedItemIndex(
string
$value)

Sets the index of the selected item in Items array

access:

public

Parameters:

string

$value

the selected item index

[ Top ]

method setSelectedItemStyle [line 471]

void setSelectedItemStyle(
string
$value)

Sets the style for selected item

access:

public

Parameters:

string

$value

the style for selected item

[ Top ]

method setSelectedItemTemplate [line 386]

void setSelectedItemTemplate(
string
$value)

Sets the selected item template string

access:

public

Parameters:

string

$value

the selected item template

[ Top ]

method setSeparatorStyle [line 522]

void setSeparatorStyle(
string
$value)

Sets the style for separator

access:

public

Parameters:

string

$value

the style for separator

[ Top ]

method setSeparatorTemplate [line 369]

void setSeparatorTemplate(
string
$value)

Sets the separator template string

access:

public

Parameters:

string

$value

the separator template

[ Top ]

method setShowFooter [line 556]

void setShowFooter(
boolean
$value)

Sets the value indicating whether to show footer

access:

public

Parameters:

boolean

$value

whether to show footer

[ Top ]

method setShowHeader [line 539]

void setShowHeader(
boolean
$value)

Sets the value indicating whether to show header

access:

public

Parameters:

boolean

$value

whether to show header

[ Top ]

Class Constants

CMD_CANCEL = 'cancel'

[line 153]

[ Top ]

CMD_DELETE = 'delete'

[line 152]

[ Top ]

CMD_EDIT = 'edit'

[line 149]

Recognized item commands

[ Top ]

CMD_SELECT = 'select'

[line 151]

[ Top ]

CMD_UPDATE = 'update'

[line 150]

[ Top ]

ID_FOOTER = 'Footer'

[line 143]

[ Top ]

ID_HEADER = 'Header'

[line 142]

Constants for item IDs

[ Top ]

ID_ITEM = 'Item'

[line 144]

[ Top ]

ID_SEPARATOR = 'Sep'

[line 145]

[ Top ]