add 'layer' axis attribute

- has 2 possible values: 'above traces' and 'below traces' for now, but opens the door for other values down the road.
plotly · etpinard · Jul 13, 2017 · Jul 7, 2017 · Jul 7, 2017 · Jul 7, 2017
commit 1c85de675ada7c46b688e49034612439a4178dc2
diff --git a/src/plots/cartesian/constants.js b/src/plots/cartesian/constants.js
@@ -65,5 +65,10 @@ module.exports = {
         'carpetlayer',
         'boxlayer',
         'scatterlayer'
-    ]
+    ],
+
+    layerValue2layerClass: {
+        'above traces': 'above',
+        'below traces': 'below'
+    }
 };
diff --git a/src/plots/cartesian/index.js b/src/plots/cartesian/index.js
@@ -296,6 +296,8 @@ function makeSubplotData(gd) {
 function makeSubplotLayer(plotinfo) {
     var plotgroup = plotinfo.plotgroup;
     var id = plotinfo.id;
+    var xLayer = constants.layerValue2layerClass[plotinfo.xaxis.layer];
+    var yLayer = constants.layerValue2layerClass[plotinfo.yaxis.layer];
 
     if(!plotinfo.mainplot) {
         var backLayer = joinLayer(plotgroup, 'g', 'layer-subplot');
@@ -308,19 +310,36 @@ function makeSubplotLayer(plotinfo) {
         plotinfo.zerolinelayer = joinLayer(plotgroup, 'g', 'zerolinelayer');
         plotinfo.overzero = joinLayer(plotgroup, 'g', 'overzero');
 
+        joinLayer(plotgroup, 'path', 'xlines-below');
+        joinLayer(plotgroup, 'path', 'ylines-below');
+        plotinfo.overlinesBelow = joinLayer(plotgroup, 'g', 'overlines-below');
+
+        joinLayer(plotgroup, 'g', 'xaxislayer-below');
+        joinLayer(plotgroup, 'g', 'yaxislayer-below');
+        plotinfo.overaxesBelow = joinLayer(plotgroup, 'g', 'overaxes-below');
+
         plotinfo.plot = joinLayer(plotgroup, 'g', 'plot');
         plotinfo.overplot = joinLayer(plotgroup, 'g', 'overplot');
 
-        plotinfo.xlines = joinLayer(plotgroup, 'path', 'xlines');
-        plotinfo.ylines = joinLayer(plotgroup, 'path', 'ylines');
-        plotinfo.overlines = joinLayer(plotgroup, 'g', 'overlines');
+        joinLayer(plotgroup, 'path', 'xlines-above');
+        joinLayer(plotgroup, 'path', 'ylines-above');
+        plotinfo.overlinesAbove = joinLayer(plotgroup, 'g', 'overlines-above');
+
+        joinLayer(plotgroup, 'g', 'xaxislayer-above');
+        joinLayer(plotgroup, 'g', 'yaxislayer-above');
+        plotinfo.overaxesAbove = joinLayer(plotgroup, 'g', 'overaxes-above');
 
-        plotinfo.xaxislayer = joinLayer(plotgroup, 'g', 'xaxislayer');
-        plotinfo.yaxislayer = joinLayer(plotgroup, 'g', 'yaxislayer');
-        plotinfo.overaxes = joinLayer(plotgroup, 'g', 'overaxes');
+        // set refs to correct layers as determined by 'axis.layer'
+        plotinfo.xlines = plotgroup.select('.xlines-' + xLayer);
+        plotinfo.ylines = plotgroup.select('.ylines-' + yLayer);
+        plotinfo.xaxislayer = plotgroup.select('.xaxislayer-' + xLayer);
+        plotinfo.yaxislayer = plotgroup.select('.yaxislayer-' + yLayer);
     }
     else {
         var mainplotinfo = plotinfo.mainplotinfo;
+        var mainplotgroup = mainplotinfo.plotgroup;
+        var xId = id + '-x';
+        var yId = id + '-y';
 
         // now make the components of overlaid subplots
         // overlays don't have backgrounds, and append all
@@ -330,11 +349,23 @@ function makeSubplotLayer(plotinfo) {
         plotinfo.gridlayer = joinLayer(mainplotinfo.overgrid, 'g', id);
         plotinfo.zerolinelayer = joinLayer(mainplotinfo.overzero, 'g', id);
 
+        joinLayer(mainplotinfo.overlinesBelow, 'path', xId);
+        joinLayer(mainplotinfo.overlinesBelow, 'path', yId);
+        joinLayer(mainplotinfo.overaxesBelow, 'g', xId);
+        joinLayer(mainplotinfo.overaxesBelow, 'g', yId);
+
         plotinfo.plot = joinLayer(mainplotinfo.overplot, 'g', id);
-        plotinfo.xlines = joinLayer(mainplotinfo.overlines, 'path', id + '-x');
-        plotinfo.ylines = joinLayer(mainplotinfo.overlines, 'path', id + '-y');
-        plotinfo.xaxislayer = joinLayer(mainplotinfo.overaxes, 'g', id + '-x');
-        plotinfo.yaxislayer = joinLayer(mainplotinfo.overaxes, 'g', id + '-y');
+
+        joinLayer(mainplotinfo.overlinesAbove, 'path', xId);
+        joinLayer(mainplotinfo.overlinesAbove, 'path', yId);
+        joinLayer(mainplotinfo.overaxesAbove, 'g', xId);
+        joinLayer(mainplotinfo.overaxesAbove, 'g', yId);
+
+        // set refs to correct layers as determined by 'abovetraces'
+        plotinfo.xlines = mainplotgroup.select('.overlines-' + xLayer).select('.' + xId);
+        plotinfo.ylines = mainplotgroup.select('.overlines-' + yLayer).select('.' + yId);
+        plotinfo.xaxislayer = mainplotgroup.select('.overaxes-' + xLayer).select('.' + xId);
+        plotinfo.yaxislayer = mainplotgroup.select('.overaxes-' + yLayer).select('.' + yId);
     }
 
     // common attributes for all subplots, overlays or not

diff --git a/src/plots/cartesian/layout_attributes.js b/src/plots/cartesian/layout_attributes.js
@@ -573,6 +573,18 @@ module.exports = {
             'If *false*, this axis does not overlay any same-letter axes.'
         ].join(' ')
     },
+    layer: {
+        valType: 'enumerated',
+        values: ['above traces', 'below traces'],
+        dflt: 'above traces',
+        role: 'info',
+        description: [
+            'Sets the layer on which this axis is displayed.',
+            'If *above traces*, this axis is displayed above all the subplot\'s traces',
+            'If *below traces*, this axis is displayed below all the subplot\'s traces,',
+            'but above the grid lines.'
+        ].join(' ')
+    },
     domain: {
         valType: 'info_array',
         role: 'info',

diff --git a/src/plots/cartesian/position_defaults.js b/src/plots/cartesian/position_defaults.js
@@ -59,5 +59,7 @@ module.exports = function handlePositionDefaults(containerIn, containerOut, coer
         Lib.noneOrAll(containerIn.domain, containerOut.domain, [0, 1]);
     }
 
+    coerce('layer');
+
     return containerOut;
 };
diff --git a/src/plots/plots.js b/src/plots/plots.js
@@ -638,24 +638,35 @@ plots.linkSubplots = function(newFullData, newFullLayout, oldFullData, oldFullLa
     var ids = Plotly.Axes.getSubplots(mockGd);
 
     for(var i = 0; i < ids.length; i++) {
-        var id = ids[i],
-            oldSubplot = oldSubplots[id],
-            plotinfo;
+        var id = ids[i];
+        var oldSubplot = oldSubplots[id];
+        var xaxis = Plotly.Axes.getFromId(mockGd, id, 'x');
+        var yaxis = Plotly.Axes.getFromId(mockGd, id, 'y');
+        var plotinfo;
 
         if(oldSubplot) {
             plotinfo = newSubplots[id] = oldSubplot;
 
             if(plotinfo._scene2d) {
                 plotinfo._scene2d.updateRefs(newFullLayout);
             }
-        }
-        else {
+
+            if(plotinfo.xaxis.layer !== xaxis.layer) {
+                plotinfo.xlines.attr('d', null);
+                plotinfo.xaxislayer.selectAll('*').remove();
+            }
+
+            if(plotinfo.yaxis.layer !== yaxis.layer) {
+                plotinfo.ylines.attr('d', null);
+                plotinfo.yaxislayer.selectAll('*').remove();
+            }
+        } else {
             plotinfo = newSubplots[id] = {};
             plotinfo.id = id;
         }
 
-        plotinfo.xaxis = Plotly.Axes.getFromId(mockGd, id, 'x');
-        plotinfo.yaxis = Plotly.Axes.getFromId(mockGd, id, 'y');
+        plotinfo.xaxis = xaxis;
+        plotinfo.yaxis = yaxis;
 
         // By default, we clip at the subplot level,
         // but if one trace on a given subplot has *cliponaxis* set to false,

diff --git a/test/jasmine/tests/cartesian_test.js b/test/jasmine/tests/cartesian_test.js
@@ -403,4 +403,79 @@ describe('subplot creation / deletion:', function() {
         .catch(failTest)
         .then(done);
     });
+
+    it('should clear obsolete content out of axis layers when relayout\'ing *layer*', function(done) {
+        var fig = Lib.extendDeep({}, require('@mocks/overlaying-axis-lines.json'));
+
+        function assertPathDatum(sel, expected, msg) {
+            expect(sel.attr('d') === null ? false : true).toBe(expected, msg);
+        }
+
+        function assertChildrenCnt(sel, expected, msg) {
+            expect(sel.selectAll('*').size()).toBe(expected, msg);
+        }
+
+        function _assert(xBelow, yBelow, xAbove, yAbove) {
+            var g = d3.select('.subplot.xy');
+
+            assertPathDatum(g.select('.xlines-below'), xBelow[0], 'xlines below');
+            assertChildrenCnt(g.select('.xaxislayer-below'), xBelow[1], 'xaxislayer below');
+
+            assertPathDatum(g.select('.ylines-below'), yBelow[0], 'ylines below');
+            assertChildrenCnt(g.select('.yaxislayer-below'), yBelow[1], 'yaxislayer below');
+
+            assertPathDatum(g.select('.xlines-above'), xAbove[0], 'xlines above');
+            assertChildrenCnt(g.select('.xaxislayer-above'), xAbove[1], 'xaxislayer above');
+
+            assertPathDatum(g.select('.ylines-above'), yAbove[0], 'ylines above');
+            assertChildrenCnt(g.select('.yaxislayer-above'), yAbove[1], 'yaxislayer above');
+        }
+
+        Plotly.plot(gd, fig).then(function() {
+            _assert(
+                [false, 0],
+                [false, 0],
+                [true, 10],
+                [true, 10]
+            );
+            return Plotly.relayout(gd, 'xaxis.layer', 'below traces');
+        })
+        .then(function() {
+            _assert(
+                [true, 10],
+                [false, 0],
+                [false, 0],
+                [true, 10]
+            );
+            return Plotly.relayout(gd, 'yaxis.layer', 'below traces');
+        })
+        .then(function() {
+            _assert(
+                [true, 10],
+                [true, 10],
+                [false, 0],
+                [false, 0]
+            );
+            return Plotly.relayout(gd, { 'xaxis.layer': null, 'yaxis.layer': null });
+        })
+        .then(function() {
+            _assert(
+                [false, 0],
+                [false, 0],
+                [true, 10],
+                [true, 10]
+            );
+            return Plotly.relayout(gd, { 'xaxis.layer': 'below traces', 'yaxis.layer': 'below traces' });
        })
+        .then(function() {
+            _assert(
+                [true, 10],
+                [true, 10],
+                [false, 0],
+                [false, 0]
+            );
+        })
+        .catch(failTest)
+        .then(done);
+    });
 });
diff --git a/test/jasmine/tests/plots_test.js b/test/jasmine/tests/plots_test.js
@@ -1,5 +1,6 @@
 var Plotly = require('@lib/index');
 var Plots = require('@src/plots/plots');
+var Lib = require('@src/lib');
 
 var d3 = require('d3');
 var createGraphDiv = require('../assets/create_graph_div');
@@ -38,13 +39,18 @@ describe('Test Plots', function() {
 
             var oldFullLayout = {
                 _plots: { xy: { plot: {} } },
-                xaxis: { c2p: function() {} },
-                yaxis: { _m: 20 },
+                xaxis: { c2p: function() {}, layer: 'above traces' },
+                yaxis: { _m: 20, layer: 'above traces' },
                 scene: { _scene: {} },
                 annotations: [{ _min: 10, }, { _max: 20 }],
                 someFunc: function() {}
             };
 
+            Lib.extendFlat(oldFullLayout._plots.xy, {
+                xaxis: oldFullLayout.xaxis,
+                yaxis: oldFullLayout.yaxis
+            });
+
             var newData = [{
                 type: 'scatter3d',
                 z: [1, 2, 3, 4]