add trace meta attribute + add _meta helpers

Author: etpinard

Diff for: src/plots/attributes.js

@@ -102,6 +102,24 @@ module.exports = {
             'DOM elements'
         ].join(' ')
     },
+    meta: {
+        valType: 'any',
+        arrayOk: true,
+        editType: 'plot',
+        description: [
+            'Assigns extra meta information associated with this trace',
+            'that can be used in various text attributes.',
+            'Attributes such as trace `name`, graph, axis and colorbar `title.text`, annotation `text`',
+            '`rangeselector`, `updatemenues` and `sliders` `label` text',
+            'all support `meta`.',
+            'To access the trace `meta` values in an attribute in the same trace, simply use',
+            '`%{meta[i]}` where `i` is the index or key of the `meta`',
+            'item in question.',
+            'To access trace `meta` in layout attributes, use',
+            '`%{data[n[.meta[i]}` where `i` is the index or key of the `meta`',
+            'and `n` is the trace index.'
+        ].join(' ')
+    },
 
     // N.B. these cannot be 'data_array' as they do not have the same length as
     // other data arrays and arrayOk attributes in general

Diff for: src/plots/plots.js

@@ -6,7 +6,6 @@
 * LICENSE file in the root directory of this source tree.
 */
 
-
 'use strict';
 
 var d3 = require('d3');
@@ -483,6 +482,10 @@ plots.supplyDefaults = function(gd, opts) {
         oldFullLayout._zoomlayer.selectAll('.select-outline').remove();
     }
 
+
+    // fill in meta helpers
+    fillMetaTextHelpers(newFullData, newFullLayout);
+
     // relink functions and _ attributes to promote consistency between plots
     relinkPrivateKeys(newFullLayout, oldFullLayout);
 
@@ -698,6 +701,39 @@ function getFormatter(formatObj, separators) {
     return d3.locale(formatObj);
 }
 
+function fillMetaTextHelpers(newFullData, newFullLayout) {
+    var _meta;
+    var meta4data = [];
+
+    if(newFullLayout.meta) {
+        _meta = newFullLayout._meta = {};
+        _meta.meta = newFullLayout.meta;
+        _meta.layout = {meta: newFullLayout.meta};
+    }
+
+    for(var i = 0; i < newFullData.length; i++) {
+        var trace = newFullData[i];
+
+        if(trace.meta) {
+            meta4data[trace.index] = {meta: trace.meta};
+        }
+
+        trace._meta = {
+            meta: Lib.extendFlat({}, newFullLayout.meta || {}, trace.meta)
+        };
+        if(newFullLayout.meta) {
+            trace._meta.layout = {meta: newFullLayout.meta};
+        }
+    }
+
+    if(meta4data.length) {
+        if(!_meta) {
+            _meta = newFullLayout._meta = {};
+        }
+        _meta.data = meta4data;
+    }
+}
+
 // Create storage for all of the data related to frames and transitions:
 plots.createTransitionData = function(gd) {
     // Set up the default keyframe if it doesn't exist:
@@ -1236,6 +1272,7 @@ plots.supplyTraceDefaults = function(traceIn, traceOut, colorIndex, layout, trac
     if(visible) {
         coerce('customdata');
         coerce('ids');
+        coerce('meta');
 
         if(Registry.traceIs(traceOut, 'showLegend')) {
             traceOut._dfltShowLegend = true;