includes/tablesort.inc

   1 <?php
   2 // $Id: tablesort.inc 144 2007-03-28 07:52:20Z thierry $
   3
   4 /**
   5  * @file
   6  * Functions to aid in the creation of sortable tables.
   7  *
   8  * All tables created with a call to theme('table') have the option of having
   9  * column headers that the user can click on to sort the table by that column.
  10  */
  11
  12 /**
  13  * Initialize the table sort context.
  14  */
  15 function tablesort_init($header) {
  16   $ts = tablesort_get_order($header);
  17   $ts['sort'] = tablesort_get_sort($header);
  18   $ts['query_string'] = tablesort_get_querystring();
  19   return $ts;
  20 }
  21
  22 /**
  23  * Create an SQL sort clause.
  24  *
  25  * This function produces the ORDER BY clause to insert in your SQL queries,
  26  * assuring that the returned database table rows match the sort order chosen
  27  * by the user.
  28  *
  29  * @param $header
  30  *   An array of column headers in the format described in theme_table().
  31  * @param $before
  32  *   An SQL string to insert after ORDER BY and before the table sorting code.
  33  *   Useful for sorting by important attributes like "sticky" first.
  34  * @return
  35  *   An SQL string to append to the end of a query.
  36  *
  37  * @ingroup database
  38  */
  39 function tablesort_sql($header, $before = '') {
  40   $ts = tablesort_init($header);
  41   if ($ts['sql']) {
  42     $sql = db_escape_string($ts['sql']);
  43     $sort = drupal_strtoupper(db_escape_string($ts['sort']));
  44     return " ORDER BY $before $sql $sort";
  45   }
  46 }
  47
  48 /**
  49  * Format a column header.
  50  *
  51  * If the cell in question is the column header for the current sort criterion,
  52  * it gets special formatting. All possible sort criteria become links.
  53  *
  54  * @param $cell
  55  *   The cell to format.
  56  * @param $header
  57  *   An array of column headers in the format described in theme_table().
  58  * @param $ts
  59  *   The current table sort context as returned from tablesort_init().
  60  * @return
  61  *   A properly formatted cell, ready for _theme_table_cell().
  62  */
  63 function tablesort_header($cell, $header, $ts) {
  64   // Special formatting for the currently sorted column header.
  65   if (is_array($cell) && isset($cell['field'])) {
  66     $title = t('sort by %s', array('%s' => $cell['data']));
  67     if ($cell['data'] == $ts['name']) {
  68       $ts['sort'] = (($ts['sort'] == 'asc') ? 'desc' : 'asc');
  69       $cell['class'] = 'active';
  70       $image = theme('tablesort_indicator', $ts['sort']);
  71     }
  72     else {
  73       // If the user clicks a different header, we want to sort ascending initially.
  74       $ts['sort'] = 'asc';
  75       $image = '';
  76     }
  77
  78     if (!empty($ts['query_string'])) {
  79       $ts['query_string'] = '&'. $ts['query_string'];
  80     }
  81     $cell['data'] = l($cell['data'] . $image, $_GET['q'], array('title' => $title), 'sort='. $ts['sort'] .'&order='. urlencode($cell['data']) . $ts['query_string'], NULL, FALSE, TRUE);
  82
  83     unset($cell['field'], $cell['sort']);
  84   }
  85   return $cell;
  86 }
  87
  88 /**
  89  * Format a table cell.
  90  *
  91  * Adds a class attribute to all cells in the currently active column.
  92  *
  93  * @param $cell
  94  *   The cell to format.
  95  * @param $header
  96  *   An array of column headers in the format described in theme_table().
  97  * @param $ts
  98  *   The current table sort context as returned from tablesort_init().
  99  * @param $i
 100  *   The index of the cell's table column.
 101  * @return
 102  *   A properly formatted cell, ready for _theme_table_cell().
 103  */
 104 function tablesort_cell($cell, $header, $ts, $i) {
 105   if (isset($header[$i]) && $header[$i]['data'] == $ts['name'] && $header[$i]['field']) {
 106     if (is_array($cell)) {
 107       if (isset($cell['class'])) {
 108         $cell['class'] .= ' active';
 109       }
 110       else {
 111         $cell['class'] = 'active';
 112       }
 113     }
 114     else {
 115       $cell = array('data' => $cell, 'class' => 'active');
 116     }
 117   }
 118   return $cell;
 119 }
 120
 121 /**
 122  * Compose a query string to append to table sorting requests.
 123  *
 124  * @return
 125  *   A query string that consists of all components of the current page request
 126  *   except for those pertaining to table sorting.
 127  */
 128 function tablesort_get_querystring() {
 129   return drupal_query_string_encode($_REQUEST, array_merge(array('q', 'sort', 'order'), array_keys($_COOKIE)));
 130 }
 131
 132 /**
 133  * Determine the current sort criterion.
 134  *
 135  * @param $headers
 136  *   An array of column headers in the format described in theme_table().
 137  * @return
 138  *   An associative array describing the criterion, containing the keys:
 139  *   - "name": The localized title of the table column.
 140  *   - "sql": The name of the database field to sort on.
 141  */
 142 function tablesort_get_order($headers) {
 143   $order = isset($_GET['order']) ? $_GET['order'] : '';
 144   foreach ($headers as $header) {
 145     if (isset($header['data']) && $order == $header['data']) {
 146       return array('name' => $header['data'], 'sql' => $header['field']);
 147     }
 148
 149     if (isset($header['sort']) && ($header['sort'] == 'asc' || $header['sort'] == 'desc')) {
 150       $default = array('name' => $header['data'], 'sql' => $header['field']);
 151     }
 152   }
 153
 154   if (isset($default)) {
 155     return $default;
 156   }
 157   else {
 158     // The first column specified is initial 'order by' field unless otherwise specified
 159     if (is_array($headers[0])) {
 160       return array('name' => $headers[0]['data'], 'sql' => $headers[0]['field']);
 161     }
 162     else {
 163       return array('name' => $headers[0]);
 164     }
 165   }
 166 }
 167
 168 /**
 169  * Determine the current sort direction.
 170  *
 171  * @param $headers
 172  *   An array of column headers in the format described in theme_table().
 173  * @return
 174  *   The current sort direction ("asc" or "desc").
 175  */
 176 function tablesort_get_sort($headers) {
 177   if (isset($_GET['sort'])) {
 178     return ($_GET['sort'] == 'desc') ? 'desc' : 'asc';
 179   }
 180   // User has not specified a sort. Use default if specified; otherwise use "asc".
 181   else {
 182     foreach ($headers as $header) {
 183       if (is_array($header) && array_key_exists('sort', $header)) {
 184         return $header['sort'];
 185       }
 186     }
 187   }
 188   return 'asc';
 189 }