Adding sortable columns to a table in a component - Revision history

Munchkin: /* Step 1: The Model */ Joomla 3 compabitibility: escape(...) instead of getEscaped(...)

2013-06-03T20:18:19Z

‎Step 1: The Model: Joomla 3 compabitibility: escape(...) instead of getEscaped(...)

Munchkin: Adds again the removed version hint

2013-06-02T15:39:51Z

Adds again the removed version hint

Munchkin: adds missing filter_fields configuration

2013-06-02T15:29:45Z

adds missing filter_fields configuration

Munchkin: Adapt to Joomla! 2.5 (mainly filter_order -> list.ordering)

2013-06-02T14:58:34Z

Adapt to Joomla! 2.5 (mainly filter_order -> list.ordering)

Wilsonge: /* See also */ Removing 1.5 link

2013-05-28T12:27:34Z

‎See also: Removing 1.5 link

Wilsonge at 12:26, 28 May 2013

2013-05-28T12:26:14Z

Show changes

Wilsonge: Wilsonge moved page Adding sortable columns to a table in a component to J1.5:Adding sortable columns to a table in a component: Move to 1.5 Namespace

2013-05-28T12:24:59Z

Wilsonge moved page Adding sortable columns to a table in a component to J1.5:Adding sortable columns to a table in a component: Move to 1.5 Namespace

New page

#REDIRECT [[J1.5:Adding sortable columns to a table in a component]]

@@ Line 42: / Line 42: @@
 	// ...
-	$query->order($db->getEscaped($this->getState('list.ordering', 'default_sort_column')).' '.
+	$query->order($db->escape($this->getState('list.ordering', 'default_sort_column')).' '.
-		$db->getEscaped($this->getState('list.direction', 'ASC')));
+		$db->escape($this->getState('list.direction', 'ASC')));
 	return $query;

← Older revision		Revision as of 15:39, 2 June 2013
Line 1:		Line 1:
		+	{{version/tutor\|2.5,3.x}}
	Given that you have a table of data already in your component, how do you make some, or all, of the table columns sortable, like many of them are in the Joomla Administrator? It's not particularly hard to do, but there are several steps required and details you need to be aware of so everything fits together properly. There are variations on the procedure given here and once you are confident that you understand how it all works you should feel free to explore other possibilities that may suit your purposes better.		Given that you have a table of data already in your component, how do you make some, or all, of the table columns sortable, like many of them are in the Joomla Administrator? It's not particularly hard to do, but there are several steps required and details you need to be aware of so everything fits together properly. There are variations on the procedure given here and once you are confident that you understand how it all works you should feel free to explore other possibilities that may suit your purposes better.

@@ Line 12: / Line 12: @@
+}
 </source>
 In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the HTML table. Most often this is the [[JModelList::getListQuery|getListQuery()]] method, but might not be.
@@ Line 93: / Line 108: @@
 # 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.
+# 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).

@@ Line 1: / Line 1: @@
 Given that you have a table of data already in your component, how do you make some, or all, of the table columns sortable, like many of them are in the Joomla Administrator?  It's not particularly hard to do, but there are several steps required and details you need to be aware of so everything fits together properly.  There are variations on the procedure given here and once you are confident that you understand how it all works you should feel free to explore other possibilities that may suit your purposes better.
-This procedure assumes that your component is structured according to the [[Model-View-Controller]] (MVC) design pattern.  The general idea behind the procedure will still be applicable to non-MVC components if you apply a bit of imagination!
+This procedure assumes that your component is structured according to the [[Model-View-Controller]] (MVC) design pattern. The general idea behind the procedure will still be applicable to non-MVC components if you apply a bit of imagination!
 ==Step 1: The Model==
