View source for Adding sortable columns to a table in a component

==Step 3: The Template==
Now you need to add some elements to the component layout file.  The table must be included in a form.  This might already be the case as, for example, you might already have implemented pagination or filtering on the table.  But if the table is not yet in a form then now is the time to wrap it in <form> and </form> tags.  The reason that a form is required is that the sortable columns rely on a bit of JavaScript that will submit the form with sort parameters added.  Naturally, this will involve a page load, so if you would prefer an [[AJAX]]-based solution, then this procedure is not for you.

The form tags will look something like this:

<source lang="php">
<form id="adminForm" method="post" name="adminForm">

.... table goes here ....

</form>
</source>
Notice that the form name must be "adminForm". In some special cases you might need to add the action attribute (e.g. action="<?php echo JRoute::_( 'index.php' );?>"), but usually this should not be required, when it's not there the form will just be submitted to the current documents address, i.e. the same page, which is usually the correct behavior.

You also need to add a couple of hidden fields to the form. They can be placed anywhere between the <form> and </form> tags, but generally they are placed just before the closing tag, like this:
<source lang="php">
<form id="adminForm" method="post" name="adminForm">

	.... table goes here ....

	<input type="hidden" name="filter_order" value="<?php echo $this->sortColumn; ?>" />
	<input type="hidden" name="filter_order_Dir" value="<?php echo $this->sortDirection; ?>" />
</form>
</source>

Now look at the table itself. You might have a table with static headings already, looking vaguely like this:
<source lang="php">
<tr>
	<th>Name</th>
	<th>Description</th>
</tr>
</source>
You need to replace the static column names with calls to the Joomla [[JHTML]] static class, so that your code will look something like this:
<source lang="php">
<tr>
	<th><?php echo JHTML::_( 'grid.sort', 'Name', 'DbNameColumn', $this->sortDirection, $this->sortColumn); ?></th>
	<th><?php echo JHTML::_( 'grid.sort', 'Description', 'DbDescriptionColumn', $this->sortDirection, $this->sortColumn); ?></th>
</tr>
</source>
You will definitely need to adapt this code to your specific requirements. The arguments to the [[JHTML]] call are as follows:
# Must be 'grid.sort' so that [[JHTML]] will insert the correct behaviour for a sortable column.
# This is the name of the column that your visitors will actually see. You need to change this for your particular table columns.
# This is the name of the corresponding database field (column) that is to be sorted on.  This will be passed to the model, most likely so it can be added to an "ORDER BY" clause in the SQL query statement (whatever is here needs to match one of the column names specified in the whitelist, including any possible prefixes).
# Must be exactly as shown here. It is the current order direction (ascending or descending) and comes from the view (see later).
# Must be exactly as shown here. It is the name of the column that the table is currently sorted on and comes from the view (see later).

In short, you need to amend the second and third arguments to each [[JHTML]] call appropriately.

Finally, if your sortable table is going to be in the front-end of your site, then you need to add a little snippet of JavaScript to the layout.  Alternatively, you can add it to the view code (using [[JDocument/addScriptDeclaration|JDocument->addScriptDeclaration]]) if you would rather keep your JavaScript code in the HTML <head> section.
<source lang="javascript">
<script language="javascript" type="text/javascript">
function tableOrdering( order, dir, task )
{
	var form = document.adminForm;

	form.filter_order.value = order;
	form.filter_order_Dir.value = dir;
	document.adminForm.submit( task );
}
</script>
</source>
You don't need to add this code if your sortable table is in the Administrator as this code is loaded for you automatically anyway.

This completes the changes you need to make to the layout. [[JHTML]] [[JHTMLGrid|grid.sort]] will now add a call to the ''tableOrdering'' function so that ''tableOrdering'' will be called whenever the user clicks on the column header.  ''tableOrdering'' puts the name of the column that was clicked, and the sort direction, into the hidden form fields and submits the form; the changed values will get picked up by the populateState method, and then retrieved by your model via the list.ordering/list.dirc.