Merge pull request #5412 from plotly/make-Plotly.plot-internal

Drop Plotly.plot from the API

src/plot_api/edit_types.js

@@ -18,12 +18,12 @@ var traceOpts = {
     flags: ['calc', 'clearAxisTypes', 'plot', 'style', 'markerSize', 'colorbars'],
     description: [
         'trace attributes should include an `editType` string matching this flaglist.',
-        '*calc* is the most extensive: a full `Plotly.plot` starting by clearing `gd.calcdata`',
+        '*calc* is the most extensive: a full (re)plot starting by clearing `gd.calcdata`',
         'to force it to be regenerated',
         '*clearAxisTypes* resets the types of the axes this trace is on, because new data could',
         'cause the automatic axis type detection to change. Log type will not be cleared, as that',
         'is never automatically chosen so must have been user-specified.',
-        '*plot* calls `Plotly.plot` but without first clearing `gd.calcdata`.',
+        '*plot* (re)plots but without first clearing `gd.calcdata`.',
         '*style* only calls `module.style` (or module.editStyle) for all trace modules and redraws the legend.',
         '*markerSize* is like *style*, but propagate axis-range changes due to scatter `marker.size`',
         '*colorbars* only redraws colorbars.'
@@ -39,9 +39,9 @@ var layoutOpts = {
     ],
     description: [
         'layout attributes should include an `editType` string matching this flaglist.',
-        '*calc* is the most extensive: a full `Plotly.plot` starting by clearing `gd.calcdata`',
+        '*calc* is the most extensive: a full (re)plot starting by clearing `gd.calcdata`',
         'to force it to be regenerated',
-        '*plot* calls `Plotly.plot` but without first clearing `gd.calcdata`.',
+        '*plot* (re)plots but without first clearing `gd.calcdata`.',
         '*legend* only redraws the legend.',
         '*ticks* only redraws axis ticks, labels, and gridlines.',
         '*axrange* minimal sequence when updating axis ranges.',

src/plot_api/index.js

@@ -10,7 +10,7 @@
 
 var main = require('./plot_api');
 
-exports.plot = main.plot;
+exports._doPlot = main._doPlot;
 exports.newPlot = main.newPlot;
 exports.restyle = main.restyle;
 exports.relayout = main.relayout;

src/plot_api/plot_api.js

@@ -41,7 +41,7 @@ var numericNameWarningCount = 0;
 var numericNameWarningCountLimit = 5;
 
 /**
- * Main plot-creation function
+ * Internal plot-creation function
  *
  * @param {string id or DOM element} gd
  *      the id or DOM element of the graph container div
@@ -61,7 +61,7 @@ var numericNameWarningCountLimit = 5;
  *      object containing `data`, `layout`, `config`, and `frames` members
  *
  */
-function plot(gd, data, layout, config) {
+function _doPlot(gd, data, layout, config) {
     var frames;
 
     gd = Lib.getGraphDiv(gd);
@@ -83,7 +83,7 @@ function plot(gd, data, layout, config) {
     // if there's no data or layout, and this isn't yet a plotly plot
     // container, log a warning to help plotly.js users debug
     if(!data && !layout && !Lib.isPlotDiv(gd)) {
-        Lib.warn('Calling Plotly.plot as if redrawing ' +
+        Lib.warn('Calling _doPlot as if redrawing ' +
             'but this container doesn\'t yet have a plot.', gd);
     }
 
@@ -139,7 +139,7 @@ function plot(gd, data, layout, config) {
     var fullLayout = gd._fullLayout;
     var hasCartesian = fullLayout._has('cartesian');
 
-    // so we don't try to re-call Plotly.plot from inside
+    // so we don't try to re-call _doPlot from inside
     // legend and colorbar, if margins changed
     fullLayout._replotting = true;
 
@@ -167,7 +167,7 @@ function plot(gd, data, layout, config) {
     // prepare the data and find the autorange
 
     // generate calcdata, if we need to
-    // to force redoing calcdata, just delete it before calling Plotly.plot
+    // to force redoing calcdata, just delete it before calling _doPlot
     var recalc = !gd.calcdata || gd.calcdata.length !== (gd._fullData || []).length;
     if(recalc) Plots.doCalcdata(gd);
 
@@ -552,7 +552,7 @@ function redraw(gd) {
     helpers.cleanLayout(gd.layout);
 
     gd.calcdata = undefined;
-    return exports.plot(gd).then(function() {
+    return exports._doPlot(gd).then(function() {
         gd.emit('plotly_redraw');
         return gd;
     });
@@ -573,7 +573,7 @@ function newPlot(gd, data, layout, config) {
     Plots.cleanPlot([], {}, gd._fullData || [], gd._fullLayout || {});
 
     Plots.purge(gd);
-    return exports.plot(gd, data, layout, config);
+    return exports._doPlot(gd, data, layout, config);
 }
 
 /**
@@ -1284,7 +1284,7 @@ function restyle(gd, astr, val, _traces) {
     var seq = [];
 
     if(flags.fullReplot) {
-        seq.push(exports.plot);
+        seq.push(exports._doPlot);
     } else {
         seq.push(Plots.previousPromises);
 
@@ -2313,7 +2313,7 @@ function update(gd, traceUpdate, layoutUpdate, _traces) {
         // relayoutFlags.layoutReplot and restyleFlags.fullReplot are true
         seq.push(subroutines.layoutReplot);
     } else if(restyleFlags.fullReplot) {
-        seq.push(exports.plot);
+        seq.push(exports._doPlot);
     } else {
         seq.push(Plots.previousPromises);
         axRangeSupplyDefaultsByPass(gd, relayoutFlags, relayoutSpecs) || Plots.supplyDefaults(gd);
@@ -2705,7 +2705,7 @@ function react(gd, data, layout, config) {
             });
         } else if(restyleFlags.fullReplot || relayoutFlags.layoutReplot || configChanged) {
             gd._fullLayout._skipDefaults = true;
-            seq.push(exports.plot);
+            seq.push(exports._doPlot);
         } else {
             for(var componentType in relayoutFlags.arrays) {
                 var indices = relayoutFlags.arrays[componentType];
@@ -3604,7 +3604,7 @@ function deleteFrames(gd, frameList) {
 }
 
 /**
- * Purge a graph container div back to its initial pre-Plotly.plot state
+ * Purge a graph container div back to its initial pre-_doPlot state
  *
  * @param {string id or DOM element} gd
  *      the id or DOM element of the graph container div
@@ -3627,7 +3627,7 @@ function purge(gd) {
     // remove plot container
     if(fullLayout._container) fullLayout._container.remove();
 
-    // in contrast to Plotly.Plots.purge which does NOT clear _context!
+    // in contrast to _doPlots.purge which does NOT clear _context!
     delete gd._context;
 
     return gd;
@@ -3808,7 +3808,7 @@ exports.moveTraces = moveTraces;
 exports.prependTraces = prependTraces;
 
 exports.newPlot = newPlot;
-exports.plot = plot;
+exports._doPlot = _doPlot;
 exports.purge = purge;
 
 exports.react = react;

src/plot_api/plot_config.js

@@ -10,7 +10,7 @@
 
 /**
  * This will be transferred over to gd and overridden by
- * config args to Plotly.plot.
+ * config args to Plotly.newPlot.
  *
  * The defaults are the appropriate settings for plotly.js,
  * so we get the right experience without any config argument.

src/plot_api/subroutines.js

@@ -536,7 +536,7 @@ exports.doColorBars = function(gd) {
 exports.layoutReplot = function(gd) {
     var layout = gd.layout;
     gd.layout = undefined;
-    return Registry.call('plot', gd, '', layout);
+    return Registry.call('_doPlot', gd, '', layout);
 };
 
 exports.doLegend = function(gd) {

src/plot_api/to_image.js

@@ -229,7 +229,7 @@ function toImage(gd, opts) {
     }
 
     return new Promise(function(resolve, reject) {
-        plotApi.plot(clonedGd, data, layoutImage, configImage)
+        plotApi.newPlot(clonedGd, data, layoutImage, configImage)
             .then(redrawFunc)
             .then(wait)
             .then(convert)

src/plots/mapbox/constants.js

@@ -167,7 +167,7 @@ module.exports = {
         'Missing Mapbox access token.',
         'Mapbox trace type require a Mapbox access token to be registered.',
         'For example:',
-        '  Plotly.plot(gd, data, layout, { mapboxAccessToken: \'my-access-token\' });',
+        '  Plotly.newPlot(gd, data, layout, { mapboxAccessToken: \'my-access-token\' });',
         'More info here: https://www.mapbox.com/help/define-access-token/'
     ].join('\n'),
 

src/plots/plots.js

@@ -124,7 +124,7 @@ plots.previousPromises = function(gd) {
 
 /**
  * Adds the 'Edit chart' link.
- * Note that now Plotly.plot() calls this so it can regenerate whenever it replots
+ * Note that now _doPlot calls this so it can regenerate whenever it replots
  *
  * Add source links to your graph inside the 'showSources' config argument.
  */
@@ -1750,7 +1750,7 @@ plots.purge = function(gd) {
     delete gd.autoplay; // are we doing an action that doesn't go in undo queue?
     delete gd.changed;
 
-    // these get recreated on Plotly.plot anyway, but just to be safe
+    // these get recreated on _doPlot anyway, but just to be safe
     // (and to have a record of them...)
     delete gd._promises;
     delete gd._redrawTimer;
@@ -2077,7 +2077,7 @@ plots.doAutoMargin = function(gd) {
         var maxNumberOfRedraws = 3 * (1 + Object.keys(pushMarginIds).length);
 
         if(fullLayout._redrawFromAutoMarginCount < maxNumberOfRedraws) {
-            return Registry.call('plot', gd);
+            return Registry.call('_doPlot', gd);
         } else {
             fullLayout._size = oldMargins;
             Lib.warn('Too many auto-margin redraws.');

src/snapshot/toimage.js

@@ -61,7 +61,7 @@ function toImage(gd, opts) {
 
     var redrawFunc = helpers.getRedrawFunc(clonedGd);
 
-    Registry.call('plot', clonedGd, clone.data, clone.layout, clone.config)
+    Registry.call('_doPlot', clonedGd, clone.data, clone.layout, clone.config)
         .then(redrawFunc)
         .then(wait)
         .catch(function(err) {

tasks/util/container_commands.js

@@ -3,6 +3,7 @@ var constants = require('./constants');
 var containerCommands = {
     cdHome: 'cd ' + constants.testContainerHome,
     cpIndex: 'cp -f test/image/index.html ../server_app/index.html',
+    replacePlotbyNewPlot: 'sed -i \'s/Plotly.plot/Plotly.newPlot/g\' ../server_app/main.js',
     injectEnv: [
         'sed -i',
         's/process.env.PLOTLY_MAPBOX_DEFAULT_ACCESS_TOKEN/\\\'' + constants.mapboxAccessToken + '\\\'/',
@@ -20,6 +21,7 @@ containerCommands.ping = [
 containerCommands.setup = [
     containerCommands.cpIndex,
     containerCommands.injectEnv,
+    containerCommands.replacePlotbyNewPlot,
     containerCommands.restart,
     containerCommands.ping,
     'sleep 5'

test/jasmine/tests/parcoords_test.js

@@ -1,5 +1,10 @@
 var Plotly = require('@lib/index');
 var Lib = require('@src/lib');
+var Registry = require('@src/registry');
+function _doPlot(gd, fig) {
+    return Registry.call('_doPlot', gd, fig.data, fig.layout);
+}
+
 var d3Select = require('../../strict-d3').select;
 var d3SelectAll = require('../../strict-d3').selectAll;
 var Plots = require('@src/plots/plots');
@@ -668,7 +673,7 @@ describe('parcoords Lifecycle methods', function() {
             .then(function() {
                 expect(gd.data.length).toEqual(1);
                 expect(document.querySelectorAll('.y-axis').length).toEqual(10);
-                return Plotly.plot(gd, mockCopy2);
+                return _doPlot(gd, mockCopy2);
             })
             .then(function() {
                 expect(gd.data.length).toEqual(2);
@@ -737,7 +742,7 @@ describe('parcoords Lifecycle methods', function() {
     });
 
     describe('Having two datasets', function() {
-        it('@gl Two subsequent calls to Plotly.plot should create two parcoords rows', function(done) {
+        it('@gl Two subsequent calls to _doPlot should create two parcoords rows', function(done) {
             var mockCopy = Lib.extendDeep({}, mock);
             var mockCopy2 = Lib.extendDeep({}, mock);
             mockCopy.data[0].domain = {x: [0, 0.45]};
@@ -752,7 +757,7 @@ describe('parcoords Lifecycle methods', function() {
                     expect(document.querySelectorAll('.gl-container').length).toEqual(1);
                     expect(gd.data.length).toEqual(1);
 
-                    return Plotly.plot(gd, mockCopy2);
+                    return _doPlot(gd, mockCopy2);
                 })
                 .then(function() {
                     expect(1).toEqual(1);
@@ -944,15 +949,15 @@ describe('parcoords basic use', function() {
         .then(done, done.fail);
     });
 
-    it('@gl Calling `Plotly.plot` again should add the new parcoords', function(done) {
+    it('@gl Calling _doPlot again should add the new parcoords', function(done) {
         var reversedMockCopy = Lib.extendDeep({}, mockCopy);
         reversedMockCopy.data[0].dimensions = reversedMockCopy.data[0].dimensions.slice().reverse();
         reversedMockCopy.data[0].dimensions.forEach(function(d) {d.id = 'R_' + d.id;});
         reversedMockCopy.data[0].dimensions.forEach(function(d) {d.label = 'R_' + d.label;});
 
         Plotly.react(gd, mockCopy)
         .then(function() {
-            return Plotly.plot(gd, reversedMockCopy);
+            return _doPlot(gd, reversedMockCopy);
         })
         .then(function() {
             expect(gd.data.length).toEqual(2);

test/jasmine/tests/plot_api_react_test.js

@@ -37,7 +37,7 @@ describe('@noCIdep Plotly.react', function() {
     beforeEach(function() {
         gd = createGraphDiv();
 
-        spyOn(plotApi, 'plot').and.callThrough();
+        spyOn(plotApi, '_doPlot').and.callThrough();
         spyOn(Registry, 'call').and.callThrough();
 
         mockedMethods.forEach(function(m) {
@@ -54,7 +54,7 @@ describe('@noCIdep Plotly.react', function() {
     afterEach(destroyGraphDiv);
 
     function countPlots() {
-        plotApi.plot.calls.reset();
+        plotApi._doPlot.calls.reset();
         subroutines.layoutStyles.calls.reset();
         annotations.draw.calls.reset();
         annotations.drawOne.calls.reset();
@@ -73,13 +73,13 @@ describe('@noCIdep Plotly.react', function() {
             subroutines[m].calls.reset();
         });
 
-        // calls to Plotly.newPlot via plot_api.js or Registry.call('plot')
-        var plotCalls = plotApi.plot.calls.count() +
+        // calls to Plotly.newPlot via plot_api.js or Registry.call('_doPlot')
+        var plotCalls = plotApi._doPlot.calls.count() +
             Registry.call.calls.all()
-                .filter(function(d) { return d.args[0] === 'plot'; })
+                .filter(function(d) { return d.args[0] === '_doPlot'; })
                 .length;
         expect(plotCalls).toBe(counts.plot || 0, 'Plotly.newPlot calls');
-        plotApi.plot.calls.reset();
+        plotApi._doPlot.calls.reset();
         Registry.call.calls.reset();
 
         // only consider annotation and image draw calls if we *don't* do a full plot.