feat: Add template string fallback attributes #7577

camdecoster · 2025-10-09T00:18:54Z

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

camdecoster · 2025-10-09T19:59:11Z

FYI @alexshoe.

emilykl · 2025-10-09T21:17:57Z

@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.

emilykl · 2025-10-14T22:20:02Z

src/plots/template_attributes.js

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


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.

camdecoster · 2025-10-15T23:47:32Z

@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.

emilykl · 2025-10-16T15:30:16Z

@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?' ?

emilykl · 2025-10-21T21:15:31Z

src/plots/template_attributes.js

+        'Note that this will override `hoverinfo`.',
+        templateFormatStringDescription({ supportOther: true }),
+        'The variables available in `hovertemplate` are the ones emitted as event data described at this link https://plotly.com/javascript/plotlyjs-events/#event-data.',
+        'Additionally, every attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',


Suggested change

'Additionally, every attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',

'Additionally, all attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',

emilykl · 2025-10-21T21:17:07Z

src/plots/template_attributes.js

+        'Template string used for rendering the information text that appears on points.',
+        'Note that this will override `textinfo`.',
+        templateFormatStringDescription(),
+        'Every attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',


Suggested change

'Every attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',

'All attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',

emilykl · 2025-10-21T21:20:53Z

src/plots/template_attributes.js

+    valType: 'string',
+    dflt: '',
+    editType,
+    description: "Fallback value that's displayed when a variable referenced in a template can't be found."


just a comment to flag that this description should be updated once the final behavior is decided (e.g. Fallback value that's displayed when a variable referenced in a template has an undefined value)

emilykl · 2025-10-21T21:49:35Z

src/lib/index.js

+ * @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


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

emilykl · 2025-10-21T21:51:51Z

@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.

emilykl · 2025-10-23T21:06:12Z

src/lib/index.js

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


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"

camdecoster · 2025-10-24T22:16:54Z

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.

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

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

	'Additionally, every attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',
	'Additionally, all attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',

	'Every attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',
	'All attributes that can be specified per-point (the ones that are `arrayOk: true`) are available.',

Uh oh!

feat: Add template string fallback attributes #7577

Are you sure you want to change the base?

feat: Add template string fallback attributes #7577

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!

camdecoster Oct 15, 2025

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!

emilykl Oct 21, 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!

emilykl Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

emilykl Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

emilykl Oct 21, 2025

Choose a reason for hiding this comment

Uh oh!

emilykl commented Oct 21, 2025

Uh oh!

emilykl Oct 23, 2025

Choose a reason for hiding this comment

Uh oh!

camdecoster commented Oct 24, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

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

emilykl Oct 21, 2025 •

edited

Loading