Class \Prado\Web\UI\WebControls\TListControl

TListControl class

TListControl is a base class for list controls, such as TListBox, TDropDownList, TCheckBoxList, etc. It manages the items and their status in a list control. It also implements how the items can be populated from template and data source.

The property getItems returns a list of the items in the control. To specify or determine which item is selected, use the \Prado\Web\UI\WebControls\getSelectedIndex property that indicates the zero-based index of the selected item in the item list. You may also use \Prado\Web\UI\WebControls\getSelectedItem and \Prado\Web\UI\WebControls\getSelectedValue to get the selected item and its value. For multiple selection lists (such as TCheckBoxList and TListBox), property \Prado\Web\UI\WebControls\getSelectedIndices is useful.

TListControl implements \Prado\Web\UI\WebControls\setAutoPostBack which allows a list control to postback the page if the selections of the list items are changed. The \Prado\Web\UI\WebControls\setCausesValidation and \Prado\Web\UI\WebControls\setValidationGroup properties may be used to specify that validation be performed when auto postback occurs.

There are three ways to populate the items in a list control: from template, using \Prado\Web\UI\WebControls\setDataSource and using \Prado\Web\UI\WebControls\setDataSourceID. The latter two are covered in TDataBoundControl. To specify items via template, using the following template syntax:

<com:TListControl>
  <com:TListItem Value="xxx" Text="yyy" >
  <com:TListItem Value="xxx" Text="yyy" Selected="true" >
  <com:TListItem Value="xxx" Text="yyy" >
</com:TListControl>

When \Prado\Web\UI\WebControls\setDataSource or \Prado\Web\UI\WebControls\setDataSourceID is used to populate list items, the \Prado\Web\UI\WebControls\setDataTextField and \Prado\Web\UI\WebControls\setDataValueField properties are used to specify which columns of the data will be used to populate the text and value of the items. For example, if a data source is as follows,

$dataSource=array(
   array('name'=>'John', 'age'=>31),
   array('name'=>'Cary', 'age'=>28),
   array('name'=>'Rose', 'age'=>35),
);

setting \Prado\Web\UI\WebControls\setDataTextField and \Prado\Web\UI\WebControls\setDataValueField to 'name' and 'age' will make the first item's text be 'John', value be 31, the second item's text be 'Cary', value be 28, and so on. The \Prado\Web\UI\WebControls\setDataTextFormatString property may be further used to format how the item should be displayed. See formatDataValue() for an explanation of the format string.

The \Prado\Web\UI\WebControls\setPromptText and \Prado\Web\UI\WebControls\setPromptValue properties can be used to add a dummy list item that will be rendered first.

Class hierarchy

\Prado\Web\UI\WebControls\TListControl implements IDataRenderer

\Prado\Web\UI\WebControls\TDataBoundControl

\Prado\Web\UI\WebControls\TWebControl implements IStyleable

\Prado\Web\UI\TControl implements IRenderable, IBindable

\Prado\TApplicationComponent

\Prado\TComponent

Author: Qiang Xue <qiang.xue@gmail.com>
Since: 3.0

