Notes

  • In v2.24.4,
    • Added a getParam (get URL parameter) & a removeParam utility function to help deal with parameters in the URL hash. See the "Functions" section below for more details.
    • Alex Weissman has also provided code for a custom hash transformation in this gist; this code sets hash parameters that include the table id & named columns, e.g. &filter[table0][first_name]=foobar.
  • In v2.24.0, lots of changes were made:
    • Removed sort2Hash_useHeaderText and sort2Hash_processHeaderText options.
    • Added sort2Hash_headerTextAttr option to replace the above two options.
    • Added sort2Hash_encodeHash, sort2Hash_decodeHash and sort2Hash_cleanHash options to allow custom value to hash processing.
    • This widget now works with the pager & filter, so the hash now includes pager current page, pager page size and current filters in the hash.
    • Lots of internal tweaks.
  • Added v2.22.4. Instead of using the saveSort widget, this widget updates the hash tag to allow saving & sharing a sort applied to a tablesorter table.
  • Sort the tables in the demo below. Notice the changes made to the location hash, then reload the page to have the hash applied to the tables.
  • This widget requires jQuery version 1.7+.
  • This widget does NOT work with tablesorter v2.0.5.

Options

Sort2Hash widget default options (added inside of tablesorter widgetOptions)

TIP! Click on the link in the option column to reveal full details (or toggle|show|hide all) or double click to update the browser location.
OptionDefaultDescription
sort2hash_hash '#' The hash should always be there. This option was added to allow setting extra hash parameters and/or hashbang or whatever.
',' Change the hash separator using this option. There are some limitations.

In the location hash, the sort parameters are added as &tableID=column,direction, ... ,column,direction (no spaces). This option allows changing the column-direction separator, a comma by default, into the chosen separator.

