1: <?php
  2:     /**
  3:      * contains QListBoxBase class
  4:      * @package Controls
  5:      */
  6: 
  7:     /**
  8:      * QListBoxBase will render an HTML DropDown or MultiSelect box [SELECT] element.
  9:      * It extends {@link QListControl}.  By default, the number of visible rows is set to 1 and
 10:      * the selection mode is set to single, creating a dropdown select box.
 11:      *
 12:      * @property integer $Rows          specifies how many rows you want to have shown.
 13:      * @property string  $LabelForRequired
 14:      * @property string  $LabelForRequiredUnnamed
 15:      * @property string  $SelectionMode {@link QSelectionMode} specifies if this is a "Single" or "Multiple" select control.
 16:      * @see     QSelectionMode
 17:      * @package Controls
 18:      */
 19:     abstract class QListBoxBase extends QListControl {
 20:         ///////////////////////////
 21:         // Private Member Variables
 22:         ///////////////////////////
 23: 
 24:         // APPEARANCE
 25:         /** @var string Error to be shown if the box is empty, has a name and is marked as required */
 26:         protected $strLabelForRequired;
 27:         /** @var string Error to be shown If the box is empty, doesn't have a name and is marked as required */
 28:         protected $strLabelForRequiredUnnamed;
 29: 
 30:         //////////
 31:         // Methods
 32:         //////////
 33:         /**
 34:          * QControl-Constructor
 35:          * 
 36:          * @param QControl|QForm $objParentObject
 37:          * @param string $strControlId
 38:          */
 39:         public function __construct($objParentObject, $strControlId = null) {
 40:             parent::__construct($objParentObject, $strControlId);
 41: 
 42:             $this->strLabelForRequired = QApplication::Translate('%s is required');
 43:             $this->strLabelForRequiredUnnamed = QApplication::Translate('Required');
 44:             $this->objItemStyle = new QListItemStyle();
 45:         }
 46: 
 47:         /**
 48:          * Parses the data received back from the client/browser
 49:          */
 50:         public function ParsePostData() {
 51:             if (array_key_exists($this->strControlId, $_POST)) {
 52:                 if (is_array($_POST[$this->strControlId])) {
 53:                     // Multi-Select, so find them all.
 54:                     $this->SetSelectedItemsById($_POST[$this->strControlId], false);
 55:                 } elseif ($_POST[$this->strControlId] === '') {
 56:                     $this->UnselectAllItems(false);
 57:                 }
 58:                 else {
 59:                     // Single-select
 60:                     $this->SetSelectedItemsById(array($_POST[$this->strControlId]), false);
 61:                 }
 62:             } else {
 63:                 // Multiselect forms with nothing passed via $_POST means that everything was DE selected
 64:                 if ($this->SelectionMode == QSelectionMode::Multiple) {
 65:                     $this->UnselectAllItems(false);
 66:                 }
 67:             }
 68:         }
 69: 
 70:         /**
 71:          * Returns the HTML-Code for a single Item
 72:          * 
 73:          * @param QListItem $objItem
 74:          * @return string resulting HTML
 75:          */
 76:         protected function GetItemHtml(QListItem $objItem) {
 77:             // The Default Item Style
 78:             if ($this->objItemStyle) {
 79:                 $objStyler = clone ($this->objItemStyle);
 80:             } else {
 81:                 $objStyler = new QListItemStyle();
 82:             }
 83: 
 84:             // Apply any Style Override (if applicable)
 85:             if ($objStyle = $objItem->ItemStyle) {
 86:                 $objStyler->Override($objStyle);
 87:             }
 88: 
 89:             $objStyler->SetHtmlAttribute('value', ($objItem->Empty) ? '' : $objItem->Id);
 90:             if ($objItem->Selected) {
 91:                 $objStyler->SetHtmlAttribute('selected', 'selected');
 92:             }
 93: 
 94:             $strHtml = QHtml::RenderTag('option', $objStyler->RenderHtmlAttributes(), QApplication::HtmlEntities($objItem->Name), false, true) . _nl();
 95: 
 96:             return $strHtml;
 97:         }
 98: 
 99:         /**
100:          * Returns the html for the entire control.
101:          * @return string
102:          */
103:         protected function GetControlHtml() {
104:             // If no selection is specified, we select the first item, because once we draw this, that is what the browser
105:             // will consider selected on the screen.
106:             // We need to make sure that what we draw is mirrored in our current state
107:             if ($this->SelectionMode == QSelectionMode::Single &&
108:                     $this->SelectedIndex == -1 &&
109:                     $this->ItemCount > 0) {
110:                 $this->SelectedIndex = 0;
111:             }
112: 
113:             if ($this->SelectionMode == QSelectionMode::Multiple) {
114:                 $attrOverride['name'] = $this->strControlId . "[]";
115:             } else {
116:                 $attrOverride['name'] = $this->strControlId;
117:             }
118: 
119:             $strToReturn = $this->RenderTag('select', $attrOverride, null, $this->RenderInnerHtml());
120: 
121:             // If MultiSelect and if NOT required, add a "Reset" button to deselect everything
122:             if (($this->SelectionMode == QSelectionMode::Multiple) && (!$this->blnRequired) && ($this->Enabled) && ($this->blnVisible)) {
123:                 $strToReturn .= $this->GetResetButtonHtml();
124:             }
125:             return $strToReturn;
126:         }
127: 
128:         /**
129:          * Return the inner html for the select box.
130:          * @return string
131:          */
132:         protected function RenderInnerHtml() {
133:             $strHtml = '';
134:             $intItemCount = $this->GetItemCount();
135:             if (!$intItemCount) return '';
136:             $groups = array();
137: 
138:             for ($intIndex = 0; $intIndex < $intItemCount; $intIndex++) {
139:                 $objItem = $this->GetItem ($intIndex);
140:                 // Figure Out Groups (if applicable)
141:                 if ($strGroup = $objItem->ItemGroup) {
142:                     $groups[$strGroup][] = $objItem;
143:                 } else {
144:                     $groups[''][] = $objItem;
145:                 }
146:             }
147: 
148:             foreach ($groups as $strGroup=>$items) {
149:                 if (!$strGroup) {
150:                     foreach ($items as $objItem) {
151:                         $strHtml .= $this->GetItemHtml($objItem);
152:                     }
153:                 }
154:                 else {
155:                     $strGroupHtml = '';
156:                     foreach ($items as $objItem) {
157:                         $strGroupHtml .= $this->GetItemHtml($objItem);
158:                     }
159:                     $strHtml .= QHtml::RenderTag('optgroup', ['label' => QApplication::HtmlEntities($strGroup)], $strGroupHtml);
160:                 }
161:             }
162:             return $strHtml;
163:         }
164: 
165:         // For multiple-select based listboxes, you must define the way a "Reset" button should look
166:         abstract protected function GetResetButtonHtml();
167: 
168:         /**
169:          * Determines whether the supplied input data is valid or not.
170:          * @return bool
171:          */
172:         public function Validate() {
173:             if ($this->blnRequired) {
174:                 if ($this->SelectedIndex == -1) {
175:                     if ($this->strName)
176:                         $this->ValidationError = sprintf($this->strLabelForRequired, $this->strName);
177:                     else
178:                         $this->ValidationError = $this->strLabelForRequiredUnnamed;
179:                     return false;
180:                 }
181: 
182:                 if (($this->SelectedIndex == 0) && (strlen($this->SelectedValue) == 0)) {
183:                     if ($this->strName)
184:                         $this->ValidationError = sprintf($this->strLabelForRequired, $this->strName);
185:                     else
186:                         $this->ValidationError = $this->strLabelForRequiredUnnamed;
187:                     return false;
188:                 }
189:             }
190: 
191:             $this->ValidationError = null;
192:             return true;
193:         }
194: 
195:         /**
196:          * Override of superclass that will update the selection using javascript so that the whole control does
197:          * not need to be redrawn.
198:          */
199:         protected function RefreshSelection() {
200:             $items = $this->SelectedItems;
201:             $values = [];
202:             foreach ($items as $objItem) {
203:                 $values[] = $objItem->Id;
204:             }
205:             QApplication::ExecuteControlCommand($this->ControlId, 'val', $values);
206:         }
207: 
208:         /**
209:          * Restore the  state of the control. This override makes sure the item exists before putting it. Otherwise,
210:          * if the item did not exist, the default selection would be removed and nothing would be selected.
211:          * @param mixed $state
212:          */
213:         public function PutState($state) {
214:             if (!empty($state['SelectedValues'])) {
215:                 // assume only one selection in list
216:                 $strValue = reset($state['SelectedValues']);
217:                 if ($this->FindItemByValue($strValue)) {
218:                     $this->SelectedValues = [$strValue];
219:                 }
220:             }
221:         }
222: 
223: 
224:         /////////////////////////
225:         // Public Properties: GET
226:         /////////////////////////
227:         /**
228:          * PHP magic function
229:          * @param string $strName
230:          *
231:          * @return mixed
232:          * @throws Exception|QCallerException
233:          */
234:         public function __get($strName) {
235:             switch ($strName) {
236:                 // APPEARANCE
237:                 case "Rows": return $this->GetHtmlAttribute('size');
238:                 case "LabelForRequired": return $this->strLabelForRequired;
239:                 case "LabelForRequiredUnnamed": return $this->strLabelForRequiredUnnamed;
240: 
241:                 // BEHAVIOR
242:                 case "SelectionMode": return $this->HasHtmlAttribute('multiple') ? QSelectionMode::Multiple : QSelectionMode::Single;
243: 
244:                 default:
245:                     try {
246:                         return parent::__get($strName);
247:                     } catch (QCallerException $objExc) {
248:                         $objExc->IncrementOffset();
249:                         throw $objExc;
250:                     }
251:             }
252:         }
253: 
254:         /////////////////////////
255:         // Public Properties: SET
256:         /////////////////////////
257:         /**
258:          * PHP magic method
259:          * @param string $strName
260:          * @param string $mixValue
261:          *
262:          * @return mixed
263:          * @throws Exception|QCallerException|QInvalidCastException
264:          */
265:         public function __set($strName, $mixValue) {
266:             switch ($strName) {
267:                 // APPEARANCE
268:                 case "Rows":
269:                     try {
270:                         $this->SetHtmlAttribute('size', QType::Cast($mixValue, QType::Integer));
271:                         break;
272:                     } catch (QInvalidCastException $objExc) {
273:                         $objExc->IncrementOffset();
274:                         throw $objExc;
275:                     }
276:                 case "LabelForRequired":
277:                     try {
278:                         $this->strLabelForRequired = QType::Cast($mixValue, QType::String);
279:                         break;
280:                     } catch (QInvalidCastException $objExc) {
281:                         $objExc->IncrementOffset();
282:                         throw $objExc;
283:                     }
284:                 case "LabelForRequiredUnnamed":
285:                     try {
286:                         $this->strLabelForRequiredUnnamed = QType::Cast($mixValue, QType::String);
287:                         break;
288:                     } catch (QInvalidCastException $objExc) {
289:                         $objExc->IncrementOffset();
290:                         throw $objExc;
291:                     }
292: 
293:                 // BEHAVIOR
294:                 case "SelectionMode":
295:                     try {
296:                         if (QType::Cast($mixValue, QType::String) == QSelectionMode::Multiple) {
297:                             $this->SetHtmlAttribute('multiple', 'multiple');
298:                         } else {
299:                             $this->RemoveHtmlAttribute('multiple');
300:                         }
301:                         break;
302:                     } catch (QInvalidCastException $objExc) {
303:                         $objExc->IncrementOffset();
304:                         throw $objExc;
305:                     }
306:                 
307:                 default:
308:                     try {
309:                         parent::__set($strName, $mixValue);
310:                     } catch (QCallerException $objExc) {
311:                         $objExc->IncrementOffset();
312:                         throw $objExc;
313:                     }
314:                     break;
315:             }
316:         }
317: 
318:         /**
319:          * Returns an description of the options available to modify by the designer for the code generator.
320:          *
321:          * @return QModelConnectorParam[]
322:          */
323:         public static function GetModelConnectorParams() {
324:             return array_merge(parent::GetModelConnectorParams(), array(
325:                 new QModelConnectorParam (get_called_class(), 'Rows', 'Height of field for multirow field', QType::Integer),
326:                 new QModelConnectorParam (get_called_class(), 'SelectionMode', 'Single or multiple selections', QModelConnectorParam::SelectionList,
327:                     array (null=>'Default',
328:                         'QSelectionMode::Single'=>'Single',
329:                         'QSelectionMode::Multiple'=>'Multiple'
330:                     ))
331:             ));
332:         }
333: 
334:     }
335: