templates - big commit implementing most of it, coerce-level integration

src/components/colorbar/defaults.js

@@ -10,6 +10,8 @@
 'use strict';
 
 var Lib = require('../../lib');
+var Template = require('../../plot_api/plot_template');
+
 var handleTickValueDefaults = require('../../plots/cartesian/tick_value_defaults');
 var handleTickMarkDefaults = require('../../plots/cartesian/tick_mark_defaults');
 var handleTickLabelDefaults = require('../../plots/cartesian/tick_label_defaults');
@@ -18,7 +20,7 @@ var attributes = require('./attributes');
 
 
 module.exports = function colorbarDefaults(containerIn, containerOut, layout) {
-    var colorbarOut = containerOut.colorbar = {},
+    var colorbarOut = Template.newContainer(containerOut, 'colorbar'),
         colorbarIn = containerIn.colorbar || {};
 
     function coerce(attr, dflt) {

src/components/errorbars/defaults.js

@@ -12,14 +12,15 @@ var isNumeric = require('fast-isnumeric');
 
 var Registry = require('../../registry');
 var Lib = require('../../lib');
+var Template = require('../../plot_api/plot_template');
 
 var attributes = require('./attributes');
 
 
 module.exports = function(traceIn, traceOut, defaultColor, opts) {
-    var objName = 'error_' + opts.axis,
-        containerOut = traceOut[objName] = {},
-        containerIn = traceIn[objName] || {};
+    var objName = 'error_' + opts.axis;
+    var containerOut = Template.newContainer(traceOut, objName);
+    var containerIn = traceIn[objName] || {};
 
     function coerce(attr, dflt) {
         return Lib.coerce(containerIn, containerOut, attributes, attr, dflt);

src/components/grid/index.js

@@ -12,6 +12,7 @@ var Lib = require('../../lib');
 var counterRegex = require('../../lib/regex').counter;
 var domainAttrs = require('../../plots/domain').attributes;
 var cartesianIdRegex = require('../../plots/cartesian/constants').idRegex;
+var Template = require('../../plot_api/plot_template');
 
 var gridAttrs = {
     rows: {
@@ -201,7 +202,7 @@ function sizeDefaults(layoutIn, layoutOut) {
         if(hasXaxes) dfltColumns = xAxes.length;
     }
 
-    var gridOut = {};
+    var gridOut = Template.newContainer(layoutOut, 'grid');
 
     function coerce(attr, dflt) {
         return Lib.coerce(gridIn, gridOut, gridAttrs, attr, dflt);
@@ -210,7 +211,10 @@ function sizeDefaults(layoutIn, layoutOut) {
     var rows = coerce('rows', dfltRows);
     var columns = coerce('columns', dfltColumns);
 
-    if(!(rows * columns > 1)) return;
+    if(!(rows * columns > 1)) {
+        delete layoutOut.grid;
+        return;
+    }
 
     if(!hasSubplotGrid && !hasXaxes && !hasYaxes) {
         var useDefaultSubplots = coerce('pattern') === 'independent';
@@ -234,8 +238,6 @@ function sizeDefaults(layoutIn, layoutOut) {
         x: fillGridPositions('x', coerce, dfltGapX, dfltSideX, columns),
         y: fillGridPositions('y', coerce, dfltGapY, dfltSideY, rows, reversed)
     };
-
-    layoutOut.grid = gridOut;
 }
 
 // coerce x or y sizing attributes and return an array of domains for this direction

src/components/legend/defaults.js

@@ -11,6 +11,7 @@
 
 var Registry = require('../../registry');
 var Lib = require('../../lib');
+var Template = require('../../plot_api/plot_template');
 
 var attributes = require('./attributes');
 var basePlotLayoutAttributes = require('../../plots/layout_attributes');
@@ -19,7 +20,6 @@ var helpers = require('./helpers');
 
 module.exports = function legendDefaults(layoutIn, layoutOut, fullData) {
     var containerIn = layoutIn.legend || {};
-    var containerOut = {};
 
     var visibleTraces = 0;
     var defaultOrder = 'normal';
@@ -47,16 +47,16 @@ module.exports = function legendDefaults(layoutIn, layoutOut, fullData) {
         }
     }
 
-    function coerce(attr, dflt) {
-        return Lib.coerce(containerIn, containerOut, attributes, attr, dflt);
-    }
-
     var showLegend = Lib.coerce(layoutIn, layoutOut,
         basePlotLayoutAttributes, 'showlegend', visibleTraces > 1);
 
     if(showLegend === false) return;
 
-    layoutOut.legend = containerOut;
+    var containerOut = Template.newContainer(layoutOut, 'legend');
+
+    function coerce(attr, dflt) {
+        return Lib.coerce(containerIn, containerOut, attributes, attr, dflt);
+    }
 
     coerce('bgcolor', layoutOut.paper_bgcolor);
     coerce('bordercolor');

src/components/rangeslider/defaults.js

@@ -9,9 +9,11 @@
 'use strict';
 
 var Lib = require('../../lib');
+var Template = require('../../plot_api/plot_template');
+var axisIds = require('../../plots/cartesian/axis_ids');
+
 var attributes = require('./attributes');
 var oppAxisAttrs = require('./oppaxis_attributes');
-var axisIds = require('../../plots/cartesian/axis_ids');
 
 module.exports = function handleDefaults(layoutIn, layoutOut, axName) {
     var axIn = layoutIn[axName];
@@ -25,13 +27,14 @@ module.exports = function handleDefaults(layoutIn, layoutOut, axName) {
     }
 
     var containerIn = axIn.rangeslider;
-    var containerOut = axOut.rangeslider = {};
+    var containerOut = Template.newContainer(axOut, 'rangeslider');
 
     function coerce(attr, dflt) {
         return Lib.coerce(containerIn, containerOut, attributes, attr, dflt);
     }
 
-    function coerceRange(rangeContainerIn, rangeContainerOut, attr, dflt) {
+    var rangeContainerIn, rangeContainerOut;
+    function coerceRange(attr, dflt) {
         return Lib.coerce(rangeContainerIn, rangeContainerOut, oppAxisAttrs, attr, dflt);
     }
 
@@ -59,8 +62,8 @@ module.exports = function handleDefaults(layoutIn, layoutOut, axName) {
         for(var i = 0; i < yNames.length; i++) {
             var yName = yNames[i];
 
-            var rangeContainerIn = containerIn[yName] || {};
-            var rangeContainerOut = containerOut[yName] = {};
+            rangeContainerIn = containerIn[yName] || {};
+            rangeContainerOut = Template.newContainer(containerOut, yName, 'yaxis');
 
             var yAxOut = layoutOut[yName];
 
@@ -69,9 +72,9 @@ module.exports = function handleDefaults(layoutIn, layoutOut, axName) {
                 rangemodeDflt = 'fixed';
             }
 
-            var rangeMode = coerceRange(rangeContainerIn, rangeContainerOut, 'rangemode', rangemodeDflt);
+            var rangeMode = coerceRange('rangemode', rangemodeDflt);
             if(rangeMode !== 'match') {
-                coerceRange(rangeContainerIn, rangeContainerOut, 'range', yAxOut.range.slice());
+                coerceRange('range', yAxOut.range.slice());
             }
             yAxOut._rangesliderAutorange = (rangeMode === 'auto');
         }

src/lib/coerce.js

@@ -343,12 +343,12 @@ exports.valObjectMeta = {
                         return false;
                     }
                     for(var j = 0; j < v[i].length; j++) {
-                        if(!exports.validate(v[i][j], arrayItems ? items[i][j] : items)) {
+                        if(!validate(v[i][j], arrayItems ? items[i][j] : items)) {
                             return false;
                         }
                     }
                 }
-                else if(!exports.validate(v[i], arrayItems ? items[i] : items)) return false;
+                else if(!validate(v[i], arrayItems ? items[i] : items)) return false;
             }
 
             return true;
@@ -369,10 +369,17 @@ exports.valObjectMeta = {
  *      as a convenience, returns the value it finally set
  */
 exports.coerce = function(containerIn, containerOut, attributes, attribute, dflt) {
-    var opts = nestedProperty(attributes, attribute).get(),
-        propIn = nestedProperty(containerIn, attribute),
-        propOut = nestedProperty(containerOut, attribute),
-        v = propIn.get();
+    var opts = nestedProperty(attributes, attribute).get();
+    var propIn = nestedProperty(containerIn, attribute);
+    var propOut = nestedProperty(containerOut, attribute);
+    var v = propIn.get();
+
+    var template = containerOut._template;
+    if(v === undefined && template) {
+        v = nestedProperty(template, attribute).get();
+        // already used the template value, so short-circuit the second check
+        template = 0;
+    }
 
     if(dflt === undefined) dflt = opts.dflt;
 
@@ -387,9 +394,18 @@ exports.coerce = function(containerIn, containerOut, attributes, attribute, dflt
         return v;
     }
 
-    exports.valObjectMeta[opts.valType].coerceFunction(v, propOut, dflt, opts);
+    var coerceFunction = exports.valObjectMeta[opts.valType].coerceFunction;
+    coerceFunction(v, propOut, dflt, opts);
 
-    return propOut.get();
+    var out = propOut.get();
+    // in case v was provided but invalid, try the template again so it still
+    // overrides the regular default
+    if(template && out === dflt && !validate(v, opts)) {
+        v = nestedProperty(template, attribute).get();
+        coerceFunction(v, propOut, dflt, opts);
+        out = propOut.get();
+    }
+    return out;
 };
 
 /**
@@ -486,7 +502,7 @@ exports.coerceSelectionMarkerOpacity = function(traceOut, coerce) {
     coerce('unselected.marker.opacity', usmoDflt);
 };
 
-exports.validate = function(value, opts) {
+function validate(value, opts) {
     var valObjectDef = exports.valObjectMeta[opts.valType];
 
     if(opts.arrayOk && isArrayOrTypedArray(value)) return true;
@@ -503,4 +519,5 @@ exports.validate = function(value, opts) {
 
     valObjectDef.coerceFunction(value, propMock, failed, opts);
     return out !== failed;
-};
+}
+exports.validate = validate;

src/plot_api/index.js

@@ -31,3 +31,4 @@ exports.setPlotConfig = main.setPlotConfig;
 exports.toImage = require('./to_image');
 exports.validate = require('./validate');
 exports.downloadImage = require('../snapshot/download');
+exports.makeTemplate = require('./make_template');