Methods summary
`public`	`addParsedObject(mixed $object) : mixed` Adds object parsed from template to the control. This method adds only TListItem objects into the \Prado\Web\UI\WebControls\getItems collection. All other objects are ignored.
`public`	`clearSelection() : mixed` Clears all existing selections.
`public`	`getAppendDataBoundItems() : bool`
`public`	`getAutoPostBack() : bool`
`public`	`getCausesValidation() : bool`
`public`	`getData() : string` Returns the value of the selected item with the lowest cardinal index. This method is required by IDataRenderer. It is the same as getSelectedValue().
`public`	`getDataGroupField() : string`
`public`	`getDataTextField() : string`
`public`	`getDataTextFormatString() : string`
`public`	`getDataValueField() : string`
`public`	`getEnableClientScript() : bool`
`public`	`getHasItems() : bool`
`public`	`getItemCount() : int`
`public`	`getItems() : TListItemCollection`
`public`	`getPromptText() : string`
`public`	`getPromptValue() : string`
`public`	`getSelectedIndex() : int`
`public`	`getSelectedIndices() : array<string\|int, mixed>`
`public`	`getSelectedItem() : null\|TListItem`
`public`	`getSelectedValue() : string`
`public`	`getSelectedValues() : array<string\|int, mixed>`
`public`	`getText() : string`
`public`	`getValidationGroup() : string`
`public`	`loadState() : mixed` Loads items from viewstate. This method is invoked right after control state is loaded.
`public`	`onSelectedIndexChanged(TEventParameter $param) : mixed` Raises OnSelectedIndexChanged event when selection is changed. This method is invoked when the list control has its selection changed by end-users.
`public`	`onTextChanged(TEventParameter $param) : mixed` Raises OnTextChanged event when selection is changed. This method is invoked when the list control has its selection changed by end-users.
`public`	`renderContents(THtmlWriter $writer) : mixed` Renders body content of the list control. This method renders items contained in the list control as the body content.
`public`	`saveState() : mixed` Saves items into viewstate. This method is invoked right before control state is to be saved.
`public`	`setAppendDataBoundItems(bool $value) : mixed`
`public`	`setAutoPostBack(bool $value) : mixed` Sets the value indicating if postback automatically. An automatic postback to the server will occur whenever the user makes change to the list control and then tabs out of it.
`public`	`setCausesValidation(bool $value) : mixed`
`public`	`setData(string $value) : mixed` Selects an item by the specified value. This method is required by IDataRenderer. It is the same as setSelectedValue().
`public`	`setDataGroupField(string $value) : mixed`
`public`	`setDataTextField(string $value) : mixed`
`public`	`setDataTextFormatString(string $value) : mixed` Sets data text format string. The format string is used in TDataValueFormatter::format() to format the Text property value of each item in the list control.
`public`	`setDataValueField(string $value) : mixed`
`public`	`setEnableClientScript(bool $value) : mixed`
`public`	`setPromptText(string $value) : mixed`
`public`	`setPromptValue(string $value) : mixed`
`public`	`setSelectedIndex(int $index) : mixed`
`public`	`setSelectedIndices(array<string\|int, mixed> $indices) : mixed`
`public`	`setSelectedValue(string $value) : mixed` Sets selection by item value. Existing selections will be cleared if the item value is found in the item collection. Note, if the value is null, existing selections will also be cleared.
`public`	`setSelectedValues(array<string\|int, mixed> $values) : mixed`
`public`	`setText(string $value) : mixed`
`public`	`setValidationGroup(string $value) : mixed`
`protected`	`addAttributesToRender(THtmlWriter $writer) : mixed` Adds attributes to renderer.
`protected`	`createListItemCollection() : TListItemCollection` Creates a collection object to hold list items. This method may be overriden to create a customized collection.
`protected`	`formatDataValue(string $formatString, mixed $value) : string` Formats the text value according to a format string. If the format string is empty, the original value is converted into a string and returned. If the format string starts with '#', the string is treated as a PHP expression within which the token '{0}' is translated with the data value to be formated. Otherwise, the format string and the data value are passed as the first and second parameters in sprintf.
`protected`	`getClientClassName() : string` Gets the name of the javascript class responsible for performing postback for this control. Derived classes may override this method and return customized js class names.
`protected`	`getIsMultiSelect() : bool`
`protected`	`getPostBackOptions() : array<string\|int, mixed>`
`protected`	`getTagName() : string`
`protected`	`performDataBinding(Traversable $data) : mixed` Performs databinding to populate list items from data source. This method is invoked by dataBind(). You may override this function to provide your own way of data population.
`protected`	`renderClientControlScript(mixed $writer) : mixed` Renders the javascript for list control.
`protected`	`renderPrompt(THtmlWriter $writer) : mixed` Renders the prompt text, if any.
`private`	`resetCachedSelections() : mixed`

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

Inherited constants
\Prado\Web\UI\TControl::AUTOMATIC_ID_PREFIX, \Prado\Web\UI\TControl::CLIENT_ID_SEPARATOR, \Prado\Web\UI\TControl::CS_CHILD_INITIALIZED, \Prado\Web\UI\TControl::CS_CONSTRUCTED, \Prado\Web\UI\TControl::CS_INITIALIZED, \Prado\Web\UI\TControl::CS_LOADED, \Prado\Web\UI\TControl::CS_PRERENDERED, \Prado\Web\UI\TControl::CS_STATE_LOADED, \Prado\TApplicationComponent::FX_CACHE_FILE, \Prado\TComponent::GLOBAL_RAISE_EVENT_LISTENER, \Prado\Web\UI\TControl::ID_FORMAT, \Prado\Web\UI\TControl::ID_SEPARATOR, \Prado\Web\UI\TControl::IS_CHILD_CREATED, \Prado\Web\UI\TControl::IS_CREATING_CHILD, \Prado\Web\UI\TControl::IS_DISABLE_THEMING, \Prado\Web\UI\TControl::IS_DISABLE_VIEWSTATE, \Prado\Web\UI\TControl::IS_ID_SET, \Prado\Web\UI\TControl::IS_SKIN_APPLIED, \Prado\Web\UI\TControl::IS_STYLESHEET_APPLIED, \Prado\Web\UI\TControl::RF_ADAPTER, \Prado\Web\UI\TControl::RF_AUTO_BINDINGS, \Prado\Web\UI\TControl::RF_CHILD_STATE, \Prado\Web\UI\TControl::RF_CONTROLS, \Prado\Web\UI\TControl::RF_CONTROLSTATE, \Prado\Web\UI\TControl::RF_DATA_BINDINGS, \Prado\Web\UI\TControl::RF_EVENTS, \Prado\Web\UI\TControl::RF_NAMED_CONTROLS, \Prado\Web\UI\TControl::RF_NAMED_CONTROLS_ID, \Prado\Web\UI\TControl::RF_NAMED_OBJECTS, \Prado\Web\UI\TControl::RF_SKIN_ID

Classes

Interfaces

Traits

Search results

Class \Prado\Web\UI\WebControls\TListControl

Class hierarchy