Better localization docs for dashboard elements and field picker customization - #735
Better localization docs for dashboard elements and field picker customization#735zdrawku wants to merge 2 commits into
Conversation
…icker customization
|
hmm, this PR would just describe onFieldsInitializing as the supported hook for the entry list, but it would be better to handle it as a code fix we should either wire localizedStringsProvider into the picker, or make the selected-value renderer use field.label instead of field.FieldName RevealBi/Reveal.Sdk#700 So, this PR should be merged once the issue in the SDK is addressed |
PVillarmarzo
left a comment
PVillarmarzo
left a comment
There was a problem hiding this comment.
I left a few comments around wording precision, the distinction between FieldLabel and VisualizationFieldLabel, the scope of onFieldsInitializing, and keeping the 1.8.4 documentation aligned with the actual behavior of that version.
| } | ||
| ``` | ||
|
|
||
| Once a field is selected as a dashboard filter, the filter control continues to display the label assigned through `onFieldsInitializing`, consistent with what was shown in the picker. |
There was a problem hiding this comment.
Since the SDK fix will not be backported to 1.8.4, this statement should not be included in the 1.8.4 documentation. The versioned docs should reflect the actual behavior of that release. The onFieldsInitializing guidance for the picker entries is still valid, but the selected Field value will continue to display the raw field name in 1.8.4.
|  | ||
|
|
||
| You can use this way to customize the localization behavior for the following element types: `DashboardFilterTitle`, `DashboardTitle`, `FieldLabel`, `VisualizationFieldLabel` and `VisualizationTitle`. | ||
| `localizedStringsProvider` is a dashboard-model pass: it walks the dashboard title, global filters, and widgets that are already part of the dashboard, and only ever sees elements that have been bound into that model. It does not hook into UI surfaces that are populated directly from a data source's schema, such as the field picker shown when adding a dashboard filter. The table below shows where each element type is actually raised. |
There was a problem hiding this comment.
I think this wording is a bit too implementation-specific and absolute for the public docs. localizedStringsProvider is also invoked for supported elements while creating visualizations, so describing it as a “dashboard-model pass” that “only ever sees” already-bound elements may be misleading.
Could we describe the observable behavior instead? For example:
“localizedStringsProvider is invoked for supported dashboard and visualization titles and field metadata. It is not invoked for the schema fields returned specifically for the dashboard-filter field picker.”
| | `DashboardTitle` | The dashboard's title | | ||
| | `DashboardFilterTitle` | The title of a global (dashboard) filter that has already been added to the dashboard | | ||
| | `VisualizationTitle` | A visualization's title | | ||
| | `FieldLabel` | A field that is bound to the dashboard but not (yet) part of any visualization, nor used in a summarization definition | |
There was a problem hiding this comment.
The FieldLabel description may be too narrow. In the current implementation, it can be raised for fields in the tabular field collection even when those fields are also used by the visualization.
Suggested wording:
“A source field available to a tabular visualization. This can include fields that are not currently selected by the visualization.”
| | `DashboardFilterTitle` | The title of a global (dashboard) filter that has already been added to the dashboard | | ||
| | `VisualizationTitle` | A visualization's title | | ||
| | `FieldLabel` | A field that is bound to the dashboard but not (yet) part of any visualization, nor used in a summarization definition | | ||
| | `VisualizationFieldLabel` | A field that is being used in a visualization, and can have an aggregation applied to it | |
There was a problem hiding this comment.
The VisualizationFieldLabel description may be incomplete. It is raised for fields or calculated columns used by a visualization, including non-measure fields, which report Auto as their aggregation type.
Suggested wording:
“A field or calculated column used by a visualization. The element includes its aggregation type, which is Auto for non-measure fields.”
|
|
||
| When you choose **Add Dashboard Filter** and then **Select a field**, the field list shown there is populated directly from the data source's schema, not from the dashboard model. Because `localizedStringsProvider` only processes elements already bound into the dashboard, it is never invoked for this list, and returning a translation from it has no effect on the field picker. | ||
|
|
||
| To customize the field names shown in this list, use the `revealView.onFieldsInitializing` event instead. It is raised whenever a field list is being populated from a data source's schema — including the dashboard filter field picker — and lets you rename, remove, or reorder the fields shown. |
There was a problem hiding this comment.
“Whenever a field list is being populated” seems too absolute. Could we limit this to the known supported surfaces: the visualization editor after selecting a data source and the tabular dashboard-filter field picker?
2 participants
localizedStringsProviderdoesn't cover the filter field picker, withrevealView.onFieldsInitializingas the supported hook.onFieldsInitializing, matching what's shown in the picker — this was a known gap, now resolved as of the corresponding SDK fix (see [related PR/issue link]).$.ig.prefix convention in the 1.8.4 files while keepingonFieldsInitializingunprefixed (correctly, since it's set on theRevealViewinstance).{#localizing-dashboard-filter-fields}anchors so the cross-reference link resolves correctly even where the heading text is in Japanese.VisualizationFieldLabelwas left untouched as the correct public API name.