datatables.net-select 2.0.5 → 3.0.0

package/js/dataTables.select.js

@@ -1,4 +1,4 @@
-/*! Select for DataTables 2.0.5
+/*! Select for DataTables 3.0.0
  * © SpryMedia Ltd - datatables.net/license/mit
  */
 
@@ -56,7 +56,7 @@ DataTable.select.classes = {
 	checkbox: 'dt-select-checkbox'
 };
 
-DataTable.select.version = '2.0.5';
+DataTable.select.version = '3.0.0';
 
 DataTable.select.init = function (dt) {
 	var ctx = dt.settings()[0];
@@ -126,11 +126,13 @@ DataTable.select.init = function (dt) {
 	var style = 'api';
 	var blurable = false;
 	var toggleable = true;
+	var selectable = null;
 	var info = true;
 	var selector = 'td, th';
 	var className = 'selected';
 	var headerCheckbox = true;
 	var setStyle = false;
+	var keys = false;
 
 	ctx._select = {
 		infoEls: []
@@ -182,6 +184,14 @@ DataTable.select.init = function (dt) {
 		if (opts.headerCheckbox !== undefined) {
 			headerCheckbox = opts.headerCheckbox;
 		}
+
+		if (opts.selectable !== undefined) {
+			selectable = opts.selectable;
+		}
+
+		if (opts.keys !== undefined) {
+			keys = opts.keys;
+		}
 	}
 
 	dt.select.selector(selector);
@@ -190,6 +200,8 @@ DataTable.select.init = function (dt) {
 	dt.select.blurable(blurable);
 	dt.select.toggleable(toggleable);
 	dt.select.info(info);
+	dt.select.keys(keys);
+	dt.select.selectable(selectable);
 	ctx._select.className = className;
 
 	// If the init options haven't enabled select, but there is a selectable
@@ -199,11 +211,9 @@ DataTable.select.init = function (dt) {
 	}
 
 	// Insert a checkbox into the header if needed - might need to wait
-	// for init complete, or it might already be done
+	// for init complete
 	if (headerCheckbox || headerCheckbox === 'select-page' || headerCheckbox === 'select-all') {
-		initCheckboxHeader(dt, headerCheckbox);
-
-		dt.on('init', function () {
+		dt.ready(function () {
 			initCheckboxHeader(dt, headerCheckbox);
 		});
 	}
@@ -570,9 +580,17 @@ function info(api, node) {
 		return;
 	}
 
-	var rows = api.rows({ selected: true }).flatten().length;
-	var columns = api.columns({ selected: true }).flatten().length;
-	var cells = api.cells({ selected: true }).flatten().length;
+	var ctx = api.settings()[0];
+	var rowSetLength = ctx._select_set.length;
+	var rows = rowSetLength ? rowSetLength : api.rows({ selected: true }).count();
+	var columns = api.columns({ selected: true }).count();
+	var cells = api.cells({ selected: true }).count();
+
+	// If subtractive selection, then we need to take the number of rows and
+	// subtract those that have been deselected
+	if (ctx._select_mode === 'subtractive') {
+		rows = api.page.info().recordsDisplay - rowSetLength;
+	}
 
 	var add = function (el, name, num) {
 		el.append(
@@ -612,7 +630,8 @@ function info(api, node) {
  * @param {*} headerCheckbox the header checkbox option
  */
 function initCheckboxHeader( dt, headerCheckbox ) {
-	var dtInternalColumns = dt.settings()[0].aoColumns;
+	var dtSettings = dt.settings()[0];
+	var dtInternalColumns = dtSettings.aoColumns;
 
 	// Find any checkbox column(s)
 	dt.columns().iterator('column', function (s, idx) {
@@ -636,33 +655,37 @@ function initCheckboxHeader( dt, headerCheckbox ) {
 				.on('change', function () {
 					if (this.checked) {
 						if (headerCheckbox == 'select-page') {
-							dt.rows({page: 'current'}).select()
-						} else {
+							dt.rows({page: 'current'}).select();
+						}
+						else {
 							dt.rows({search: 'applied'}).select();
 						}
 					}
 					else {
-						dt.rows({selected: true}).deselect();
+						if (headerCheckbox == 'select-page') {
+							dt.rows({page: 'current', selected: true}).deselect();
+						}
+						else {
+							dt.rows({selected: true}).deselect();
+						}
 					}
 				})
 				.on('click', function (e) {
 					e.stopPropagation();
 				});
-	
+
 			// Update the header checkbox's state when the selection in the
 			// table changes
 			dt.on('draw select deselect', function (e, pass, type) {
 				if (type === 'row' || ! type) {
-					var count = dt.rows({selected: true}).count();
-					var search = dt.rows({search: 'applied', selected: true}).count();
-					var available = headerCheckbox == 'select-page' ? dt.rows({page: 'current'}).count() : dt.rows({search: 'applied'}).count();
+					var nums = headerCheckboxState(dt, headerCheckbox);
 
-					if (search && search <= count && search === available) {
+					if (nums.search && nums.search <= nums.count && nums.search === nums.available) {
 						input
 							.prop('checked', true)
 							.prop('indeterminate', false);
 					}
-					else if (search === 0 && count === 0) {
+					else if (nums.search === 0 && nums.count === 0) {
 						input
 							.prop('checked', false)
 							.prop('indeterminate', false);
@@ -678,6 +701,188 @@ function initCheckboxHeader( dt, headerCheckbox ) {
 	});
 }
 
+function keysSet(dt) {
+	var ctx = dt.settings()[0];
+	var flag = ctx._select.keys;
+	var namespace = 'dts-keys-' + ctx.sTableId;
+
+	if (flag) {
+		// Need a tabindex of the `tr` elements to make them focusable by the browser
+		$(dt.rows({page: 'current'}).nodes()).attr('tabindex', 0);
+
+		dt.on('draw.' + namespace, function () {
+			$(dt.rows({page: 'current'}).nodes()).attr('tabindex', 0);
+		});
+
+		// Listen on document for tab, up and down
+		$(document).on('keydown.' + namespace, function (e) {
+			var key = e.keyCode;
+			var active = document.activeElement;
+
+			// Can't use e.key as it wasn't widely supported until 2017
+			// 9 Tab
+			// 13 Return
+			// 32 Space
+			// 38 ArrowUp
+			// 40 ArrowDown
+			if (! [9, 13, 32, 38, 40].includes(key)) {
+				return;
+			}
+
+			var nodes = dt.rows({page: 'current'}).nodes().toArray();
+			var idx = nodes.indexOf(active);
+			var preventDefault = true;
+
+			// Only take an action if a row has focus
+			if (idx === -1) {
+				return;
+			}
+
+			if (key === 9) {
+				// Tab focus change
+				if (e.shift === false && idx === nodes.length - 1) {
+					keysPageDown(dt);
+				}
+				else if (e.shift === true && idx === 0) {
+					keysPageUp(dt);
+				}
+				else {
+					// Browser will do it for us
+					preventDefault = false;
+				}
+			}
+			else if (key === 13 || key === 32) {
+				// Row selection / deselection
+				var row = dt.row(active);
+
+				if (row.selected()) {
+					row.deselect();
+				}
+				else {
+					row.select();
+				}
+			}
+			else if (key === 38) {
+				// Move up
+				if (idx > 0) {
+					nodes[idx-1].focus();
+				}
+				else {
+					keysPageUp(dt);
+				}
+			}
+			else {
+				// Move down
+				if (idx < nodes.length -1) {
+					nodes[idx+1].focus();
+				}
+				else {
+					keysPageDown(dt);
+				}
+			}
+
+			if (preventDefault) {
+				e.stopPropagation();
+				e.preventDefault();
+			}
+		});
+	}
+	else {
+		// Stop the rows from being able to gain focus
+		$(dt.rows().nodes()).removeAttr('tabindex');
+
+		// Nuke events
+		dt.off('draw.' + namespace);
+		$(document).off('keydown.' + namespace);
+	}
+}
+
+/**
+ * Change to the next page and focus on the first row
+ *
+ * @param {DataTable.Api} dt DataTable instance
+ */
+function keysPageDown(dt) {
+	// Is there another page to turn to?
+	var info = dt.page.info();
+
+	if (info.page < info.pages - 1) {
+		dt
+			.one('draw', function () {
+				dt.row(':first-child').node().focus();
+			})
+			.page('next')
+			.draw(false);
+	}
+}
+
+/**
+ * Change to the previous page and focus on the last row
+ *
+ * @param {DataTable.Api} dt DataTable instance
+ */
+function keysPageUp(dt) {
+	// Is there another page to turn to?
+	var info = dt.page.info();
+
+	if (info.page > 0) {
+		dt
+			.one('draw', function () {
+				dt.row(':last-child').node().focus();
+			})
+			.page('previous')
+			.draw(false);
+	}
+}
+
+/**
+ * Determine the counts used to define the header checkbox's state
+ *
+ * @param {*} dt DT API
+ * @param {*} headerCheckbox Configuration for what the header checkbox does
+ * @returns Counts object
+ */
+function headerCheckboxState(dt, headerCheckbox) {
+	var ctx = dt.settings()[0];
+	var selectable = ctx._select.selectable;
+	var available = 0;
+	var count = headerCheckbox == 'select-page'
+		? dt.rows({page: 'current', selected: true}).count()
+		: dt.rows({selected: true}).count();
+	var search = headerCheckbox == 'select-page'
+		? dt.rows({page: 'current', selected: true}).count()
+		: dt.rows({search: 'applied', selected: true}).count();
+
+	if (! selectable) {
+		available = headerCheckbox == 'select-page'
+			? dt.rows({page: 'current'}).count()
+			: dt.rows({search: 'applied'}).count();	
+	}
+	else {
+		// Need to count how many rows are actually selectable to know if all selectable
+		// rows are selected or not
+		var indexes = headerCheckbox == 'select-page'
+			? dt.rows({page: 'current'}).indexes()
+			: dt.rows({search: 'applied'}).indexes();
+
+		for (var i=0 ; i<indexes.length ; i++) {
+			// For speed I use the internal DataTables object.
+			var rowInternal = ctx.aoData[indexes[i]];
+			var result = selectable(rowInternal._aData, rowInternal.nTr, indexes[i]);
+
+			if (result) {
+				available++;
+			}
+		}
+	}
+
+	return {
+		available: available,
+		count: count,
+		search: search
+	}
+}
+
 /**
  * Initialisation of a new table. Attach event handlers and callbacks to allow
  * Select to operate correctly.
@@ -692,6 +897,12 @@ function init(ctx) {
 	var api = new DataTable.Api(ctx);
 	ctx._select_init = true;
 
+	// When `additive` then `_select_set` contains a list of the row ids that
+	// are selected. If `subtractive` then all rows are selected, except those
+	// in `_select_set`, which is a list of ids.
+	ctx._select_mode = 'additive';
+	ctx._select_set = [];
+
 	// Row callback so that classes can be added to rows and cells if the item
 	// was selected before the element was created. This will happen with the
 	// `deferRender` option enabled.
@@ -702,9 +913,16 @@ function init(ctx) {
 	ctx.aoRowCreatedCallback.push(function (row, data, index) {
 			var i, ien;
 			var d = ctx.aoData[index];
+			var id = api.row(index).id();
 
 			// Row
-			if (d._select_selected) {
+			if (
+				d._select_selected ||
+				(ctx._select_mode === 'additive' && ctx._select_set.includes(id)) ||
+				(ctx._select_mode === 'subtractive' && ! ctx._select_set.includes(id))
+			) {
+				d._select_selected = true;
+
 				$(row)
 					.addClass(ctx._select.className)
 					.find('input.' + checkboxClass(true)).prop('checked', true);
@@ -723,46 +941,7 @@ function init(ctx) {
 		}
 	);
 
-	// On Ajax reload we want to reselect all rows which are currently selected,
-	// if there is an rowId (i.e. a unique value to identify each row with)
-	api.on('preXhr.dt.dtSelect', function (e, settings) {
-		if (settings !== api.settings()[0]) {
-			// Not triggered by our DataTable!
-			return;
-		}
-
-		// note that column selection doesn't need to be cached and then
-		// reselected, as they are already selected
-		var rows = api
-			.rows({ selected: true })
-			.ids(true)
-			.filter(function (d) {
-				return d !== undefined;
-			});
-
-		var cells = api
-			.cells({ selected: true })
-			.eq(0)
-			.map(function (cellIdx) {
-				var id = api.row(cellIdx.row).id(true);
-				return id ? { row: id, column: cellIdx.column } : undefined;
-			})
-			.filter(function (d) {
-				return d !== undefined;
-			});
-
-		// On the next draw, reselect the currently selected items
-		api.one('draw.dt.dtSelect', function () {
-			api.rows(rows).select();
-
-			// `cells` is not a cell index selector, so it needs a loop
-			if (cells.any()) {
-				cells.each(function (id) {
-					api.cells(id.row, id.column).select();
-				});
-			}
-		});
-	});
+	_cumulativeEvents(api);
 
 	// Update the table information element with selected item summary
 	api.on('info.dt', function (e, ctx, node) {
@@ -935,6 +1114,73 @@ function _safeId(node) {
 	return node.id.replace(/[^a-zA-Z0-9\-\_]/g, '-');
 }
 
+/**
+ * Set up event handlers for cumulative selection
+ *
+ * @param {*} api DT API instance
+ */
+function _cumulativeEvents(api) {
+	// Add event listeners to add / remove from the _select_set
+	api.on('select', function (e, dt, type, indexes) {
+		// Only support for rows at the moment
+		if (type !== 'row') {
+			return;
+		}
+
+		var ctx = api.settings()[0];
+
+		if (ctx._select_mode === 'additive') {
+			// Add row to the selection list if it isn't already there
+			_add(api, ctx._select_set, indexes);
+		}
+		else {
+			// Subtractive - if a row is selected it should not in the list
+			// as in subtractive mode the list gives the rows which are not
+			// selected
+			_remove(api, ctx._select_set, indexes);
+		}
+	});
+
+	api.on('deselect', function (e, dt, type, indexes) {
+		// Only support for rows at the moment
+		if (type !== 'row') {
+			return;
+		}
+
+		var ctx = api.settings()[0];
+
+		if (ctx._select_mode === 'additive') {
+			// List is of those rows selected, so remove it
+			_remove(api, ctx._select_set, indexes);
+		}
+		else {
+			// List is of rows which are deselected, so add it!
+			_add(api, ctx._select_set, indexes);
+		}
+	});
+}
+
+function _add(api, arr, indexes) {
+	for (var i=0 ; i<indexes.length ; i++) {
+		var id = api.row(indexes[i]).id();
+
+		if (id && id !== 'undefined' && ! arr.includes(id)) {
+			arr.push(id);
+		}
+	}
+}
+
+function _remove(api, arr, indexes) {
+	for (var i=0 ; i<indexes.length ; i++) {
+		var id = api.row(indexes[i]).id();
+		var idx = arr.indexOf(id);
+
+		if (idx !== -1) {
+			arr.splice(idx, 1);
+		}
+	}
+}
+
 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
  * DataTables selectors
  */
@@ -1062,6 +1308,22 @@ apiRegister('select.items()', function (items) {
 	});
 });
 
+apiRegister('select.keys()', function (flag) {
+	if (flag === undefined) {
+		return this.context[0]._select.keys;
+	}
+
+	return this.iterator('table', function (ctx) {
+		if (!ctx._select) {
+			DataTable.select.init(new DataTable.Api(ctx));
+		}
+
+		ctx._select.keys = flag;
+
+		keysSet(new DataTable.Api(ctx));
+	});
+});
+
 // Takes effect from the _next_ selection. None disables future selection, but
 // does not clear the current selection. Use the `deselect` methods for that
 apiRegister('select.style()', function (style) {
@@ -1083,10 +1345,15 @@ apiRegister('select.style()', function (style) {
 		// Add / remove mouse event handlers. They aren't required when only
 		// API selection is available
 		var dt = new DataTable.Api(ctx);
-		disableMouseSelection(dt);
 
 		if (style !== 'api') {
-			enableMouseSelection(dt);
+			dt.ready(function () {
+				disableMouseSelection(dt);
+				enableMouseSelection(dt);
+			});
+		}
+		else {
+			disableMouseSelection(dt);
 		}
 
 		eventTrigger(new DataTable.Api(ctx), 'selectStyle', [style]);
@@ -1099,16 +1366,36 @@ apiRegister('select.selector()', function (selector) {
 	}
 
 	return this.iterator('table', function (ctx) {
-		disableMouseSelection(new DataTable.Api(ctx));
+		var dt = new DataTable.Api(ctx);
+		var style = ctx._select.style;
+
+		disableMouseSelection(dt);
 
 		ctx._select.selector = selector;
 
-		if (ctx._select.style !== 'api') {
-			enableMouseSelection(new DataTable.Api(ctx));
+		if (style && style !== 'api') {
+			dt.ready(function () {
+				disableMouseSelection(dt);
+				enableMouseSelection(dt);
+			});
+		}
+		else {
+			disableMouseSelection(dt);
 		}
 	});
 });
 
+apiRegister('select.selectable()', function (set) {
+	let ctx = this.context[0];
+
+	if (set) {
+		ctx._select.selectable = set;
+		return this;
+	}
+
+	return ctx._select.selectable;
+});
+
 apiRegister('select.last()', function (set) {
 	let ctx = this.context[0];
 
@@ -1120,8 +1407,50 @@ apiRegister('select.last()', function (set) {
 	return ctx._select_lastCell;
 });
 
+apiRegister('select.cumulative()', function (mode) {
+	if (mode) {
+		return this.iterator('table', function (ctx) {
+			if (ctx._select_mode === mode) {
+				return;
+			}
+
+			var dt = new DataTable.Api(ctx);
+
+			// Convert from the current mode, to the new
+			if (mode === 'subtractive') {
+				// For subtractive mode we track the row ids which are not selected
+				var unselected = dt.rows({selected: false}).ids().toArray();
+
+				ctx._select_mode = mode;
+				ctx._select_set.length = 0;
+				ctx._select_set.push.apply(ctx._select_set, unselected);
+			}
+			else {
+				// Switching to additive, so selected rows are to be used
+				var selected = dt.rows({selected: true}).ids().toArray();
+
+				ctx._select_mode = mode;
+				ctx._select_set.length = 0;
+				ctx._select_set.push.apply(ctx._select_set, selected);
+			}
+		}).draw(false);
+	}
+
+	let ctx = this.context[0];
+
+	if (ctx && ctx._select_set) {
+		return {
+			mode: ctx._select_mode,
+			rows: ctx._select_set
+		};
+	}
+
+	return null;
+});
+
 apiRegisterPlural('rows().select()', 'row().select()', function (select) {
 	var api = this;
+	var selectedIndexes = [];
 
 	if (select === false) {
 		return this.deselect();
@@ -1136,9 +1465,20 @@ apiRegisterPlural('rows().select()', 'row().select()', function (select) {
 		var dtData = ctx.aoData[idx];
 		var dtColumns = ctx.aoColumns;
 
+		if (ctx._select.selectable) {
+			var result = ctx._select.selectable(dtData._aData, dtData.nTr, idx);
+
+			if (result === false) {
+				// Not selectable - do nothing
+				return;
+			}
+		}
+
 		$(dtData.nTr).addClass(ctx._select.className);
 		dtData._select_selected = true;
 
+		selectedIndexes.push(idx);
+
 		for (var i=0 ; i<dtColumns.length ; i++) {
 			var col = dtColumns[i];
 
@@ -1163,8 +1503,8 @@ apiRegisterPlural('rows().select()', 'row().select()', function (select) {
 		}
 	});
 
-	this.iterator('table', function (ctx, i) {
-		eventTrigger(api, 'select', ['row', api[i]], true);
+	this.iterator('table', function (ct) {
+		eventTrigger(api, 'select', ['row', selectedIndexes], true);
 	});
 
 	return this;
@@ -1180,6 +1520,22 @@ apiRegister('row().selected()', function () {
 	return false;
 });
 
+apiRegister('row().focus()', function () {
+	var ctx = this.context[0];
+
+	if (ctx && this.length && ctx.aoData[this[0]] && ctx.aoData[this[0]].nTr) {
+		ctx.aoData[this[0]].nTr.focus();
+	}
+});
+
+apiRegister('row().blur()', function () {
+	var ctx = this.context[0];
+
+	if (ctx && this.length && ctx.aoData[this[0]] && ctx.aoData[this[0]].nTr) {
+		ctx.aoData[this[0]].nTr.blur();
+	}
+});
+
 apiRegisterPlural('columns().select()', 'column().select()', function (select) {
 	var api = this;
 
@@ -1526,6 +1882,8 @@ $.each(['Row', 'Column', 'Cell'], function (i, item) {
 		init: function (dt) {
 			var that = this;
 
+			this.active(dt.select.items() === lc);
+
 			dt.on('selectItems.dt.DT', function (e, ctx, items) {
 				that.active(items === lc);
 			});
@@ -1576,8 +1934,18 @@ DataTable.render.select = function (valueProp, nameProp) {
 		var dtRow = meta.settings.aoData[meta.row];
 		var selected = dtRow._select_selected;
 		var ariaLabel = meta.settings.oLanguage.select.aria.rowCheckbox;
+		var selectable = meta.settings._select.selectable;
 
 		if (type === 'display') {
+			// Check if the row is selectable before showing the checkbox
+			if (selectable) {
+				var result = selectable(row, dtRow.nTr, meta.row);
+	
+				if (result === false) {
+					return '';
+				}
+			}
+
 			return $('<input>')
 				.attr({
 					'aria-label': ariaLabel,
@@ -1636,11 +2004,10 @@ $.fn.DataTable.select = DataTable.select;
  * Initialisation
  */
 
-// DataTables creation - check if select has been defined in the options. Note
-// this required that the table be in the document! If it isn't then something
-// needs to trigger this method unfortunately. The next major release of
-// DataTables will rework the events and address this.
-$(document).on('preInit.dt.dtSelect', function (e, ctx) {
+// DataTables creation - we need this to run _before_ data is read in, but
+// for backwards compat. we also run again on preInit. If it happens twice
+// it will simply do nothing the second time around.
+$(document).on('i18n.dt.dtSelect preInit.dt.dtSelect', function (e, ctx) {
 	if (e.namespace !== 'dt') {
 		return;
 	}