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
 120    *   Assoc array as described above.
 121    * @param string $defaultSortOrder
 122    *   Order to sort.
 123    *
 124    * @return \CRM_Utils_Sort
 125   @access public
 126    */
 127   public function __construct(&$vars, $defaultSortOrder = NULL) {
 128     $this->_vars = array();
 129     $this->_response = array();
 130
 131     foreach ($vars as $weight => $value) {
 132       $this->_vars[$weight] = array(
 133         'name' => $value['sort'],
 134         'direction' => CRM_Utils_Array::value('direction', $value),
 135         'title' => $value['name'],
 136       );
 137     }
 138
 139     $this->_currentSortID = 1;
 140     if (isset($this->_vars[$this->_currentSortID])) {
 141       $this->_currentSortDirection = $this->_vars[$this->_currentSortID]['direction'];
 142     }
 143     $this->_urlVar = self::SORT_ID;
 144     $this->_link = CRM_Utils_System::makeURL($this->_urlVar, TRUE);
 145
 146     $this->initialize($defaultSortOrder);
 147   }
 148
 149   /**
 150    * Function returns the string for the order by clause
 151    *
 152    * @return string
 153    *   the order by clause
 154    */
 155   public function orderBy() {
 156     if (empty($this->_vars[$this->_currentSortID])) {
 157       return '';
 158     }
 159
 160     if ($this->_vars[$this->_currentSortID]['direction'] == self::ASCENDING ||
 161       $this->_vars[$this->_currentSortID]['direction'] == self::DONTCARE
 162     ) {
 163       $this->_vars[$this->_currentSortID]['name'] = str_replace(' ', '_', $this->_vars[$this->_currentSortID]['name']);
 164       return $this->_vars[$this->_currentSortID]['name'] . ' asc';
 165     }
 166     else {
 167       $this->_vars[$this->_currentSortID]['name'] = str_replace(' ', '_', $this->_vars[$this->_currentSortID]['name']);
 168       return $this->_vars[$this->_currentSortID]['name'] . ' desc';
 169     }
 170   }
 171
 172   /**
 173    * Create the sortID string to be used in the GET param
 174    *
 175    * @param int $index
 176    *   The field index.
 177    * @param int $dir
 178    *   The direction of the sort.
 179    *
 180    * @return string
 181    *   the string to append to the url
 182    * @static
 183    */
 184   public static function sortIDValue($index, $dir) {
 185     return ($dir == self::DESCENDING) ? $index . '_d' : $index . '_u';
 186   }
 187
 188   /**
 189    * Init the sort ID values in the object
 190    *
 191    * @param string $defaultSortOrder
 192    *   The sort order to use by default.
 193    *
 194    * @return returns null if $url- (sort url) is not found
 195    */
 196   public function initSortID($defaultSortOrder) {
 197     $url = CRM_Utils_Array::value(self::SORT_ID, $_GET, $defaultSortOrder);
 198
 199     if (empty($url)) {
 200       return;
 201     }
 202
 203     list($current, $direction) = explode('_', $url);
 204
 205     // if current is wierd and does not exist in the vars array, skip
 206     if (!array_key_exists($current, $this->_vars)) {
 207       return;
 208     }
 209
 210     if ($direction == 'u') {
 211       $direction = self::ASCENDING;
 212     }
 213     elseif ($direction == 'd') {
 214       $direction = self::DESCENDING;
 215     }
 216     else {
 217       $direction = self::DONTCARE;
 218     }
 219
 220     $this->_currentSortID = $current;
 221     $this->_currentSortDirection = $direction;
 222     $this->_vars[$current]['direction'] = $direction;
 223   }
 224
 225   /**
 226    * Init the object
 227    *
 228    * @param string $defaultSortOrder
 229    *   The sort order to use by default.
 230    *
 231    * @return void
 232    */
 233   public function initialize($defaultSortOrder) {
 234     $this->initSortID($defaultSortOrder);
 235
 236     $this->_response = array();
 237
 238     $current = $this->_currentSortID;
 239     foreach ($this->_vars as $index => $item) {
 240       $name = $item['name'];
 241       $this->_response[$name] = array();
 242
 243       $newDirection = ($item['direction'] == self::ASCENDING) ? self::DESCENDING : self::ASCENDING;
 244
 245       if ($current == $index) {
 246         if ($item['direction'] == self::ASCENDING) {
 247           $class = 'sorting_asc';
 248         }
 249         else {
 250           $class = 'sorting_desc';
 251         }
 252       }
 253       else {
 254         $class = 'sorting';
 255       }
 256
 257       $this->_response[$name]['link'] = '<a href="' . $this->_link . $this->sortIDValue($index, $newDirection) . '" class="' . $class . '">' . $item['title'] . '</a>';
 258     }
 259   }
 260
 261   /**
 262    * Getter for currentSortID
 263    *
 264    * @return int
 265    *   returns of the current sort id
 266    * @acccess public
 267    */
 268   public function getCurrentSortID() {
 269     return $this->_currentSortID;
 270   }
 271
 272   /**
 273    * Getter for currentSortDirection
 274    *
 275    * @return int
 276    *   returns of the current sort direction
 277    * @acccess public
 278    */
 279   public function getCurrentSortDirection() {
 280     return $this->_currentSortDirection;
 281   }
 282
 283   /**
 284    * Universal callback function for sorting by weight, id, title or name
 285    *
 286    * @param $a
 287    * @param $b
 288    *
 289    * @return int
 290    *   (-1 or 1)
 291    */
 292   public static function cmpFunc($a, $b) {
 293     $cmp_order = array('weight', 'id', 'title', 'name');
 294     foreach ($cmp_order as $attribute) {
 295       if (isset($a[$attribute]) && isset($b[$attribute])) {
 296         if ($a[$attribute] < $b[$attribute]) {
 297           return -1;
 298         }
 299         elseif ($a[$attribute] > $b[$attribute]) {
 300           return 1;
 301         } // else: $a and $b are equal wrt to this attribute, try next...
 302       }
 303     }
 304     // if we get here, $a and $b es equal for all we know
 305     // however, as I understand we don't want equality here:
 306     return -1;
 307   }
 308 }