## Class TRepeater

Description

Implements interfaces:

- INamingContainer

TRepeater class.

TRepeater displays its content repeatedly based on the data fetched from DataSource. The repeated contents in TRepeater are called items, which are controls and can be accessed through Items. When dataBind() is invoked, TRepeater creates an item for each row of data and binds the data row to the item. Optionally, a repeater can have a header, a footer and/or separators between items.

The layout of the repeated contents are specified by inline templates. Repeater 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 specified by renderers. A renderer is a control class that can be instantiated as repeater 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 repeater item collection, and the ItemType property as the item's type (such as TListItemType::Item). TRepeaterItemRenderer 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 repeater:

- 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 repeater header.

- FooterTemplate, FooterRenderer:

for the repeater footer.

- SeparatorTemplate, SeparatorRenderer:

for content to be displayed between items.

- EmptyTemplate, EmptyRenderer:

used when data bound to the repeater is empty.

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

When dataBind() is being called, TRepeater 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:

TRepeater raises an OnItemCommand whenever a button control within some repeater 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.

When a page containing a repeater is post back, the repeater 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 repeater 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
- version: $Id: TRepeater.php 2227 2007-09-17 12:56:51Z xue $
- author: Qiang Xue <qiang.xue@gmail.com>

Located in /Web/UI/WebControls/TRepeater.php (line 94)

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

Class Constant Summary
IT_ALTERNATINGITEM = 'AlternatingItem'
IT_FOOTER = 'Footer'
IT_HEADER = 'Header'
IT_ITEM = 'Item'
IT_SEPARATOR = 'Separator'
Method Summary
boolean bubbleEvent (TControl $sender, TEventParameter $param)
void createEmptyContent ()
TControl createItem (integer $itemIndex, TListItemType $itemType)
string getAlternatingItemRenderer ()
ITemplate getAlternatingItemTemplate ()
mixed getDataFieldValue (mixed $data, mixed $field)
string getDataKeyField ()
TList getDataKeys ()
string getEmptyRenderer ()
ITemplate getEmptyTemplate ()
TControl getFooter ()
string getFooterRenderer ()
ITemplate getFooterTemplate ()
TControl getHeader ()
string getHeaderRenderer ()
ITemplate getHeaderTemplate ()
string getItemRenderer ()
TRepeaterItemCollection getItems ()
ITemplate getItemTemplate ()
string getSeparatorRenderer ()
ITemplate getSeparatorTemplate ()
void loadState ()
void onItemCommand (TRepeaterCommandEventParameter $param)
void onItemCreated (TRepeaterItemEventParameter $param)
void onItemDataBound (TRepeaterItemEventParameter $param)
void performDataBinding (Traversable $data)
void render (THtmlWriter $writer)
void reset ()
void restoreItemsFromViewState ()
void saveState ()
void setAlternatingItemRenderer (string $value)
void setAlternatingItemTemplate (ITemplate $value)
void setDataKeyField (string $value)
void setEmptyRenderer (string $value)
void setEmptyTemplate (ITemplate $value)
void setFooterRenderer (string $value)
void setFooterTemplate (ITemplate $value)
void setHeaderRenderer (string $value)
void setHeaderTemplate (ITemplate $value)
void setItemRenderer (string $value)
void setItemTemplate (ITemplate $value)
void setSeparatorRenderer (string $value)
void setSeparatorTemplate (ITemplate $value)
Methods
bubbleEvent (line 703)

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

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)

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

Redefinition of:

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

createEmptyContent (line 572)

Creates empty repeater content.

- access: protected

void createEmptyContent ()
createItem (line 515)

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

- return: created repeater item
- access: protected

TControl createItem (integer $itemIndex, TListItemType $itemType)

- integer $itemIndex: zero-based item index
- TListItemType $itemType: item type

getAlternatingItemRenderer (line 172)

- return: the class name for alternative repeater items. Defaults to empty, meaning not set.
- access: public
- since: 3.1.0

string getAlternatingItemRenderer ()
getAlternatingItemTemplate (line 312)

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

