feat: Add template string fallback attributes

src/lib/index.js

@@ -1118,7 +1118,7 @@ var TEMPLATE_STRING_FORMAT_SEPARATOR = /^[:|\|]/;
  *
  * @param {object}  options - Configuration object
  * @param {array}   options.data - Data objects containing substitution values
- * @param {string}  options.fallback - Fallback value when substitution fails
+ * @param {boolean|string}  options.fallback - Fallback value when substitution fails. If false, the specifier is used.
  * @param {object}  options.labels - Data object containing fallback text when no formatting is specified, ex.: {yLabel: 'formattedYValue'}
  * @param {object}  options.locale - D3 locale for formatting
  * @param {object}  options.opts - Additional options
@@ -1151,47 +1151,43 @@ function templateFormatString({ data = [], locale, fallback, labels = {}, opts,
             parsedNumber = _match.number;
         }
 
-        let keyIsMissing = true;
         let value = undefined;
         if (hasOther) {
             // 'other' specifiers that are undefined return an empty string by design
             if (labels[key] === undefined) return '';
             value = labels[key];
-            keyIsMissing = false;
         } else {
             for (const obj of data) {
                 if (!obj) continue;
                 if (obj.hasOwnProperty(key)) {
                     value = obj[key];
-                    keyIsMissing = false;
                     break;
                 }
 
                 if (!SIMPLE_PROPERTY_REGEX.test(key)) {
                     // true here means don't convert null to undefined
                     value = lib.nestedProperty(obj, key).get(true);
-                    keyIsMissing = false;
                 }
                 if (value !== undefined) break;
             }
         }
 
-        if (keyIsMissing) {
+        if (value === undefined) {
             const { count, max, name } = opts;
-            if (count < max)
+            const fallbackValue = fallback === false ? match : fallback;
+            if (count < max) {
                 lib.warn(
                     [
                         `Variable '${key}' in ${name} could not be found!`,
-                        'Please verify that the template is correct.'
+                        'Please verify that the template is correct.',
+                        `Using value: '${fallbackValue}'.`
                     ].join(' ')
                 );
+            }
             if (count === max) lib.warn(`Too many '${name}' warnings - additional warnings will be suppressed.`);
             opts.count++;
 
-            return match;
-        } else if (value === undefined) {
-            // In this case, the actual value in the data set is 'undefined', so use fallback without warning
-            return fallback;
+            return fallbackValue;
         }
 
         if (parsedOp === '*') value *= parsedNumber;

src/plots/template_attributes.js

@@ -96,8 +96,11 @@ exports.shapeTexttemplateAttrs = ({ editType = 'arraydraw', newshape } = {}, ext
 });
 
 exports.templatefallbackAttrs = ({ editType = 'none' } = {}) => ({
-    valType: 'string',
+    valType: 'any',
     dflt: '-',
     editType,
-    description: "Fallback value that's displayed when a variable referenced in a template has an undefined value."
+    description: [
+        "Fallback string that's displayed when a variable referenced in a template is missing.",
+        "If the boolean value 'false' is passed in, the specifier with the missing variable will be displayed."
+    ].join(' ')
 });

test/image/mocks/icicle_with-without_values_template.json

@@ -3,6 +3,7 @@
     {
       "type": "icicle",
       "texttemplate": "<sup>%{currentPath}<b>%{label}</b></sup><br><b>%{text}</b><br>%{value}<br>%{parent} <=> %{percentParent}<br>%{entry} <=> %{percentEntry}<br>%{root} <=> %{percentRoot}",
+      "texttemplatefallback": "Scruffy, the Janitor",
       "hovertemplate": "<sup>%{currentPath}<b>%{label}</b></sup><br><b>%{text}</b><br>%{value}<br>%{parent} <=> %{percentParent}<br>%{entry} <=> %{percentEntry}<br>%{root} <=> %{percentRoot}",
       "name": "without values",
       "level": "Oscar",

test/image/mocks/treemap_with-without_values_template.json

@@ -3,6 +3,7 @@
     {
       "type": "treemap",
       "texttemplate": "<sup>%{currentPath}<b>%{label}</b></sup><br><b>%{text}</b><br>%{value}<br>%{parent} <=> %{percentParent}<br>%{entry} <=> %{percentEntry}<br>%{root} <=> %{percentRoot}",
+      "texttemplatefallback": false,
       "hovertemplate": "<sup>%{currentPath}<b>%{label}</b></sup><br><b>%{text}</b><br>%{value}<br>%{parent} <=> %{percentParent}<br>%{entry} <=> %{percentEntry}<br>%{root} <=> %{percentRoot}",
       "name": "without values",
       "level": "Oscar",

test/jasmine/tests/icicle_test.js

@@ -931,7 +931,7 @@ describe('Test icicle texttemplate without `values` should work at root level:',
             [
                 '%{percentParent} of %{parent}',
                 [
-                    ' of ',
+                    '- of -',
                     '100% of Seth',
                     '33% of Eve',
                     '17% of Eve',
@@ -957,7 +957,7 @@ describe('Test icicle texttemplate without `values` should work at root level:',
                 [
                     'label: Eve',
                     'text: fourteen',
-                    'value: ', // N.B. there is no `values` array
+                    'value: -', // N.B. there is no `values` array
                     '17% of Eve',
                     '17% of Eve',
                     '17% of Eve',
@@ -1085,7 +1085,7 @@ describe('Test icicle texttemplate with *total* `values` should work at root lev
             [
                 '%{percentParent} of %{parent}',
                 [
-                    ' of ',
+                    '- of -',
                     '22% of Eve',
                     '18% of Eve',
                     '9% of Eve',

test/jasmine/tests/lib_test.js

@@ -2706,18 +2706,18 @@ describe('Test lib.js:', function () {
         });
 
         // This test must come after the warning count since it will affect the count
-        it('replaces template specifiers where the key is missing with the specifier', () => {
+        it('replaces template specifiers with the specifier when fallback is false', () => {
             expect(
                 Lib.hovertemplateString({
                     data: [{ group: 1 }],
-                    fallback: 'Planet Express',
+                    fallback: false,
                     template: 'foo %{group} %{trace}'
                 })
             ).toEqual('foo 1 %{trace}');
         });
 
         // This test must come after the warning count since it will affect the count
-        it('replaces template specifiers where the value is undefined with the fallback value', () => {
+        it('replaces template specifiers with the fallback value when fallback is provided', () => {
             expect(
                 Lib.hovertemplateString({
                     data: [{ group: 1, trace: undefined }],
@@ -2773,18 +2773,18 @@ describe('Test lib.js:', function () {
         });
 
         // This test must come after the warning count since it will affect the count
-        it('replaces template specifiers where the key is missing with the specifier', () => {
+        it('replaces template specifiers with the specifier when fallback is false', () => {
             expect(
                 Lib.texttemplateString({
                     data: [{ group: 1 }],
-                    fallback: 'Zoidberg',
+                    fallback: false,
                     template: 'foo %{group} %{trace}'
                 })
             ).toEqual('foo 1 %{trace}');
         });
 
         // This test must come after the warning count since it will affect the count
-        it('replaces template specifiers where the value is undefined with the fallback value', () => {
+        it('replaces template specifiers with the fallback value when fallback is provided', () => {
             expect(
                 Lib.texttemplateString({
                     data: [{ group: 1, trace: undefined }],

test/jasmine/tests/sunburst_test.js

@@ -2293,7 +2293,7 @@ describe('Test sunburst texttemplate without `values` should work at root level:
             [
                 '%{percentParent} of %{parent}',
                 [
-                    ' of ',
+                    '- of -',
                     '100% of Seth',
                     '33% of Eve',
                     '17% of Eve',
@@ -2319,7 +2319,7 @@ describe('Test sunburst texttemplate without `values` should work at root level:
                 [
                     'label: Eve',
                     'text: fourteen',
-                    'value: ', // N.B. there is no `values` array
+                    'value: -', // N.B. there is no `values` array
                     '17% of Eve',
                     '17% of Eve',
                     '17% of Eve',
@@ -2447,7 +2447,7 @@ describe('Test sunburst texttemplate with *total* `values` should work at root l
             [
                 '%{percentParent} of %{parent}',
                 [
-                    ' of ',
+                    '- of -',
                     '22% of Eve',
                     '18% of Eve',
                     '9% of Eve',
@@ -2601,7 +2601,7 @@ describe('Test sunburst texttemplate with *remainder* `values` should work at ro
             [
                 '%{percentParent} of %{parent}',
                 [
-                    ' of ',
+                    '- of -',
                     '20% of Eve',
                     '12% of Eve',
                     '6% of Eve',

test/jasmine/tests/treemap_test.js

@@ -1937,7 +1937,7 @@ describe('Test treemap texttemplate without `values` should work:', function ()
                     'Eve',
                     'label: Cain, text: fourteen',
                     'Seth',
-                    'value: ', // N.B. there is no `values` array
+                    'value: -', // N.B. there is no `values` array
                     '17% of Eve',
                     '17% of Eve',
                     'Awan',