3 * TDropDownListColumn class file
5 * @author Qiang Xue <qiang.xue@gmail.com>
6 * @link https://github.com/pradosoft/prado
7 * @copyright Copyright © 2005-2016 The PRADO Group
8 * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT
9 * @package System.Web.UI.WebControls
12 Prado::using('System.Web.UI.WebControls.TDataGridColumn');
13 Prado::using('System.Web.UI.WebControls.TDropDownList');
16 * TDropDownListColumn class
18 * TDropDownListColumn represents a column that is bound to a field in a data source.
19 * The cells in the column will be displayed using the data indexed by
20 * {@link setDataTextField DataTextField}. You can customize the display by
21 * setting {@link setDataTextFormatString DataTextFormatString}.
23 * If {@link setReadOnly ReadOnly} is false, TDropDownListColumn will display cells in edit mode
24 * with dropdown lists. Otherwise, a static text is displayed.
25 * The currently selected dropndown list item is specified by the data indexed with
26 * {@link setDataValueField DataValueField}.
28 * There are two approaches to specify the list items available for selection.
29 * The first approach uses template syntax as follows,
31 * <com:TDropDownListColumn ....>
32 * <com:TListItem Value="1" Text="first item" />
33 * <com:TListItem Value="2" Text="second item" />
34 * <com:TListItem Value="3" Text="third item" />
35 * </com:TDropDownListColumn>
37 * The second approach specifies a data source to be bound to the dropdown lists
38 * by setting {@link setListDataSource ListDataSource}. Like generic list controls,
39 * you may also want to specify which data fields are used for item values and texts
40 * by setting {@link setListValueField ListValueField} and
41 * {@link setListTextField ListTextField}, respectively.
42 * Furthermore, the item texts may be formatted by using {@link setListTextFormatString ListTextFormatString}.
43 * Note, if you specify {@link setListDataSource ListDataSource}, do it before
44 * calling the datagrid's dataBind().
46 * The dropdown list control in the TDropDownListColumn can be accessed by one of
47 * the following two methods:
49 * $datagridItem->DropDownListColumnID->DropDownList
50 * $datagridItem->DropDownListColumnID->Controls[0]
52 * The second method is possible because the dropdown list control created within the
53 * datagrid cell is the first child.
55 * @author Qiang Xue <qiang.xue@gmail.com>
56 * @package System.Web.UI.WebControls
59 class TDropDownListColumn extends TDataGridColumn
61 private $_stateLoaded=false;
62 private $_dataBound=false;
63 private $_listControl=null;
65 public function __construct()
67 $this->_listControl=new TDropDownList;
71 * Loads items from viewstate.
72 * This method overrides the parent implementation by loading list items
73 * @param mixed state values
75 public function loadState($state)
77 parent::loadState($state);
78 $this->_stateLoaded=true;
79 if(!$this->_dataBound)
80 $this->_listControl->getItems()->loadState($this->getViewState('Items',null));
84 * Saves items into viewstate.
85 * This method overrides the parent implementation by saving list items
87 public function saveState()
89 $this->setViewState('Items',$this->_listControl->getItems()->saveState(),null);
90 return parent::saveState();
94 * Adds object parsed from template to the control.
95 * This method adds only {@link TListItem} objects into the {@link getItems Items} collection.
96 * All other objects are ignored.
97 * @param mixed object parsed from template
99 public function addParsedObject($object)
101 // Do not add items from template if items are loaded from viewstate
102 if(!$this->_stateLoaded && ($object instanceof TListItem))
104 $object->setSelected(false);
105 $index=$this->_listControl->getItems()->add($object);
110 * @return string the field of the data source that provides the text content of the column.
112 public function getDataTextField()
114 return $this->getViewState('DataTextField','');
118 * Sets the field of the data source that provides the text content of the column.
119 * If this is not set, the data specified via {@link getDataValueField DataValueField}
120 * will be displayed in the column.
121 * @param string the field of the data source that provides the text content of the column.
123 public function setDataTextField($value)
125 $this->setViewState('DataTextField',$value,'');
129 * @return string the formatting string used to control how the bound data will be displayed.
131 public function getDataTextFormatString()
133 return $this->getViewState('DataTextFormatString','');
137 * @param string the formatting string used to control how the bound data will be displayed.
139 public function setDataTextFormatString($value)
141 $this->setViewState('DataTextFormatString',$value,'');
145 * @return string the field of the data source that provides the key selecting an item in dropdown list.
147 public function getDataValueField()
149 return $this->getViewState('DataValueField','');
153 * Sets the field of the data source that provides the key selecting an item in dropdown list.
154 * If this is not present, the data specified via {@link getDataTextField DataTextField} (without
155 * applying the formatting string) will be used for selection, instead.
156 * @param string the field of the data source that provides the key selecting an item in dropdown list.
158 public function setDataValueField($value)
160 $this->setViewState('DataValueField',$value,'');
164 * @return boolean whether the items in the column can be edited. Defaults to false.
166 public function getReadOnly()
168 return $this->getViewState('ReadOnly',false);
172 * @param boolean whether the items in the column can be edited
174 public function setReadOnly($value)
176 $this->setViewState('ReadOnly',TPropertyValue::ensureBoolean($value),false);
180 * @return Traversable data source to be bound to the dropdown list boxes.
182 public function getListDataSource()
184 return $this->_listControl->getDataSource();
188 * @param Traversable|array|string data source to be bound to the dropdown list boxes.
190 public function setListDataSource($value)
192 $this->_listControl->setDataSource($value);
196 * @return string the data field used to populate the values of the dropdown list items. Defaults to empty.
198 public function getListValueField()
200 return $this->getViewState('ListValueField','');
204 * @param string the data field used to populate the values of the dropdown list items
206 public function setListValueField($value)
208 $this->setViewState('ListValueField',$value,'');
212 * @return string the data field used to populate the texts of the dropdown list items. Defaults to empty.
214 public function getListTextField()
216 return $this->getViewState('ListTextField','');
220 * @param string the data field used to populate the texts of the dropdown list items
222 public function setListTextField($value)
224 $this->setViewState('ListTextField',$value,'');
228 * @return string the formatting string used to control how the list item texts will be displayed.
230 public function getListTextFormatString()
232 return $this->getViewState('ListTextFormatString','');
236 * @param string the formatting string used to control how the list item texts will be displayed.
238 public function setListTextFormatString($value)
240 $this->setViewState('ListTextFormatString',$value,'');
244 * Initializes the specified cell to its initial values.
245 * This method overrides the parent implementation.
246 * It creates a textbox for item in edit mode and the column is not read-only.
247 * Otherwise it displays a static text.
248 * The caption of the button and the static text are retrieved
249 * from the datasource.
250 * @param TTableCell the cell to be initialized.
251 * @param integer the index to the Columns property that the cell resides in.
252 * @param string the type of cell (Header,Footer,Item,AlternatingItem,EditItem,SelectedItem)
254 public function initializeCell($cell,$columnIndex,$itemType)
256 if(!$this->_dataBound && $this->_listControl->getDataSource()!==null)
258 $this->_listControl->setDataTextField($this->getListTextField());
259 $this->_listControl->setDataValueField($this->getListValueField());
260 $this->_listControl->setDataTextFormatString($this->getListTextFormatString());
261 $this->_listControl->dataBind();
262 $this->_dataBound=true;
266 case TListItemType::EditItem:
267 if(!$this->getReadOnly())
269 $listControl=clone $this->_listControl;
270 $cell->getControls()->add($listControl);
271 $cell->registerObject('DropDownList',$listControl);
272 $control=$listControl;
276 $control->attachEventHandler('OnDataBinding',array($this,'dataBindColumn'));
278 case TListItemType::Item:
279 case TListItemType::AlternatingItem:
280 case TListItemType::SelectedItem:
281 if($this->getDataTextField()!=='' || $this->getDataValueField()!=='')
282 $cell->attachEventHandler('OnDataBinding',array($this,'dataBindColumn'));
285 parent::initializeCell($cell,$columnIndex,$itemType);
291 * Databinds a cell in the column.
292 * This method is invoked when datagrid performs databinding.
293 * It populates the content of the cell with the relevant data from data source.
295 public function dataBindColumn($sender,$param)
297 $item=$sender->getNamingContainer();
298 $data=$item->getData();
299 if(($valueField=$this->getDataValueField())!=='')
300 $value=$this->getDataFieldValue($data,$valueField);
303 if(($textField=$this->getDataTextField())!=='')
305 $text=$this->getDataFieldValue($data,$textField);
308 $formatString=$this->getDataTextFormatString();
309 $text=$this->formatDataValue($formatString,$text);
313 if($sender instanceof TTableCell)
314 $sender->setText($text);
315 else if($sender instanceof TDropDownList)
316 $sender->setSelectedValue($value);