PRADO Component Framework for PHP 5
  • Home
  • About
  • Testimonials
  • Demos
  • Download
  • Documentation
  • Forum
  • Development
  • Tutorials
  • Class Docs
  • API Manual
  • Wiki

Packages

  • None
  • System
    • Caching
    • Collections
    • Data
      • ActiveRecord
        • Relations
        • Scaffold
          • InputBuilder
      • Commom
        • Sqlite
      • Common
        • Mssql
        • Mysql
        • Oracle
        • Pgsql
        • Sqlite
      • DataGateway
      • SqlMap
        • Configuration
        • Statements
    • Exceptions
    • I18N
    • IO
    • Security
    • Util
    • Web
      • Javascripts
      • Services
      • UI
        • ActiveControls
        • WebControls
    • Xml
  • Wsat
    • pages
  • Overview
  • Package
  • Class
  • Tree
  • Deprecated
  • Todo

Class TRepeater

TRepeater class.

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

  • setItemTemplate ItemTemplate, setItemRenderer ItemRenderer:

for each repeated row of data

  • setAlternatingItemTemplate AlternatingItemTemplate, setAlternatingItemRenderer AlternatingItemRenderer:

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

  • setHeaderTemplate HeaderTemplate, setHeaderRenderer HeaderRenderer:

for the repeater header.

  • setFooterTemplate FooterTemplate, setFooterRenderer FooterRenderer:

for the repeater footer.

  • setSeparatorTemplate SeparatorTemplate, setSeparatorRenderer SeparatorRenderer:

for content to be displayed between items.

  • setEmptyTemplate EmptyTemplate, setEmptyRenderer 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 TDataBoundControl::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 OnItemCreated:
  • add the item as a child control
  • call dataBind() of the item
  • raise onItemDataBound OnItemDataBound:

TRepeater raises an onItemCommand 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 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 getDataKeys 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.

TComponent
Extended by TApplicationComponent
Extended by TControl implements IRenderable, IBindable
Extended by TWebControl implements IStyleable
Extended by TDataBoundControl
Extended by TRepeater implements INamingContainer

Direct known subclasses

TActiveRepeater
Package: System\Web\UI\WebControls
Copyright: Copyright © 2005-2014 PradoSoft
License: http://www.pradosoft.com/license/
Author: Qiang Xue <qiang.xue@gmail.com>
Since: 3.0
Located at Web/UI/WebControls/TRepeater.php
Methods summary
public string
# getItemRenderer( )

Returns

string
the class name for repeater items. Defaults to empty, meaning not set.

Since

3.1.0
public
# setItemRenderer( string $value )

Sets the item renderer class.

Sets the item renderer class.

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

Parameters

$value
string
the renderer class name in namespace format.

Since

3.1.0

See

TRepeater::setItemTemplate()
public string
# getAlternatingItemRenderer( )

Returns

string
the class name for alternative repeater items. Defaults to empty, meaning not set.

Since

3.1.0
public
# setAlternatingItemRenderer( string $value )

Sets the alternative item renderer class.

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 getAlternatingItemTemplate AlternatingItemTemplate.

Parameters

$value
string
the renderer class name in namespace format.

Since

3.1.0

See

TRepeater::setAlternatingItemTemplate()
public string
# getSeparatorRenderer( )

Returns

string
the class name for repeater item separators. Defaults to empty, meaning not set.

Since

3.1.0
public
# setSeparatorRenderer( string $value )

Sets the repeater item separator renderer class.

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 getSeparatorTemplate SeparatorTemplate.

Parameters

$value
string
the renderer class name in namespace format.

Since

3.1.0

See

TRepeater::setSeparatorTemplate()
public string
# getHeaderRenderer( )

Returns

string
the class name for repeater header item. Defaults to empty, meaning not set.

Since

3.1.0
public
# setHeaderRenderer( string $value )

Sets the repeater header renderer class.

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 getHeaderTemplate HeaderTemplate.

