Code coverage for /20080809/includes/tablesort.inc

Line #Times calledCode
1
<?php
2
// $Id: tablesort.inc,v 1.48 2008/04/14 17:48:33 dries 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
 */
152027
function tablesort_init($header) {
16243
  $ts = tablesort_get_order($header);
17243
  $ts['sort'] = tablesort_get_sort($header);
18243
  $ts['query_string'] = tablesort_get_querystring();
19243
  return $ts;
200
}
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
 */
392027
function tablesort_sql($header, $before = '') {
4047
  $ts = tablesort_init($header);
4147
  if ($ts['sql']) {
42
    // Based on code from db_escape_table(), but this can also contain a
dot.
4347
    $field = preg_replace('/[^A-Za-z0-9_.]+/', '', $ts['sql']);
44
45
    // Sort order can only be ASC or DESC.
4647
    $sort = drupal_strtoupper($ts['sort']);
4747
    $sort = in_array($sort, array('ASC', 'DESC')) ? $sort : '';
48
4947
    return " ORDER BY $before $field $sort";
500
  }
510
}
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
 */
682027
function tablesort_header($cell, $header, $ts) {
69
  // Special formatting for the currently sorted column header.
70240
  if (is_array($cell) && isset($cell['field'])) {
7144
    $title = t('sort by @s', array('@s' => $cell['data']));
7244
    if ($cell['data'] == $ts['name']) {
7344
      $ts['sort'] = (($ts['sort'] == 'asc') ? 'desc' : 'asc');
7444
      if (isset($cell['class'])) {
750
        $cell['class'] .= ' active';
760
      }
77
      else {
7844
        $cell['class'] = 'active';
79
      }
8044
      $image = theme('tablesort_indicator', $ts['sort']);
8144
    }
82
    else {
83
      // If the user clicks a different header, we want to sort ascending
initially.
8444
      $ts['sort'] = 'asc';
8544
      $image = '';
86
    }
87
8844
    if (!empty($ts['query_string'])) {
890
      $ts['query_string'] = '&' . $ts['query_string'];
900
    }
9144
    $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
9344
    unset($cell['field'], $cell['sort']);
9444
  }
95240
  return $cell;
960
}
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
 */
1142027
function tablesort_cell($cell, $header, $ts, $i) {
115221
  if (isset($header[$i]['data']) && $header[$i]['data'] == $ts['name'] &&
!empty($header[$i]['field'])) {
11636
    if (is_array($cell)) {
1171
      if (isset($cell['class'])) {
1180
        $cell['class'] .= ' active';
1190
      }
120
      else {
1211
        $cell['class'] = 'active';
122
      }
1231
    }
124
    else {
12535
      $cell = array('data' => $cell, 'class' => 'active');
126
    }
12736
  }
128221
  return $cell;
1290
}
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
 */
1382027
function tablesort_get_querystring() {
139243
  return drupal_query_string_encode($_REQUEST, array_merge(array('q',
'sort', 'order'), array_keys($_COOKIE)));
1400
}
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
 */
1522027
function tablesort_get_order($headers) {
153243
  $order = isset($_GET['order']) ? $_GET['order'] : '';
154243
  foreach ($headers as $header) {
155243
    if (isset($header['data']) && $order == $header['data']) {
1560
      return array('name' => $header['data'], 'sql' =>
isset($header['field']) ? $header['field'] : '');
1570
    }
158
159243
    if (isset($header['sort']) && ($header['sort'] == 'asc' ||
$header['sort'] == 'desc')) {
16046
      $default = array('name' => $header['data'], 'sql' =>
isset($header['field']) ? $header['field'] : '');
16146
    }
162243
  }
163
164243
  if (isset($default)) {
16546
    return $default;
1660
  }
167
  else {
168
    // The first column specified is initial 'order by' field unless
otherwise specified
169197
    if (is_array($headers[0])) {
17045
      $headers[0] += array('data' => NULL, 'field' => NULL);
17145
      return array('name' => $headers[0]['data'], 'sql' =>
$headers[0]['field']);
1720
    }
173
    else {
174153
      return array('name' => $headers[0]);
175
    }
176
  }
1770
}
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
 */
1872027
function tablesort_get_sort($headers) {
188243
  if (isset($_GET['sort'])) {
1890
    return ($_GET['sort'] == 'desc') ? 'desc' : 'asc';
1900
  }
191
  // User has not specified a sort. Use default if specified; otherwise use
"asc".
192
  else {
193243
    foreach ($headers as $header) {
194243
      if (is_array($header) && array_key_exists('sort', $header)) {
19546
        return $header['sort'];
1960
      }
197228
    }
198
  }
199197
  return 'asc';
2000
}
2012027