Code coverage for /20081101/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
 */
152366
function tablesort_init($header) {
16275
  $ts = tablesort_get_order($header);
17275
  $ts['sort'] = tablesort_get_sort($header);
18275
  $ts['query_string'] = tablesort_get_querystring();
19275
  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
 */
392366
function tablesort_sql($header, $before = '') {
4059
  $ts = tablesort_init($header);
4159
  if ($ts['sql']) {
42
    // Based on code from db_escape_table(), but this can also contain a
dot.
4355
    $field = preg_replace('/[^A-Za-z0-9_.]+/', '', $ts['sql']);
44
45
    // Sort order can only be ASC or DESC.
4655
    $sort = drupal_strtoupper($ts['sort']);
4755
    $sort = in_array($sort, array('ASC', 'DESC')) ? $sort : '';
48
4955
    return " ORDER BY $before $field $sort";
500
  }
514
}
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
 */
682366
function tablesort_header($cell, $header, $ts) {
69
  // Special formatting for the currently sorted column header.
70271
  if (is_array($cell) && isset($cell['field'])) {
7155
    $title = t('sort by @s', array('@s' => $cell['data']));
7255
    if ($cell['data'] == $ts['name']) {
7351
      $ts['sort'] = (($ts['sort'] == 'asc') ? 'desc' : 'asc');
7451
      if (isset($cell['class'])) {
750
        $cell['class'] .= ' active';
760
      }
77
      else {
7851
        $cell['class'] = 'active';
79
      }
8051
      $image = theme('tablesort_indicator', $ts['sort']);
8151
    }
82
    else {
83
      // If the user clicks a different header, we want to sort ascending
initially.
8455
      $ts['sort'] = 'asc';
8555
      $image = '';
86
    }
87
8855
    if (!empty($ts['query_string'])) {
891
      $ts['query_string'] = '&' . $ts['query_string'];
901
    }
9155
    $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
9355
    unset($cell['field'], $cell['sort']);
9455
  }
95271
  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
 */
1142366
function tablesort_cell($cell, $header, $ts, $i) {
115252
  if (isset($header[$i]['data']) && $header[$i]['data'] == $ts['name'] &&
!empty($header[$i]['field'])) {
11643
    if (is_array($cell)) {
1173
      if (isset($cell['class'])) {
1180
        $cell['class'] .= ' active';
1190
      }
120
      else {
1213
        $cell['class'] = 'active';
122
      }
1233
    }
124
    else {
12540
      $cell = array('data' => $cell, 'class' => 'active');
126
    }
12743
  }
128252
  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
 */
1382366
function tablesort_get_querystring() {
139275
  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
 */
1522366
function tablesort_get_order($headers) {
153275
  $order = isset($_GET['order']) ? $_GET['order'] : '';
154275
  foreach ($headers as $header) {
155275
    if (isset($header['data']) && $order == $header['data']) {
1564
      return array('name' => $header['data'], 'sql' =>
isset($header['field']) ? $header['field'] : '');
1570
    }
158
159275
    if (isset($header['sort']) && ($header['sort'] == 'asc' ||
$header['sort'] == 'desc')) {
16052
      $default = array('name' => $header['data'], 'sql' =>
isset($header['field']) ? $header['field'] : '');
16152
    }
162275
  }
163
164271
  if (isset($default)) {
16552
    return $default;
1660
  }
167
  else {
168
    // The first column specified is initial 'order by' field unless
otherwise specified
169219
    if (is_array($headers[0])) {
17052
      $headers[0] += array('data' => NULL, 'field' => NULL);
17152
      return array('name' => $headers[0]['data'], 'sql' =>
$headers[0]['field']);
1720
    }
173
    else {
174169
      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
 */
1872366
function tablesort_get_sort($headers) {
188275
  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 {
193275
    foreach ($headers as $header) {
194275
      if (is_array($header) && array_key_exists('sort', $header)) {
19552
        return $header['sort'];
1960
      }
197260
    }
198
  }
199223
  return 'asc';
2000
}
2012366