New datasets update plugin extensions

Add `beforeDatasetsUpdate` and `afterDatasetsUpdate` plugin notifications during the chart update. Plugins are able to cancel the datasets update by explicitly returning false to `beforeDatasetsUpdate`. For consistency, rename `(before|after)DatasetDraw` to `(before|after)DatasetsDraw`.

diff --git a/docs/09-Advanced.md b/docs/09-Advanced.md
index 952ec88f51badf944de859ff347487165fde3980..58dd50da996ad5825c53443e88c726aea57be130 100644 (file)
--- a/docs/09-Advanced.md
+++ b/docs/09-Advanced.md
@@ -378,6 +378,8 @@ Plugins will be called at the following times
 * End of initialization
 * Start of update
 * After the chart scales have calculated
+* Start of datasets update
+* End of datasets update
 * End of update (before render occurs)
 * Start of draw
 * End of draw
@@ -396,9 +398,11 @@ Plugins should derive from Chart.PluginBase and implement the following interfac
 
        beforeUpdate: function(chartInstance) { },
        afterScaleUpdate: function(chartInstance) { }
+       beforeDatasetsUpdate: function(chartInstance) { }
+       afterDatasetsUpdate: function(chartInstance) { }
        afterUpdate: function(chartInstance) { },
 
-       // This is called at the start of a render. It is only called once, even if the animation will run for a number of frames. Use beforeDraw or afterDraw 
+       // This is called at the start of a render. It is only called once, even if the animation will run for a number of frames. Use beforeDraw or afterDraw
        // to do something on each animation frame
        beforeRender: function(chartInstance) { },
 
@@ -406,8 +410,8 @@ Plugins should derive from Chart.PluginBase and implement the following interfac
        beforeDraw: function(chartInstance, easing) { },
        afterDraw: function(chartInstance, easing) { },
        // Before the datasets are drawn but after scales are drawn
-       beforeDatasetDraw: function(chartInstance, easing) { },
-       afterDatasetDraw: function(chartInstance, easing) { },
+       beforeDatasetsDraw: function(chartInstance, easing) { },
+       afterDatasetsDraw: function(chartInstance, easing) { },
 
        destroy: function(chartInstance) { }
 }

diff --git a/src/core/core.controller.js b/src/core/core.controller.js
index eb472d63cc1376ed5319e9f4e2d36a26185a3733..2d0148b7749ce9b5b0b4c517b481b1f3a06175e6 100644 (file)
--- a/src/core/core.controller.js
+++ b/src/core/core.controller.js
@@ -13,7 +13,10 @@ module.exports = function(Chart) {
        // Controllers available for dataset visualization eg. bar, line, slice, etc.
        Chart.controllers = {};
 
-       // The main controller of a chart
+       /**
+        * @class Chart.Controller
+        * The main controller of a chart.
+        */
        Chart.Controller = function(instance) {
 
                this.chart = instance;
@@ -40,7 +43,7 @@ module.exports = function(Chart) {
                return this;
        };
 
-       helpers.extend(Chart.Controller.prototype, {
+       helpers.extend(Chart.Controller.prototype, /** @lends Chart.Controller */ {
 
                initialize: function initialize() {
                        var me = this;
@@ -248,10 +251,7 @@ module.exports = function(Chart) {
                                controller.reset();
                        });
 
-                       // This will loop through any data and do the appropriate element update for the type
-                       helpers.each(me.data.datasets, function(dataset, datasetIndex) {
-                               me.getDatasetMeta(datasetIndex).controller.update();
-                       }, me);
+                       me.updateDatasets();
 
                        // Do this before render so that any plugins that need final scale updates can use it
                        Chart.plugins.notify('afterUpdate', [me]);
@@ -259,6 +259,47 @@ module.exports = function(Chart) {
                        me.render(animationDuration, lazy);
                },
 
+               /**
+                * @method beforeDatasetsUpdate
+                * @description Called before all datasets are updated. If a plugin returns false,
+                * the datasets update will be cancelled until another chart update is triggered.
+                * @param {Object} instance the chart instance being updated.
+                * @returns {Boolean} false to cancel the datasets update.
+                * @memberof Chart.PluginBase
+                * @since version 2.1.5
+                * @instance
+                */
+
+               /**
+                * @method afterDatasetsUpdate
+                * @description Called after all datasets have been updated. Note that this
+                * extension will not be called if the datasets update has been cancelled.
+                * @param {Object} instance the chart instance being updated.
+                * @memberof Chart.PluginBase
+                * @since version 2.1.5
+                * @instance
+                */
+
+               /**
+                * Updates all datasets unless a plugin returns false to the beforeDatasetsUpdate
+                * extension, in which case no datasets will be updated and the afterDatasetsUpdate
+                * notification will be skipped.
+                * @protected
+                * @instance
+                */
+               updateDatasets: function() {
+                       var me = this;
+                       var i, ilen;
+
+                       if (Chart.plugins.notify('beforeDatasetsUpdate', [ me ])) {
+                               for (i = 0, ilen = me.data.datasets.length; i < ilen; ++i) {
+                                       me.getDatasetMeta(i).controller.update();
+                               }
+
+                               Chart.plugins.notify('afterDatasetsUpdate', [ me ]);
+                       }
+               },
+
                render: function render(duration, lazy) {
                        var me = this;
                        Chart.plugins.notify('beforeRender', [me]);
@@ -307,7 +348,7 @@ module.exports = function(Chart) {
                                me.scale.draw();
                        }
 
-                       Chart.plugins.notify('beforeDatasetDraw', [me, easingDecimal]);
+                       Chart.plugins.notify('beforeDatasetsDraw', [me, easingDecimal]);
 
                        // Draw each dataset via its respective controller (reversed to support proper line stacking)
                        helpers.each(me.data.datasets, function(dataset, datasetIndex) {
@@ -316,7 +357,7 @@ module.exports = function(Chart) {
                                }
                        }, me, true);
 
-                       Chart.plugins.notify('afterDatasetDraw', [me, easingDecimal]);
+                       Chart.plugins.notify('afterDatasetsDraw', [me, easingDecimal]);
 
                        // Finally draw the tooltip
                        me.tooltip.transition(easingDecimal).draw();

diff --git a/src/core/core.plugin.js b/src/core/core.plugin.js
index 5fce4007715448f0c4952aaf08ba770dc0c491ff..d6f95c4d11782d55d856da87decfd168d4425529 100644 (file)
--- a/src/core/core.plugin.js
+++ b/src/core/core.plugin.js
@@ -91,9 +91,12 @@ module.exports = function(Chart) {
                }
        };
 
+       /**
+        * Plugin extension methods.
+        * @interface Chart.PluginBase
+        * @since 2.1.0
+        */
        Chart.PluginBase = Chart.Element.extend({
-               // Plugin extensions. All functions are passed the chart instance
-
                // Called at start of chart init
                beforeInit: noop,