Handle undefined values and missing values differently

plotly · camdecoster · Oct 27, 2025 · Sep 29, 2025 · Sep 29, 2025 · Oct 2, 2025
commit 14ab31ccb710ec449fa79acbfb746a5f7f9dcd3f
diff --git a/src/lib/index.js b/src/lib/index.js
@@ -1122,24 +1122,26 @@ var TEMPLATE_STRING_FORMAT_SEPARATOR = /^[:|\|]/;
  * @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
- * @param {string}  options.template - Input string containing %{...:...} template strings
+ * @param {number}  options.opts.count - Count of warnings for missing values
+ * @param {number}  options.opts.max - Maximum allowed count of warnings for missing values before suppressing the warning message
+ * @param {string}  options.opts.name - Template name, used in warning message
+ * @param {boolean} options.opts.parseMultDiv - Parse * and / operators in template string (used in shape labels)
+ * @param {string}  options.template - Input string containing %{...:...} template string specifiers
  *
  * @return {string} templated string
  */
 function templateFormatString({ data = [], locale, fallback, labels = {}, opts, template }) {
-    return template.replace(lib.TEMPLATE_STRING_REGEX, (_, rawKey, format) => {
-        const isOther = ['xother', 'yother'].includes(rawKey);
-        const isSpaceOther = ['_xother', '_yother'].includes(rawKey);
-        const isSpaceOtherSpace = ['_xother_', '_yother_'].includes(rawKey);
-        const isOtherSpace = ['xother_', 'yother_'].includes(rawKey);
+    return template.replace(lib.TEMPLATE_STRING_REGEX, (match, key, format) => {
+        const isOther = ['xother', 'yother'].includes(key);
+        const isSpaceOther = ['_xother', '_yother'].includes(key);
+        const isSpaceOtherSpace = ['_xother_', '_yother_'].includes(key);
+        const isOtherSpace = ['xother_', 'yother_'].includes(key);
         const hasOther = isOther || isSpaceOther || isOtherSpace || isSpaceOtherSpace;
 
-        let key = rawKey;
+        // Remove underscores from key
         if (isSpaceOther || isSpaceOtherSpace) key = key.substring(1);
         if (isOtherSpace || isSpaceOtherSpace) key = key.substring(0, key.length - 1);
 
-        // Shape labels support * and / operators in template string
-        // Parse these if the parseMultDiv param is set to true
         let parsedOp = null;
         let parsedNumber = null;
         if (opts.parseMultDiv) {
@@ -1149,32 +1151,46 @@ function templateFormatString({ data = [], locale, fallback, labels = {}, opts,
             parsedNumber = _match.number;
         }
 
-        let value;
+        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 (value === undefined) {
+        if (keyIsMissing) {
             const { count, max, name } = opts;
-            if (count < max) lib.warn(`Variable '${key}' in ${name} could not be found! Using fallback value.`);
-            if (count === max) lib.warn(`Too many '${name}' warnings - additional warnings will be suppressed`);
+            if (count < max)
+                lib.warn(
+                    [
+                        `Variable '${key}' in ${name} could not be found!`,
+                        'Please verify that the template is correct.'
+                    ].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;
         }