[DX] Allow sorting in all tables rendered via 'theme_table()'

[klonos]

Describe your issue or idea

While working on #3316 I have tried enabling sorting in the table that lists the fields. I have never done this, so I researched and found some articles around the internet that add sorting functionality to tables. Some examples:

• Drupal 7 - Creating Drupal style tables with paging, sorting and sticky headers
• Drupal 7 - Creating Drupal style tables with paging, sorting and filter.
• theme_table() isn't respecting sortable fieldname
• How to disable sortable headers in Admin theme tables
• A Drupal 7 table with sortable headers and pager

Steps to reproduce (if reporting a bug)

1. Taking the table in /admin/reports/fields as an example, try to add 'field' => 'something' to each header cell. You can test the sandbox from this dummy PR: TEST/DUMMY PR - DO NOT REVIEW OR MERGE backdrop#2325

Actual behavior (if reporting a bug)

Although adding 'field' => 'something' to the header cells causes the table headers to be rendered as sortable, the actual sorting itself does not work: the page refreshes, the ascending/descending sorting indicator and header color changes, but no sorting happens.

Expected behavior (if reporting a bug)

As a new Backdrop dev, I would expect that sorting should "magically" work in theme_table(), simply by adding 'field' => 'something' to the header cells, no matter what the source of the table cells is (db query, or simple arrays passed).

[klonos]

...perhaps I am just a total newbie and I've got this whole thing wrong. Perhaps there is a way to achieve this that I am not aware of. Any feedback/ideas/pointers welcomed.

I was just about to post an issue about this! 😄

theme_table() says:

The database field represented in the table column (required if user is to be able to sort on this column).

(emphasis mine)

That's always indicated to me that you can't sort arbitrary tables, they have to have data pulled from the database in order to be sortable.

But today, when researching this myself for something I'm working on, I found this (tablesort.inc):

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.

(emphasis mine)

So that gave me some hope.

In the end, I found some code in layout_block_list() which allowed me to create my own arbitrary, sortable table:

$header = array(
  array('data' => t('First'), 'field' => 'first'),
  array('data' => t('Last'), 'field' => 'last', 'sort' => 'asc'),
);

$rows = array(
  array('first' => 'Peter', 'last' => 'Anderson'),
  array('first' => 'Greg', 'last' => 'Netsas'),
  array('first' => 'Jen', 'last' => 'Lampton'),
  array('first' => 'Tim', 'last' => 'Erickson'),
);

$ts = tablesort_init($header);
backdrop_sort($rows, array($ts['sql'] => SORT_STRING), ($ts['sort'] == 'asc') ? SORT_ASC : SORT_DESC);

$form['table'] = array(
  '#theme' => 'table',
  '#header' => $header,
  '#rows' => $rows,
);

Things to note:

• field in the table header is required (as we already suspected)
• Those same field names are required to be added as array keys in $rows (though this doesn't seem to be documented)
• It seems like the $ts and backdrop_sort() lines should be automated somehow (i.e. we shouldn't need to add these manually ourselves)...

So looks like there are some documentation changes needed to sort (😄) all this out and make it clearer.