Support configurable update

docs/developers/api.md

@@ -17,7 +17,7 @@ This must be called before the canvas is reused for a new chart.
 myLineChart.destroy();
 ```
 
-## .update(duration, lazy)
+## .update(config)
 
 Triggers an update of the chart. This can be safely called after updating the data object. This will update all scales, legends, and then re-render the chart.
 
@@ -30,6 +30,23 @@ myLineChart.update(); // Calling update now animates the position of March from
 
 > **Note:** replacing the data reference (e.g. `myLineChart.data = {datasets: [...]}` only works starting **version 2.6**. Prior that, replacing the entire data object could be achieved with the following workaround: `myLineChart.config.data = {datasets: [...]}`.
 
+A `config` object can be provided with additional configuration for the update process. This is useful when `update` is manually called inside an event handler and some different animation is desired.
+
+The following properties are supported:
+* **duration** (number): Time for the animation of the redraw in milliseconds
+* **lazy** (boolean): If true, the animation can be interrupted by other animations
+* **easing** (string): The animation easing function. See [Animation Easing](../configuration/animations.md) for possible values.
+
+Example:
+```javascript
+myChart.update({
+    duration: 800,
+    easing: 'easeOutBounce'
+})
+```
+
+> **Note:** `.update(duration, lazy)` is still supported in backwards compatibility mode.
+
 See [Updating Charts](updates.md) for more details.
 
 ## .reset()
@@ -40,16 +57,24 @@ Reset the chart to it's state before the initial animation. A new animation can
 myLineChart.reset();
 ```
 
-## .render(duration, lazy)
+## .render(config)
 
 Triggers a redraw of all chart elements. Note, this does not update elements for new data. Use `.update()` in that case.
 
+See `.update(config)` for more details on the config object.
+
 ```javascript
 // duration is the time for the animation of the redraw in milliseconds
 // lazy is a boolean. if true, the animation can be interrupted by other animations
-myLineChart.render(duration, lazy);
+myLineChart.render({
+	duration: 800,
+	lazy: false,
+	easing: 'easeOutBounce'
+});
 ```
 
+> **Note:** `.render(duration, lazy)` is still supported in backwards compatibility mode.
+
 ## .stop()
 
 Use this to stop any current animation loop. This will pause the chart during any current animation frame. Call `.render()` to re-animate.

src/core/core.controller.js

@@ -334,9 +334,17 @@ module.exports = function(Chart) {
 			this.tooltip.initialize();
 		},
 
-		update: function(animationDuration, lazy) {
+		update: function(config) {
 			var me = this;
 
+			if (!config || typeof config !== 'object') {
+				// backwards compatibility
+				config = {
+					duration: config,
+					lazy: arguments[1]
+				};
+			}
+
 			updateConfig(me);
 
 			if (plugins.notify(me, 'beforeUpdate') === false) {
@@ -368,11 +376,12 @@ module.exports = function(Chart) {
 
 			if (me._bufferedRender) {
 				me._bufferedRequest = {
-					lazy: lazy,
-					duration: animationDuration
+					duration: config.duration,
+					easing: config.easing,
+					lazy: config.lazy
 				};
 			} else {
-				me.render(animationDuration, lazy);
+				me.render(config);
 			}
 		},
 
@@ -442,9 +451,20 @@ module.exports = function(Chart) {
 			plugins.notify(me, 'afterDatasetUpdate', [args]);
 		},
 
-		render: function(duration, lazy) {
+		render: function(config) {
 			var me = this;
 
+			if (!config || typeof config !== 'object') {
+				// backwards compatibility
+				config = {
+					duration: config,
+					lazy: arguments[1]
+				};
+			}
+
+			var duration = config.duration;
+			var lazy = config.lazy;
+
 			if (plugins.notify(me, 'beforeRender') === false) {
 				return;
 			}
@@ -458,7 +478,7 @@ module.exports = function(Chart) {
 			if (animationOptions && ((typeof duration !== 'undefined' && duration !== 0) || (typeof duration === 'undefined' && animationOptions.duration !== 0))) {
 				var animation = new Chart.Animation({
 					numSteps: (duration || animationOptions.duration) / 16.66, // 60 fps
-					easing: animationOptions.easing,
+					easing: config.easing || animationOptions.easing,
 
 					render: function(chart, animationObject) {
 						var easingFunction = helpers.easingEffects[animationObject.easing];
@@ -771,7 +791,7 @@ module.exports = function(Chart) {
 			var bufferedRequest = me._bufferedRequest;
 			if (bufferedRequest) {
 				// If we have an update that was triggered, we need to do a normal render
-				me.render(bufferedRequest.duration, bufferedRequest.lazy);
+				me.render(bufferedRequest);
 			} else if (changed && !me.animating) {
 				// If entering, leaving, or changing elements, animate the change via pivot
 				me.stop();

test/specs/core.controller.tests.js

@@ -807,4 +807,107 @@ describe('Chart', function() {
 			]);
 		});
 	});
+
+	describe('controller.update', function() {
+		var chart;
+		var renderSpy;
+
+		beforeEach(function() {
+			chart = acquireChart({
+				type: 'line',
+				data: {
+					labels: ['A', 'B', 'C', 'D'],
+					datasets: [{
+						data: [10, 20, 30, 100]
+					}]
+				},
+				options: {
+					responsive: true
+				}
+			});
+
+			renderSpy = spyOn(chart, 'render');
+		});
+
+		describe('when _bufferedRender is true', function() {
+			beforeEach(function() {
+				chart._bufferedRender = true;
+			});
+
+			it('does not call render', function() {
+				chart.update({
+					duration: 800,
+					easing: 'easeOutBounce'
+				});
+
+				expect(renderSpy).not.toHaveBeenCalled();
+			});
+
+			it('builds _bufferedRequest with config properties', function() {
+				chart.update({
+					duration: 800,
+					easing: 'easeOutBounce'
+				});
+
+				expect(chart._bufferedRequest).toEqual({
+					duration: 800,
+					lazy: undefined,
+					easing: 'easeOutBounce'
+				});
+			});
+		});
+
+		describe('when _bufferedRender is false', function() {
+			beforeEach(function() {
+				chart._bufferedRender = false;
+			});
+
+			it('calls render with the config object', function() {
+				chart.update({
+					duration: 800,
+					easing: 'easeOutBounce'
+				});
+
+				expect(renderSpy).toHaveBeenCalledWith({
+					duration: 800,
+					easing: 'easeOutBounce'
+				});
+			});
+		});
+
+		describe('when using backwards compatibility', function() {
+			describe('when _bufferedRender is true', function() {
+				beforeEach(function() {
+					chart._bufferedRender = true;
+				});
+
+				it('does not call render', function() {
+					chart.update(800, false);
+
+					expect(renderSpy).not.toHaveBeenCalled();
+				});
+
+				it('builds _bufferedRequest with duration and lazy properties', function() {
+					chart.update(800, false);
+
+					expect(chart._bufferedRequest).toEqual({
+						duration: 800,
+						lazy: false,
+						easing: undefined
+					});
+				});
+			});
+
+			describe('when _bufferedRender is false', function() {
+				it('calls render with duration and lazy properties', function() {
+					chart.update(800, true);
+
+					expect(renderSpy).toHaveBeenCalledWith({
+						duration: 800,
+						lazy: true
+					});
+				});
+			});
+		});
+	});
 });