Add layout.shapes.layer

* Added functionality to show layer below traces.

* The axis references of a 'below'-shape determine the subplots under
  which a shape is shown.

* If both axis references of a 'below'-shape are set to 'paper', then
  the shape is shown below all the subplots.

* Updated `test/image/mocks/shapes.json` to exercise the new
  functionality.

* Updated `test/jasmine/tests/shapes_test.js` to account for the new
  shape layers.

Author: n-riesco

src/components/shapes/attributes.js

@@ -38,6 +38,14 @@ module.exports = {
         ].join(' ')
     },
 
+    layer: {
+        valType: 'enumerated',
+        values: ['below', 'above'],
+        dflt: 'above',
+        role: 'info',
+        description: 'Specifies whether shapes are drawn below or above traces.'
+    },
+
     xref: extendFlat({}, annAttrs.xref, {
         description: [
             'Sets the shape\'s x coordinate axis.',

src/components/shapes/index.js

@@ -34,6 +34,7 @@ function handleShapeDefaults(shapeIn, fullLayout) {
                                  attr, dflt);
     }
 
+    coerce('layer');
     coerce('opacity');
     coerce('fillcolor');
     coerce('line.color');
@@ -167,7 +168,8 @@ function updateAllShapes(gd, opt, value) {
 }
 
 function deleteShape(gd, index) {
-    gd._fullLayout._shapelayer.selectAll('[data-index="' + index + '"]')
+    getShapeLayer(gd, index)
+        .selectAll('[data-index="' + index + '"]')
         .remove();
 
     gd._fullLayout.shapes.splice(index, 1);
@@ -177,9 +179,9 @@ function deleteShape(gd, index) {
     for(var i = index; i < gd._fullLayout.shapes.length; i++) {
         // redraw all shapes past the removed one,
         // so they bind to the right events
-        gd._fullLayout._shapelayer
-            .selectAll('[data-index="' + (i+1) + '"]')
-            .attr('data-index', String(i));
+        getShapeLayer(gd, i)
+            .selectAll('[data-index="' + (i + 1) + '"]')
+            .attr('data-index', i);
         shapes.draw(gd, i);
     }
 }
@@ -197,10 +199,13 @@ function insertShape(gd, index, newShape) {
         gd.layout.shapes = [rule];
     }
 
+    // there is no need to call shapes.draw(gd, index),
+    // because updateShape() is called from within shapes.draw()
+
     for(var i = gd._fullLayout.shapes.length - 1; i > index; i--) {
-        gd._fullLayout._shapelayer
+        getShapeLayer(gd, i)
             .selectAll('[data-index="' + (i - 1) + '"]')
-            .attr('data-index', String(i));
+            .attr('data-index', i);
         shapes.draw(gd, i);
     }
 }
@@ -209,7 +214,8 @@ function updateShape(gd, index, opt, value) {
     var i;
 
     // remove the existing shape if there is one
-    gd._fullLayout._shapelayer.selectAll('[data-index="' + index + '"]')
+    getShapeLayer(gd, index)
+        .selectAll('[data-index="' + index + '"]')
         .remove();
 
     // remember a few things about what was already there,
@@ -284,24 +290,73 @@ function updateShape(gd, index, opt, value) {
     gd._fullLayout.shapes[index] = options;
 
     var attrs = {
-            'data-index': String(index),
+            'data-index': index,
             'fill-rule': 'evenodd',
             d: shapePath(gd, options)
         },
         clipAxes = (options.xref + options.yref).replace(/paper/g, '');
 
     var lineColor = options.line.width ? options.line.color : 'rgba(0,0,0,0)';
 
-    var path = gd._fullLayout._shapelayer.append('path')
-        .attr(attrs)
-        .style('opacity', options.opacity)
-        .call(Plotly.Color.stroke, lineColor)
-        .call(Plotly.Color.fill, options.fillcolor)
-        .call(Plotly.Drawing.dashLine, options.line.dash, options.line.width);
+    if(options.layer !== 'below') {
+        drawShape(gd._fullLayout._shapeUpperLayer);
+    }
+    else if(options.xref === 'paper' && options.yref === 'paper') {
+        drawShape(gd._fullLayout._shapeLowerLayer);
+    } else {
+        forEachSubplot(gd, function(plotinfo) {
+            if(isShapeInSubplot(gd, options, plotinfo.id)) {
+                drawShape(plotinfo.shapelayer);
+            }
+        });
+    }
+
+    return;
+
+    function drawShape(shapeLayer) {
+        var path = shapeLayer.append('path')
+            .attr(attrs)
+            .style('opacity', options.opacity)
+            .call(Plotly.Color.stroke, lineColor)
+            .call(Plotly.Color.fill, options.fillcolor)
+            .call(Plotly.Drawing.dashLine, options.line.dash,
+                options.line.width);
+
+        if(clipAxes) {
+            path.call(Plotly.Drawing.setClipUrl,
+                'clip' + gd._fullLayout._uid + clipAxes);
+        }
+    }
+}
+
+function getShapeLayer(gd, index) {
+    var shape = gd._fullLayout.shapes[index],
+        shapeLayer = gd._fullLayout._shapeUpperLayer;
+
+    if(!shape) {
+        console.log('getShapeLayer: undefined shape: index', index);
+    }
+    else if(shape.layer === 'below') {
+        shapeLayer = (shape.xref === 'paper' && shape.yref === 'paper') ?
+            gd._fullLayout._shapeLowerLayer :
+            gd._fullLayout._subplotShapeLayer;
+    }
+
+    return shapeLayer;
+}
+
+function isShapeInSubplot(gd, shape, subplot) {
+    var xa = Plotly.Axes.getFromId(gd, subplot, 'x')._id,
+        ya = Plotly.Axes.getFromId(gd, subplot, 'y')._id;
+    return shape.layer === 'below' && (xa === shape.xref || ya === shape.yref);
+}
+
+function forEachSubplot(gd, fn) {
+    var plots = gd._fullLayout._plots || {},
+        subplots = Object.getOwnPropertyNames(plots);
 
-    if(clipAxes) {
-        path.call(Plotly.Drawing.setClipUrl,
-            'clip' + gd._fullLayout._uid + clipAxes);
+    for(var i = 0, n = subplots.length; i < n; i++) {
+        fn(plots[subplots[i]]);
     }
 }
 

src/plot_api/plot_api.js

@@ -2615,16 +2615,27 @@ function makePlotFramework(gd) {
     fullLayout._draggers = fullLayout._paper.append('g')
         .classed('draglayer', true);
 
+    // lower shape layer
+    // (only for shapes to be drawn below the whole plot)
+    fullLayout._shapeLowerLayer = fullLayout._paper.append('g')
+        .classed('shapelayer shapelayer-below', true);
+
     var subplots = Plotly.Axes.getSubplots(gd);
     if(subplots.join('') !== Object.keys(gd._fullLayout._plots || {}).join('')) {
         makeSubplots(gd, subplots);
     }
 
     if(fullLayout._hasCartesian) makeCartesianPlotFramwork(gd, subplots);
 
-    // single ternary, shape and pie layers for the whole plot
+    // single ternary layer for the whole plot
     fullLayout._ternarylayer = fullLayout._paper.append('g').classed('ternarylayer', true);
-    fullLayout._shapelayer = fullLayout._paper.append('g').classed('shapelayer', true);
+
+    // upper shape layer
+    // (only for shapes to be drawn above the whole plot, including subplots)
+    fullLayout._shapeUpperLayer = fullLayout._paper.append('g')
+        .classed('shapelayer shapelayer-above', true);
+
+    // single pie layer for the whole plot
     fullLayout._pielayer = fullLayout._paper.append('g').classed('pielayer', true);
 
     // fill in image server scrape-svg
@@ -2752,6 +2763,10 @@ function makeCartesianPlotFramwork(gd, subplots) {
                 // the plot and containers for overlays
                 plotinfo.bg = plotgroup.append('rect')
                     .style('stroke-width', 0);
+                // shape layer
+                // (only for shapes to be drawn below a subplot)
+                plotinfo.shapelayer = plotgroup.append('g')
+                    .classed('shapelayer shapelayer-subplot', true);
                 plotinfo.gridlayer = plotgroup.append('g');
                 plotinfo.overgrid = plotgroup.append('g');
                 plotinfo.zerolinelayer = plotgroup.append('g');
@@ -2800,6 +2815,10 @@ function makeCartesianPlotFramwork(gd, subplots) {
             .style('fill', 'none')
             .classed('crisp', true);
     });
+
+    // shape layers in subplots
+    fullLayout._subplotShapeLayer = fullLayout._paper
+        .selectAll('.shapelayer-subplot');
 }
 
 // layoutStyles: styling for plot layout elements

test/image/mocks/shapes.json

@@ -21,18 +21,18 @@
         "margin": {"l":20,"r":20,"top":10,"bottom":10,"pad":0},
         "showlegend":false,
         "shapes":[
-            {"xref":"paper","yref":"paper","x0":0,"x1":0.1,"y0":0,"y1":0.1},
+            {"layer":"below","xref":"paper","yref":"paper","x0":0,"x1":0.1,"y0":0,"y1":0.1},
             {"xref":"paper","yref":"paper","path":"M0,0.2V0.3H0.05L0,0.4Q0.1,0.4 0.1,0.3T0.15,0.3C0.1,0.4 0.2,0.4 0.2,0.3S0.15,0.3 0.15,0.2Z","fillcolor":"#4c0"},
             {"xref":"paper","yref":"paper","type":"circle","x0":0.23,"x1":0.3,"y0":0.2,"y1":0.4},
             {"xref":"paper","yref":"paper","type":"line","x0":0.2,"x1":0.3,"y0":0,"y1":0.1},
-            {"x0":0.1,"x1":0.4,"y0":1.5,"y1":20,"opacity":0.5,"fillcolor":"#f00","line":{"width":8,"color":"#008","dash":"dashdot"}},
+            {"layer":"below","x0":0.1,"x1":0.4,"y0":1.5,"y1":20,"opacity":0.5,"fillcolor":"#f00","line":{"width":8,"color":"#008","dash":"dashdot"}},
             {"path":"M0.5,3C0.5,9 0.9,9 0.9,3C0.9,1 0.5,1 0.5,3ZM0.6,4C0.6,5 0.66,5 0.66,4ZM0.74,4C0.74,5 0.8,5 0.8,4ZM0.6,3C0.63,2 0.77,2 0.8,3Z","fillcolor":"#fd2","line":{"width":1,"color":"black"}},
-            {"xref":"x2","yref":"y2","type":"circle","x0":"2000-01-01 02","x1":"2000-01-01 08:30:33.456","y0":0.1,"y1":0.9,"fillcolor":"rgba(0,0,0,0.5)","line":{"color":"rgba(0,255,0,0.5)", "width":5}},
+            {"layer":"below","xref":"x2","yref":"y2","type":"circle","x0":"2000-01-01 02","x1":"2000-01-01 08:30:33.456","y0":0.1,"y1":0.9,"fillcolor":"rgba(0,0,0,0.5)","line":{"color":"rgba(0,255,0,0.5)", "width":5}},
             {"xref":"x2","yref":"y2","path":"M2000-01-01_11:20:45.6,0.2Q2000-01-01_10:00,0.85 2000-01-01_21,0.8Q2000-01-01_22:20,0.15 2000-01-01_11:20:45.6,0.2Z","fillcolor":"rgb(151,73,58)"},
             {"yref":"paper","type":"line","x0":0.1,"x1":0.4,"y0":0,"y1":0.4,"line":{"color":"#009","dash":"dot","width":1}},
             {"yref":"paper","path":"M0.5,0H1.1L0.8,0.4Z","line":{"width":0},"fillcolor":"#ccd3ff"},
             {"xref":"paper","x0":0.1,"x1":0.2,"y0":-1,"y1":3,"fillcolor":"#ccc"},
-            {"xref":"paper","path":"M0.05,4C0.4,12 -0.1,12 0.25,4Z","fillcolor":"#a66"}
+            {"layer":"above","xref":"paper","path":"M0.05,4C0.4,12 -0.1,12 0.25,4Z","fillcolor":"#a66"}
         ]
     }
 }