## Class TDataBoundControl

Description

TDataBoundControl class.

TDataBoundControl is the based class for controls that need to populate data from data sources. It provides basic properties and methods that allow the derived controls to associate with data sources and retrieve data from them.

TBC....

TDataBoundControl is equipped with paging capabilities. By setting AllowPaging to true, the input data will be paged and only one page of data is actually populated into the data-bound control. This saves a lot of memory when dealing with larget datasets.

To specify the number of data items displayed on each page, set the PageSize property, and to specify which page of data to be displayed, set CurrentPageIndex.

When the size of the original data is too big to be loaded all in the memory, one can enable custom paging. In custom paging, the total number of data items is specified manually via VirtualItemCount, and the data source only needs to contain the current page of data. To enable custom paging, set AllowCustomPaging to true.

- abstract:
- since: 3.0
- version: $Id: TDataBoundControl.php 2492 2008-08-09 01:30:05Z knut $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TDataBoundControl.php (line 46)

    TComponent
       |
       --TApplicationComponent
          |
          --TControl
             |
             --TWebControl
                |
                --TDataBoundControl

Direct descendents

Class | Description
--- | ---
TBaseDataList | TBaseDataList class
TListControl | TListControl class
TRepeater | TRepeater class.

Method Summary
TPagedDataSource createPagedDataSource ()
void dataBind ()
void dataSourceViewChanged (mixed $sender, mixed $param)
void determineDataSource ()
void ensureDataBound ()
boolean getAllowCustomPaging ()
boolean getAllowPaging ()
integer getCurrentPageIndex ()
void getDataMember ()
Traversable getDataSource ()
string getDataSourceID ()
void getDataSourceView ()
boolean getInitialized ()
boolean getIsDataBound ()
integer getPageCount ()
integer getPageSize ()
boolean getRequiresDataBinding ()
void getSelectParameters ()
boolean getUsingDataSourceID ()
integer getVirtualItemCount ()
void onDataBound (mixed $param)
void onDataSourceChanged ()
void onInit (TEventParameter $param)
void onPreRender (TEventParameter $param)
void pagePreLoad (mixed $sender, TEventParameter $param)
void performDataBinding (mixed $data)
void setAllowCustomPaging (boolean $value)
void setAllowPaging (boolean $value)
void setCurrentPageIndex (integer $value)
void setDataMember (mixed $value)
void setDataSource (Traversable|array|string $value)
void setDataSourceID (string $value)
void setInitialized (boolean $value)
void setIsDataBound (boolean $value)
void setPageSize (integer $value)
void setRequiresDataBinding (boolean $value)
void setVirtualItemCount (integer $value)
Traversable validateDataSource (Traversable|array|string $value)
Methods
createPagedDataSource (line 309)

- return: creates a paged data source
- access: protected

TPagedDataSource createPagedDataSource ()
dataBind (line 326)

Performs databinding.

This method overrides the parent implementation by calling performSelect which fetches data from data source and does the actual binding work.

- access: public

void dataBind ()

Redefinition of:

TControl::dataBind()
  Performs the databinding for this control.

dataSourceViewChanged (line 361)

- access: public

void dataSourceViewChanged (mixed $sender, mixed $param)
determineDataSource (line 388)

- access: protected

void determineDataSource ()
ensureDataBound (line 297)

Ensures any pending dataBind is called.

This method calls dataBind if the data source is specified by setDataSourceID or if RequiresDataBinding is true.

- access: protected

void ensureDataBound ()
getAllowCustomPaging (line 189)

- return: whether the custom paging is enabled. Defaults to false.
- access: public

boolean getAllowCustomPaging ()
getAllowPaging (line 173)

- return: whether paging is enabled. Defaults to false.
- access: public

boolean getAllowPaging ()
getCurrentPageIndex (line 209)

- return: the zero-based index of the current page. Defaults to 0.
- access: public

integer getCurrentPageIndex ()
getDataMember (line 495)

- access: public

void getDataMember ()
getDataSource (line 64)

- return: data source object, defaults to null.
- access: public

Traversable getDataSource ()
getDataSourceID (line 85)

- return: ID path to the data source control. Defaults to empty.
- access: public

string getDataSourceID ()
getDataSourceView (line 367)

- access: protected

void getDataSourceView ()
getInitialized (line 129)

- return: whether the databound control has been initialized. By default, the control is initialized after its viewstate has been restored.
- access: protected

boolean getInitialized ()
getIsDataBound (line 149)

- return: whether databind has been invoked in the previous page request
- access: protected

boolean getIsDataBound ()
getPageCount (line 247)

- return: number of pages of data items available
- access: public

integer getPageCount ()
getPageSize (line 228)

- return: the number of data items on each page. Defaults to 10.
- access: public

integer getPageSize ()
getRequiresDataBinding (line 165)

- return: whether a databind call is required (by the data bound control)
- access: protected

boolean getRequiresDataBinding ()
getSelectParameters (line 505)

- access: public

void getSelectParameters ()
getUsingDataSourceID (line 108)

- return: if the databound control uses the data source specified by setDataSourceID, or it uses the data source object specified by setDataSource.
- access: protected

boolean getUsingDataSourceID ()
getVirtualItemCount (line 256)

- return: virtual number of data items in the data source. Defaults to 0.
- access: public
- see: TDataBoundControl::setAllowCustomPaging()