Parameters

$value
string
the renderer class name in namespace format.

Since

3.1.0

See

TRepeater::setHeaderTemplate()
public string
# getFooterRenderer( )

Returns

string
the class name for repeater footer item. Defaults to empty, meaning not set.

Since

3.1.0
public
# setFooterRenderer( string $value )

Sets the repeater footer renderer class.

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 getFooterTemplate FooterTemplate.

Parameters

$value
string
the renderer class name in namespace format.

Since

3.1.0

See

TRepeater::setFooterTemplate()
public string
# getEmptyRenderer( )

Returns

string
the class name for empty repeater item. Defaults to empty, meaning not set.

Since

3.1.0
public
# setEmptyRenderer( string $value )

Sets the repeater empty renderer class.

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 getEmptyTemplate EmptyTemplate.

Parameters

$value
string
the renderer class name in namespace format.

Since

3.1.0

See

TRepeater::setEmptyTemplate()
public ITemplate
# getItemTemplate( )

Returns

ITemplate
the template for repeater items
public
# setItemTemplate( ITemplate $value )

Parameters

$value
ITemplate
the template for repeater items

Throws

TInvalidDataTypeException
if the input is not an ITemplate or not null.
public ITemplate
# getAlternatingItemTemplate( )

Returns

ITemplate
the alternative template string for the item
public
# setAlternatingItemTemplate( ITemplate $value )

Parameters

$value
ITemplate
the alternative item template

Throws

TInvalidDataTypeException
if the input is not an ITemplate or not null.
public ITemplate
# getHeaderTemplate( )

Returns

ITemplate
the header template
public
# setHeaderTemplate( ITemplate $value )

Parameters

$value
ITemplate
the header template

Throws

TInvalidDataTypeException
if the input is not an ITemplate or not null.
public ITemplate
# getFooterTemplate( )

Returns

ITemplate
the footer template
public
# setFooterTemplate( ITemplate $value )

Parameters

$value
ITemplate
the footer template

Throws

TInvalidDataTypeException
if the input is not an ITemplate or not null.
public ITemplate
# getEmptyTemplate( )

Returns

ITemplate
the template applied when no data is bound to the repeater
public
# setEmptyTemplate( ITemplate $value )

Parameters

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

Throws

TInvalidDataTypeException
if the input is not an ITemplate or not null.
public ITemplate
# getSeparatorTemplate( )

Returns

ITemplate
the separator template
public
# setSeparatorTemplate( ITemplate $value )

Parameters

$value
ITemplate
the separator template

Throws

TInvalidDataTypeException
if the input is not an ITemplate or not null.
public TControl
# getHeader( )

Returns

TControl
the header item
public TControl
# getFooter( )

Returns

TControl
the footer item
public TRepeaterItemCollection
# getItems( )

Returns

TRepeaterItemCollection
list of repeater item controls
public string
# getDataKeyField( )

Returns

string
the field of the data source that provides the keys of the list items.
public
# setDataKeyField( string $value )

Parameters

$value
string
the field of the data source that provides the keys of the list items.
public TList
# getDataKeys( )

Returns

TList
the keys used in the data listing control.
protected TControl
# createItem( integer $itemIndex, TListItemType $itemType )

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

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

Parameters

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

Returns

TControl
created repeater item
protected
# createEmptyContent( )

Creates empty repeater content.

Creates empty repeater content.

public
# render( THtmlWriter $writer )

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.

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.

Parameters

$writer
THtmlWriter
writer

Overrides

TWebControl::render()
public
# saveState( )

Saves item count in viewstate. This method is invoked right before control state is to be saved.

Saves item count in viewstate. This method is invoked right before control state is to be saved.

Overrides

TControl::saveState()
public
# loadState( )

Loads item count information from viewstate. This method is invoked right after control state is loaded.

Loads item count information from viewstate. This method is invoked right after control state is loaded.

