History: Tablesorter

This page documents the implementation of the ((doc:Tablesorter|jQuery Tablesorter plugin within Tiki)). Tablesorter was applied more extensively to ((doc:PluginFancytable)) in Tiki 11, and then to the user table at {DIV(type="span" class="inline_syntax")}tiki-adminusers.php{DIV} in Tiki 12.

The method used for ((doc:PluginFancytable)) differs from the one described here - the plugin implementation will be changed to be incorporated into the one described here so that Tablesorter can be more easily applied to other plugin tables.

!!Wishlist
!!!Open
{wishes filtervalue="307" status="o"}

!!!Pending
{wishes filtervalue="307" status="p"}

!!!-Closed
{wishes filtervalue="307" status="c"}
!community members interested in Trackers/Tracker dev.
{TRACKERLIST(trackerId=>2,fields=>39:11,filterfield=>61,filtervalue=>307,showstatus=>y,status=>opc,showlinks=>y)}{TRACKERLIST}

!!Description
Tablesorter is a jQuery plugin used to sort and filter table columns and also apply pagination. Where tables represent rows of data from  a Tiki database table, the pagination, filtering and sorting can be applied on the server side and displayed through Ajax. The benefit of using Tablesorter is (hopefully) quicker filtering, sorting and paginating without needing to refresh the entire page.

Tablesorter is housed on github at [https://github.com/Mottie/tablesorter]. Documentation can be found at [http://mottie.github.io/tablesorter/docs/].

!!Implementation
The jQuery external files for Tablesorter are maintained in {DIV(type="span" class="inline_syntax")}/vendor/jquery/plugins/tablesorter{DIV} through ((Composer)). The additional Tiki-specific code used to generate the needed Tablesorter jQuery code to load into the header is in {DIV(type="span" class="inline_syntax")}/lib/core/Table{DIV}.

Here is a brief outline of how the Tiki portion of the code works when initiated through a static call:
* Call the the {DIV(type="span" class="inline_syntax")}Table_Factory{DIV} class as follows:
+ {CODE(wrap="1" colors="php")}Table_Factory::build('users', $usersettings);{CODE}
*  {DIV(type="span" class="inline_syntax")}Table_Factory{DIV} will call itself to build the settings for the specified table (the users table at tiki-adminusers.php in this example) by calling {DIV(type="span" class="inline_syntax")}Table_Settings_Users{DIV} 
* These table settings are included in a call to the {DIV(type="span" class="inline_syntax")}Table_Manager{DIV} class made by {DIV(type="span" class="inline_syntax")}Table_Factory{DIV}
* The {DIV(type="span" class="inline_syntax")}Table_Manager{DIV} class calls the {DIV(type="span" class="inline_syntax")}Table_Code_Manager{DIV} class to generrate the jQuery code based on the table settings
* The {DIV(type="span" class="inline_syntax")}Table_Code_Manager{DIV} class will call various other the {DIV(type="span" class="inline_syntax")}Table_Code{DIV} classes (such as {DIV(type="span" class="inline_syntax")}Table_Code_Pager{DIV}) to create the various sections of the jQuery code and then put the sections together to create the final complete code
* {DIV(type="span" class="inline_syntax")}Table_Manager{DIV} then loads the complete jQuery code into the header

!!How to Apply to a Table in Tiki
Below are the key steps to implementing Tablesorter for a table in Tiki. The users table at {DIV(type="span" class="inline_syntax")}tiki-adminusers.php{DIV} will be used as an example.
# Add a file to generate the table settings in {DIV(type="span" class="inline_syntax")}/lib/core/Table/Settings{DIV}. See  {DIV(type="span" class="inline_syntax")}/lib/core/Table/Settings/Users.php{DIV} for an example and {DIV(type="span" class="inline_syntax")}/lib/core/Table/Settings/Abstract.php{DIV} for more information on possible settings
** The naming conventions for {DIV(type="span" class="inline_syntax")}/lib/core{DIV} needs to be followed in order for classes to properly autoload:
*** If the new table is the listing of Tiki groups, then the file should be called {DIV(type="span" class="inline_syntax")}/lib/core/Groups.php{DIV} and the class will need to be:
+++ {CODE(wrap="1" colors="html")}class Table_Settings_Groups extends Table_Settings_Abstract{CODE}
+ %%%
# Prepare the smarty template (or HTML)
** Add an id to the table element as follows. In this example, the id "usertable" was added to tiki-adminusers.tpl
++ {CODE(wrap="1" colors="html")}<table id="usertable" class="normal">{CODE}
++ This id is used in the table settings file
** Make sure the table has a {DIV(type="span" class="inline_syntax")}thead{DIV} and {DIV(type="span" class="inline_syntax")}tbody{DIV} element
** Some parts of the page may need to be hidden, for example filtering fields and pagination controls that will be replaced with the Tablesorter functionality
** Any  {DIV(type="span" class="inline_syntax")}self_link{DIV} smarty functions used in the header (previous method of sorting columns) will automatically eliminated through jQuery so no changes to the smarty template are needed for this
** The reset sort and reset filter buttons are also added through jQuery, so no changes to the smarty template are needed for this
+ %%%
# Prepare the php file where the data for the table is pulled from the database - {DIV(type="span" class="inline_syntax")}tiki-adminusers.php{DIV} in this example
+ This file will be called twice when first invoked. The first time, before the Tablesorter code is loaded into the header, we need to skip the call to the database and invoke {DIV(type="span" class="inline_syntax")}Table_Factory{DIV} instead (although the total records in the database is needed for this call). Once the jQuery is loaded into the header, the file will be called again through Ajax - this time the database call should be made. See below for an example:
+ {CODE(wrap="1" colors="php")}/////////////this part was added for Tablesorter///////////////////////////////////
//this variable means that Tablesorter will be applied
$tsOn = $prefs['disableJavascript'] == 'n' && $prefs['feature_jquery_tablesorter'] == 'y' ? true : false;
//this should be a smarty variable in case some parts of the smarty template need to be hidded or altered when applying Tablesorter
$smarty->assign('ts', $tsOn);
//if $_REQUEST['tsAjax'] is true, that means this is an ajax call from Tablesorter
$tsAjax = isset($_REQUEST['tsAjax']) && $_REQUEST['tsAjax'] ? true : false;

//do the database call if this is the Tablesorter Ajax call or if Tablesorter won't be used
if ($tsAjax || !$tsOn) {
///////////////end of first part added for Tablesorter////////////////////////////////////
	$users = $userlib->get_users(
		$offset,
		$numrows,
		$sort_mode,
		$find,
		$initial,
		true,
		$filterGroup,
		$filterEmail,
		!empty($_REQUEST['filterEmailNotConfirmed']),
		!empty($_REQUEST['filterNotValidated']),
		!empty($_REQUEST['filterNeverLoggedIn'])
	);
/////////////this part was added for Tablesorter///////////////////////////////////
//if Tablesorter will be used, invoke it before getting rows from the database
} elseif($tsOn) {
    //the total number of rows is needed for the Tablesorter pager to work properly
	$users['cant'] = $userlib->count_users('');
	$users['data'] = $users['cant'] > 0 ? true : false;
	Table_Factory::build('users', array('total' => $users['cant']));
}
///////////////end of second part added for Tablesorter////////////////////////////////////
{CODE}