feat: Add template string fallback attributes by camdecoster · Pull Request #7577 · plotly/plotly.js · GitHub

Description

Add template string fallback attributes.

Closes #7564
Closes #7565

Changes

Lints/formats files updated in this PR
Adds hovertemplatefallback and texttemplatefallback attributes
Adds helper functions to include these attributes
Updates templateFormatString (and derived functions) to pass fallback value in, use in case of missing variable
Updates tests, baseline images per above changes

Demo video or screenshots

Before	After

Testing

Be on master

Load the following mock using plotly.js DevTools:

{
  "data": [
    {
    "hovertemplate": "Time: %{x}<br>User: %{y}<br>Usage: $%{z:.2f}<extra></extra>",
    "hovertemplatefallback": "Citra Hops",
    "showscale": true,
    "z": {
      "dtype": "f8",
      "bdata": "fDCpKCrK3z8qBd4FpbLBv2heJFDdueQ/K6oBjlRe+D9AplffvPjNvzvbcCYz+M2/CHRAqHRE+T/z1/BG047oP4ueeUveC96/AAAAAAAA+H9wG8Guoqjdv+fvFiuEzt2/cPmepZ74zj++Ne6+y5z+vwAAAAAAAPh/YzyhakL+4b95UaNnjjTwvx+GFtigHNQ/+QOLgYgO7b/HExTEy5j2v0ENnx9Mc/c/2Zhm4TzmzL/GNbFGh0mxP2InDcHEy/a/KPrKUZVr4b81BjE/bGW8PxX1zj14avK/6N19s28L2D/SOz2hbjjjvwAAAAAAAPh/p/2pOS5B479X9hhz7qL9P4aDsNZupIu/AAAAAAAA+H83Lh+1SVLqPxx64lmTiPO/tWnv0gq8yj/DMFAPz1r/v/9asANAQPW/QDr0vL8yyT++nUiqhKHnPwwupFVl78U/XzGyNiCbvb/hr1BvSEXTvwa4sKwGqPe/J6aouPYI578AAAAAAAD4f2LC1/746fA/iEEAkdf91T9OFQ2YaTX8vwAAAAAAAPh/QA8qJjCl2L9NOahTWKnlv/nsCSfakuM/1Pz0Wvl+8D8enOD2C83tP1MVD7Xe2uq/zylztCLK07+KTA+JazPVPwBoGGqqN+8/VWYobMqq3r8AAAAAAAD4fzBuPE2Ms/G/9PWajqkj87+w1UonNgDqP/3Ng74os/U/+iMrXUFvsr9qgA6DeA7wP0KkKG0LJdc/rwoBL9Kk5L+P6aQIGyHXPwAAAAAAAPh/UhmlZMpXor8AAAAAAAD4f19fz+s89QTAv1gZewZN6j8hrkt3t0i2P8Dt4LnvItO/OIpGXqJ9tz/iHOwPFc3/v8FsDls1Hsy/04nor+7a1j8AAAAAAAD4fwAAAAAAAPh/S3Lu+S3f6b+hdpfJZA7gvwAAAAAAAPh/gMUgGEIK1T/02ryry/PgvwNc6tKvbOA/AAAAAAAA+H9TvHjHI//uP3hIyAw4d+a/l5Lxpmr41L8apYzLTBjZvxD0dqaOave/IzBrdqLz0j8UgR0sIbXQPw06yBDZ8XQ/hE70gPMGzr8EJo3KW6X2v3SGH1za69q/CzQW3gjv1b98MTRhQazpv8BzdZwCpcS/Mxz8H/jb2T8bAn5E0S3+P5EnXNaQWMY/AAAAAAAA+H9gVYk14w6zv+1yI3JJs/6/OEbHD3Qmm78AAAAAAAD4f7gI2ke4tANA5IZhukifyL9yMGE5jUzTPwgyV7e9xaG/zxHyveey8r9cb1eTAEnyP1Z/Bd3VD+g/",
      "shape": "10, 12"
    },
    "type": "heatmap"
    }
  ]
}

Hover over a blank square and note that the 'Usage' line contains the format specifier
Switch to this branch
Reload the same mock
Hover over a blank square and note that the 'Usage' line contains the fallback value
Update the mock value for hovertemplatefallback to be false and reload the mock
Hover over a blank square and note that the 'Usage' line contains the format specifier
Remove hovertemplatefallback from the mock and reload the mock
Hover over a blank square and note that the 'Usage' line contains the default fallback value

Notes

