Fixes #4772: added scope for tooltip position mode call and added docs (#4784)

* added scope for tooltip position mode call and added docs

* added test for positioner

* removed named func for lint

* resolved pull-request comments

docs/configuration/tooltip.md

@@ -51,6 +51,28 @@ The tooltip configuration is passed into the `options.tooltips` namespace. The g
 
 New modes can be defined by adding functions to the Chart.Tooltip.positioners map.
 
+Example:
+```javascript
+/**
+ * Custom positioner
+ * @function Chart.Tooltip.positioners.custom
+ * @param elements {Chart.Element[]} the tooltip elements
+ * @param eventPosition {Point} the position of the event in canvas coordinates
+ * @returns {Point} the tooltip position
+ */
+Chart.Tooltip.positioners.custom = function(elements, eventPosition) {
+    /** @type {Chart.Tooltip} */
+    var tooltip = this;
+	    
+    /* ... */
+	    
+    return {
+        x: 0,
+        y: 0
+    };
+}
+```
+
 ### Sort Callback
 
 Allows sorting of [tooltip items](#tooltip-item-interface). Must implement at minimum a function that can be passed to [Array.prototype.sort](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/sort).  This function can also accept a third parameter that is the data object passed to the chart.

src/core/core.tooltip.js

@@ -495,7 +495,7 @@ module.exports = function(Chart) {
 
 				var labelColors = [];
 				var labelTextColors = [];
-				tooltipPosition = Chart.Tooltip.positioners[opts.position](active, me._eventPosition);
+				tooltipPosition = Chart.Tooltip.positioners[opts.position].call(me, active, me._eventPosition);
 
 				var tooltipItems = [];
 				for (i = 0, len = active.length; i < len; ++i) {

test/specs/core.tooltip.tests.js

@@ -822,4 +822,64 @@ describe('Core.Tooltip', function() {
 		node.dispatchEvent(firstEvent);
 		expect(tooltip.update).not.toHaveBeenCalled();
 	});
+
+	describe('positioners', function() {
+		it('Should call custom positioner with correct parameters and scope', function() {
+
+			Chart.Tooltip.positioners.test = function() {
+				return {x: 0, y: 0};
+			};
+
+			spyOn(Chart.Tooltip.positioners, 'test').and.callThrough();
+
+			var chart = window.acquireChart({
+				type: 'line',
+				data: {
+					datasets: [{
+						label: 'Dataset 1',
+						data: [10, 20, 30],
+						pointHoverBorderColor: 'rgb(255, 0, 0)',
+						pointHoverBackgroundColor: 'rgb(0, 255, 0)'
+					}, {
+						label: 'Dataset 2',
+						data: [40, 40, 40],
+						pointHoverBorderColor: 'rgb(0, 0, 255)',
+						pointHoverBackgroundColor: 'rgb(0, 255, 255)'
+					}],
+					labels: ['Point 1', 'Point 2', 'Point 3']
+				},
+				options: {
+					tooltips: {
+						mode: 'nearest',
+						position: 'test'
+					}
+				}
+			});
+
+			// Trigger an event over top of the
+			var pointIndex = 1;
+			var datasetIndex = 0;
+			var meta = chart.getDatasetMeta(datasetIndex);
+			var point = meta.data[pointIndex];
+			var node = chart.canvas;
+			var rect = node.getBoundingClientRect();
+			var evt = new MouseEvent('mousemove', {
+				view: window,
+				bubbles: true,
+				cancelable: true,
+				clientX: rect.left + point._model.x,
+				clientY: rect.top + point._model.y
+			});
+
+			// Manually trigger rather than having an async test
+			node.dispatchEvent(evt);
+
+			var fn = Chart.Tooltip.positioners.test;
+			expect(fn.calls.count()).toBe(1);
+			expect(fn.calls.first().args[0] instanceof Array).toBe(true);
+			expect(fn.calls.first().args[1].hasOwnProperty('x')).toBe(true);
+			expect(fn.calls.first().args[1].hasOwnProperty('y')).toBe(true);
+			expect(fn.calls.first().object instanceof Chart.Tooltip).toBe(true);
+		});
+	});
 });