Templates

src/components/annotations/attributes.js

@@ -11,11 +11,10 @@
 var ARROWPATHS = require('./arrow_paths');
 var fontAttrs = require('../../plots/font_attributes');
 var cartesianConstants = require('../../plots/cartesian/constants');
+var templatedArray = require('../../plot_api/plot_template').templatedArray;
 
 
-module.exports = {
-    _isLinkedToArray: 'annotation',
-
+module.exports = templatedArray('annotation', {
     visible: {
         valType: 'boolean',
         role: 'info',
@@ -543,4 +542,4 @@ module.exports = {
             ].join(' ')
         }
     }
-};
+});

src/components/annotations3d/attributes.js

@@ -11,10 +11,9 @@
 
 var annAtts = require('../annotations/attributes');
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
+var templatedArray = require('../../plot_api/plot_template').templatedArray;
 
-module.exports = overrideAll({
-    _isLinkedToArray: 'annotation',
-
+module.exports = overrideAll(templatedArray('annotation', {
     visible: annAtts.visible,
     x: {
         valType: 'any',
@@ -94,4 +93,4 @@ module.exports = overrideAll({
     // xref: 'x'
     // yref: 'y
     // zref: 'z'
-}, 'calc', 'from-root');
+}), 'calc', 'from-root');

src/components/images/attributes.js

@@ -9,11 +9,10 @@
 'use strict';
 
 var cartesianConstants = require('../../plots/cartesian/constants');
+var templatedArray = require('../../plot_api/plot_template').templatedArray;
 
 
-module.exports = {
-    _isLinkedToArray: 'image',
-
+module.exports = templatedArray('image', {
     visible: {
         valType: 'boolean',
         role: 'info',
@@ -178,4 +177,4 @@ module.exports = {
         ].join(' ')
     },
     editType: 'arraydraw'
-};
+});

src/components/rangeselector/attributes.js

@@ -10,12 +10,64 @@
 
 var fontAttrs = require('../../plots/font_attributes');
 var colorAttrs = require('../color/attributes');
-var extendFlat = require('../../lib/extend').extendFlat;
-var buttonAttrs = require('./button_attributes');
-
-buttonAttrs = extendFlat(buttonAttrs, {
-    _isLinkedToArray: 'button',
+var templatedArray = require('../../plot_api/plot_template').templatedArray;
 
+var buttonAttrs = templatedArray('button', {
+    visible: {
+        valType: 'boolean',
+        role: 'info',
+        dflt: true,
+        editType: 'plot',
+        description: 'Determines whether or not this button is visible.'
+    },
+    step: {
+        valType: 'enumerated',
+        role: 'info',
+        values: ['month', 'year', 'day', 'hour', 'minute', 'second', 'all'],
+        dflt: 'month',
+        editType: 'plot',
+        description: [
+            'The unit of measurement that the `count` value will set the range by.'
+        ].join(' ')
+    },
+    stepmode: {
+        valType: 'enumerated',
+        role: 'info',
+        values: ['backward', 'todate'],
+        dflt: 'backward',
+        editType: 'plot',
+        description: [
+            'Sets the range update mode.',
+            'If *backward*, the range update shifts the start of range',
+            'back *count* times *step* milliseconds.',
+            'If *todate*, the range update shifts the start of range',
+            'back to the first timestamp from *count* times',
+            '*step* milliseconds back.',
+            'For example, with `step` set to *year* and `count` set to *1*',
+            'the range update shifts the start of the range back to',
+            'January 01 of the current year.',
+            'Month and year *todate* are currently available only',
+            'for the built-in (Gregorian) calendar.'
+        ].join(' ')
+    },
+    count: {
+        valType: 'number',
+        role: 'info',
+        min: 0,
+        dflt: 1,
+        editType: 'plot',
+        description: [
+            'Sets the number of steps to take to update the range.',
+            'Use with `step` to specify the update interval.'
+        ].join(' ')
+    },
+    label: {
+        valType: 'string',
+        role: 'info',
+        editType: 'plot',
+        description: 'Sets the text label to appear on the button.'
+    },
+    editType: 'plot',
     description: [
         'Sets the specifications for each buttons.',
         'By default, a range selector comes with no buttons.'

src/components/rangeselector/defaults.js

@@ -14,7 +14,6 @@ var Template = require('../../plot_api/plot_template');
 var handleArrayContainerDefaults = require('../../plots/array_container_defaults');
 
 var attributes = require('./attributes');
-var buttonAttrs = require('./button_attributes');
 var constants = require('./constants');
 
 
@@ -55,7 +54,7 @@ function buttonDefaults(buttonIn, buttonOut, selectorOut, opts) {
     var calendar = opts.calendar;
 
     function coerce(attr, dflt) {
-        return Lib.coerce(buttonIn, buttonOut, buttonAttrs, attr, dflt);
+        return Lib.coerce(buttonIn, buttonOut, attributes.buttons, attr, dflt);
     }
 
     var visible = coerce('visible');

src/components/shapes/attributes.js

@@ -12,10 +12,9 @@ var annAttrs = require('../annotations/attributes');
 var scatterLineAttrs = require('../../traces/scatter/attributes').line;
 var dash = require('../drawing/attributes').dash;
 var extendFlat = require('../../lib/extend').extendFlat;
+var templatedArray = require('../../plot_api/plot_template').templatedArray;
 
-module.exports = {
-    _isLinkedToArray: 'shape',
-
+module.exports = templatedArray('shape', {
     visible: {
         valType: 'boolean',
         role: 'info',
@@ -240,4 +239,4 @@ module.exports = {
         ].join(' ')
     },
     editType: 'arraydraw'
-};
+});

src/components/sliders/attributes.js

@@ -13,11 +13,10 @@ var padAttrs = require('../../plots/pad_attributes');
 var extendDeepAll = require('../../lib/extend').extendDeepAll;
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
 var animationAttrs = require('../../plots/animation_attributes');
+var templatedArray = require('../../plot_api/plot_template').templatedArray;
 var constants = require('./constants');
 
-var stepsAttrs = {
-    _isLinkedToArray: 'step',
-
+var stepsAttrs = templatedArray('step', {
     visible: {
         valType: 'boolean',
         role: 'info',
@@ -78,11 +77,9 @@ var stepsAttrs = {
             'specification of `method` and `args`.'
         ].join(' ')
     }
-};
-
-module.exports = overrideAll({
-    _isLinkedToArray: 'slider',
+});
 
+module.exports = overrideAll(templatedArray('slider', {
     visible: {
         valType: 'boolean',
         role: 'info',
@@ -293,4 +290,4 @@ module.exports = overrideAll({
         role: 'style',
         description: 'Sets the length in pixels of minor step tick marks'
     }
-}, 'arraydraw', 'from-root');
+}), 'arraydraw', 'from-root');

src/components/updatemenus/attributes.js

@@ -13,10 +13,9 @@ var colorAttrs = require('../color/attributes');
 var extendFlat = require('../../lib/extend').extendFlat;
 var overrideAll = require('../../plot_api/edit_types').overrideAll;
 var padAttrs = require('../../plots/pad_attributes');
+var templatedArray = require('../../plot_api/plot_template').templatedArray;
 
-var buttonsAttrs = {
-    _isLinkedToArray: 'button',
-
+var buttonsAttrs = templatedArray('button', {
     visible: {
         valType: 'boolean',
         role: 'info',
@@ -67,10 +66,9 @@ var buttonsAttrs = {
             'specification of `method` and `args`.'
         ].join(' ')
     }
-};
+});
 
-module.exports = overrideAll({
-    _isLinkedToArray: 'updatemenu',
+module.exports = overrideAll(templatedArray('updatemenu', {
     _arrayAttrRegexps: [/^updatemenus\[(0|[1-9][0-9]+)\]\.buttons/],
 
     visible: {
@@ -191,4 +189,4 @@ module.exports = overrideAll({
         editType: 'arraydraw',
         description: 'Sets the width (in px) of the border enclosing the update menu.'
     }
-}, 'arraydraw', 'from-root');
+}), 'arraydraw', 'from-root');

src/plot_api/plot_template.js

@@ -12,7 +12,56 @@
 var Lib = require('../lib');
 var plotAttributes = require('../plots/attributes');
 
-var TEMPLATEITEMNAME = exports.TEMPLATEITEMNAME = 'templateitemname';
+var TEMPLATEITEMNAME = 'templateitemname';
+
+var templateAttrs = {
+    name: {
+        valType: 'string',
+        role: 'style',
+        editType: 'none',
+        description: [
+            'When used in a template, named items are created in the output figure',
+            'in addition to any items the figure already has in this array.',
+            'You can modify these items in the output figure by making your own',
+            'item with `templateitemname` matching this `name`',
+            'alongside your modifications (including `visible: false` to hide it).',
+            'Has no effect outside of a template.'
+        ].join(' ')
+    }
+};
+templateAttrs[TEMPLATEITEMNAME] = {
+    valType: 'string',
+    role: 'info',
+    editType: 'calc',
+    description: [
+        'Used to refer to a named item in this array in the template. Named',
+        'items from the template will be created even without a matching item',
+        'in the input figure, but you can modify one by making an item with',
+        '`templateitemname` matching its `name`, alongside your',
+        'modifications (including `visible: false` to hide it).',
+        'If there is no template or no matching item, this item will be',
+        'hidden unless you explicitly show it with `visible: true`.'
+    ].join(' ')
+};
+
+/**
+ * templatedArray: decorate an attributes object with templating (and array)
+ * properties.
+ *
+ * @param {string} name: the singular form of the array name. Sets
+ *     `_isLinkedToArray` to this, so the schema knows to treat this as an array.
+ * @param {object} attrs: the item attributes. Since all callers are expected
+ *     to be constructing this object on the spot, we mutate it here for
+ *     performance, rather than extending a new object with it.
+ *
+ * @returns {object}: the decorated `attrs` object
+ */
+exports.templatedArray = function(name, attrs) {
+    attrs._isLinkedToArray = name;
+    attrs.name = templateAttrs.name;
+    attrs[TEMPLATEITEMNAME] = templateAttrs[TEMPLATEITEMNAME];
+    return attrs;
+};
 
 /**
  * traceTemplater: logic for matching traces to trace templates

src/plots/cartesian/layout_attributes.js

@@ -12,6 +12,7 @@ var fontAttrs = require('../font_attributes');
 var colorAttrs = require('../../components/color/attributes');
 var dash = require('../../components/drawing/attributes').dash;
 var extendFlat = require('../../lib/extend').extendFlat;
+var templatedArray = require('../../plot_api/plot_template').templatedArray;
 
 var constants = require('./constants');
 
@@ -510,9 +511,7 @@ module.exports = {
             '*%H~%M~%S.%2f* would display *09~15~23.46*'
         ].join(' ')
     },
-    tickformatstops: {
-        _isLinkedToArray: 'tickformatstop',
-
+    tickformatstops: templatedArray('tickformatstop', {
         visible: {
             valType: 'boolean',
             role: 'info',
@@ -547,7 +546,7 @@ module.exports = {
             ].join(' ')
         },
         editType: 'ticks'
-    },
+    }),
     hoverformat: {
         valType: 'string',
         dflt: '',