*NOTE* Do not set this option to use a hash (#), ampersand (&) or equal sign (=) as it will interfere with how the hash parameters are set up.

null Set an ID here to override the table id attribute.

In the location hash, the sort parameters are added as &tableID=column,direction, ... ,column,direction (no spaces). The tableID is set by this option.

This option setting is prioritized over the actual table ID attribute. If neither are set, the tableID will be set as the table's zero-based index on the page.

sort2Hash_tableID > table.id attribute > table index
'data-header' Data attribute on header cell containing alternate column identifier added to location hash.

This option replaces both sort2Hash_useHeaderText and sort2Hash_processHeaderText options.

The contents of this attribute will be used in the hash to identify a sorted column.

Use the header attribute as follows:

<th data-header="first">First Name</th>
[ 0, 1 ] Set the direction text shown in the URL.

Only the first two values will be used from this array. The first value is assigned to ascending sorts and the second is assigned to descending sorts.

Use the option as follows:

sort2Hash_directionText : [ 'asc', 'desc' ]
*NOTE* When converting the hash into a value, if the direction hash does not match the second value ('desc' in the example above), it will fallback to an ascending sort no matter what text in contained within the first value.
sort2Hash_overrideSaveSort false if true, the hash sort will override any stored sort (saveSort widget).
null Add a function to create a custom hash (v2.24.4).

The following example is a duplicate of the internal code that encodes the hash. Adapt to fit your needs:
sort2Hash_encodeHash : function( config, tableId, component, value, rawValue ) {
  // config = table.config settings
  // tableId = processed table ID
  // component: 'sort', 'page', 'size' or 'filter'
  // value = string value that has encodeURIComponent applied
  // rawValue = value ( array or number )
  // return false to let the widget encode the string
  return '&' + component + '[' + tableId + ']=' + value;
}
Return a string to add to the window.location.hash directly.

If this function returns false, then the internal code will encode the hash for that component. This was done in case only one parameter needs special handling:

sort2Hash_encodeHash : function( config, tableId, component, value, rawValue ) {
  // only the filter gets special handling
  if ( component === 'filter' ) {
    // if working with rawValue, make sure to use
    // encodeURIComponent on the results
    var newValue = encodeURIComponent( rawValue.join( '--' ) );
    return tableId + 'filter=' + newValue;
  }
  return false;
}
null Add a function to process a custom hash (v2.24.4).

The following example is a duplicate of the internal code that decodes the hash. Adapt to fit your needs:
sort2Hash_decodeHash : function( config, tableId, component ) {
  // config = table.config settings
  // tableId = processed table ID
  // component: 'sort', 'page', 'size' or 'filter'
  // return false to let the widget decode the hash

  // $.tablesorter.sort2Hash.getParam( parameter, url ); function added in v2.24.4
  // parameter = desired parameter to extract
  // url (optional) = hash or href string to extract the parameter value from
  return $.tablesorter.sort2Hash.getParam( component + '[' + tableId + ']' ) || '';
}
Return the component value or an empty string.

If this function returns false, then the internal code will attempt to decode the hash for that component. This was done in case only one parameter needs special handling:

sort2Hash_decodeHash : function( config, tableId, component ) {
  // only the filter gets special handling
  if ( component === 'filter' ) {
    return $.tablesorter.sort2Hash.getParam( tableId + 'filter' ) || '';
  }
  return false;
}
null Add a function to remove a custom hash (v2.24.4).

The following example is a duplicate of the internal code that removes unused values in the hash. Adapt to fit your needs:
sort2Hash_cleanHash : function( config, tableId, component, hash ) {
  // removeParam function added v2.24.4
  return $.tablesorter.sort2Hash.removeParam( component + '[' + tableId + ']' );
}
Return a string of the remaining components or an empty string.

If this function returns false, then the internal code will attempt to clean the hash for that component. This was done in case only one parameter needs special handling:

sort2Hash_cleanHash : function( config, tableId, component, hash ) {
  // config = table.config settings
  // tableId = processed table ID
  // component: 'sort', 'page', 'size' or 'filter'
  // return false to let the widget decode the hash

  if ( component === 'filter' ) {
    // removeParam function added v2.24.4
    return $.tablesorter.sort2Hash.removeParam( tableId + 'filter' );
    /* ORIGINAL METHOD, use if the "getParam" function doesn't work on your custom parameter
    var index,
      result = [],
      // regular expression to match the component & value
      regex = new RegExp( tableId + 'filter=([^&]*)' );
      // split hash into component parts
      parts = ( hash || '' ).slice(1).split( '&' ),
      len = parts.length;
    // cycle through each component part
    for ( index = 0; index < len; index++ ) {
      // if the component doesn't match the regular expression...
      if ( !regex.test( parts[ index ] ) ) {
        // then save it
        result.push( parts[ index ] );
      }
    }
    // if we still have something left, join the components back together
    // and return it so the next component can be processed
    // we don't update the window.location.hash, or the page jumps to the top!
    return result.length ? c.widgetOptions.sort2Hash_hash + result.join( '&' ) : '';
    */
  }
  return false;
}
Deprecated/Removed Options
false This option has been removed in v2.24.0! It has been replaced by sort2Hash_headerTextAttr.

If true, text from the header is used instead of a zero-based column index.

Please be aware that if the column text contains spaces or special characters, they will be encoded in the URL. So, "First £$€¤¥¢ Name" will become "First%20%C2%A3$%E2%82%AC%C2%A4%C2%A5%C2%A2%20Name". This would make the hash very difficult to read.

Further processing of this header cell text can be done using the sort2Hash_processHeaderText function.

null This option has been removed in v2.24.0! It has been replaced by sort2Hash_headerTextAttr.

If the sort2Hash_useHeaderText option is true, a function here will further process the header cell text.

Use this function to perform any processing on the header cell text, as desired.

At this point, the header cell text has not been encoded.

Here is one example:

sort2Hash_processHeaderText : function( text, config, columnIndex ) {
  // remove all non-alphanumeric characters (including spaces)
  return text.replace( /[^a-z0-9]/gi, '' );
}
Another example:
sort2Hash_processHeaderText : function( text, config, columnIndex ) {
  // completely custom text to use for the hash
  // this method assumes that the table layout is constant
  // (i.e. columns are not added, removed or rearranged)
  return [ 'first', 'last', 'age', 'total', 'disc', 'date' ][ columnIndex ];
}

Functions

Sort2Hash utility functions (added to $.tablesorter.sort2Hash)

TIP! Click on the link in the function column to reveal full details (or toggle|show|hide all) or double click to update the browser location.
FunctionDescription
Get URL Parameter (getParam) function

This function will extract the value of the name passed to the function. Use it as follows:

// $.tablesorter.sort2Hash.getParam( name, hash );
// name = parameter name (key)
// hash = (optional) if undefined, it will get the string value from window.location.hash
var hash = '&sort[table-users][user_name]=asc&page[table-users]=1&size[table-users]=10&filter[table-users][user_name]=ad',
	result = $.tablesorter.sort2Hash.getParam( 'filter[table-users][user_name]', hash );
// result = "ad";
Remove parameter from hash

This function will remove the key & value from the passed hash. Use it as follows:

// $.tablesorter.sort2Hash.removeParam( name, hash );
// name = parameter name (key)
// hash = (optional) if undefined, it will get the string value from window.location.hash
var hash = '&sort[table-users][user_name]=asc&page[table-users]=1&size[table-users]=10&filter[table-users][user_name]=ad',
	result = $.tablesorter.sort2Hash.removeParam( 'filter[table-users][user_name]', hash );
// result = "&sort[table-users][user_name]=asc&page[table-users]=1&size[table-users]=10";
*NOTE* This function does not update window.location.hash.

Demo

Basic Usage

First Name Last Name Age Total Discount Date
PeterParker28$9.9920%Jul 6, 2006 8:14 AM
JohnHood33$19.9925%Dec 10, 2002 5:14 AM
ClarkKent18$15.8944%Jan 12, 2003 11:14 AM
BruceAlmighty45$153.1944%Jan 18, 2001 9:12 AM
BruceEvans22$13.1911%Jan 18, 2007 9:12 AM
This table shows up as "table4" because there is no ID assigned, and it is the fifth table (zero-based index) on the page. The first table is in the "Options" section. The second is actually the stickyheader table for "Options". The third & forth (sticky header) are in the "Functions" section.

Data Header (Using symbols for headers)

First Name (^) Last Name (&) Age (#) Total ($) Discount (%) Date (*)
PeterParker28$9.9920%Jul 6, 2006 8:14 AM
JohnHood33$19.9925%Dec 10, 2002 5:14 AM
ClarkKent18$15.8944%Jan 12, 2003 11:14 AM
BruceAlmighty45$153.1944%Jan 18, 2001 9:12 AM
BruceEvans22$13.1911%Jan 18, 2007 9:12 AM

Pager (page & size)

First Prev Next Last
Name Major Sex English Japanese Calculus Geometry
Name Major Sex English Japanese Calculus Geometry
Student01Languagesmale80707580
Student02Mathematicsmale908810090
Student03Languagesfemale85958085
Student04Languagesmale6055100100
Student05Languagesfemale68809580
Student06Mathematicsmale1009910090
Student07Mathematicsmale85689090
Student08Languagesmale100909085
Student09Mathematicsmale80506575
Student10Languagesmale8510010090
Student11Languagesmale8685100100
Student12Mathematicsfemale100757085
Student13Languagesfemale1008010090
Student14Languagesfemale50455590
Student15Languagesmale953510090
Student16Languagesfemale100503070
Student17Languagesfemale801005565
Student18Mathematicsmale30495575
Student19Languagesmale68908870
Student20Mathematicsmale40454080
Student21Languagesmale5045100100
Student22Mathematicsmale1009910090
Student23Mathematicsmale8277079
Student24Languagesfemale100911382
Student25Mathematicsmale22968253
Student26Languagesfemale37295659
Student27Mathematicsmale86826923
Student28Languagesfemale4425431
Student29Mathematicsmale77472238
Student30Languagesfemale19352310
Student31Mathematicsmale90271750
Student32Languagesfemale60753338
Student33Mathematicsmale4313715
Student34Languagesfemale77978144
Student35Mathematicsmale5815195
Student36Languagesfemale70617094
Student37Mathematicsmale6036184
Student38Languagesfemale6339011
Student39Mathematicsmale50463238
Student40Languagesfemale5175253
Student41Mathematicsmale43342878
Student42Languagesfemale11896095
Student43Mathematicsmale48921888
Student44Languagesfemale8225973
Student45Mathematicsmale91733739
Student46Languagesfemale481210
Student47Mathematicsmale8910611
Student48Languagesfemale90322118
Student49Mathematicsmale42494972
Student50Languagesfemale56376754

Javascript


	

HTML