[Summary view] [Print] [Text view]

   1  <?php
   2  // $Id: tablesort.inc,v 1.47.2.1 2009/07/01 20:51:55 goba Exp $
   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      // Based on code from db_escape_table(), but this can also contain a dot.
  43      $field = preg_replace('/[^A-Za-z0-9_.]+/', '', $ts['sql']);
  44  
  45      // Sort order can only be ASC or DESC.
  46      $sort = drupal_strtoupper($ts['sort']);
  47      $sort = in_array($sort, array('ASC', 'DESC')) ? $sort : '';
  48  
  49      return " ORDER BY $before $field $sort";
  50    }
  51  }
  52  
  53  /**
  54   * Format a column header.
  55   *
  56   * If the cell in question is the column header for the current sort criterion,
  57   * it gets special formatting. All possible sort criteria become links.
  58   *
  59   * @param $cell
  60   *   The cell to format.
  61   * @param $header
  62   *   An array of column headers in the format described in theme_table().
  63   * @param $ts
  64   *   The current table sort context as returned from tablesort_init().
  65   * @return
  66   *   A properly formatted cell, ready for _theme_table_cell().
  67   */
  68  function tablesort_header($cell, $header, $ts) {
  69    // Special formatting for the currently sorted column header.
  70    if (is_array($cell) && isset($cell['field'])) {
  71      $title = t('sort by @s', array('@s' => $cell['data']));
  72      if ($cell['data'] == $ts['name']) {
  73        $ts['sort'] = (($ts['sort'] == 'asc') ? 'desc' : 'asc');
  74        if (isset($cell['class'])) {
  75          $cell['class'] .= ' active';
  76        }
  77        else {
  78          $cell['class'] = 'active';
  79        }
  80        $image = theme('tablesort_indicator', $ts['sort']);
  81      }
  82      else {
  83        // If the user clicks a different header, we want to sort ascending initially.
  84        $ts['sort'] = 'asc';
  85        $image = '';
  86      }
  87  
  88      if (!empty($ts['query_string'])) {
  89        $ts['query_string'] = '&'. $ts['query_string'];
  90      }
  91      $cell['data'] = l($cell['data'] . $image, $_GET['q'], array('attributes' => array('title' => $title), 'query' => 'sort='. $ts['sort'] .'&order='. urlencode($cell['data']) . $ts['query_string'], 'html' => TRUE));
  92  
  93      unset($cell['field'], $cell['sort']);
  94    }
  95    return $cell;
  96  }
  97  
  98  /**
  99   * Format a table cell.
 100   *
 101   * Adds a class attribute to all cells in the currently active column.
 102   *
 103   * @param $cell
 104   *   The cell to format.
 105   * @param $header
 106   *   An array of column headers in the format described in theme_table().
 107   * @param $ts
 108   *   The current table sort context as returned from tablesort_init().
 109   * @param $i
 110   *   The index of the cell's table column.
 111   * @return
 112   *   A properly formatted cell, ready for _theme_table_cell().
 113   */
 114  function tablesort_cell($cell, $header, $ts, $i) {
 115    if (isset($header[$i]['data']) && $header[$i]['data'] == $ts['name'] && !empty($header[$i]['field'])) {
 116      if (is_array($cell)) {
 117        if (isset($cell['class'])) {
 118          $cell['class'] .= ' active';
 119        }
 120        else {
 121          $cell['class'] = 'active';
 122        }
 123      }
 124      else {
 125        $cell = array('data' => $cell, 'class' => 'active');
 126      }
 127    }
 128    return $cell;
 129  }
 130  
 131  /**
 132   * Compose a query string to append to table sorting requests.
 133   *
 134   * @return
 135   *   A query string that consists of all components of the current page request
 136   *   except for those pertaining to table sorting.
 137   */
 138  function tablesort_get_querystring() {
 139    return drupal_query_string_encode($_REQUEST, array_merge(array('q', 'sort', 'order', 'pass'), array_keys($_COOKIE)));
 140  }
 141  
 142  /**
 143   * Determine the current sort criterion.
 144   *
 145   * @param $headers
 146   *   An array of column headers in the format described in theme_table().
 147   * @return
 148   *   An associative array describing the criterion, containing the keys:
 149   *   - "name": The localized title of the table column.
 150   *   - "sql": The name of the database field to sort on.
 151   */
 152  function tablesort_get_order($headers) {
 153    $order = isset($_GET['order']) ? $_GET['order'] : '';
 154    foreach ($headers as $header) {
 155      if (isset($header['data']) && $order == $header['data']) {
 156        return array('name' => $header['data'], 'sql' => isset($header['field']) ? $header['field'] : '');
 157      }
 158  
 159      if (isset($header['sort']) && ($header['sort'] == 'asc' || $header['sort'] == 'desc')) {
 160        $default = array('name' => $header['data'], 'sql' => isset($header['field']) ? $header['field'] : '');
 161      }
 162    }
 163  
 164    if (isset($default)) {
 165      return $default;
 166    }
 167    else {
 168      // The first column specified is initial 'order by' field unless otherwise specified
 169      if (is_array($headers[0])) {
 170        $headers[0] += array('data' => NULL, 'field' => NULL);
 171        return array('name' => $headers[0]['data'], 'sql' => $headers[0]['field']);
 172      }
 173      else {
 174        return array('name' => $headers[0]);
 175      }
 176    }
 177  }
 178  
 179  /**
 180   * Determine the current sort direction.
 181   *
 182   * @param $headers
 183   *   An array of column headers in the format described in theme_table().
 184   * @return
 185   *   The current sort direction ("asc" or "desc").
 186   */
 187  function tablesort_get_sort($headers) {
 188    if (isset($_GET['sort'])) {
 189      return ($_GET['sort'] == 'desc') ? 'desc' : 'asc';
 190    }
 191    // User has not specified a sort. Use default if specified; otherwise use "asc".
 192    else {
 193      foreach ($headers as $header) {
 194        if (is_array($header) && array_key_exists('sort', $header)) {
 195          return $header['sort'];
 196        }
 197      }
 198    }
 199    return 'asc';
 200  }