Add templateString method to perform substitutions

Author: rreusser

src/lib/index.js

@@ -728,3 +728,33 @@ lib.numSeparate = function(value, separators, separatethousands) {
 
     return x1 + x2;
 };
+
+var TEMPLATE_STRING_REGEX = /%{([^\s%{}]*)}/g;
+var SIMPLE_PROPERTY_REGEX = /^\w*$/;
+
+/*
+ * Substitute values from an object into a string
+ *
+ * Examples:
+ *  Lib.templateString('name: %{trace}', {trace: 'asdf'}) --> 'name: asdf'
+ *  Lib.templateString('name: %{trace[0].name}', {trace: [{name: 'asdf'}]}) --> 'name: asdf'
+ *
+ * @param {string}  input string containing %{...} template strings
+ * @param {obj}     data object containing substitution values
+ *
+ * @return {string} templated string
+ */
+
+lib.templateString = function(string, obj) {
+    // 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] || '';
+        }
+        getterCache[key] = getterCache[key] || lib.nestedProperty(obj, key).get;
+        return getterCache[key]() || '';
+    });
+};

src/transforms/groupby.js

@@ -39,11 +39,11 @@ exports.attributes = {
         valType: 'string',
         description: [
             'Pattern by which grouped traces are named. If only one trace is present,',
-            'defaults to the group name (`"%g"`), otherwise defaults to the group name',
-            'with trace name (`"%g (%t)"`). Available escape sequences are `%g`, which',
-            'inserts the group name, and `%t`, which inserts the trace name. If grouping',
+            'defaults to the group name (`"%{group}"`), otherwise defaults to the group name',
+            'with trace name (`"%{group} (%{trace})"`). Available escape sequences are `%{group}`, which',
+            'inserts the group name, and `%{trace}`, which inserts the trace name. If grouping',
             'GDP data by country when more than one trace is present, for example, the',
-            'default "%g (%t)" would return "Monaco (GDP per capita)".'
+            'default "%{group} (%{trace})" would return "Monaco (GDP per capita)".'
         ].join(' ')
     },
     groupnames: {
@@ -100,7 +100,7 @@ exports.attributes = {
  * @return {object} transformOut
  *  copy of transformIn that contains attribute defaults
  */
-exports.supplyDefaults = function(transformIn, traceOut, layout, traceIn) {
+exports.supplyDefaults = function(transformIn, traceOut, layout) {
     var i;
     var transformOut = {};
 
@@ -113,7 +113,7 @@ exports.supplyDefaults = function(transformIn, traceOut, layout, traceIn) {
     if(!enabled) return transformOut;
 
     coerce('groups');
-    coerce('nameformat', layout._dataLength > 1 ? '%g (%t)' : '%g');
+    coerce('nameformat', layout._dataLength > 1 ? '%{group} (%{trace})' : '%{group}');
 
     var nameFormatIn = transformIn.groupnames;
     var nameFormatOut = transformOut.groupnames = [];
@@ -172,12 +172,6 @@ exports.transform = function(data, state) {
     return newData;
 };
 
-function computeName(pattern, traceName, groupName) {
-    return pattern.replace(/%g/g, groupName)
-        .replace(/%t/g, traceName);
-}
-
-
 function transformOne(trace, state) {
     var i, j, k, attr, srcArray, groupName, newTrace, transforms, arrayLookup;
     var groupNameObj;
@@ -224,7 +218,10 @@ function transformOne(trace, state) {
         if(suppliedName) {
             newTrace.name = suppliedName;
         } else {
-            newTrace.name = computeName(opts.nameformat, trace.name, groupName);
+            newTrace.name = Lib.templateString(opts.nameformat, {
+                trace: trace.name,
+                group: groupName
+            });
         }
 
         // In order for groups to apply correctly to other transform data (e.g.

test/jasmine/tests/lib_test.js

@@ -1728,6 +1728,32 @@ describe('Test lib.js:', function() {
             });
         });
     });
+
+    describe('templateString', function() {
+        it('evaluates attributes', function() {
+            expect(Lib.templateString('foo %{bar}', {bar: 'baz'})).toEqual('foo baz');
+        });
+
+        it('evaluates nested properties', function() {
+            expect(Lib.templateString('foo %{bar.baz}', {bar: {baz: 'asdf'}})).toEqual('foo asdf');
+        });
+
+        it('evaluates array nested properties', function() {
+            expect(Lib.templateString('foo %{bar[0].baz}', {bar: [{baz: 'asdf'}]})).toEqual('foo asdf');
+        });
+
+        it('subtitutes multiple matches', function() {
+            expect(Lib.templateString('foo %{group} %{trace}', {group: 'asdf', trace: 'jkl;'})).toEqual('foo asdf jkl;');
+        });
+
+        it('replaces missing matches with empty string', function() {
+            expect(Lib.templateString('foo %{group} %{trace}', {})).toEqual('foo  ');
+        });
+
+        it('replaces empty key with empty string', function() {
+            expect(Lib.templateString('foo %{} %{}', {})).toEqual('foo  ');
+        });
+    });
 });
 
 describe('Queue', function() {