Newer
Older
/**
* @file
* 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.
*/
Dries Buytaert
committed
/**
* Query extender class for tablesort queries.
*/
class TableSort extends SelectQueryExtender {
/**
* The array of fields that can be sorted by.
*
* @var array
*/
protected $header = array();
Angie Byron
committed
public function __construct(SelectQueryInterface $query, DatabaseConnection $connection) {
parent::__construct($query, $connection);
// Add convenience tag to mark that this is an extended query. We have to
// do this in the constructor to ensure that it is set before preExecute()
// gets called.
$this->addTag('tablesort');
Dries Buytaert
committed
}
Angie Byron
committed
/**
* Order the query based on a header array.
*
* @see theme_table()
* @param $header
* Table header array.
*/
Dries Buytaert
committed
public function orderByHeader(Array $header) {
$this->header = $header;
Dries Buytaert
committed
$ts = $this->init();
Dries Buytaert
committed
if (!empty($ts['sql'])) {
Dries Buytaert
committed
// Based on code from db_escape_table(), but this can also contain a dot.
$field = preg_replace('/[^A-Za-z0-9_.]+/', '', $ts['sql']);
// Sort order can only be ASC or DESC.
$sort = drupal_strtoupper($ts['sort']);
$sort = in_array($sort, array('ASC', 'DESC')) ? $sort : '';
$this->orderBy($field, $sort);
}
return $this;
}
/**
* Initialize the table sort context.
*/
protected function init() {
$ts = $this->order();
$ts['sort'] = $this->getSort();
Dries Buytaert
committed
$ts['query'] = $this->getQueryParameters();
Dries Buytaert
committed
return $ts;
}
/**
* Determine the current sort direction.
*
* @param $headers
* An array of column headers in the format described in theme_table().
* @return
* The current sort direction ("asc" or "desc").
*/
protected function getSort() {
if (isset($_GET['sort'])) {
return ($_GET['sort'] == 'desc') ? 'desc' : 'asc';
}
// User has not specified a sort. Use default if specified; otherwise use "asc".
else {
foreach ($this->header as $header) {
if (is_array($header) && array_key_exists('sort', $header)) {
return $header['sort'];
}
}
}
return 'asc';
}
/**
Dries Buytaert
committed
* Compose a URL query parameter array to append to table sorting requests.
Dries Buytaert
committed
*
* @return
Dries Buytaert
committed
* A URL query parameter array that consists of all components of the current
* page request except for those pertaining to table sorting.
*
* @see tablesort_get_query_parameters()
Dries Buytaert
committed
*/
Dries Buytaert
committed
protected function getQueryParameters() {
return tablesort_get_query_parameters();
Dries Buytaert
committed
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
}
/**
* Determine the current sort criterion.
*
* @param $headers
* An array of column headers in the format described in theme_table().
* @return
* An associative array describing the criterion, containing the keys:
* - "name": The localized title of the table column.
* - "sql": The name of the database field to sort on.
*/
protected function order() {
$order = isset($_GET['order']) ? $_GET['order'] : '';
foreach ($this->header as $header) {
if (isset($header['data']) && $order == $header['data']) {
return array('name' => $header['data'], 'sql' => isset($header['field']) ? $header['field'] : '');
}
if (isset($header['sort']) && ($header['sort'] == 'asc' || $header['sort'] == 'desc')) {
$default = array('name' => $header['data'], 'sql' => isset($header['field']) ? $header['field'] : '');
}
}
if (isset($default)) {
return $default;
}
else {
// The first column specified is initial 'order by' field unless otherwise specified
if (is_array($this->header[0])) {
$this->header[0] += array('data' => NULL, 'field' => NULL);
return array('name' => $this->header[0]['data'], 'sql' => $this->header[0]['field']);
}
else {
return array('name' => $this->header[0]);
}
}
}
}
/**
* Initialize the table sort context.
*/
function tablesort_init($header) {
$ts = tablesort_get_order($header);
$ts['sort'] = tablesort_get_sort($header);
Dries Buytaert
committed
$ts['query'] = tablesort_get_query_parameters();
/**
* Format a column header.
*
* If the cell in question is the column header for the current sort criterion,
* it gets special formatting. All possible sort criteria become links.
*
* @param $cell
* The cell to format.
* @param $header
* An array of column headers in the format described in theme_table().
* @param $ts
* The current table sort context as returned from tablesort_init().
* @return
* A properly formatted cell, ready for _theme_table_cell().
*/
Dries Buytaert
committed
function tablesort_header($cell, $header, $ts) {
// Special formatting for the currently sorted column header.
if (is_array($cell) && isset($cell['field'])) {
$title = t('sort by @s', array('@s' => $cell['data']));
Dries Buytaert
committed
if ($cell['data'] == $ts['name']) {
$ts['sort'] = (($ts['sort'] == 'asc') ? 'desc' : 'asc');
$cell['class'][] = 'active';
$image = theme('tablesort_indicator', $ts['sort']);
Dries Buytaert
committed
}
else {
// If the user clicks a different header, we want to sort ascending initially.
$ts['sort'] = 'asc';
Dries Buytaert
committed
}
Dries Buytaert
committed
$cell['data'] = l($cell['data'] . $image, $_GET['q'], array('attributes' => array('title' => $title), 'query' => array_merge($ts['query'], array('sort' => $ts['sort'], 'order' => $cell['data'])), 'html' => TRUE));
Dries Buytaert
committed
unset($cell['field'], $cell['sort']);
}
return $cell;
}
/**
* Format a table cell.
*
* Adds a class attribute to all cells in the currently active column.
*
* @param $cell
* The cell to format.
* @param $header
* An array of column headers in the format described in theme_table().
* @param $ts
* The current table sort context as returned from tablesort_init().
* @param $i
* The index of the cell's table column.
* @return
* A properly formatted cell, ready for _theme_table_cell().
*/
Dries Buytaert
committed
function tablesort_cell($cell, $header, $ts, $i) {
Dries Buytaert
committed
if (isset($header[$i]['data']) && $header[$i]['data'] == $ts['name'] && !empty($header[$i]['field'])) {
Dries Buytaert
committed
if (is_array($cell)) {
$cell['class'][] = 'active';
Dries Buytaert
committed
}
else {
$cell = array('data' => $cell, 'class' => array('active'));
Dries Buytaert
committed
}
}
Dries Buytaert
committed
* Compose a URL query parameter array for table sorting links.
Dries Buytaert
committed
* A URL query parameter array that consists of all components of the current
* page request except for those pertaining to table sorting.
Dries Buytaert
committed
function tablesort_get_query_parameters() {
return drupal_get_query_parameters($_REQUEST, array_merge(array('q', 'sort', 'order'), array_keys($_COOKIE)));
/**
* Determine the current sort criterion.
*
* @param $headers
* An array of column headers in the format described in theme_table().
* @return
* An associative array describing the criterion, containing the keys:
* - "name": The localized title of the table column.
* - "sql": The name of the database field to sort on.
*/
function tablesort_get_order($headers) {
$order = isset($_GET['order']) ? $_GET['order'] : '';
if (isset($header['data']) && $order == $header['data']) {
return array('name' => $header['data'], 'sql' => isset($header['field']) ? $header['field'] : '');
if (isset($header['sort']) && ($header['sort'] == 'asc' || $header['sort'] == 'desc')) {
$default = array('name' => $header['data'], 'sql' => isset($header['field']) ? $header['field'] : '');
Angie Byron
committed
// The first column specified is the initial 'order by' field unless otherwise specified.
$first = current($headers);
if (is_array($first)) {
$first += array('data' => NULL, 'field' => NULL);
return array('name' => $first['data'], 'sql' => $first['field']);
Angie Byron
committed
return array('name' => $first, 'sql' => '');
/**
* Determine the current sort direction.
*
* @param $headers
* An array of column headers in the format described in theme_table().
* @return
* The current sort direction ("asc" or "desc").
*/
function tablesort_get_sort($headers) {
if (isset($_GET['sort'])) {
return ($_GET['sort'] == 'desc') ? 'desc' : 'asc';
// User has not specified a sort. Use default if specified; otherwise use "asc".
if (is_array($header) && array_key_exists('sort', $header)) {