Class TRepeater
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. property will be set as the data row during databinding. Many PRADO controls implement this interface, such as TLabel, TTextBox, etc. 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: for each repeated row of data for each alternating row of data. If not set, ItemTemplate or ItemRenderer will be used instead. for the repeater header. for the repeater footer. for content to be displayed between items. 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.
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,
|
Method Summary |
boolean
|
This method overrides parent's implementation to handle onItemCommand event which is bubbled from repeater items and their child controls.
|
protected
void
|
Creates empty repeater content.
|
protected
TControl
|
Creates a repeater item instance based on the item type and index.
|
string
|
|
ITemplate
|
|
protected
mixed
|
Returns the value of the data at the specified field.
|
string
|
|
TList
|
|
string
|
|
ITemplate
|
|
TControl
|
|
string
|
|
ITemplate
|
|
TControl
|
|
string
|
|
ITemplate
|
|
string
|
|
TRepeaterItemCollection
|
|
ITemplate
|
|
string
|
|
ITemplate
|
|
void
|
Loads item count information from viewstate.
|
void
|
Raises OnItemCommand event.
|
void
|
Raises OnItemCreated event.
|
void
|
Raises OnItemDataBound event.
|
protected
void
|
Performs databinding to populate repeater items from data source.
|
void
|
Renders the repeater.
|
void
|
Clears up all items in the repeater.
|
protected
void
|
Creates repeater items based on viewstate information.
|
void
|
Saves item count in viewstate.
|
void
|
Sets the alternative item renderer class.
|
void
|
|
void
|
|
void
|
Sets the repeater empty renderer class.
|
void
|
|
void
|
Sets the repeater footer renderer class.
|
void
|
|
void
|
Sets the repeater header renderer class.
|
void
|
|
void
|
Sets the item renderer class.
|
void
|
|
void
|
Sets the repeater item separator renderer class.
|
void
|
|
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::setAllowCustomPaging(), TDataBoundControl::setAllowPaging(), TDataBoundControl::setCurrentPageIndex(), TDataBoundControl::setDataMember(), TDataBoundControl::setDataSource(), TDataBoundControl::setDataSourceID(), TDataBoundControl::setInitialized(), TDataBoundControl::setIsDataBound(), TDataBoundControl::setPageSize(), TDataBoundControl::setRequiresDataBinding(), TDataBoundControl::setVirtualItemCount(), TDataBoundControl::validateDataSource()
|
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()
|
Methods Inherited From TControl |
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()
|
Methods 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()
|
Method Details |
bubbleEvent
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.
Input |
TControl | $sender | the sender of the event |
TEventParameter | $param | event parameter |
Output |
boolean
| whether the event bubbling should stop here. |
Exception |
|
createEmptyContent
protected void createEmptyContent |
() |
Creates empty repeater content.
|
createItem
Creates a repeater item instance based on the item type and index.
Input |
integer | $itemIndex | zero-based item index |
TListItemType | $itemType | item type |
Output |
TControl
| created repeater item |
Exception |
|
getAlternatingItemRenderer
public string getAlternatingItemRenderer |
() |
Output |
string
| the class name for alternative repeater items. Defaults to empty, meaning not set. |
Exception |
|
getAlternatingItemTemplate
public ITemplate getAlternatingItemTemplate |
() |
Output |
ITemplate
| the alternative template string for the item |
Exception |
|
getDataFieldValue
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.
Input |
mixed | $data | data item |
mixed | $field | field name |
Output |
mixed
| data value at the specified field |
Exception |
throws | TInvalidDataValueException if the data is invalid |
|
getDataKeyField
public string getDataKeyField |
() |
Output |
string
| the field of the data source that provides the keys of the list items. |
Exception |
|
getDataKeys
public TList getDataKeys |
() |
Output |
TList
| the keys used in the data listing control. |
Exception |
|
getEmptyRenderer
public string getEmptyRenderer |
() |
Output |
string
| the class name for empty repeater item. Defaults to empty, meaning not set. |
Exception |
|
getEmptyTemplate
Output |
ITemplate
| the template applied when no data is bound to the repeater |
Exception |
|
getFooter
Output |
TControl
| the footer item |
Exception |
|
getFooterRenderer
public string getFooterRenderer |
() |
Output |
string
| the class name for repeater footer item. Defaults to empty, meaning not set. |
Exception |
|
getFooterTemplate
Output |
ITemplate
| the footer template |
Exception |
|
getHeader
Output |
TControl
| the header item |
Exception |
|
getHeaderRenderer
public string getHeaderRenderer |
() |
Output |
string
| the class name for repeater header item. Defaults to empty, meaning not set. |
Exception |
|
getHeaderTemplate
Output |
ITemplate
| the header template |
Exception |
|
getItemRenderer
public string getItemRenderer |
() |
Output |
string
| the class name for repeater items. Defaults to empty, meaning not set. |
Exception |
|
getItems
|
getItemTemplate
Output |
ITemplate
| the template for repeater items |
Exception |
|
getSeparatorRenderer
public string getSeparatorRenderer |
() |
Output |
string
| the class name for repeater item separators. Defaults to empty, meaning not set. |
Exception |
|
getSeparatorTemplate
Output |
ITemplate
| the separator template |
Exception |
|
loadState
Loads item count information from viewstate.
This method is invoked right after control state is loaded.
|
onItemCommand
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.
|
onItemCreated
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.
|
onItemDataBound
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.
|
performDataBinding
protected void 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.
Input |
Traversable | $data | the data |
Output |
Exception |
|
render
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.
|
reset
Clears up all items in the repeater.
|
restoreItemsFromViewState
protected void restoreItemsFromViewState |
() |
Creates repeater items based on viewstate information.
|
saveState
Saves item count in viewstate.
This method is invoked right before control state is to be saved.
|
setAlternatingItemRenderer
public void setAlternatingItemRenderer |
(string $value ) |
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.
Input |
string | $value | the renderer class name in namespace format. |
Output |
Exception |
|
setAlternatingItemTemplate
public void setAlternatingItemTemplate |
(ITemplate $value ) |
Input |
ITemplate | $value | the alternative item template |
Output |
Exception |
throws | TInvalidDataTypeException if the input is not an ITemplate or not null. |
|
setDataKeyField
public void setDataKeyField |
(string $value ) |
Input |
string | $value | the field of the data source that provides the keys of the list items. |
Output |
Exception |
|
setEmptyRenderer
public void setEmptyRenderer |
(string $value ) |
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.
Input |
string | $value | the renderer class name in namespace format. |
Output |
Exception |
|
setEmptyTemplate
public void setEmptyTemplate |
(ITemplate $value ) |
Input |
ITemplate | $value | the template applied when no data is bound to the repeater |
Output |
Exception |
throws | TInvalidDataTypeException if the input is not an ITemplate or not null. |
|
setFooterRenderer
public void setFooterRenderer |
(string $value ) |
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.
Input |
string | $value | the renderer class name in namespace format. |
Output |
Exception |
|
setFooterTemplate
public void setFooterTemplate |
(ITemplate $value ) |
Input |
ITemplate | $value | the footer template |
Output |
Exception |
throws | TInvalidDataTypeException if the input is not an ITemplate or not null. |
|
setHeaderRenderer
public void setHeaderRenderer |
(string $value ) |
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.
Input |
string | $value | the renderer class name in namespace format. |
Output |
Exception |
|
setHeaderTemplate
public void setHeaderTemplate |
(ITemplate $value ) |
Input |
ITemplate | $value | the header template |
Output |
Exception |
throws | TInvalidDataTypeException if the input is not an ITemplate or not null. |
|
setItemRenderer
public void setItemRenderer |
(string $value ) |
Sets the item renderer class.
If not empty, the class will be used to instantiate as repeater items. This property takes precedence over ItemTemplate.
Input |
string | $value | the renderer class name in namespace format. |
Output |
Exception |
|
setItemTemplate
public void setItemTemplate |
(ITemplate $value ) |
Input |
ITemplate | $value | the template for repeater items |
Output |
Exception |
throws | TInvalidDataTypeException if the input is not an ITemplate or not null. |
|
setSeparatorRenderer
public void setSeparatorRenderer |
(string $value ) |
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.
Input |
string | $value | the renderer class name in namespace format. |
Output |
Exception |
|
setSeparatorTemplate
public void setSeparatorTemplate |
(ITemplate $value ) |
Input |
ITemplate | $value | the separator template |
Output |
Exception |
throws | TInvalidDataTypeException if the input is not an ITemplate or not null. |
|
Constant Details |
IT_ALTERNATINGITEM
Type:
string
Value:
'AlternatingItem'
|
IT_FOOTER
Type:
string
Value:
'Footer'
|
IT_HEADER
Repeater item types
Type:
string
Value:
'Header'
Deprecated:
deprecated since version 3.0.4. Use TListItemType constants instead.
|
IT_ITEM
Type:
string
Value:
'Item'
|
IT_SEPARATOR
Type:
string
Value:
'Separator'
|
|