images: add 'visible' attribute

- ... and make sure that
  layout.images.length === fullLayout.image.length always,
  i.e. item with no source are coerced to { visible: false }
  and skipped during the draw step.

Author: etpinard

src/components/images/attributes.js

@@ -14,6 +14,15 @@ var cartesianConstants = require('../../plots/cartesian/constants');
 module.exports = {
     _isLinkedToArray: true,
 
+    visible: {
+        valType: 'boolean',
+        role: 'info',
+        dflt: true,
+        description: [
+            'Determines whether or not this annotation is visible.'
+        ].join(' ')
+    },
+
     source: {
         valType: 'string',
         role: 'info',

src/components/images/defaults.js

@@ -12,36 +12,34 @@ var Axes = require('../../plots/cartesian/axes');
 var Lib = require('../../lib');
 var attributes = require('./attributes');
 
+var name = 'images';
 
 module.exports = function supplyLayoutDefaults(layoutIn, layoutOut) {
+    var contIn = Array.isArray(layoutIn[name]) ? layoutIn[name] : [],
+        contOut = layoutOut[name] = [];
 
-    if(!layoutIn.images || !Array.isArray(layoutIn.images)) return;
+    for(var i = 0; i < contIn.length; i++) {
+        var itemIn = contIn[i] || {},
+            itemOut = {};
 
+        imageDefaults(itemIn, itemOut, layoutOut);
 
-    var containerIn = layoutIn.images,
-        containerOut = layoutOut.images = [];
-
-
-    for(var i = 0; i < containerIn.length; i++) {
-        var image = containerIn[i];
-
-        if(!image.source) continue;
-
-        var defaulted = imageDefaults(containerIn[i] || {}, containerOut[i] || {}, layoutOut);
-        containerOut.push(defaulted);
+        contOut.push(itemOut);
     }
 };
 
 
 function imageDefaults(imageIn, imageOut, fullLayout) {
 
-    imageOut = imageOut || {};
-
     function coerce(attr, dflt) {
         return Lib.coerce(imageIn, imageOut, attributes, attr, dflt);
     }
 
-    coerce('source');
+    var source = coerce('source');
+    var visible = coerce('visible', !!source);
+
+    if(!visible) return imageOut;
+
     coerce('layer');
     coerce('x');
     coerce('y');
@@ -52,12 +50,12 @@ function imageDefaults(imageIn, imageOut, fullLayout) {
     coerce('sizing');
     coerce('opacity');
 
-    for(var i = 0; i < 2; i++) {
-        var tdMock = { _fullLayout: fullLayout },
-            axLetter = ['x', 'y'][i];
+    var gdMock = { _fullLayout: fullLayout },
+        axLetters = ['x', 'y'];
 
+    for(var i = 0; i < 2; i++) {
         // 'paper' is the fallback axref
-        Axes.coerceRef(imageIn, imageOut, tdMock, axLetter, 'paper');
+        Axes.coerceRef(imageIn, imageOut, gdMock, axLetters[i], 'paper');
     }
 
     return imageOut;

src/components/images/draw.js

@@ -14,25 +14,23 @@ var Axes = require('../../plots/cartesian/axes');
 var xmlnsNamespaces = require('../../constants/xmlns_namespaces');
 
 module.exports = function draw(gd) {
-
     var fullLayout = gd._fullLayout,
         imageDataAbove = [],
         imageDataSubplot = [],
         imageDataBelow = [];
 
-    if(!fullLayout.images) return;
-
-
     // Sort into top, subplot, and bottom layers
     for(var i = 0; i < fullLayout.images.length; i++) {
         var img = fullLayout.images[i];
 
-        if(img.layer === 'below' && img.xref !== 'paper' && img.yref !== 'paper') {
-            imageDataSubplot.push(img);
-        } else if(img.layer === 'above') {
-            imageDataAbove.push(img);
-        } else {
-            imageDataBelow.push(img);
+        if(img.visible) {
+            if(img.layer === 'below' && img.xref !== 'paper' && img.yref !== 'paper') {
+                imageDataSubplot.push(img);
+            } else if(img.layer === 'above') {
+                imageDataAbove.push(img);
+            } else {
+                imageDataBelow.push(img);
+            }
         }
     }
 

test/image/mocks/layout_image.json

@@ -51,6 +51,19 @@
         "opacity": 0.4,
         "layer": "below"
       },
+      {
+          "visible": false,
+          "source": "https://images.plot.ly/language-icons/api-home/python-logo.png",
+          "xref": "x",
+          "yref": "y",
+          "x": 1,
+          "y": 3,
+          "sizex": 2,
+          "sizey": 2,
+          "sizing": "stretch",
+          "opacity": 0.4,
+          "layer": "below"
+      },
       {
         "source": "https://images.plot.ly/language-icons/api-home/matlab-logo.png",
         "xref": "x",

test/jasmine/tests/layout_images_test.js

@@ -27,7 +27,7 @@ describe('Layout images', function() {
 
             Images.supplyLayoutDefaults(layoutIn, layoutOut);
 
-            expect(layoutOut.images.length).toEqual(0);
+            expect(layoutOut.images).toEqual([{ visible: false }]);
         });
 
         it('should reject when not an array', function() {
@@ -40,14 +40,15 @@ describe('Layout images', function() {
 
             Images.supplyLayoutDefaults(layoutIn, layoutOut);
 
-            expect(layoutOut.images).not.toBeDefined();
+            expect(layoutOut.images).toEqual([]);
         });
 
         it('should coerce the correct defaults', function() {
             layoutIn.images[0] = { source: jsLogo };
 
             var expected = {
                 source: jsLogo,
+                visible: true,
                 layer: 'above',
                 x: 0,
                 y: 0,
@@ -319,30 +320,48 @@ describe('Layout images', function() {
                 assertImages(0);
 
                 return Plotly.relayout(gd, 'images[0]', makeImage(jsLogo, 0.1, 0.1));
-            }).then(function() {
+            })
+            .then(function() {
                 assertImages(1);
 
                 return Plotly.relayout(gd, 'images[1]', makeImage(pythonLogo, 0.9, 0.9));
-            }).then(function() {
+            })
+            .then(function() {
                 assertImages(2);
 
                 return Plotly.relayout(gd, 'images[2]', makeImage(pythonLogo, 0.2, 0.5));
-            }).then(function() {
+            })
+            .then(function() {
+                assertImages(3);
+                expect(gd.layout.images.length).toEqual(3);
+
+                return Plotly.relayout(gd, 'images[1].visible', false);
+            })
+            .then(function() {
+                assertImages(2);
+                expect(gd.layout.images.length).toEqual(3);
+
+                return Plotly.relayout(gd, 'images[1].visible', true);
+            })
+            .then(function() {
                 assertImages(3);
                 expect(gd.layout.images.length).toEqual(3);
 
                 return Plotly.relayout(gd, 'images[2]', null);
-            }).then(function() {
+            })
+            .then(function() {
                 assertImages(2);
                 expect(gd.layout.images.length).toEqual(2);
 
                 return Plotly.relayout(gd, 'images[1]', null);
-            }).then(function() {
+            })
+            .then(function() {
                 assertImages(1);
                 expect(gd.layout.images.length).toEqual(1);
 
                 return Plotly.relayout(gd, 'images[0]', null);
-            }).then(function() {
+            })
+            .then(function() {
                 assertImages(0);
                 expect(gd.layout.images).toEqual([]);