ITemplate getAlternatingItemTemplate ()
getDataFieldValue (line 773)

Returns the value of the data at the specified field.

If data is an array, TMap or TList, the value will be returned at the index of the specified field. If the data is a component with a property named as the field name, the property value will be returned. Otherwise, an exception will be raised.

- return: data value at the specified field
- access: protected
- throws: TInvalidDataValueException if the data is invalid

mixed getDataFieldValue (mixed $data, mixed $field)

- mixed $data: data item
- mixed $field: field name

getDataKeyField (line 438)

- return: the field of the data source that provides the keys of the list items.
- access: public

string getDataKeyField ()
getDataKeys (line 454)

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

TList getDataKeys ()
getEmptyRenderer (line 268)

- return: the class name for empty repeater item. Defaults to empty, meaning not set.
- access: public
- since: 3.1.0

string getEmptyRenderer ()
getEmptyTemplate (line 372)

- return: the template applied when no data is bound to the repeater
- access: public

ITemplate getEmptyTemplate ()
getFooter (line 420)

- return: the footer item
- access: public

TControl getFooter ()
getFooterRenderer (line 244)

- return: the class name for repeater footer item. Defaults to empty, meaning not set.
- access: public
- since: 3.1.0

string getFooterRenderer ()
getFooterTemplate (line 352)

- return: the footer template
- access: public

ITemplate getFooterTemplate ()
getHeader (line 412)

- return: the header item
- access: public

TControl getHeader ()
getHeaderRenderer (line 220)

- return: the class name for repeater header item. Defaults to empty, meaning not set.
- access: public
- since: 3.1.0

string getHeaderRenderer ()
getHeaderTemplate (line 332)

- return: the header template
- access: public

ITemplate getHeaderTemplate ()
getItemRenderer (line 148)

- return: the class name for repeater items. Defaults to empty, meaning not set.
- access: public
- since: 3.1.0

string getItemRenderer ()
getItems (line 428)

- return: list of repeater item controls
- access: public

TRepeaterItemCollection getItems ()
getItemTemplate (line 292)

- return: the template for repeater items
- access: public

ITemplate getItemTemplate ()
getSeparatorRenderer (line 196)

- return: the class name for repeater item separators. Defaults to empty, meaning not set.
- access: public
- since: 3.1.0

string getSeparatorRenderer ()
getSeparatorTemplate (line 392)

- return: the separator template
- access: public

ITemplate getSeparatorTemplate ()
loadState (line 609)

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.

onItemCommand (line 757)

Raises OnItemCommand event.

This method is invoked after a button control in a template raises OnCommand event. The repeater control responsible for the event can be determined from the event parameter. The event parameter also contains the information about the initial sender of the OnCommand event, command name and command parameter. 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.

- access: public

void onItemCommand (TRepeaterCommandEventParameter $param)

- TRepeaterCommandEventParameter $param: event parameter

onItemCreated (line 724)

Raises OnItemCreated event.

This method is invoked after a repeater item is created and instantiated with template, but before added to the page hierarchy. The repeater 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.

- access: public

void onItemCreated (TRepeaterItemEventParameter $param)

- TRepeaterItemEventParameter $param: event parameter

onItemDataBound (line 738)

Raises OnItemDataBound event.

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

- access: public

void onItemDataBound (TRepeaterItemEventParameter $param)

- TRepeaterItemEventParameter $param: event parameter

performDataBinding (line 659)

Performs databinding to populate repeater 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 586)

Renders the repeater.

This method overrides the parent implementation by rendering the body content as the whole presentation of the repeater. Outer tag is not rendered.

- access: public

void render (THtmlWriter $writer)

- THtmlWriter $writer: writer

Redefinition of:

TWebControl::render()
  Renders the control.

reset (line 620)

Clears up all items in the repeater.

- access: public

void reset ()
restoreItemsFromViewState (line 631)

Creates repeater items based on viewstate information.

- access: protected

void restoreItemsFromViewState ()
saveState (line 596)

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.

setAlternatingItemRenderer (line 187)

Sets the alternative item renderer class.

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

