support template string on hover

src/components/fx/hover.js

@@ -144,7 +144,8 @@ exports.loneHover = function loneHover(hoverItem, opts) {
         rotateLabels: false,
         bgColor: opts.bgColor || Color.background,
         container: container3,
-        outerContainer: outerContainer3
+        outerContainer: outerContainer3,
+        hovertemplate: opts.hovertemplate || false
     };
 
     var hoverLabel = createHoverText([pointData], fullOpts, opts.gd);
@@ -200,7 +201,8 @@ exports.multiHovers = function multiHovers(hoverItems, opts) {
         rotateLabels: false,
         bgColor: opts.bgColor || Color.background,
         container: container3,
-        outerContainer: outerContainer3
+        outerContainer: outerContainer3,
+        hovertemplate: opts.hovertemplate || false
     };
 
     var hoverLabel = createHoverText(pointsData, fullOpts, opts.gd);
@@ -882,7 +884,7 @@ function createHoverText(hoverData, opts, gd) {
 
     // then put the text in, position the pointer to the data,
     // and figure out sizes
-    hoverLabels.each(function(d) {
+    hoverLabels.each(function(d, curveNumber) {
         var g = d3.select(this).attr('transform', '');
         var name = '';
         var text = '';
@@ -950,6 +952,12 @@ function createHoverText(hoverData, opts, gd) {
             text = name;
         }
 
+        // hovertemplate
+        var trace = d.trace, hovertemplate = opts.hovertemplate || trace.hovertemplate || false;
+        if(hovertemplate) {
+            text = Lib.templateString(hovertemplate, gd._hoverdata[curveNumber], trace);
+        }
+
         // main label
         var tx = g.select('text.nums')
             .call(Drawing.font,

src/lib/index.js

@@ -978,33 +978,53 @@ lib.numSeparate = function(value, separators, separatethousands) {
     return x1 + x2;
 };
 
-var TEMPLATE_STRING_REGEX = /%{([^\s%{}]*)}/g;
+var TEMPLATE_STRING_REGEX = /%{([^\s%{}:]*)(:[^}]*)?}/g;
 var SIMPLE_PROPERTY_REGEX = /^\w*$/;
 
 /*
- * Substitute values from an object into a string
+ * Substitute values from an object into a string and optionally formats them using d3-format
  *
  * Examples:
  *  Lib.templateString('name: %{trace}', {trace: 'asdf'}) --> 'name: asdf'
  *  Lib.templateString('name: %{trace[0].name}', {trace: [{name: 'asdf'}]}) --> 'name: asdf'
+ *  Lib.templateString('price: %{y:$.2f}', {y: 1}) --> 'price: $1.00'
  *
- * @param {string}  input string containing %{...} template strings
- * @param {obj}     data object containing substitution values
+ * @param {string}  input string containing %{...:...} template strings
+ * @param {obj}     data objects containing substitution values
  *
  * @return {string} templated string
  */
 
-lib.templateString = function(string, obj) {
+lib.templateString = function(string) {
+    var args = arguments;
     // Not all that useful, but cache nestedProperty instantiation
     // just in case it speeds things up *slightly*:
     var getterCache = {};
 
-    return string.replace(TEMPLATE_STRING_REGEX, function(dummy, key) {
-        if(SIMPLE_PROPERTY_REGEX.test(key)) {
-            return obj[key] || '';
+    return string.replace(TEMPLATE_STRING_REGEX, function(dummy, key, format) {
+        var obj, value, i;
+        for(i = 1; i < args.length; i++) {
+            obj = args[i];
+            if(obj.hasOwnProperty(key)) {
+                value = obj[key];
+                break;
+            }
+
+            if(!SIMPLE_PROPERTY_REGEX.test(key)) {
+                // getterCache[key] = getterCache[key] || lib.nestedProperty(obj, key).get;
+                // value = getterCache[key]();
+                value = getterCache[key] || lib.nestedProperty(obj, key).get();
+                if(value) getterCache[key] = value;
+            }
+            if(value !== undefined) break;
+        }
+
+        if(value === undefined) value = '';
+
+        if(format) {
+            value = d3.format(format.replace(/^:/, ''))(value);
         }
-        getterCache[key] = getterCache[key] || lib.nestedProperty(obj, key).get;
-        return getterCache[key]() || '';
+        return value;
     });
 };
 

src/plots/attributes.js

@@ -129,6 +129,18 @@ module.exports = {
         ].join(' ')
     },
     hoverlabel: fxAttrs.hoverlabel,
+    hovertemplate: {
+        valType: 'string',
+        role: 'info',
+        dflt: false,
+        editType: 'none',
+        description: [
+            'Template string used for rendering the information that appear on hover box.',
+            'Note that this will override `hoverinfo`.',
+            'Variables are inserted using %{variable}, for example "y: %{y}".',
+            'Numbers are formatted using d3-format\'s syntax %{variable:d3-format}, for example "Price: %{y:$.2f}".'
+        ].join(' ')
+    },
     stream: {
         token: {
             valType: 'string',

src/plots/plots.js

@@ -1170,6 +1170,8 @@ plots.supplyTraceDefaults = function(traceIn, traceOut, colorIndex, layout, trac
             Lib.coerceHoverinfo(traceIn, traceOut, layout);
         }
 
+        coerce('hovertemplate');
+
         if(!Registry.traceIs(traceOut, 'noOpacity')) coerce('opacity');
 
         if(Registry.traceIs(traceOut, 'notLegendIsolatable')) {

test/jasmine/tests/hover_label_test.js

@@ -1549,6 +1549,36 @@ describe('hover info', function() {
               .toBeWithin(0, 1); // Be robust against floating point arithmetic and subtle future layout changes
         });
     });
+
+    describe('hovertemplate', function() {
+        var mockCopy = Lib.extendDeep({}, mock);
+
+        beforeEach(function(done) {
+            Plotly.plot(createGraphDiv(), mockCopy.data, mockCopy.layout).then(done);
+        });
+
+        it('should format labels according to a template string', function(done) {
+            var gd = document.getElementById('graph');
+            Plotly.restyle(gd, 'hovertemplate', '%{y:$.2f}')
+            .then(function() {
+                Fx.hover('graph', evt, 'xy');
+
+                var hoverTrace = gd._hoverdata[0];
+
+                expect(hoverTrace.curveNumber).toEqual(0);
+                expect(hoverTrace.pointNumber).toEqual(17);
+                expect(hoverTrace.x).toEqual(0.388);
+                expect(hoverTrace.y).toEqual(1);
+
+                assertHoverLabelContent({
+                    nums: '$1.00',
+                    axis: '0.388'
+                });
+            })
+            .catch(failTest)
+            .then(done);
+        });
+    });
 });
 
 describe('hover info on stacked subplots', function() {

test/jasmine/tests/lib_test.js

@@ -2124,6 +2124,10 @@ describe('Test lib.js:', function() {
             expect(Lib.templateString('foo %{bar}', {bar: 'baz'})).toEqual('foo baz');
         });
 
+        it('evaluates attributes with a dot in their name', function() {
+            expect(Lib.templateString('%{marker.size}', {'marker.size': 12}, {marker: {size: 14}})).toEqual('12');
+        });
+
         it('evaluates nested properties', function() {
             expect(Lib.templateString('foo %{bar.baz}', {bar: {baz: 'asdf'}})).toEqual('foo asdf');
         });
@@ -2143,6 +2147,25 @@ describe('Test lib.js:', function() {
         it('replaces empty key with empty string', function() {
             expect(Lib.templateString('foo %{} %{}', {})).toEqual('foo  ');
         });
+
+        it('uses the value from the first object with the specified key', function() {
+            var obj1 = {a: 'first'}, obj2 = {a: 'second', foo: {bar: 'bar'}};
+
+            // Simple key
+            expect(Lib.templateString('foo %{a}', obj1, obj2)).toEqual('foo first');
+            expect(Lib.templateString('foo %{a}', obj2, obj1)).toEqual('foo second');
+
+            // Nested Keys
+            expect(Lib.templateString('foo %{foo.bar}', obj1, obj2)).toEqual('foo bar');
+
+            // Nested keys with 0
+            expect(Lib.templateString('y: %{y}', {y: 0}, {y: 1})).toEqual('y: 0');
+        });
+
+        it('formats value using d3 mini-language', function() {
+            expect(Lib.templateString('a: %{a:.0%}', {a: 0.123})).toEqual('a: 12%');
+            expect(Lib.templateString('b: %{b:2.2f}', {b: 43})).toEqual('b: 43.00');
+        });
     });
 
     describe('relativeAttr()', function() {