Overrides

TControl::loadState()
public
# reset( )

Clears up all items in the repeater.

Clears up all items in the repeater.

protected
# restoreItemsFromViewState( )

Creates repeater items based on viewstate information.

Creates repeater items based on viewstate information.

protected
# performDataBinding( Traversable $data )

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.

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.

Parameters

$data
Traversable
the data
public boolean
# bubbleEvent( TControl $sender, TEventParameter $param )

This method overrides parent's implementation to handle onItemCommand OnItemCommand event which is bubbled from repeater items and their child controls. This method should only be used by control developers.

This method overrides parent's implementation to handle onItemCommand OnItemCommand event which is bubbled from repeater items and their child controls. This method should only be used by control developers.

Parameters

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

Returns

boolean
whether the event bubbling should stop here.

Overrides

TControl::bubbleEvent()
public
# onItemCreated( TRepeaterItemEventParameter $param )

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.

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.

Parameters

$param
TRepeaterItemEventParameter
event parameter
public
# onItemDataBound( TRepeaterItemEventParameter $param )

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.

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.

Parameters

$param
TRepeaterItemEventParameter
event parameter
public
# onItemCommand( TRepeaterCommandEventParameter $param )

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.

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.

Parameters

$param
TRepeaterCommandEventParameter
event parameter
protected mixed
# getDataFieldValue( mixed $data, mixed $field )

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.

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.

Parameters

$data
mixed
data item
$field
mixed
field name

Returns

mixed
data value at the specified field

Throws

TInvalidDataValueException
if the data is invalid
Methods inherited from TDataBoundControl
createPagedDataSource(), dataBind(), dataSourceViewChanged(), determineDataSource(), ensureDataBound(), getAllowCustomPaging(), getAllowPaging(), getCurrentPageIndex(), getDataMember(), getDataSource(), getDataSourceID(), getDataSourceView(), getInitialized(), getIsDataBound(), getPageCount(), getPageSize(), getRequiresDataBinding(), getSelectParameters(), getUsingDataSourceID(), getVirtualItemCount(), onDataBound(), onDataSourceChanged(), onInit(), onPreRender(), pagePreLoad(), setAllowCustomPaging(), setAllowPaging(), setCurrentPageIndex(), setDataMember(), setDataSource(), setDataSourceID(), setInitialized(), setIsDataBound(), setPageSize(), setRequiresDataBinding(), setVirtualItemCount(), validateDataSource()
Methods inherited from TWebControl
addAttributesToRender(), clearStyle(), copyBaseAttributes(), createStyle(), getAccessKey(), getBackColor(), getBorderColor(), getBorderStyle(), getBorderWidth(), getCssClass(), getDecorator(), getDisplay(), getEnsureId(), getFont(), getForeColor(), getHasStyle(), getHeight(), getStyle(), getTabIndex(), getTagName(), getToolTip(), getWidth(), renderBeginTag(), renderContents(), renderEndTag(), setAccessKey(), setBackColor(), setBorderColor(), setBorderStyle(), setBorderWidth(), setCssClass(), setDisplay(), setEnsureId(), setForeColor(), setHeight(), setStyle(), setTabIndex(), setToolTip(), setWidth()
Methods inherited from TControl
__construct(), __get(), addParsedObject(), addToPostDataLoader(), addedControl(), applyStyleSheetSkin(), autoBindProperty(), autoDataBindProperties(), bindProperty(), broadcastEvent(), clearChildState(), clearControlState(), clearNamingContainer(), clearViewState(), convertUniqueIdToClientId(), createChildControls(), createControlCollection(), dataBindChildren(), dataBindProperties(), ensureChildControls(), findControl(), findControlsByID(), findControlsByType(), focus(), getAdapter(), getAllowChildControls(), getAttribute(), getAttributes(), getChildControlsCreated(), getClientID(), getControlStage(), getControlState(), getControls(), getCustomData(), getEnableTheming(), getEnableViewState(), getEnabled(), getHasAdapter(), getHasAttributes(), getHasChildInitialized(), getHasControls(), getHasInitialized(), getHasLoaded(), getHasLoadedPostData(), getHasPreRendered(), getID(), getIsSkinApplied(), getNamingContainer(), getPage(), getParent(), getRegisteredObject(), getSkinID(), getSourceTemplateControl(), getTemplateControl(), getUniqueID(), getViewState(), getVisible(), hasAttribute(), initRecursive(), isDescendentOf(), isObjectRegistered(), loadRecursive(), loadStateRecursive(), onDataBinding(), onLoad(), onUnload(), preRenderRecursive(), raiseBubbleEvent(), registerObject(), removeAttribute(), removedControl(), renderChildren(), renderControl(), saveStateRecursive(), setAdapter(), setAttribute(), setChildControlsCreated(), setControlStage(), setControlState(), setCustomData(), setEnableTheming(), setEnableViewState(), setEnabled(), setID(), setPage(), setSkinID(), setTemplateControl(), setViewState(), setVisible(), trackViewState(), traverseChildControls(), unbindProperty(), unloadRecursive(), unregisterObject()
Methods inherited from TApplicationComponent
getApplication(), getRequest(), getResponse(), getService(), getSession(), getUser(), publishAsset(), publishFilePath()
Methods inherited from TComponent
__call(), __destruct(), __isset(), __set(), __sleep(), __unset(), __wakeup(), asa(), attachBehavior(), attachBehaviors(), attachClassBehavior(), attachEventHandler(), canGetProperty(), canSetProperty(), clearBehaviors(), createdOnTemplate(), detachBehavior(), detachBehaviors(), detachClassBehavior(), detachEventHandler(), disableBehavior(), disableBehaviors(), enableBehavior(), enableBehaviors(), evaluateExpression(), evaluateStatements(), fxAttachClassBehavior(), fxDetachClassBehavior(), getAutoGlobalListen(), getBehaviorsEnabled(), getClassHierarchy(), getEventHandlers(), getListeningToGlobalEvents(), getSubProperty(), hasEvent(), hasEventHandler(), hasProperty(), isa(), listen(), raiseEvent(), setSubProperty(), unlisten()
Constants summary
string IT_HEADER 'Header'
#