- access: public
- since: 3.1.0
- see: TRepeater::setAlternatingItemTemplate()

void setAlternatingItemRenderer (string $value)

- string $value: the renderer class name in namespace format.

setAlternatingItemTemplate (line 321)

- access: public
- throws: TInvalidDataTypeException if the input is not an ITemplate or not null.

void setAlternatingItemTemplate (ITemplate $value)

- ITemplate $value: the alternative item template

setDataKeyField (line 446)

- access: public

void setDataKeyField (string $value)

- string $value: the field of the data source that provides the keys of the list items.

setEmptyRenderer (line 284)

Sets the repeater empty renderer class.

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

- access: public
- since: 3.1.0
- see: TRepeater::setEmptyTemplate()

void setEmptyRenderer (string $value)

- string $value: the renderer class name in namespace format.

setEmptyTemplate (line 381)

- access: public
- throws: TInvalidDataTypeException if the input is not an ITemplate or not null.

void setEmptyTemplate (ITemplate $value)

- ITemplate $value: the template applied when no data is bound to the repeater

setFooterRenderer (line 259)

Sets the repeater footer renderer class.

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

- access: public
- since: 3.1.0
- see: TRepeater::setFooterTemplate()

void setFooterRenderer (string $value)

- string $value: the renderer class name in namespace format.

setFooterTemplate (line 361)

- access: public
- throws: TInvalidDataTypeException if the input is not an ITemplate or not null.

void setFooterTemplate (ITemplate $value)

- ITemplate $value: the footer template

setHeaderRenderer (line 235)

Sets the repeater header renderer class.

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

- access: public
- since: 3.1.0
- see: TRepeater::setHeaderTemplate()

void setHeaderRenderer (string $value)

- string $value: the renderer class name in namespace format.

setHeaderTemplate (line 341)

- access: public
- throws: TInvalidDataTypeException if the input is not an ITemplate or not null.

void setHeaderTemplate (ITemplate $value)

- ITemplate $value: the header template

setItemRenderer (line 163)

Sets the item renderer class.

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

- access: public
- since: 3.1.0
- see: TRepeater::setItemTemplate()

void setItemRenderer (string $value)

- string $value: the renderer class name in namespace format.

setItemTemplate (line 301)

- access: public
- throws: TInvalidDataTypeException if the input is not an ITemplate or not null.

void setItemTemplate (ITemplate $value)

- ITemplate $value: the template for repeater items

setSeparatorRenderer (line 211)

Sets the repeater item separator renderer class.

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

- access: public
- since: 3.1.0
- see: TRepeater::setSeparatorTemplate()

void setSeparatorRenderer (string $value)

- string $value: the renderer class name in namespace format.

setSeparatorTemplate (line 401)

- access: public
- throws: TInvalidDataTypeException if the input is not an ITemplate or not null.

void setSeparatorTemplate (ITemplate $value)

- ITemplate $value: the separator template

#### Inherited 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::performDataBinding()
> TDataBoundControl::setAllowCustomPaging()
> TDataBoundControl::setAllowPaging()
> TDataBoundControl::setCurrentPageIndex()
> TDataBoundControl::setDataMember()
> TDataBoundControl::setDataSource()
> TDataBoundControl::setDataSourceID()
> TDataBoundControl::setInitialized()
> TDataBoundControl::setIsDataBound()
> TDataBoundControl::setPageSize()
> TDataBoundControl::setRequiresDataBinding()
> TDataBoundControl::setVirtualItemCount()
> TDataBoundControl::validateDataSource()

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
IT_ALTERNATINGITEM = 'AlternatingItem' (line 104)
IT_FOOTER = 'Footer' (line 101)
IT_HEADER = 'Header' (line 100)

Repeater item types

- deprecated: deprecated since version 3.0.4. Use TListItemType constants instead.

IT_ITEM = 'Item' (line 102)
IT_SEPARATOR = 'Separator' (line 103)

#### 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 Sun, 30 Sep 2007 19:17:07 -0400 by phpDocumentor 1.3.0RC4