1: <?php
  2: 
  3: /**
  4:  * A HtmlTable that is connected to data. Detects and responds to sort clicks.
  5:  *
  6:  * Uses FontAwesome for sort indicators - a font based icon library. Using this allows the icons to be colored
  7:  * and styled, and will size along with the rest of the text.
  8:  *
  9:  * @package Controls
 10:  */
 11: 
 12: 
 13: if (!defined('__FONT_AWESOME__')) {
 14:     define('__FONT_AWESOME__', 'https://opensource.keycdn.com/fontawesome/4.6.3/font-awesome.min.css');
 15: }
 16: 
 17: class QDataGrid_SortEvent extends QEvent {
 18:     const JsReturnParam = 'ui'; // returns the col id
 19:     const EventName = 'qdg2sort';
 20: }
 21: 
 22: 
 23: /**
 24:  * Class QDataGridBase
 25:  *
 26:  * This class is designed primarily to work alongside the code generator, but it can be independent as well. It creates
 27:  * an html table that displays data from the database. The data can possibly be sorted by clicking on the header cell
 28:  * of the sort column.
 29:  *
 30:  * This grid also has close ties to the QDataGrid_CheckboxColumn to easily enable the addition of a column or columns
 31:  * of checkboxes.
 32:  *
 33:  * This class is NOT intended to support column filters, but a subclass could be created that could do so. Just don't
 34:  * do that here.
 35:  *
 36:  * @property-read  QQClause $OrderByClause The sorting clause based on the selected headers.
 37:  * @property  string    $SortColumnId The id of the currently sorted column. Does not change if columns are re-ordered.
 38:  * @property  int       $SortColumnIndex The index of the currently sorted column.
 39:  * @property  int       $SortDirection SortAscending or SortDescending.
 40:  *
 41:  */
 42: class QDataGridBase extends QHtmlTable
 43: {
 44:     /** Numbers than can be used to multiply against the results of comparison functions to reverse the order. */
 45:     const SortAscending = 1;
 46:     const SortDescending = -1;
 47: 
 48:     /** @var int Couter to generate column ids for columns that do not have them. */
 49:     protected $intLastColumnId = 0;
 50: 
 51:     /** @var  string Keeps track of current sort column. We do it by id so that the table can add/hide/show or rearrange columns and maintain the sort column. */
 52:     protected $strSortColumnId;
 53: 
 54:     /** @var int The direction of the currently sorted column.  */
 55:     protected $intSortDirection = self::SortAscending;
 56: 
 57:     /** @var string Default class */
 58:     protected $strCssClass = 'datagrid';
 59: 
 60: 
 61:     /**
 62:      * QDataGridBase constructor.
 63:      * @param QControl|QControlBase|QForm $objParentObject
 64:      * @param string|null $strControlId
 65:      */
 66:     public function __construct($objParentObject, $strControlId = null) {
 67:         try {
 68:             parent::__construct($objParentObject, $strControlId);
 69: 
 70:             $this->AddCssFile(__FONT_AWESOME__);
 71: 
 72:             $this->AddActions();
 73: 
 74:         } catch (QCallerException  $objExc) {
 75:             $objExc->IncrementOffset();
 76:             throw $objExc;
 77:         }
 78:     }
 79: 
 80:     /**
 81:      * An override to add the paginator to the caption area.
 82:      * @return string
 83:      */
 84:     protected function RenderCaption() {
 85:         return $this->RenderPaginator();
 86:     }
 87: 
 88:     /**
 89:      * Renders the given paginator in a span in the caption. If a caption already exists, it will add the caption.
 90:      * @return string
 91:      * @throws QCallerException
 92:      */
 93:     protected function RenderPaginator () {
 94:         $objPaginator = $this->objPaginator;
 95:         if (!$objPaginator) return '';
 96: 
 97:         $strHtml = $objPaginator->Render(false);
 98:         $strHtml = QHtml::RenderTag('span', ['class'=>'paginator-control'], $strHtml);
 99:         if ($this->strCaption) {
100:             $strHtml = '<span>' . QApplication::HtmlEntities($this->strCaption) . '</span>' . $strHtml;
101:         }
102: 
103:         $strHtml = QHtml::RenderTag('caption', null, $strHtml);
104: 
105:         return $strHtml;
106:     }
107: 
108:     /**
109:      * Adds the actions for the table. Override to add additional actions. If you are detecting clicks
110:      * that need to cancel the default action, put those in front of this function.
111:      */
112:     public function AddActions() {
113:         $this->AddAction(new QHtmlTableCheckBoxColumn_ClickEvent(), new QAjaxControlAction ($this, 'CheckClick'));
114:         $this->AddAction(new QHtmlTableCheckBoxColumn_ClickEvent(), new QStopPropagationAction()); // prevent check click from bubbling as a row click.
115: 
116:         $this->AddAction(new QDataGrid_SortEvent(), new QAjaxControlAction ($this, 'SortClick'));
117:     }
118: 
119:     /**
120:      * An override to create an id for every column, since the id is what we use to track sorting.
121:      *
122:      * @param int $intColumnIndex
123:      * @param QAbstractHtmlTableColumn $objColumn
124:      * @throws QInvalidCastException
125:      */
126:     public function AddColumnAt($intColumnIndex, QAbstractHtmlTableColumn $objColumn) {
127:         parent::AddColumnAt($intColumnIndex, $objColumn);
128:         // Make sure the column has an Id, since we use that to track sorting.
129:         if (!$objColumn->Id) {
130:             $objColumn->Id = $this->ControlId . '_col_' . $this->intLastColumnId++;
131:         }
132:     }
133: 
134:     /**
135:      * Transfers clicks to any checkbox columns.
136:      *
137:      * @param $strFormId
138:      * @param $strControlId
139:      * @param $strParameter
140:      */
141:     protected function CheckClick($strFormId, $strControlId, $strParameter) {
142:         $intColumnIndex = $strParameter['col'];
143:         $objColumn = $this->GetColumn ($intColumnIndex, true);
144: 
145:         if ($objColumn instanceof QDataGrid_CheckboxColumn) {
146:             $objColumn->Click($strParameter);
147:         }
148:     }
149: 
150:     /**
151:      * Clears all checkboxes in checkbox columns. If you have multiple checkbox columns, you can specify which column
152:      * to clear. Otherwise, it will clear all of them.
153:      *
154:      * @param string|null $strColId
155:      */
156:     public function ClearCheckedItems($strColId = null) {
157:         foreach ($this->objColumnArray as $objColumn) {
158:             if ($objColumn instanceof QDataGrid_CheckboxColumn) {
159:                 if (is_null($strColId) || $objColumn->Id === $strColId) {
160:                     $objColumn->ClearCheckedItems();
161:                 }
162:             }
163:         }
164:     }
165: 
166:     /**
167:      * Returns the checked item ids if the data grid has a QDataGrid_CheckboxColumn column. If there is more than
168:      * one column, you can specify which column to want to query. If no id is specified, it
169:      * will return the ids from the first column found. If no column was found, then null is returned.
170:      *
171:      * @param mixed $strColId
172:      * @return array|null
173:      */
174:     public function GetCheckedItemIds($strColId = null) {
175:         foreach ($this->objColumnArray as $objColumn) {
176:             if ($objColumn instanceof QDataGrid_CheckboxColumn) {
177:                 if (is_null($strColId) ||
178:                         $objColumn->Id === $strColId) {
179:                     return $objColumn->GetCheckedItemIds();
180:                 }
181:             }
182:         }
183:         return null; // column not found
184:     }
185: 
186:     /**
187:      * Processes clicks on a sortable column head.
188:      *
189:      * @param string $strFormId
190:      * @param string $strControlId
191:      * @param mixed $mixParameter
192:      * @throws QCallerException
193:      * @throws QInvalidCastException
194:      */
195:     protected function SortClick($strFormId, $strControlId, $mixParameter) {
196: 
197:         $intColumnIndex = QType::Cast($mixParameter, QType::Integer);
198:         $objColumn = $this->GetColumn ($intColumnIndex, true);
199: 
200:         if (!$objColumn) return;
201: 
202:         $this->blnModified = true;
203: 
204:         $strId = $objColumn->Id;
205: 
206:         if (!$objColumn) {
207:             return;
208:         }
209: 
210:         // Reset pagination (if applicable)
211:         if ($this->objPaginator) {
212:             $this->PageNumber = 1;
213:         }
214: 
215:         // Make sure the Column is Sortable
216:         if ($objColumn->OrderByClause) {
217:             // It is
218: 
219:             // Are we currently sorting by this column?
220:             if ($this->strSortColumnId === $strId) {
221:                 // Yes we are currently sorting by this column
222: 
223:                 // In Reverse?
224:                 if ($this->intSortDirection == self::SortDescending) {
225:                     // Yep -- unreverse the sort
226:                     $this->intSortDirection = self::SortAscending;
227:                 } else {
228:                     // Nope -- can we reverse?
229:                     if ($objColumn->ReverseOrderByClause) {
230:                         $this->intSortDirection = self::SortDescending;
231:                     }
232:                 }
233:             } else {
234:                 // Nope -- so let's set it to this column
235:                 $this->strSortColumnId = $strId;
236:                 $this->intSortDirection = self::SortAscending;
237:             }
238:         } else {
239:             // It isn't -- clear all sort properties
240:             $this->intSortDirection = self::SortAscending;
241:             $this->strSortColumnId = null;
242:         }
243:     }
244: 
245:     /**
246:      * Override to return the header row to indicate when a column is sortable.
247:      *
248:      * @return string
249:      */
250:     protected function GetHeaderRowHtml() {
251:         $strToReturn = '';
252:         for ($i = 0; $i < $this->intHeaderRowCount; $i++) {
253:             $this->intCurrentHeaderRowIndex = $i;
254: 
255:             $strCells = '';
256:             if ($this->objColumnArray) foreach ($this->objColumnArray as $objColumn) {
257: 
258:                 if ($objColumn->Visible) {
259:                     $strCellValue = $this->GetHeaderCellContent($objColumn);
260:                     $aParams = $objColumn->GetHeaderCellParams();
261:                     $aParams['id'] = $objColumn->Id;
262:                     if ($objColumn->OrderByClause) {
263:                         if (isset($aParams['class'])) {
264:                             $aParams['class'] .= ' ' . 'sortable';
265:                         } else {
266:                             $aParams['class'] = 'sortable';
267:                         }
268:                     }
269:                     $strCells .= QHtml::RenderTag('th', $aParams, $strCellValue);
270:                 }
271:             }
272:             $strToReturn .= QHtml::RenderTag('tr', $this->GetHeaderRowParams(), $strCells);
273:         }
274: 
275:         return $strToReturn;
276:     }
277: 
278:     /**
279:      * Override to return sortable column info.
280:      *
281:      * @param $objColumn
282:      * @return string
283:      */
284:     protected function GetHeaderCellContent($objColumn) {
285:         $blnSortable = false;
286:         $strCellValue = $objColumn->FetchHeaderCellValue();
287:         if ($objColumn->HtmlEntities) {
288:             $strCellValue = QApplication::HtmlEntities($strCellValue);
289:         }
290: 
291:         if ($this->strSortColumnId === $objColumn->Id) {
292:             if ($this->intSortDirection == self::SortAscending) {
293:                 $strCellValue = $strCellValue . ' ' . QHtml::RenderTag('i', ['class'=>'fa fa-sort-desc fa-lg']);
294:             } else {
295:                 $strCellValue = $strCellValue . ' ' . QHtml::RenderTag('i', ['class'=>'fa fa-sort-asc fa-lg']);
296:             }
297:             $blnSortable = true;
298:         }
299:         else if ($objColumn->OrderByClause) {   // sortable, but not currently being sorted
300:             $strCellValue = $strCellValue . ' ' . QHtml::RenderTag('i', ['class'=>'fa fa-sort fa-lg', 'style'=>'opacity:0.8']);
301:             $blnSortable = true;
302:         }
303: 
304:         if ($blnSortable) {
305:             // Wrap header cell in an html5 block-link to help with assistive technologies.
306:             $strCellValue = QHtml::RenderTag('div', null, $strCellValue);
307:             $strCellValue = QHtml::RenderTag('a', ['href'=>'javascript:;'], $strCellValue); // action will be handled by qcubed.js click handler in qcubed.datagrid2()
308:         }
309: 
310:         return $strCellValue;
311:     }
312: 
313:     /**
314:      * Override to enable the datagrid2 javascript.
315:      *
316:      * @return string
317:      */
318:     public function GetEndScript() {
319:         $strJS = parent::GetEndScript();
320:         QApplication::ExecuteJsFunction('qcubed.datagrid2', $this->ControlId);
321:         return $strJS;
322:     }
323: 
324: 
325:     /**
326:      * Returns the current state of the control to be able to restore it later.
327:      * @return mixed
328:      */
329:     public function GetState() {
330:         $state = array();
331:         if ($this->strSortColumnId !== null) {
332:             $state["c"] = $this->strSortColumnId;
333:             $state["d"] = $this->intSortDirection;
334:         }
335:         if ($this->Paginator || $this->PaginatorAlternate) {
336:             $state["p"] = $this->PageNumber;
337:         }
338:         return $state;
339:     }
340: 
341:     /**
342:      * Restore the state of the control.
343:      * @param mixed $state Previously saved state as returned by GetState above.
344:      */
345:     public function PutState($state) {
346:         // use the name as the column key because columns might be added or removed for some reason
347:         if (isset ($state["c"])) {
348:             $this->strSortColumnId = $state["c"];
349:         }
350:         if (isset ($state["d"])) {
351:             $this->intSortDirection = $state["d"];
352:             if ($this->intSortDirection != self::SortDescending) {
353:                 $this->intSortDirection = self::SortAscending;  // make sure its only one of two values
354:             }
355:         }
356:         if (isset ($state["p"]) &&
357:             ($this->Paginator || $this->PaginatorAlternate)) {
358:             $this->PageNumber = $state["p"];
359:         }
360:     }
361: 
362:     /**
363:      * Override to return the code generator for the list functionality.
364:      *
365:      * @param string $strClass
366:      * @return QDataGrid_CodeGenerator
367:      */
368:     public static function GetCodeGenerator($strClass = 'QDataGrid') {
369:         return new QDataGrid_CodeGenerator($strClass);
370:     }
371: 
372:     /**
373:      * Returns the index of the currently sorted column.
374:      * Returns false if nothing selected.
375:      *
376:      * @return bool|int
377:      */
378:     public function GetSortColumnIndex() {
379:         if ($this->objColumnArray && ($count = count($this->objColumnArray))) {
380:             for($i = 0; $i < $count; $i++) {
381:                 if ($this->objColumnArray[$i]->Id == $this->SortColumnId) {
382:                     return $i;
383:                 }
384:             }
385:         }
386:         return false;
387:     }
388: 
389:     /**
390:      * Return information on sorting the data. For SQL databases, this would be a QQClause. But since this just
391:      * gets the clause from the currently active column, it could be anything.
392:      *
393:      * This clause should not affect counting or limiting.
394:      *
395:      * @return mixed
396:      */
397:     public function GetOrderByInfo() {
398:         if ($this->strSortColumnId !== null) {
399:             $objColumn = $this->GetColumnById($this->strSortColumnId);
400:             if ($objColumn && $objColumn->OrderByClause) {
401:                 if ($this->intSortDirection == self::SortAscending) {
402:                     return $objColumn->OrderByClause;
403:                 }
404:                 else {
405:                     if ($objColumn->ReverseOrderByClause) {
406:                         return $objColumn->ReverseOrderByClause;
407:                     }
408:                     else {
409:                         return $objColumn->OrderByClause;
410:                     }
411:                 }
412:             }
413:             else {
414:                 return null;
415:             }
416:         } else {
417:             return null;
418:         }
419:     }
420: 
421:     /**
422:      * @param string $strName
423:      * @return bool|int|Keeps|mixed|null
424:      * @throws QCallerException
425:      */
426:     public function __get($strName) {
427:         switch ($strName) {
428:             // MISC
429:             case "OrderByClause": return $this->GetOrderByInfo();
430: 
431:             case "SortColumnId": return $this->strSortColumnId;
432:             case "SortDirection": return $this->intSortDirection;
433: 
434:             case "SortColumnIndex": return $this->GetSortColumnIndex();
435: 
436:             default:
437:                 try {
438:                     return parent::__get($strName);
439:                 } catch (QCallerException $objExc) {
440:                     $objExc->IncrementOffset();
441:                     throw $objExc;
442:                 }
443:         }
444:     }
445: 
446:     /**
447:      * @param string $strName
448:      * @param string $mixValue
449:      * @throws QCallerException
450:      * @throws QInvalidCastException
451:      */
452:     public function __set($strName, $mixValue) {
453:         switch ($strName) {
454:             case "SortColumnId":
455:                 try {
456:                     $this->strSortColumnId = QType::Cast($mixValue, QType::String);
457:                     break;
458:                 } catch (QInvalidCastException $objExc) {
459:                     $objExc->IncrementOffset();
460:                     throw $objExc;
461:                 }
462: 
463:             case "SortColumnIndex":
464:                 try {
465:                     $intIndex = QType::Cast($mixValue, QType::Integer);
466:                     if ($intIndex < 0) {
467:                         $intIndex = 0;
468:                     }
469:                     if ($intIndex < count($this->objColumnArray)) {
470:                          $objColumn = $this->objColumnArray[$intIndex];
471:                     } elseif (count($this->objColumnArray) > 0) {
472:                         $objColumn = end($this->objColumnArray);
473:                     } else {
474:                         // no columns
475:                         $objColumn = null;
476:                     }
477:                     if ($objColumn && $objColumn->OrderByClause) {
478:                         $this->strSortColumnId = $objColumn->Id;
479:                     }
480:                 } catch (QInvalidCastException $objExc) {
481:                     $objExc->IncrementOffset();
482:                     throw $objExc;
483:                 }
484:                 break;
485: 
486:             case "SortDirection":
487:                 try {
488:                     $this->intSortDirection = QType::Cast($mixValue, QType::Integer);
489:                     if ($this->intSortDirection != self::SortDescending) {
490:                         $this->intSortDirection = self::SortAscending;  // make sure its only one of two values
491:                     }
492:                     break;
493:                 } catch (QInvalidCastException $objExc) {
494:                     $objExc->IncrementOffset();
495:                     throw $objExc;
496:                 }
497: 
498:             default:
499:                 try {
500:                     parent::__set($strName, $mixValue);
501:                     break;
502:                 } catch (QCallerException $objExc) {
503:                     $objExc->IncrementOffset();
504:                     throw $objExc;
505:                 }
506:         }
507:     }
508: 
509: }