theme_table and tablesort_sql

How's this?

Committed to 7.x, with the minor adjustment of wrapping at 80 characters. Thanks!

Moving down to 6.x. Here's the patch I committed. There are other lines in that PHPDoc that should be shortened too but I wanted to protect the kittens. :)

I don't think this is clear at all.

+ *   - "sort": A default sort order for this column ("asc" or "desc"). This depends
+ *     on tablesort_sql() appending sort data when forming queries before being
+ *     passed to theme_table().

Sort "data"? Appending "sort data" to what? This depends on tablesort_sql() appending? That function does not do any appending! The query is passed to theme_table()? It should not be passed there.... Ooooh. I don't think any of the details of this sentence are clear, and helpful, except the reference to the function, with which developers might be able to run with. I think we should work on improving this, and I am not going to commit this as-is. A suggestion which you can pick up and improve.

This will only work if the output of tablesort_sql() is appended to the SQL query which selects data for this table.

Or something.

Gábor, I wish I could have been more clear.

/**
 * Return a themed table.
 *
 * @param $header
 *   An array containing the table headers. Each element of the array can be
 *   either a localized string or an associative array with the following keys:
 *   - "data": The localized title of the table column.
 *   - "field": The database field represented in the table column (required if
 *     user is to be able to sort on this column).
 *   - "sort": A default sort order for this column ("asc" or "desc"). This depends
 *     on tablesort_sql() appending sort data when forming queries before being
 *     passed to theme_table().
 * ..snip..
 */

Sort "data"? Appending "sort data" to what?

The $header parameter since it's an element of "sort". The rest isn't as clear as it could have been looking at it again. I did a quick scan and that description came out. :)

Well, we should somehow express that the original SQL query needs to be appended with the output of tablesort_sql() and $header should be passed into that as well. $header is not modified at all in that function, so there is nothing appended to $header as you describe.

Huh. For some reason this made perfect sense when I had a skull-splitting migraine the other night. ;) But I agree, it could use some clarification.

Rolled back in D7, but I agree this needs fixing. Care to have another stab?

just spent an hour trying to figure out how to get my headers to sort... knew it could be done but the extra step was no where in any documentation I could find.

Patch attached which adds the work Gabor used in #5. Read it over and it seems to read pretty clearly.

#10: tablesort_doc.patch queued for re-testing.

Lets try this

I'm not totally sure here, but it seems like the behavior of 'sort' => 'asc' is not as I understood it.

I assumed that you could set a default sort order for each column, so the first time you click a column header it would sort either as asc or desc depending on the parameter.

What seems to happen is that this is the default sort column and order for the table when is first rendered and NO sort column is specified. It *seems* like adding a 'sort' parameter to the $header_row array only works as expected if I specify one and only one field with a 'sort' parameter.

This is not what I expected, but seems to make sense... although it would be nice to be able to specify which way each column sorts when first clicked.

grammar nitpick:
" query which selects data for this table." which => that

Also, I think maybe something should be added to the description part of this documentation to address the confusion in #16.

This issue has been superceded by
#839634: Fix up documentation for table sorting

Table sort by header Drupal 9
if(empty($default) && isset($header['sort']) && ($header['sort'] == 'asc' || $header['sort'] == 'desc'))
{
$default = $header;
}

$header = [

'field_name' => [
'data' => $this->t('Name'),
'field' => 'field_name',
],
];

$build['tablesort_table'] = [
'#theme' => 'table',
'#header' => $header,
'#rows' => $data,
];