integer getVirtualItemCount ()
onDataBound (line 417)

Raises OnDataBound event.

This method should be invoked after a databind is performed. It is mainly used by framework and component developers.

- access: public

void onDataBound (mixed $param)
onDataSourceChanged (line 117)

Sets setRequiresDataBinding as true if the control is initialized.

This method is invoked when either setDataSource or setDataSourceID is changed.

- access: public

void onDataSourceChanged ()
onInit (line 429)

Sets page's OnPreLoad event handler as pagePreLoad.

If viewstate is disabled and the current request is a postback, RequiresDataBinding will be set true. This method overrides the parent implementation.

- access: public

void onInit (TEventParameter $param)

- TEventParameter $param: event parameter

Redefinition of:

TControl::onInit()
  This method is invoked when the control enters 'OnInit' stage.

onPreRender (line 455)

Ensures any pending databind is performed.

This method overrides the parent implementation.

- access: public

void onPreRender (TEventParameter $param)

- TEventParameter $param: event parameter

Redefinition of:

TControl::onPreRender()
  This method is invoked when the control enters 'OnPreRender' stage.

Redefined in descendants as:

- TCheckBoxList::onPreRender() : Registers for post data on postback.
- TRatingList::onPreRender() : Publish the the rating style css file and rating image files.
- TActiveDropDownList::onPreRender() : Updates the client-side options if the item list has changed after the OnLoad event.
- TListBox::onPreRender() : Registers the list control to load post data on postback.
- TActiveListBox::onPreRender() : Updates the client-side options if the item list has changed after the OnLoad event.

pagePreLoad (line 442)

Sets getInitialized as true.

This method is invoked when page raises PreLoad event.

- access: public

void pagePreLoad (mixed $sender, TEventParameter $param)

- mixed $sender: event sender
- TEventParameter $param: event parameter

performDataBinding (line 410)

- access: protected
- abstract:

void performDataBinding (mixed $data)

Redefined in descendants as:

- TDataGrid::performDataBinding() : Performs databinding to populate datagrid items from data source.
- TDataList::performDataBinding() : Performs databinding to populate data list items from data source.
- TListControl::performDataBinding() : Performs databinding to populate list items from data source.
- TRepeater::performDataBinding() : Performs databinding to populate repeater items from data source.

setAllowCustomPaging (line 201)

Sets a value indicating whether the custom paging should be enabled.

When the pager is in custom paging mode, the VirtualItemCount property is used to determine the paging, and the data items in the DataSource are considered to be in the current page.

- access: public

void setAllowCustomPaging (boolean $value)

- boolean $value: whether the custom paging is enabled

setAllowPaging (line 181)

- access: public

void setAllowPaging (boolean $value)

- boolean $value: whether paging is enabled

setCurrentPageIndex (line 218)

- access: public
- throws: TInvalidDataValueException if the value is less than 0

void setCurrentPageIndex (integer $value)

- integer $value: the zero-based index of the current page

setDataMember (line 500)

- access: public

void setDataMember (mixed $value)
setDataSource (line 76)

Sets the data source object associated with the databound control.

The data source must implement Traversable interface. If an array is given, it will be converted to xxx. If a string is given, it will be converted to xxx.

- access: public

void setDataSource (Traversable|array|string $value)

- Traversable|array|string $value: data source object

setDataSourceID (line 94)

- access: public

void setDataSourceID (string $value)

- string $value: ID path to the data source control. The data source control must be locatable via TControl::findControl call.

setInitialized (line 141)

Sets a value indicating whether the databound control is initialized.

If initialized, any modification to DataSource or DataSourceID will set RequiresDataBinding as true.

- access: protected

void setInitialized (boolean $value)

- boolean $value: a value indicating whether the databound control is initialized.

setIsDataBound (line 157)

- access: protected

void setIsDataBound (boolean $value)

- boolean $value: if databind has been invoked in this page request

setPageSize (line 237)

- access: public
- throws: TInvalidDataValueException if the value is less than 1

void setPageSize (integer $value)

- integer $value: the number of data items on each page.

setRequiresDataBinding (line 279)

Sets a value indicating whether a databind call is required by the data bound control.

If true and the control has been prerendered while it uses the data source specified by setDataSourceID, a databind call will be called by this method.

- access: protected

void setRequiresDataBinding (boolean $value)

- boolean $value: whether a databind call is required.

setVirtualItemCount (line 266)

- access: public
- see: TDataBoundControl::setAllowCustomPaging()
- throws: TInvalidDataValueException if the value is less than 0

void setVirtualItemCount (integer $value)

- integer $value: virtual number of data items in the data source.

validateDataSource (line 469)

Validates if the parameter is a valid data source.

If it is a string or an array, it will be converted as a TList object.

- return: the data that is traversable
- access: protected
- throws: TInvalidDataTypeException if the data is neither null nor Traversable

Traversable validateDataSource (Traversable|array|string $value)

- Traversable|array|string $value: data source to be validated

#### Inherited 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()

Inherited From TControl

> TControl::__construct()
> 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()

Inherited From TApplicationComponent

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

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()

Class Constants

#### Inherited Constants

Inherited from TControl

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

Documentation generated on Mon, 22 Feb 2010 12:17:18 +0000 by phpDocumentor 1.3.0RC4