Filter: Update buildSelect function to allow external calls to modify filter select options

docs/index.html

@@ -5653,6 +5653,30 @@ $.tablesorter.isDigit( &quot;(2,345.67)&quot; );</pre>
 				</td>
 			</tr>
 
+			<tr id="function-buildselect">
+				<td><a href="#" class="permalink">buildSelect</a></td>
+				<td>This filter widget function allows the updating or replacing of filter select options from an external source. (<span class="version">v2.17.5</span>):
+					<div class="collapsible"><br>
+						Access it as follows:
+						<pre class="prettyprint lang-js">$.tablesorter.buildSelect( table, column, options, replace, onlyAvail );</pre>
+						<ul>
+							<li><code>table</code> - table DOM element (or jQuery object) of table.</li>
+							<li><code>column</code> - zero-based column index.</li>
+							<li><code>options</code> - array of options, jQuery object of option elements, or HTML string of option elements to apply to the targetted select.</li>
+							<li><code>replace</code> - a boolean value, which if <code>true</code> all options will be replaced; if <code>false</code> the options will be appended to the current list of options.</li>
+							<li><code>onlyAvail</code> - an optional boolean flag, which will be ignored if the <code>options</code> parameter is defined or is an empty string; otherwise it is the value passed to the function which finds all table column values; if <code>true</code>, only the available options will be diplayed.</li>
+						</ul>
+						Use this function as follows:<br>
+						<pre class="prettyprint lang-js">// replace filter select options for the first column with 1,2,3,4
+$.tablesorter.buildSelect( $('table'), 0, [ 1, 2, 3, 4 ], true );
+
+// append "Aaron" and "Fred" to the second column's filter select options. These options will remain unsorted.
+$.tablesorter.buildSelect( $('table'), 1, $('<option>Aaron</option><option>Fred</option>'), false );</pre>
+						Please be aware that this function will allow you to modify the select options, but as soon as the user filters any column, all of the select options will refresh and obtain options from the table column, or from the <code>filter_selectSource</code> function.
+					</div>
+				</td>
+			</tr>
+
 			<tr id="function-getfilters">
 				<td><a href="#" class="permalink">getFilters</a></td>
 				<td>This filter widget function allows getting an array of the currently applied filters (<span class="version">v2.9</span>; <span class="version updated">v2.15</span>)

js/jquery.tablesorter.widgets.js

@@ -1284,34 +1284,58 @@ ts.filter = {
 		}
 		return arry;
 	},
-	buildSelect: function(table, column, updating, onlyAvail) {
+	buildSelect: function(table, column, arry, updating, onlyAvail) {
-		if (!table.config.cache || $.isEmptyObject(table.config.cache)) { return; }
+		table = $(table)[0];
 		column = parseInt(column, 10);
-		var indx, txt, $filters,
+		if (!table.config.cache || $.isEmptyObject(table.config.cache)) { return; }
+		var indx, txt, $filters, $filter,
 			c = table.config,
 			wo = c.widgetOptions,
 			node = c.$headers.filter('[data-column="' + column + '"]:last'),
 			// t.data('placeholder') won't work in jQuery older than 1.4.3
 			options = '<option value="">' + ( node.data('placeholder') || node.attr('data-placeholder') || wo.filter_placeholder.select || '' ) + '</option>',
-			arry = ts.filter.getOptionSource(table, column, onlyAvail),
 			// Get curent filter value
 			currentValue = c.$table.find('thead').find('select.' + ts.css.filter + '[data-column="' + column + '"]').val();
 
-		// build option list
+		// nothing included in arry (external source), so get the options from filter_selectSource or column data
-		for (indx = 0; indx < arry.length; indx++) {
+		if (typeof arry === 'undefined' || arry === '') {
-			txt = arry[indx].replace(/\"/g, "&quot;");
+			arry = ts.filter.getOptionSource(table, column, onlyAvail);
-			// replace quotes - fixes #242 & ignore empty strings - see http://stackoverflow.com/q/14990971/145346
-			options += arry[indx] !== '' ? '<option value="' + txt + '"' + (currentValue === txt ? ' selected="selected"' : '') +
-				'>' + arry[indx] + '</option>' : '';
 		}
+
+		if ($.isArray(arry)) {
+			// build option list
+			for (indx = 0; indx < arry.length; indx++) {
+				txt = ('' + arry[indx]).replace(/\"/g, "&quot;");
+				// replace quotes - fixes #242 & ignore empty strings - see http://stackoverflow.com/q/14990971/145346
+				options += arry[indx] !== '' ? '<option value="' + txt + '"' + (currentValue === txt ? ' selected="selected"' : '') +
+					'>' + arry[indx] + '</option>' : '';
+			}
+			// clear arry so it doesn't get appended twice
+			arry = [];
+		}
+
 		// update all selects in the same column (clone thead in sticky headers & any external selects) - fixes 473
 		$filters = ( c.$filters ? c.$filters : c.$table.children('thead') ).find('.' + ts.css.filter);
 		if (wo.filter_$externalFilters) {
 			$filters = $filters && $filters.length ? $filters.add(wo.filter_$externalFilters) : wo.filter_$externalFilters;
 		}
-		$filters.filter('select[data-column="' + column + '"]')[ updating ? 'html' : 'append' ](options);
+		$filter = $filters.filter('select[data-column="' + column + '"]');
-		if (!wo.filter_functions) { wo.filter_functions = {}; }
+
-		wo.filter_functions[column] = true;
+		// make sure there is a select there!
+		if ($filter.length) {
+			$filter[ updating ? 'html' : 'append' ](options);
+
+			if (!$.isArray(arry)) {
+				// append options if arry is provided externally as a string or jQuery object
+				$filter.append(arry);
+			}
+
+			if ($.isEmptyObject(wo.filter_functions)) { wo.filter_functions = {}; }
+			// don't modify already set functions
+			if (typeof wo.filter_functions[column] === 'undefined') {
+				wo.filter_functions[column] = true;
+			}
+		}
 	},
 	buildDefault: function(table, updating) {
 		var columnIndex, $header,
@@ -1323,7 +1347,7 @@ ts.filter = {
 			$header = c.$headers.filter('[data-column="' + columnIndex + '"]:last');
 			// look for the filter-select class; build/update it if found
 			if (($header.hasClass('filter-select') || ts.getColumnData( table, wo.filter_functions, columnIndex ) === true) && !$header.hasClass('filter-false')) {
-				ts.filter.buildSelect(table, columnIndex, updating, $header.hasClass(wo.filter_onlyAvail));
+				ts.filter.buildSelect(table, columnIndex, '', updating, $header.hasClass(wo.filter_onlyAvail));
 			}
 		}
 	}