Repeater item types

Repeater item types

Deprecated

deprecated since version 3.0.4. Use TListItemType constants instead.
string IT_FOOTER 'Footer'
#
string IT_ITEM 'Item'
#
string IT_SEPARATOR 'Separator'
#
string IT_ALTERNATINGITEM 'AlternatingItem'
#
Constants inherited from TControl
AUTOMATIC_ID_PREFIX, CLIENT_ID_SEPARATOR, CS_CHILD_INITIALIZED, CS_CONSTRUCTED, CS_INITIALIZED, CS_LOADED, CS_PRERENDERED, CS_STATE_LOADED, ID_FORMAT, ID_SEPARATOR, IS_CHILD_CREATED, IS_CREATING_CHILD, IS_DISABLE_THEMING, IS_DISABLE_VIEWSTATE, IS_ID_SET, IS_SKIN_APPLIED, IS_STYLESHEET_APPLIED, RF_ADAPTER, RF_AUTO_BINDINGS, RF_CHILD_STATE, RF_CONTROLS, RF_CONTROLSTATE, RF_DATA_BINDINGS, RF_EVENTS, RF_NAMED_CONTROLS, RF_NAMED_CONTROLS_ID, RF_NAMED_OBJECTS, RF_SKIN_ID
Constants inherited from TComponent
GLOBAL_RAISE_EVENT_LISTENER
Properties inherited from TWebControl
$_decorator
Terms of Service | Contact Us
PRADO v3.2.4 API Manual API documentation generated by ApiGen 2.8.0
Copyright © 2006-2014 by the PRADO Group.
Powered by PRADO