-'''Note: Since {{JVer|2.5}} the populateState of JModelList does pagination and ordering via it's own populateState() and you can skip this part.  If you need other states than the parent provides just do a parent::populateState(); in your specific one (and make sure "filter_order" is in your filter_fields config)'''
+The first thing you need to do is to populate the order state of your model. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the second parameter to DESC if you wish the default order direction to be descending. Calling the parents populateState method will make sure that the State object is filled and accessible to all of the code that might need it.
-−
-The first thing is to add the filter_order and filter_order_Dir request populateState() method of your model. Change 'default_column_name' to the name of the column you want to use as the default sort, and change the filter order direction if you wish  Adding this information to the  State object here insures it's accessible to all of the code that might need it.
 <source lang="php">
-public function populateState() {
+protected function populateState($ordering = null, $direction = null) {
-	$filter_order = JRequest::getCmd('filter_order');
+	parent::populateState('default_column_name', 'ASC');
-	$filter_order_Dir = JRequest::getCmd('filter_order_Dir');
-−
-	$this->setState('filter_order', $filter_order);
-	$this->setState('filter_order_Dir', $filter_order_Dir);
+}
 </source>
-In the model which generates the data that will form the table, you need to make a change to the method which builds the database query that will be used to populate the HTML table.  Most often this is the [[JModelList::getListQuery|getListQuery()]] method, but might not be.
+The model could pull data in from anywhere; it doesn't have to be a database, but in the vast majority of cases the model will be using the Joomla database API to submit SQL queries to a database. Assuming that to be the case, you need to adjust the query so that the sort parameters are taken into account.
-−
-The model could pull data in from anywhere; it doesn't have to be a database, but in the vast majority of cases the model will be using the Joomla database API to submit SQL queries to a database.   Assuming that to be the case, you need to adjust the query so that the sort parameters are taken into account.
 This information gets called by whatever function builds the ORDER BY clause, typically a private function like this:
@@ Line 34: / Line 26: @@
 	// ...
-	$query->order($db->getEscaped($this->getState('filter_order', 'default_sort_column')) . ' ' . $db->getEscaped($this->getState('filter_order_Dir', 'ASC')));
+	$query->order($db->getEscaped($this->getState('list.ordering', 'default_sort_column')).' '.
 	return $query;
@@ Line 51: / Line 44: @@
 	$state = $this->get('State');
-	$this->sortDirection = $state->get('filter_order_Dir');
+	$this->sortDirection = $state->get('list.direction');
-	$this->sortColumn = $state->get('filter_order');
+	$this->sortColumn = $state->get('list.ordering');
 	parent::display($tpl);
+}
 </source>
@@ Line 65: / Line 57: @@
 <source lang="php">
-<form id="adminForm" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">
+<form id="adminForm" method="post" name="adminForm">
 .... table goes here ....
@@ Line 71: / Line 63: @@
 </form>
 </source>
-Notice that the form name must be "adminForm".  You may need to adjust the action URL in some cases.
+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:
+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" action="<?php echo JRoute::_( 'index.php' );?>" method="post" name="adminForm">
+<form id="adminForm" method="post" name="adminForm">
-.... table goes here ....
+	.... table goes here ....
-<input type="hidden" name="filter_order" value="<?php echo $this->sortColumn; ?>" />
+	<input type="hidden" name="filter_order" value="<?php echo $this->sortColumn; ?>" />
-<input type="hidden" name="filter_order_Dir" value="<?php echo $this->sortDirection; ?>" />
+	<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:
+Now look at the table itself. You might have a table with static headings already, looking vaguely like this:
 <source lang="php">
 <tr>
@@ Line 98: / Line 90: @@
 </tr>
 </source>
-You will definitely need to adapt this code to your specific requirements.  The arguments to the [[JHTML]] call are as follows:
+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 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.
-# 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 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).
+# 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.
@@ Line 122: / Line 114: @@
 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.  In the next step you will see how the model picks up those field values and amends the database query appropriately.
+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.
 ==Step 4: Styling the result==

@@ Line 142: / Line 142: @@
 ==See also==
 * [[Developing a Model-View-Controller Component]]
 [[Category:Component Development]]
 [[Category:Tutorials]]