Grouping: add group_forceColumn & group_enforceSort options. See #1000

docs/example-widget-grouping.html

@@ -86,6 +86,10 @@ tr.group-header.collapsed td i {
 			group_saveReset   : '.group_reset', // element to clear saved collapsed groups
 			group_count       : " ({num})", // if not false, the "{num}" string is replaced with the number of rows in the group
 
+			// apply the grouping widget only to selected column
+			group_forceColumn : [],   // only the first value is used; set as an array for future expansion
+			group_enforceSort : true, // only apply group_forceColumn when a sort is applied to the table
+
 			// checkbox parser text used for checked/unchecked values
 			group_checkbox    : [ 'checked', 'unchecked' ],
 
@@ -151,6 +155,12 @@ tr.group-header.collapsed td i {
 		<ul>
 			<li>This widget will <strong>only work</strong> in tablesorter version 2.8+ and jQuery version 1.7+.</li>
 			<li>Please do not use this widget in very large tables (it might be really slow) <del>or when your table includes multiple tbodies</del>.<br><br></li>
+			<li>In <span class="version">v2.23.3</span>
+				<ul>
+					<li>Added <code>group_forceColumn</code> &amp; <code>group_enforceSort</code> options for force column grouping.</li>
+					<li>Updated method used to save collapsed groups, so any previously collapsed groups will be ignored after this update.</li>
+				</ul>
+			</li>
 			<li>In <span class="version">v2.22.0</span>, group headers are now keyboard accessible using <kbd>Tab</kbd>; and pressing <kbd>Enter</kbd> while the header has focus will toggle the group header, or use <kbd>Shift</kbd> + <kbd>Enter</kbd> to toggle all groups.</li>
 			<li>In <span class="version">v2.21.0</span>
 				<ul>
@@ -301,10 +311,30 @@ group_separator : /[/.]/</pre>
 						</td>
 					</tr>
 
+					<tr id="group_forcecolumn">
+						<td><a href="#" class="permalink">group_forceColumn</a></td>
+						<td><code><code>[]</code></td>
+						<td>
+							Force the group widget to only apply to one column (<span class="version">v2.23.3</span>).
+							<div class="collapsible">
+								<p>When this option is set, only the first value in the array is used; <em>it is set up as an array for future expansion</em>.</p>
+								<p>When set, the set column will be the only column grouped by this widget.</p>
+								<p>If the <code>group_enforceSort</code> option is set to <code>false</code>, the column will be grouped without a sort applied to the table.</p>
+							</div>
+						</td>
+					</tr>
+
+					<tr id="group_enforcesort">
+						<td><a href="#" class="permalink">group_enforceSort</a></td>
+						<td><code>true</code></td>
+						<td>
+							Only allow <code>group_forceColumn</code> to work when a sort is applied to the table (<span class="version">v2.23.3</span>).
+						</td>
+					</tr>
 
 					<tr id="group_checkbox">
 						<td><a href="#" class="permalink">group_checkbox</a></td>
-						<td>see description)</td>
+						<td>(see description)</td>
 						<td>
 							Set checkbox parser text (<span class="version">v2.21.0</span>)
 							<div class="collapsible">
@@ -457,7 +487,7 @@ group_dateString : function(date) {
 			<th class="group-letter-1">Animals (first <span>letter</span>)</th>
 			<th class="group-word-1">Natural Sort (first word)</th>
 			<th class="group-word-2">Inputs (second word)</th>
-			<!-- try "group-date", "group-date-year", "group-date-month", "group-date-day", "group-date-week" or "group-date-time" -->
+			<!-- try "group-date", "group-date-year", "group-date-month", "group-data-monthyear", "group-date-day", "group-date-week" or "group-date-time" -->
 			<th class="group-date">Date (<span>Full</span>)</th>
 		</tr>
 	</thead>

docs/index.html

@@ -496,7 +496,7 @@
 		<li><span class="label label-info">Beta</span> <a href="example-widget-formatter.html">Formatter widget</a> (<span class="version">v2.19.1</span>).</li>
 		<li>Grouping rows widget:
 			<ul>
-				<li><a href="example-widget-grouping.html">basic</a> (v2.8; <span class="version updated">v2.22.0</span>).</li>
+				<li><a href="example-widget-grouping.html">basic</a> (v2.8; <span class="version updated">v2.23.3</span>).</li>
 				<li><a href="example-widget-grouping-filter-childrows.html">Grouping + filter + child rows</a> (<span class="updated version">v2.15.12</span>)</li>
 			</ul>
 		</li>

js/widgets/widget-grouping.js

@@ -55,9 +55,13 @@
 		update : function(table, c, wo){
 			if ($.isEmptyObject(c.cache)) { return; }
 			var rowIndex, tbodyIndex, currentGroup, $rows, groupClass, grouping, norm_rows, saveName, direction,
+				hasSort = typeof c.sortList[0] !== 'undefined',
 				group = '',
+				groupIndex = 0,
 				savedGroup = false,
-				column = c.sortList[0] ? c.sortList[0][0] : -1;
+				column = typeof wo.group_forceColumn[0] !== 'undefined' ?
+					( wo.group_enforceSort && !hasSort ? -1 : wo.group_forceColumn[0] ) :
+					( hasSort ? c.sortList[0][0] : -1 );
 			c.$table
 				.find('tr.group-hidden').removeClass('group-hidden').end()
 				.find('tr.group-header').remove();
@@ -65,7 +69,7 @@
 				// clear pager saved spacer height (in case the rows are collapsed)
 				c.$table.data('pagerSavedHeight', 0);
 			}
-			if (column >= 0 && !c.$headerIndexed[column].hasClass('group-false')) {
+			if (column >= 0 && column < c.columns && !c.$headerIndexed[column].hasClass('group-false')) {
 				wo.group_currentGroup = ''; // save current groups
 				wo.group_currentGroups = {};
 
@@ -77,10 +81,10 @@
 				// save current grouping
 				if (wo.group_collapsible && wo.group_saveGroups && ts.storage) {
 					wo.group_currentGroups = ts.storage( table, 'tablesorter-groups' ) || {};
-					// include direction when grouping numbers > 1 (reversed direction shows different range values)
+					// include direction when saving groups (reversed numbers shows different range values)
-					direction = (grouping[1] === 'number' && grouping[2] > 1) ? 'dir' + c.sortList[0][1] : '';
+					direction = 'dir' + c.sortList[0][1];
 					// combine column, sort direction & grouping as save key
-					saveName = wo.group_currentGroup = '' + column + direction + grouping.join('');
+					saveName = wo.group_currentGroup = '' + c.sortList[0][0] + direction + grouping.join('');
 					if (!wo.group_currentGroups[saveName]) {
 						wo.group_currentGroups[saveName] = [];
 					} else {
@@ -109,9 +113,11 @@
 										currentGroup = wo.group_formatter((currentGroup || '').toString(), column, table, c, wo) || currentGroup;
 									}
 									$rows.eq(rowIndex).before('<tr class="group-header ' + c.selectorRemove.slice(1) +
-										'" unselectable="on"' + ( c.tabIndex ? ' tabindex="0"' : '' ) + '><td colspan="' +
+										'" unselectable="on" ' + ( c.tabIndex ? 'tabindex="0" ' : '' ) + 'data-group-index="' +
-										c.columns + '">' + (wo.group_collapsible ? '<i/>' : '') + '<span class="group-name">' +
+										( groupIndex++ ) + '"><td colspan="' + c.columns + '">' +
-										currentGroup + '</span><span class="group-count"></span></td></tr>');
+										( wo.group_collapsible ? '<i/>' : '' ) +
+										'<span class="group-name">' + currentGroup + '</span>' +
+										'<span class="group-count"></span></td></tr>');
 									if (wo.group_saveGroups && !savedGroup && wo.group_collapsed && wo.group_collapsible) {
 										// all groups start collapsed
 										wo.group_currentGroups[wo.group_currentGroup].push(currentGroup);
@@ -138,8 +144,8 @@
 							}
 						}
 					}
-					if (wo.group_saveGroups && wo.group_currentGroups.length && wo.group_currentGroups[wo.group_currentGroup].length) {
+					if (wo.group_saveGroups && !$.isEmptyObject(wo.group_currentGroups) && wo.group_currentGroups[wo.group_currentGroup].length) {
-						name = $row.find('.group-name').text().toLowerCase();
+						name = $row.find('.group-name').text().toLowerCase() + $row.attr('data-group-index');
 						isHidden = $.inArray( name, wo.group_currentGroups[wo.group_currentGroup] ) > -1;
 						$row.toggleClass('collapsed', isHidden);
 						$rows.toggleClass('group-hidden', isHidden);
@@ -162,7 +168,7 @@
 					if (event.type === 'keyup' && event.which !== 13) { return; }
 					var isCollapsed, $groups, indx,
 						$this = $(this),
-						name = $this.find('.group-name').text().toLowerCase();
+						name = $this.find('.group-name').text().toLowerCase() + $this.attr('data-group-index');
 					// use shift-click to toggle ALL groups
 					if (event.shiftKey && (event.type === 'click' || event.type === 'keyup')) {
 						$this.siblings('.group-header').trigger('toggleGroup');
@@ -220,6 +226,10 @@
 			group_callback    : null, // function($cell, $rows, column, table){}, callback allowing modification of the group header labels
 			group_complete    : 'groupingComplete', // event triggered on the table when the grouping widget has finished work
 
+			// apply the grouping widget only to selected column
+			group_forceColumn : [],   // only the first value is used; set as an array for future expansion
+			group_enforceSort : true, // only apply group_forceColumn when a sort is applied to the table
+
 			// checkbox parser text used for checked/unchecked values
 			group_checkbox    : [ 'checked', 'unchecked' ],
 			// change these default date names based on your language preferences