1. 8.2.x core/includes/tablesort.inc
  2. 8.0.x core/includes/tablesort.inc
  3. 8.1.x core/includes/tablesort.inc
  4. 8.3.x core/includes/tablesort.inc
  5. 4.6.x includes/tablesort.inc
  6. 4.7.x includes/tablesort.inc
  7. 5.x includes/tablesort.inc
  8. 6.x includes/tablesort.inc
  9. 7.x includes/tablesort.inc

Functions to aid in the creation of sortable tables.

All tables created with a call to theme('table') have the option of having column headers that the user can click on to sort the table by that column.

File

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

Functions

Namesort descending Description
tablesort_cell Format a table cell.
tablesort_get_order Determine the current sort criterion.
tablesort_get_querystring Compose a query string to append to table sorting requests.
tablesort_get_sort Determine the current sort direction.
tablesort_header Format a column header.
tablesort_init Initialize the table sort context.
tablesort_sql Create an SQL sort clause.