CRM/Utils/Sort.php

   1 <?php
   2 /*
   3  +--------------------------------------------------------------------+
   4  | CiviCRM version 4.6                                                |
   5  +--------------------------------------------------------------------+
   6  | Copyright CiviCRM LLC (c) 2004-2014                                |
   7  +--------------------------------------------------------------------+
   8  | This file is a part of CiviCRM.                                    |
   9  |                                                                    |
  10  | CiviCRM is free software; you can copy, modify, and distribute it  |
  11  | under the terms of the GNU Affero General Public License           |
  12  | Version 3, 19 November 2007 and the CiviCRM Licensing Exception.   |
  13  |                                                                    |
  14  | CiviCRM is distributed in the hope that it will be useful, but     |
  15  | WITHOUT ANY WARRANTY; without even the implied warranty of         |
  16  | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.               |
  17  | See the GNU Affero General Public License for more details.        |
  18  |                                                                    |
  19  | You should have received a copy of the GNU Affero General Public   |
  20  | License and the CiviCRM Licensing Exception along                  |
  21  | with this program; if not, contact CiviCRM LLC                     |
  22  | at info[AT]civicrm[DOT]org. If you have questions about the        |
  23  | GNU Affero General Public License or the licensing of CiviCRM,     |
  24  | see the CiviCRM license FAQ at http://civicrm.org/licensing        |
  25  +--------------------------------------------------------------------+
  26 */
  27
  28 /**
  29  *
  30  * @package CRM
  31  * @copyright CiviCRM LLC (c) 2004-2014
  32  * $Id$
  33  *
  34  */
  35
  36 /**
  37  *
  38  * Base class to provide generic sort functionality. Note that some ideas
  39  * have been borrowed from the drupal tablesort.inc code. Also note that
  40  * since the Pager and Sort class are similar, do match the function names
  41  * if introducing additional functionality
  42  *
  43  * @package CRM
  44  * @copyright CiviCRM LLC (c) 2004-2014
  45  * $Id$
  46  *
  47  */
  48 class CRM_Utils_Sort {
  49
  50   /**
  51    * Constants to determine what direction each variable
  52    * is to be sorted
  53    *
  54    * @var int
  55    */
  56   const ASCENDING = 1, DESCENDING = 2, DONTCARE = 4,
  57
  58   /**
  59    * The name for the sort GET/POST param
  60    *
  61    * @var string
  62    */
  63   SORT_ID = 'crmSID', SORT_DIRECTION = 'crmSortDirection', SORT_ORDER = 'crmSortOrder';
  64
  65   /**
  66    * Name of the sort function. Used to isolate session variables
  67    * @var string
  68    */
  69   protected $_name;
  70
  71   /**
  72    * Array of variables that influence the query
  73    *
  74    * @var array
  75    */
  76   public $_vars;
  77
  78   /**
  79    * The newly formulated base url to be used as links
  80    * for various table elements
  81    *
  82    * @var string
  83    */
  84   protected $_link;
  85
  86   /**
  87    * What's the name of the sort variable in a REQUEST
  88    *
  89    * @var string
  90    */
  91   protected $_urlVar;
  92
  93   /**
  94    * What variable are we currently sorting on
  95    *
  96    * @var string
  97    */
  98   protected $_currentSortID;
  99
 100   /**
 101    * What direction are we sorting on
 102    *
 103    * @var string
 104    */
 105   protected $_currentSortDirection;
 106
 107   /**
 108    * The output generated for the current form
 109    *
 110    * @var array
 111    */
 112   public $_response;
 113
 114   /**
 115    * The constructor takes an assoc array
 116    * key names of variable (which should be the same as the column name)
 117    * value: ascending or descending
 118    *
 119    * @param mixed $vars - assoc array as described above
 120    * @param string $defaultSortOrder - order to sort
 121    *
 122    * @return \CRM_Utils_Sort
 123   @access public
 124    */
 125   public function __construct(&$vars, $defaultSortOrder = NULL) {
 126     $this->_vars = array();
 127     $this->_response = array();
 128
 129     foreach ($vars as $weight => $value) {
 130       $this->_vars[$weight] = array(
 131         'name' => $value['sort'],
 132         'direction' => CRM_Utils_Array::value('direction', $value),
 133         'title' => $value['name'],
 134       );
 135     }
 136
 137     $this->_currentSortID = 1;
 138     if (isset($this->_vars[$this->_currentSortID])) {
 139       $this->_currentSortDirection = $this->_vars[$this->_currentSortID]['direction'];
 140     }
 141     $this->_urlVar = self::SORT_ID;
 142     $this->_link = CRM_Utils_System::makeURL($this->_urlVar, TRUE);
 143
 144     $this->initialize($defaultSortOrder);
 145   }
 146
 147   /**
 148    * Function returns the string for the order by clause
 149    *
 150    * @return string the order by clause
 151    */
 152   public function orderBy() {
 153     if (empty($this->_vars[$this->_currentSortID])) {
 154       return '';
 155     }
 156
 157     if ($this->_vars[$this->_currentSortID]['direction'] == self::ASCENDING ||
 158       $this->_vars[$this->_currentSortID]['direction'] == self::DONTCARE
 159     ) {
 160       $this->_vars[$this->_currentSortID]['name'] = str_replace(' ', '_', $this->_vars[$this->_currentSortID]['name']);
 161       return $this->_vars[$this->_currentSortID]['name'] . ' asc';
 162     }
 163     else {
 164       $this->_vars[$this->_currentSortID]['name'] = str_replace(' ', '_', $this->_vars[$this->_currentSortID]['name']);
 165       return $this->_vars[$this->_currentSortID]['name'] . ' desc';
 166     }
 167   }
 168
 169   /**
 170    * Create the sortID string to be used in the GET param
 171    *
 172    * @param int $index the field index
 173    * @param int $dir   the direction of the sort
 174    *
 175    * @return string  the string to append to the url
 176    * @static
 177    */
 178   public static function sortIDValue($index, $dir) {
 179     return ($dir == self::DESCENDING) ? $index . '_d' : $index . '_u';
 180   }
 181
 182   /**
 183    * Init the sort ID values in the object
 184    *
 185    * @param string $defaultSortOrder the sort order to use by default
 186    *
 187    * @return returns null if $url- (sort url) is not found
 188    */
 189   public function initSortID($defaultSortOrder) {
 190     $url = CRM_Utils_Array::value(self::SORT_ID, $_GET, $defaultSortOrder);
 191
 192     if (empty($url)) {
 193       return;
 194     }
 195
 196     list($current, $direction) = explode('_', $url);
 197
 198     // if current is wierd and does not exist in the vars array, skip
 199     if (!array_key_exists($current, $this->_vars)) {
 200       return;
 201     }
 202
 203     if ($direction == 'u') {
 204       $direction = self::ASCENDING;
 205     }
 206     elseif ($direction == 'd') {
 207       $direction = self::DESCENDING;
 208     }
 209     else {
 210       $direction = self::DONTCARE;
 211     }
 212
 213     $this->_currentSortID = $current;
 214     $this->_currentSortDirection = $direction;
 215     $this->_vars[$current]['direction'] = $direction;
 216   }
 217
 218   /**
 219    * Init the object
 220    *
 221    * @param string $defaultSortOrder the sort order to use by default
 222    *
 223    * @return void
 224    */
 225   public function initialize($defaultSortOrder) {
 226     $this->initSortID($defaultSortOrder);
 227
 228     $this->_response = array();
 229
 230     $current = $this->_currentSortID;
 231     foreach ($this->_vars as $index => $item) {
 232       $name = $item['name'];
 233       $this->_response[$name] = array();
 234
 235       $newDirection = ($item['direction'] == self::ASCENDING) ? self::DESCENDING : self::ASCENDING;
 236
 237       if ($current == $index) {
 238         if ($item['direction'] == self::ASCENDING) {
 239           $class = 'sorting_asc';
 240         }
 241         else {
 242           $class = 'sorting_desc';
 243         }
 244       }
 245       else {
 246         $class = 'sorting';
 247       }
 248
 249       $this->_response[$name]['link'] = '<a href="' . $this->_link . $this->sortIDValue($index, $newDirection) . '" class="' . $class . '">' . $item['title'] . '</a>';
 250     }
 251   }
 252
 253   /**
 254    * Getter for currentSortID
 255    *
 256    * @return int returns of the current sort id
 257    * @acccess public
 258    */
 259   public function getCurrentSortID() {
 260     return $this->_currentSortID;
 261   }
 262
 263   /**
 264    * Getter for currentSortDirection
 265    *
 266    * @return int returns of the current sort direction
 267    * @acccess public
 268    */
 269   public function getCurrentSortDirection() {
 270     return $this->_currentSortDirection;
 271   }
 272
 273   /**
 274    * Universal callback function for sorting by weight, id, title or name
 275    *
 276    * @param $a
 277    * @param $b
 278    *
 279    * @return int (-1 or 1)
 280    */
 281   public static function cmpFunc($a, $b) {
 282     $cmp_order = array('weight', 'id', 'title', 'name');
 283     foreach ($cmp_order as $attribute) {
 284       if (isset($a[$attribute]) && isset($b[$attribute])) {
 285         if ($a[$attribute] < $b[$attribute]) {
 286           return -1;
 287         } elseif ($a[$attribute] > $b[$attribute]) {
 288           return 1;
 289         } // else: $a and $b are equal wrt to this attribute, try next...
 290       }
 291     }
 292     // if we get here, $a and $b es equal for all we know
 293     // however, as I understand we don't want equality here:
 294     return -1;
 295   }
 296 }