• In v2.31.1, added math_textAttr.
• In v2.28.0
  • Fix documentation and processing of math_prefix and math_suffix options. See issue #1305.
  • Remove math_prefix content prior to parsing table cell values.
  • Added "Methods" section & more mask examples.
• In v2.27.0
  • Added check for data-math-target attribute which allows you to target an element inside the table cell. See the Attribute Settings > Targeting cell content section below.
  • Added a math_debug option which when true, enables debug logging of only the math widget.
  • The math widget no longer uses "update" after recalculating cell values. Instead it uses "updateCache" to remove the need to resort and update the other widgets.
• In v2.25.0
  • math_rowFilter can now be overridden by the row's data-math-filter attribute.
  • Lots of optimizations!
    • On initialization, only tbody cells with a rowspan or colspan are now processed and only get a "data-column" set if the internal cellIndex doesn't match the calculated cell index.
    • Initial calculation is no longer performed three times in a row
    • The cache is now only updated if cell content inside of a sortable tbody was modified.
    • These changes should improve performance and reduce lag after initialization and updating the table (see issue #1048.

• This widget will only work in tablesorter version 2.16+ and jQuery version 1.7+.
• It adds basic math capabilities. A full list of default formulas is listed in the "Attribute Settings" section.
• Add your own custom formulas which manipulating an array of values gathered from the table by row, column or a column block (above).
• This is by no means a comprehensive widget that performs like a spreadsheet, but you can customize the data gathering "type" and available "formula", as desired.
• The widget will update the calculations based on filtered rows, and will update if any data within the table changes (using update events).
• This widget is not optimized for very large tables, for two reasons:
  • On initialization, it cycles through every table row, calculates the column index , and adds a data-column attribute (Fixed in v2.25.0).
  • It uses the update method whenever it recalculates values to make the results sortable. This occurs when any of the update methods are used and after the table is filtered.
• When setting tablesorter's debug option to true, this widget will output each {type}-{formula} value found, the array of numbers used and the result.

Math widget default options (added inside of tablesorter widgetOptions)

// Include the "data-" prefix in the option
math_textAttr : 'data-math-value'

<td data-math-value="1000">1.0k</td>

// column index(es) to ignore
math_ignore : [0,1]

math_none : 'N/A',
math_complete : function($cell, wo, result, value, arry) {
  // don't include currency symbol when no result is available
  return value === wo.math_none ? value : '$ ' + value;
}

<th data-math="all-sum" data-math-mask="##0.00">all-sum</th>

// complete executed after each function
math_complete : function($cell, wo, result, value, arry) {
    return '$ ' + result + $cell.attr('data-suffix');
}

math_complete : function($cell, wo, result, value, arry) {
    var percent = Math.round( value * 1e4 ) / 100; // percent with two decimal places
    return $.tablesorter.formatMask( wo.math_mask, percent ) + ' %';
}

// complete executed after each function
math_completed : function(config) {
    var total = config.$table.find('[data-math="all-sum"]:last').text();
    console.log(total);
}

// this option will accept any of the jQuery filter types (i.e. selector, function or elements)
// for example, here is the functional equivalent
// math_rowFilter : function(index, element) { return $(element).is(':visible:not(.filtered)'); }
math_rowFilter : ':visible:not(.filtered)'

<td data-math-filter=":visible" data-math="all-sum">...</td>

Recalculate

Recalculate the values of all math cells within the table using the following method:

$('table').trigger('recalculate');

The triggered 'recalculate' method can be renamed by modifying the math_event option.

This method is automatically called:

• Tablesorter initialization.
• After any call to a tablesorter method which updates the internal cache (e.g. "update", "updateCell", etc). The math widget listens for the updateComplete event, which occurs after the internal cache has completed updating, before recalculating values.
• After a "filterReset".
• And after a "filterEnd" event, or a "pagerComplete" event (if the pager is being used), but not both!

<td data-math="{type}-{formula}"></td>

{type} (data gathering)

• row - gather the table cell values from the same row as the data-math attribute.
• above - gather the table cell values from the same column as the data-math attribute, but stop when the first table cell is reached, or when another cell with a data-attribute with an "above" type is reached; see the first table demo below to see why this is useful.
• below (v2.24.0) - gather the table cell values from the same column as the data-math attribute, but stop when the last table cell is reached, or when another cell with a data-attribute with a "below" type is reached.
• col - gather the table cell values from the same column as the data-math attribute.
• all - gather all table cell values with a data-math attribute that start with "all".

{formula} (defaults)

• count - returns the count (length) of the data set.
• sum - returns the sum of all values in the data set.
• max - returns the maximum value in the data set.
• min - returns the minimum values in the data set.
• mean - returns the mean (average) of all values in the data set; it uses the sum formula in part of the calculation.
• median - returns the median (middle value) of the data set.
• mode - returns an array of the mode(s) (most frequent value or values) in the data set; an array is always returned, even if only one mode exists (see the second demo below).
• range - returns the range (highest minus lowest value) of the data set.
• varp - returns the variance of the data set (population).
• vars - returns the variance of the data set (sample).
• stdevp - returns the standard deviation of the data set (population).
• stdevs - returns the standard deviation of the data set (sample).
• custom (not a default)
  • Custom formulas can have any name
  • Return your result after making whatever calculation from the array of data passed to the formula
  • For example:

    // adding a custom equation... named "product"
    // access from data-math="row-product" (or "above-product", "below-product" or "col-product")
    // config parameter added v2.24.0 to allow access to table settings
    $.tablesorter.equations['product'] = function(arry, config) {
        // multiple all array values together
        var product = 1;
        $.each(arry, function(i,v) {
            // oops, we shouldn't have any zero values in the array
            if (v !== 0) {
                product *= v;
            }
        });
        return product;
    };

Ignoring cells

• Entire row: if the <tr> math data-attribute contains the keyword "ignore" then that entire row of cells will be skipped when building the array of data to be used for calculations.

  <tr data-math="ignore"><td>1</td><td>2</td><td>3</td></tr>

• Cell: if the table cell math data-attribute contains the keyword "ignore" then that cell will be skipped when building the array of data to be used for calculations.

  <td data-math="ignore">1</td>

• Column: set the widget math_ignore option with an array of zero-based column indexes of columns to ignore or skip when building the array of data for calculations.

  math_ignore : [0,1]

Targeting cell content

• Version 2.27.0 added a new data-attribute. The data-math-target attribute value must contain an element selector within the same cell.

  <tr>
    <td data-math="sum-above" data-math-target=".sum">The total value is <span class="sum"></span></td>
  </tr>

• If you're using the grouping widget and want to sum up the value of the group, you'll need to also include a data-column attribute to target the table column to sum. Here is a JSFiddle demonstrating how to combine the two widgets.

  <tr>
    <td colspan="5" data-math="sum-above" data-math-target=".sum" data-column="3">The total value is <span class="sum"></span></td>
  </tr>

// $.tablesorter.formatMask(mask, value, prefix, suffix);
$.tablesorter.formatMask('$#,##0.00 USD', 12345.678, 'prefix ', ' suffix');
// result: "prefix $12,345.68 USD suffix"

• The $.tablesorter.formatMask function has the following parameters:
  • mask - please refer to the math_mask option for more details.
  • value - number to be formatted.
  • prefix - please refer to the math_prefix option for more details (v2.16.4).
  • suffix - please refer to the math_suffix option for more details (v2.16.4).

Note The difference between using # and 0 in the mask, is that when a value of zero is passed to the function, the # mask will return an empty string whereas the 0 mask will return a zero.

$.tablesorter.formatMask('$#,##0.00 USD', 0); // result: "$0.00 USD"
$.tablesorter.formatMask('$#,###.00 USD', 0); // result: "$.00 USD"
$.tablesorter.formatMask('$#,###.#0 USD', 0); // result: "$.00 USD"
$.tablesorter.formatMask('$#,###.## USD', 0); // result: "$ USD"

Experiment with the mask: