<li>In <spanclass="version">v2.31.2</span>, added the missing ability to <ahref="#attribute_settings"class="intlink">ignore cells</a>; which was already documented, but actually missing. See <ahref="https://github.com/Mottie/tablesorter/issues/1526">issue #1526</a>.</li>
<li>Fix documentation and processing of <code>math_prefix</code> and <code>math_suffix</code> options. See <ahref="https://github.com/Mottie/tablesorter/issues/1305">issue #1305</a>.</li>
<li>Remove <code>math_prefix</code> content prior to parsing table cell values.</li>
<li>Added "Methods" section & more mask examples.</li>
<li>Added check for <code>data-math-target</code> attribute which allows you to target an element inside the table cell. See the <ahref="#attribute_settings">Attribute Settings</a>><strong>Targeting cell content</strong> section below.</li>
<li>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.</li>
<li>On initialization, only tbody cells with a <code>rowspan</code> or <code>colspan</code> are now processed and only get a "data-column" set if the internal <code>cellIndex</code> doesn't match the calculated cell index.</li>
<li>Initial calculation is no longer performed three times in a row</li>
<li>The cache is now only updated if cell content inside of a sortable tbody was modified.</li>
<li>These changes should improve performance and reduce lag after initialization and updating the table (see <ahref="https://github.com/Mottie/tablesorter/issues/1048">issue #1048</a>.</li>
<li>Added "below" type of data-gathering (see <ahref="#attribute_settings">Attribute Settings</a> below for more info). See <ahref="https://github.com/Mottie/tablesorter/pull/1027">pull #873</a>; thanks to <ahref="https://github.com/LvLynx">LvLynx</a>!.</li>
<li>Added <code>math_none</code> option which allows customizing the text added to a cell when there are no matching math elements (.</li>
<li>Fixed an issue with a sum column encountering a cell without a defined "data-math" attribute returning an empty string instead of zero. See <ahref="https://github.com/Mottie/tablesorter/issues/873">issue #873</a>.</li>
<li>Fixed a javascript error occurring on empty tables & now all updates will reapply column indexing to tbody cells - I know this isn't ideal as it would be slow on larger tables.</li>
</ul>
</li>
<li>In <spanclass="version">v2.19.1</span>, added <code>math_event</code> option & fixed an issue with event unbinding in jQuery version < 1.9.</li>
<li>In <spanclass="version">v2.17.1</span>,
<ul>
<li>Values added to the data-attribute set by the <ahref="../#textattribute"><code>textAttribute</code> option</a> will now be used in the calculation instead of the actual cell content.</li>
<li>The Grand Total cells now shows a higher precision value to emphasize this point.</li>
<li>Two new options: <code>math_prefix</code> and <code>math_suffix</code>, which will be added before or after the prefix or suffix, respectively.</li>
<li>Added "Mask Examples" section with examples, and how to use the <code>$.tablesorter.formatMask</code> function.</li>
<li>This widget will <strong>only work</strong> in tablesorter version 2.16+ and jQuery version 1.7+.</li>
<li>It adds basic math capabilities. A full list of default formulas is listed in the "Attribute Settings" section.</li>
<li>Add your own custom formulas which manipulating an array of values gathered from the table by row, column or a column block (above).</li>
<li>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.</li>
<li>The widget will update the calculations based on filtered rows, and will update if any data within the table changes (using update events).</li>
<li>This widget is not optimized for very large tables, for two reasons:
<li>On initialization, it cycles through every table row, calculates the column index <del>, and adds a <code>data-column</code> attribute</del> (Fixed in <spanclass="version updated">v2.25.0</span>).</li>
<li>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.</li>
</ul>
</li>
<li>When setting tablesorter's <code>debug</code> option to <code>true</code>, this widget will output each <code>{type}-{formula}</code> value found, the array of numbers used and the result.</li>
</ul>
</div>
<h3><ahref="#">Options</a></h3>
<div>
<h3>Math widget default options (added inside of tablesorter <code>widgetOptions</code>)</h3>
<divclass="tip">
<spanclass="label label-info">TIP!</span> Click on the link in the option column to reveal full details (or <ahref="#"class="toggleAll">toggle</a>|<ahref="#"class="showAll">show</a>|<ahref="#"class="hideAll">hide</a> all) or double click to update the browser location.
Set this option to point to the named data-attribute. For example, when set to <code>'math'</code>, the widget looks for settings within the <code>data-math</code> attribute.
Set this option to <code>true</code> to enable the debug log of the math widget without all the extra noise from the overall <ahref="index.html#debug"><code>debug</code></a> option (<spanclass="version">v2.27.0</span>).
Cell attribute (data-attribute) containing the math value to use. This defaults to the <ahref="index.html#textattribute"><code>textAttribute</code></a> value when the <ahref="index.html#textextraction"><code>textExtraction</code></a> option is set to "basic" (<spanclass="version">v2.31.1</span>).
<divclass="collapsible">
<br>
Use this option as follows:
<preclass="prettyprint lang-js">// Include the "data-" prefix in the option
<li>After any call to a tablesorter method which updates the internal cache (e.g. "update", "updateCell", etc). The math widget listens for the <ahref="index.html#updatecomplete">updateComplete</a> event, which occurs after the internal cache has completed updating, before recalculating values.</li>
This option contains the text added to a math cell when no matching elements are found (<spanclass="version">v2.24.0</span>; <spanclass="version updated">v2.25.0</span>).
<p>To understand when this text is used, select a Region in the "Row & Column Sums" table below. The totals for hidden rows will display this text.</p>
<p>As of <spanclass="version">v2.16.2</span>, you can set a mask for each math cell by adding a <code>data-math-mask</code> data-attribute (the <code>math</code> part of the data-attribute is named from the <code>math_data</code> setting).</p>
<li><del>No prefix or suffix is allowed except leading negation symbol. So <code>$#,##0.00</code> or <code>#,###.##USD</code> will not yield expected outcome. Use <code>'$'+ $.tablesorter.formatMask('#,##0.00', 123.45)</code> or <code>$.tablesorter.formatMask('#,##0.00', 456.789) + 'USD'</code></del></li>
<li>The prefix or suffix can not include any numbers (<code>0-9</code>), hashes (<code>#</code>), dashes (<code>-</code>), or plus signs (<code>+</code>)</li>
<li>The difference between using <code>#</code> and <code>0</code> in the mask, is that when a value of zero is passed to the function, the <code>#</code> mask will return an empty string whereas the <code>0</code> mask will return a zero.</li>
<li>When there's only one symbol is supplied, system will always treat the single symbol as Decimal. For instance, <code>$.tablesorter.formatMask( '#,###', 1234567.890)</code> will output <code>1234567,890</code>.</li>
<li>To force a single symbol as Separator, add a trailing dot to the end like this: <code>$.tablesorter.formatMask( '#,###.', 1234567.890)</code> which will then output <code>1,234,567</code>.</li>
<spanclass="remark">†</span> The number formatter code was copied from <ahref="https://code.google.com/p/javascript-number-formatter/">javascript-number-formatter</a> (<ahref="http://opensource.org/licenses/mit-license.php">MIT</a>) - now forked on <ahref="https://github.com/Mottie/javascript-number-formatter">GitHub</a> (<ahref="https://mottie.github.io/javascript-number-formatter/">updated demo</a>).
<li><code>result</code> - the formatted result of the calculation.</li>
<li><code>value</code> - an unformatted result of the calculation.</li>
<li><code>arry</code> - the array of values gathered by the widget.</li>
</ul>
In this function, if a anything is returned, it will be automatically added to the <code>$cell</code> as html. Or, return <code>false</code> and no change is made to the cell contents; use this method if you manipulate the <code>$cell</code> contents and don't want the widget to do it.<br>
<br>
If you need to format the data output after manipulating the <code>value</code>, you can use <code>wo.math_mask</code>, or a different mask, by using the <code>$.tablesorter.formatMask( mask, value );</code> function. For example:
<p>This option applys the set filter (<ahref="http://api.jquery.com/filter/">jQuery <code>.filter()</code></a> to the targeted rows.</p>
<p>If this option is set, rows filtered out by the filter widget are included, so you will need to include them in this selector if you wish to filter them out (e.g. <code>':visible:not(.filtered)'</code> (only include visible & rows not filtered out by the filter widget)</p>
<preclass="prettyprint lang-js">// this option will accept any of the jQuery filter types (i.e. selector, function or elements)
In <spanclass="version">v2.25.0</span>, this setting may be overridden for each math type by adding a <code>data-math-filter</code> attribute (The "math" portion is set by the <code>math_data</code> option) to the cell.
<spanclass="label label-info">Note</span> The <code>data-math-filter</code> attribute is ignored if set to an empty string; instead use <code>data-math-filter="*"</code> to target all rows as done in the first example on this page.
<p>The triggered <code>'recalculate'</code> method can be renamed by modifying the <aclass="intlink"href="#math_event"><code>math_event</code> option.</a></p>
This method is automatically called:
<ul>
<li>Tablesorter initialization.</li>
<li>After any call to a tablesorter method which updates the internal cache (e.g. "update", "updateCell", etc). The math widget listens for the <ahref="index.html#updatecomplete">updateComplete</a> event, which occurs after the internal cache has completed updating, before recalculating values.</li>
<li>After a "filterReset".</li>
<li>And after a "filterEnd" event, <em>or</em> a "pagerComplete" event (if the pager is being used), but not both!</li>
<li><code>row</code> - gather the table cell values from the same row as the <code>data-math</code> attribute.</li>
<li><code>above</code> - gather the table cell values from the same column as the <code>data-math</code> 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.</li>
<li><code>below</code> (<spanclass="version">v2.24.0</span>) - gather the table cell values from the same column as the <code>data-math</code> attribute, but stop when the last table cell is reached, or when another cell with a data-attribute with a "below" type is reached.</li>
<li><code>col</code> - gather the table cell values from the same column as the <code>data-math</code> attribute.</li>
<li><code>all</code> - gather all table cell values with a data-math attribute that start with "all".</li>
</ul>
<h3><code>{formula}</code> (defaults)</h3>
<ul>
<li><code>count</code> - returns the count (length) of the data set.</li>
<li><code>sum</code> - returns the sum of all values in the data set.</li>
<li><code>max</code> - returns the maximum value in the data set.</li>
<li><code>min</code> - returns the minimum values in the data set.</li>
<li><code>mean</code> - returns the mean (average) of all values in the data set; it uses the <code>sum</code> formula in part of the calculation.</li>
<li><code>median</code> - returns the median (middle value) of the data set.</li>
<li><code>mode</code> - 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).</li>
<li><code>range</code> - returns the range (highest minus lowest value) of the data set.</li>
<li><code>varp</code> - returns the variance of the data set (population).</li>
<li><code>vars</code> - returns the variance of the data set (sample).</li>
<li><code>stdevp</code> - returns the standard deviation of the data set (population).</li>
<li><code>stdevs</code> - returns the standard deviation of the data set (sample).</li>
<li><code>custom</code> (not a default)
<ul>
<li>Custom formulas can have any name</li>
<li>Return your result after making whatever calculation from the array of data passed to the formula</li>
<li>For example:
<preclass="prettyprint lang-js">// adding a custom equation... named "product"
// oops, we shouldn't have any zero values in the array
if (v !== 0) {
product *= v;
}
});
return product;
};</pre>
</li>
</ul>
</li>
</ul>
<h4>Ignoring cells</h4>
<ul>
<li>Entire row: if the <code><tr></code> math data-attribute contains the keyword <code>"ignore"</code> then that entire row of cells will be skipped when building the array of data to be used for calculations.
<li>Cell: if the table cell math data-attribute contains the keyword <code>"ignore"</code> then that cell will be skipped when building the array of data to be used for calculations.
<li>Column: set the widget <code>math_ignore</code> option with an array of zero-based column indexes of columns to ignore or skip when building the array of data for calculations.
<li>Version <spanclass="version">2.27.0</span> added a new data-attribute. The <code>data-math-target</code> attribute value must contain an element selector within the same cell.
<preclass="prettyprint lang-html"><tr>
<td data-math="sum-above" data-math-target=".sum">The total value is <span class="sum"></span></td>
</tr></pre>
</li>
<li>If you're using the grouping widget and want to sum up the value of the group, you'll need to also include a <code>data-column</code> attribute to target the table column to sum. Here is a <ahref="https://jsfiddle.net/Mottie/st2p6uvs/">JSFiddle</a> demonstrating how to combine the two widgets.
<preclass="prettyprint lang-html"><tr>
<td colspan="5" data-math="sum-above" data-math-target=".sum" data-column="3">The total value is <span class="sum"></span></td>
<spanclass="label label-info">Note</span> The difference between using <code>#</code> and <code>0</code> in the mask, is that when a value of zero is passed to the function, the <code>#</code> mask will return an empty string whereas the <code>0</code> mask will return a zero.
