When {@link setDataSource DataSource} or {@link setDataSourceID DataSourceID}
is used to populate list items, the {@link setDataTextField DataTextField} and
{@link setDataValueField DataValueField} 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 {@link setDataTextField DataTextField} and {@link setDataValueField DataValueField}
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 {@link setDataTextFormatString DataTextFormatString} property may be further
used to format how the item should be displayed. See {@link formatDataValue()}
for an explanation of the format string.
The {@link setPromptText PromptText} and {@link setPromptValue PromptValue} properties can
be used to add a dummy list item that will be rendered first.
Show file
Open project: pradosoft/prado
Class Usage Examples
| Method | Description | |
|---|---|---|
| addParsedObject ( $object ) | Adds object parsed from template to the control. | |
| clearSelection ( ) | Clears all existing selections. | |
| getAppendDataBoundItems ( ) : boolean | ||
| getAutoPostBack ( ) : boolean | ||
| getCausesValidation ( ) : boolean | ||
| getData ( ) : string | Returns the value of the selected item with the lowest cardinal index. | |
| getDataGroupField ( ) : string | ||
| getDataTextField ( ) : string | ||
| getDataTextFormatString ( ) : string | ||
| getDataValueField ( ) : string | ||
| getEnableClientScript ( ) : boolean | ||
| getHasItems ( ) : boolean | ||
| getItemCount ( ) : integer | ||
| getItems ( ) : TListItemCollection | ||
| getPromptText ( ) : string | ||
| getPromptValue ( ) : string | ||
| getSelectedIndex ( ) : integer | ||
| getSelectedIndices ( ) : array | ||
|
getSelectedItem ( ) : |
||
| getSelectedValue ( ) : string | ||
| getSelectedValues ( ) : array | ||
| getText ( ) : string | ||
| getValidationGroup ( ) : string | ||
| loadState ( ) | Loads items from viewstate. | |
| onSelectedIndexChanged ( $param ) | Raises OnSelectedIndexChanged event when selection is changed. | |
| onTextChanged ( $param ) | Raises OnTextChanged event when selection is changed. | |
| renderContents ( $writer ) | Renders body content of the list control. | |
| saveState ( ) | Saves items into viewstate. | |
| setAppendDataBoundItems ( $value ) | ||
| setAutoPostBack ( $value ) | Sets the value indicating if postback automatically. | |
| setCausesValidation ( $value ) | ||
| setData ( $value ) | Selects an item by the specified value. | |
| setDataGroupField ( $value ) | ||
| setDataTextField ( $value ) | ||
| setDataTextFormatString ( $value ) | Sets data text format string. | |
| setDataValueField ( $value ) | ||
| setEnableClientScript ( $value ) | ||
| setPromptText ( $value ) | ||
| setPromptValue ( $value ) | ||
| setSelectedIndex ( $index ) | ||
| setSelectedIndices ( $indices ) | ||
| setSelectedValue ( $value ) | Sets selection by item value. | |
| setSelectedValues ( $values ) | ||
| setText ( $value ) | ||
| setValidationGroup ( $value ) |
| Method | Description | |
|---|---|---|
| addAttributesToRender ( $writer ) | Adds attributes to renderer. | |
| createListItemCollection ( ) : TListItemCollection | Creates a collection object to hold list items. | |
| formatDataValue ( $formatString, $value ) : string | Formats the text value according to a format string. | |
| getClientClassName ( ) : string | Gets the name of the javascript class responsible for performing postback for this control. | |
| getIsMultiSelect ( ) : boolean | ||
| getPostBackOptions ( ) : array | ||
| getTagName ( ) : string | ||
| performDataBinding ( $data ) | Performs databinding to populate list items from data source. | |
| renderClientControlScript ( $writer ) | Renders the javascript for list control. | |
| renderPrompt ( $writer ) | Renders the prompt text, if any. |
| Method | Description | |
|---|---|---|
| resetCachedSelections ( ) |
| protected addAttributesToRender ( $writer ) |
| public addParsedObject ( $object ) |
| protected createListItemCollection ( ) : TListItemCollection | ||
| return | TListItemCollection | the collection object |
| protected formatDataValue ( $formatString, $value ) : string | ||
| return | string | the formatted result |
| public getAppendDataBoundItems ( ) : boolean | ||
| return | boolean | whether performing databind should append items or clear the existing ones. Defaults to false. |
| public getAutoPostBack ( ) : boolean | ||
| return | boolean | a value indicating whether an automatic postback to the server will occur whenever the user makes change to the list control and then tabs out of it. Defaults to false. |
| public getCausesValidation ( ) : boolean | ||
| return | boolean | whether postback event trigger by this list control will cause input validation, default is true. |
| protected getClientClassName ( ) : string | ||
| return | string | the javascript class name |
| public getDataGroupField ( ) : string | ||
| return | string | the field of the data source that provides the label of the list item groups |
| public getDataTextField ( ) : string | ||
| return | string | the field of the data source that provides the text content of the list items. |
| public getDataTextFormatString ( ) : string | ||
| return | string | the formatting string used to control how data bound to the list control is displayed. |
| public getDataValueField ( ) : string | ||
| return | string | the field of the data source that provides the value of each list item. |
| public getEnableClientScript ( ) : boolean | ||
| return | boolean | whether to render javascript. |
| public getHasItems ( ) : boolean | ||
| return | boolean | whether the list control contains any items. |
| protected getIsMultiSelect ( ) : boolean | ||
| return | boolean | whether this is a multiselect control. Defaults to false. |
| public getItemCount ( ) : integer | ||
| return | integer | the number of items in the list control |
| public getItems ( ) : TListItemCollection | ||
| return | TListItemCollection | the item collection |
| protected getPostBackOptions ( ) : array | ||
| return | array | postback options for JS postback code |
| public getPromptText ( ) : string | ||
| return | string | the prompt text which is to be displayed as the first list item. |
| public getPromptValue ( ) : string | ||
| return | string | the prompt selection value. |
| public getSelectedIndex ( ) : integer | ||
| return | integer | the index (zero-based) of the item being selected, -1 if no item is selected. |
| public getSelectedIndices ( ) : array | ||
| return | array | list of index of items that are selected |
|
public getSelectedItem ( ) : |
||
| return | the selected item with the lowest cardinal index, null if no item is selected. | |
| public getSelectedValue ( ) : string | ||
| return | string | the value of the selected item with the lowest cardinal index, empty if no selection |
| public getSelectedValues ( ) : array | ||
| return | array | list of the selected item values (strings) |
| protected getTagName ( ) : string | ||
| return | string | tag name of the list control |
| public getValidationGroup ( ) : string | ||
| return | string | the group of validators which the list control causes validation upon postback |
| public loadState ( ) |
| public onSelectedIndexChanged ( $param ) |
| public onTextChanged ( $param ) |
| protected performDataBinding ( $data ) |
| protected renderClientControlScript ( $writer ) |
| public renderContents ( $writer ) |
| public saveState ( ) |
| public setAutoPostBack ( $value ) |
| public setData ( $value ) |
| public setDataTextFormatString ( $value ) |
| public setSelectedValue ( $value ) |