The default fallback value is a dash: '-'
Setting a fallback value of false will result in the specifier being returned (the current behavior)
The linting/formatting changes make it hard to review this PR. I'd suggest looking at individual commits. For the most part, these touch different files.

TODO

Add draftlog
Add/update tests for fallback value

FYI @alexshoe.

@camdecoster A couple high-level comments before I dig into the gritty details:

I'm starting to feel that - might be a better default fallback value than empty string, because it indicates that it's a placeholder for something, which looks less awkward when you're using the templated value as part of a sentence. To take an example from the Jasmine tests, '- of -' looks less awkward than ' of '.
We've discussed that there are two separate scenarios where a value may end up as undefined: (1) is where the attribute named in the template simply doesn't exist, and (2) is where the attribute exists, but some individual data values happen to be undefined. I do think these two cases should be handled differently. The first is an error on the chart developer's part, and they should be alerted to it so they can fix it; the second is a normal quirk of the data and should be handled seamlessly. Open to discussing further but at the moment my suggestion is:
- If the attribute named in the hovertemplate does not exist (e.g. dev has provided hovertemplate 'value: %{foo:.2f}' but trace.foo is not an existing attribute): Maintain existing behavior -- raw template string is rendered in hover tooltip
- If attribute named in hovertemplate does exist, but the individual data value happens to be undefined (e.g. dev has provided hovertemplate 'value: %{foo:.2f}' and trace.foo is [1, undefined, 2]: Template string is replaced with hovertemplatefallback, AND no warning is emitted. So basically the behavior implemented in this PR, but without the warning. My feeling is that the dev has not done anything wrong and doesn't need to change anything, so a warning is just log noise at that point.

Need to set the correct editType here, I think it should be calc (or possibly plot?)

Reference for meaning of different editType values

After reviewing the changes again, I think it should be 'none' for hovertemplatefallback, 'calc' for texttemplatefallback, and 'arraydraw' for the shape text template fallback. I'll go through and double check all of them.

@emilykl in the case of a Studio app showing this, the creator isn't necessarily going to understand what a hover template is and would think that the output is a bug showing garbled data (which is how this issue was found in the first place). Maybe we could use a different default value in the case of a missing key name. Something like 'value: foo not found in bar'?

I'm fine with delineating between the two cases, so I'll work on that. Using '-' as the default also seems reasonable as the empty string may not be interpreted as missing data; it could just look wrong.

@camdecoster Yeah I do feel strongly about differentiating the two cases (and issuing a warning only in the case where the variable name does not exist) but worth discussing what is the correct string to display in the "variable does not exist" case.

Ideally something that doesn't use English words... what about the variable name surrounded by question marks? So that hovertemplate 'value: %{foo:.2f}' would become 'value: ?foo?' ?

nit: IMO this argument should continue to be called d3locale for clarity

I'm going to leave it as is since the JSDoc description explains what it is.

@camdecoster My above comments still stand but I've finished reviewing the code and everything looks great otherwise 👍

…ty-string-template-format-function

This reverts commit 84fc044.

hm this is a tough one, the question is whether lib.nestedProperty(obj, key).get() provides a way to distinguish between "the value of this key path is undefined" vs. "this key path was not found in the object"

This is moot since I removed this part of the code.

I looked into providing a different value for missing vs. undefined values but that didn't work. When a value is undefined, the key for that variable might be missing from the data object passed in. So I moved forward with the fallback value getting used all the time when a value is missing. To return the specifier (the current behavior), you must set hovertemplatefallback or texttemplatefallback to false.

Let's see how the community responds (if they do) and we can adjust if necessary.

Suggested change

      
                                    `Using value: '${fallbackValue}'.`
          
                                    fallback === false ? '' : `Using fallback value: '${fallbackValue}'.`

As we discussed, I'm going to leave this as is since it clarifies what the variable is being replaced with.

@camdecoster nit: these should be single-quoted strings – does the Biome formatter enforce that?

Double quotes are okay in this case because single quotes are used within the strings: that's and 'false'. This way no quotes need to be escaped.

Nice! 🚀

camdecoster added 16 commits October 8, 2025 18:05

Linting/formatting

e980e44

Return empty string for undefined value in templateFormatString

212f892

Refactoring

75b157f

Add fallback value for template strings

5f3670f

Add fallback to calls to hovertemplateString

336e9ae

Add fallback to calls to texttemplateString

02a4cad

Add fallback to calls to texttemplateStringForShapes

77bc2b9

Update defaults calculations

85b67e9

Add helper function for template fallback attributes

680c793

Add fallback value to attributes files

52c29cc

Update esbuild strip meta plugin to handle more joined arrays

f623b22

Return array from ternary

074f8a0

Update tests per default fallback value

6f3daa8

Update schema

6719bd3

Update test baselines

84fc044

Rename object keys

e719f74

gvwilson requested a review from emilykl October 9, 2025 12:15

gvwilson assigned camdecoster Oct 9, 2025

gvwilson added feature something new P1 needed for current cycle labels Oct 9, 2025

camdecoster added 2 commits October 9, 2025 09:25

Add/update tests to check fallback value

fb7a40c

Add draftlog

faaae28

camdecoster marked this pull request as ready for review October 9, 2025 15:36

emilykl reviewed Oct 14, 2025

View reviewed changes

emilykl reviewed Oct 21, 2025

View reviewed changes

Comment thread src/plots/template_attributes.js Outdated

emilykl reviewed Oct 21, 2025

View reviewed changes

Comment thread src/plots/template_attributes.js Outdated

emilykl reviewed Oct 21, 2025

View reviewed changes

Comment thread src/plots/template_attributes.js Outdated

emilykl reviewed Oct 21, 2025

View reviewed changes

camdecoster added 8 commits October 21, 2025 15:57

Fix typos

5c032c6

Update fallback editType to match template

a0ce641

Handle undefined values and missing values differently

14ab31c

Update default fallback value and template attribute descriptions

4f79efe

Add tests for missing and undefined values

257475c

Update schema

a148edd

Merge remote-tracking branch 'origin/master' into cam/7564/return-emp…

c40fe9f

…ty-string-template-format-function

Revert "Update test baselines"

6a66148

This reverts commit 84fc044.

emilykl reviewed Oct 23, 2025

View reviewed changes

camdecoster added 5 commits October 24, 2025 15:33

Always use fallback for missing values, except when fallback is false

5215f13

Update schema

30f87f3

Update mocks to show fallback values

b61d70d

Update tests per final behavior

d900ca3

Update baseline images

a061787

camdecoster requested a review from emilykl October 27, 2025 14:39

emilykl reviewed Oct 27, 2025

View reviewed changes

emilykl approved these changes Oct 27, 2025

View reviewed changes

camdecoster merged commit 222a6f5 into master Oct 27, 2025
6 checks passed

camdecoster deleted the cam/7564/return-empty-string-template-format-function branch October 27, 2025 20:28

emilykl mentioned this pull request Jan 26, 2026

Multi-axis Shapes #7666

Merged

5 tasks

+               * @param {array}   options.data - Data objects containing substitution values
+               * @param {string}  options.fallback - Fallback value when substitution fails
+               * @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

                               if (!SIMPLE_PROPERTY_REGEX.test(key)) {
                                   // true here means don't convert null to undefined
                                   value = lib.nestedProperty(obj, key).get(true);
+                                  keyIsMissing = false;

                                       `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}'.`

                   dflt: '-',
                   editType,
-                  description: "Fallback value that's displayed when a variable referenced in a template has an undefined value."
+                  description: [

+                  ].join(' ')
+              });
+              exports.templatefallbackAttrs = ({ editType = 'none' } = {}) => ({

	`Using value: '${fallbackValue}'.`
	fallback === false ? '' : `Using fallback value: '${fallbackValue}'.`

feat: Add template string fallback attributes by camdecoster · Pull Request #7577 · plotly/plotly.js · GitHub

Uh oh!

Uh oh!

feat: Add template string fallback attributes - #7577

feat: Add template string fallback attributes#7577camdecoster merged 31 commits intomasterplotly/plotly.js:masterfrom cam/7564/return-empty-string-template-format-functionplotly/plotly.js:cam/7564/return-empty-string-template-format-functionCopy head branch name to clipboard

Conversation

camdecoster commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Demo video or screenshots

Testing

Notes

TODO

Uh oh!

camdecoster commented Oct 9, 2025

Uh oh!

emilykl commented Oct 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

emilykl Oct 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camdecoster commented Oct 15, 2025

Uh oh!

emilykl commented Oct 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emilykl commented Oct 21, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

camdecoster commented Oct 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

emilykl left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

feat: Add template string fallback attributes#7577
camdecoster merged 31 commits into
masterfrom
cam/7564/return-empty-string-template-format-function

camdecoster commented Oct 9, 2025 •
edited
Loading

emilykl commented Oct 9, 2025 •
edited
Loading

emilykl Oct 14, 2025 •
edited
Loading

emilykl commented Oct 16, 2025 •
edited
Loading