diff --git a/docs/web/localizing.md b/docs/web/localizing.md index 137cd70e..e458b7a3 100644 --- a/docs/web/localizing.md +++ b/docs/web/localizing.md @@ -52,7 +52,35 @@ RevealSdkSettings.localizedStringsProvider = function (element, context) { ![](images/localization-test-visualization-fields.jpg) -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. + +| Element type | Raised for | +| --- | --- | +| `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 | +| `VisualizationFieldLabel` | A field that is being used in a visualization, and can have an aggregation applied to it | + +In other words, `FieldLabel` and `VisualizationFieldLabel` only cover fields that are already bound into a dashboard or a visualization — they are not raised for schema-driven pickers such as the field list shown when adding a dashboard filter. See [Localizing dashboard filter fields](#localizing-dashboard-filter-fields) below for how to localize that list. + +## Localizing dashboard filter fields {#localizing-dashboard-filter-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. + +```js +revealView.onFieldsInitializing = function (args) { + var editedFields = args.fields; + // change name to show to Spend field to Spent + var fieldToChange = editedFields.find(f => f.name == "Spend"); + if (fieldToChange) { fieldToChange.label = "Spent"; } + args.fields = editedFields; +} +``` + +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. ## Example: Selecting the locale from a combo box diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/localizing.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/localizing.md index 8eeb407a..af4c65c0 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/web/localizing.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/web/localizing.md @@ -52,7 +52,35 @@ RevealSdkSettings.localizedStringsProvider = function (element, context) { ![](images/localization-test-visualization-fields.jpg) -この方法を使用して、要素タイプ `DashboardFilterTitle`、`DashboardTitle`、`FieldLabel`、`VisualizationFieldLabel`、および `VisualizationTitle` のローカライズ動作をカスタマイズできます。 +`localizedStringsProvider` はダッシュボード モデルに対するパスです。ダッシュボードのタイトル、グローバル フィルター、およびすでにダッシュボードの一部になっているウィジェットを走査し、そのモデルにバインドされている要素のみを認識します。データ ソースのスキーマから直接生成される UI 要素、たとえばダッシュボード フィルターを追加する際に表示されるフィールド ピッカーには、このイベントはフックされません。以下の表は、各要素タイプが実際にどこで発生するかを示しています。 + +| 要素タイプ | 発生するタイミング | +| --- | --- | +| `DashboardTitle` | ダッシュボードのタイトル | +| `DashboardFilterTitle` | すでにダッシュボードに追加されているグローバル (ダッシュボード) フィルターのタイトル | +| `VisualizationTitle` | ビジュアライゼーションのタイトル | +| `FieldLabel` | ダッシュボードにバインドされているが、まだどのビジュアライゼーションにも含まれておらず、サマリー定義でも使用されていないフィールド | +| `VisualizationFieldLabel` | ビジュアライゼーションで使用されている、集計が適用され得るフィールド | + +つまり、`FieldLabel` と `VisualizationFieldLabel` は、すでにダッシュボードやビジュアライゼーションにバインドされているフィールドのみをカバーします。ダッシュボード フィルターを追加する際に表示されるフィールド一覧のような、スキーマ駆動のピッカーに対しては発生しません。このフィールド一覧をローカライズする方法については、以下の[ダッシュボード フィルターのフィールドをローカライズする](#localizing-dashboard-filter-fields)を参照してください。 + +## ダッシュボード フィルターのフィールドをローカライズする {#localizing-dashboard-filter-fields} + +**ダッシュボード フィルターの追加** を選択し、続けて **フィールドを選択** を選ぶと表示されるフィールド一覧は、ダッシュボード モデルではなく、データ ソースのスキーマから直接生成されます。`localizedStringsProvider` はダッシュボードにすでにバインドされている要素しか処理しないため、この一覧に対しては呼び出されず、ここから翻訳を返してもフィールド ピッカーには反映されません。 + +この一覧に表示されるフィールド名をカスタマイズするには、代わりに `revealView.onFieldsInitializing` イベントを使用します。このイベントは、ダッシュボード フィルターのフィールド ピッカーを含め、データ ソースのスキーマからフィールド一覧が生成されるたびに発生し、表示されるフィールドの名前変更、削除、並べ替えができます。 + +```js +revealView.onFieldsInitializing = function (args) { + var editedFields = args.fields; + // Spend フィールドの表示名を Spent に変更する + var fieldToChange = editedFields.find(f => f.name == "Spend"); + if (fieldToChange) { fieldToChange.label = "Spent"; } + args.fields = editedFields; +} +``` + +フィールドがダッシュボード フィルターとして選択された後も、フィルター コントロールはピッカーに表示されていたものと変わらず、`onFieldsInitializing` で設定したラベルを引き続き表示します。 ## 例: コンボ ボックスからロケールを選択する diff --git a/i18n/ja/docusaurus-plugin-content-docs/version-1.8.4/web/localizing.md b/i18n/ja/docusaurus-plugin-content-docs/version-1.8.4/web/localizing.md index 50e8d7cf..268b1769 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/version-1.8.4/web/localizing.md +++ b/i18n/ja/docusaurus-plugin-content-docs/version-1.8.4/web/localizing.md @@ -52,7 +52,35 @@ $.ig.RevealSdkSettings.localizedStringsProvider = function (element, context) { ![](images/localization-test-visualization-fields.jpg) -この方法を使用して、要素タイプ `DashboardFilterTitle`、`DashboardTitle`、`FieldLabel`、`VisualizationFieldLabel`、および `VisualizationTitle` のローカライズ動作をカスタマイズできます。 +`$.ig.RevealSdkSettings.localizedStringsProvider` はダッシュボード モデルに対するパスです。ダッシュボードのタイトル、グローバル フィルター、およびすでにダッシュボードの一部になっているウィジェットを走査し、そのモデルにバインドされている要素のみを認識します。データ ソースのスキーマから直接生成される UI 要素、たとえばダッシュボード フィルターを追加する際に表示されるフィールド ピッカーには、このイベントはフックされません。以下の表は、各要素タイプが実際にどこで発生するかを示しています。 + +| 要素タイプ | 発生するタイミング | +| --- | --- | +| `DashboardTitle` | ダッシュボードのタイトル | +| `DashboardFilterTitle` | すでにダッシュボードに追加されているグローバル (ダッシュボード) フィルターのタイトル | +| `VisualizationTitle` | ビジュアライゼーションのタイトル | +| `FieldLabel` | ダッシュボードにバインドされているが、まだどのビジュアライゼーションにも含まれておらず、サマリー定義でも使用されていないフィールド | +| `VisualizationFieldLabel` | ビジュアライゼーションで使用されている、集計が適用され得るフィールド | + +つまり、`FieldLabel` と `VisualizationFieldLabel` は、すでにダッシュボードやビジュアライゼーションにバインドされているフィールドのみをカバーします。ダッシュボード フィルターを追加する際に表示されるフィールド一覧のような、スキーマ駆動のピッカーに対しては発生しません。このフィールド一覧をローカライズする方法については、以下の[ダッシュボード フィルターのフィールドをローカライズする](#localizing-dashboard-filter-fields)を参照してください。 + +## ダッシュボード フィルターのフィールドをローカライズする {#localizing-dashboard-filter-fields} + +**ダッシュボード フィルターの追加** を選択し、続けて **フィールドを選択** を選ぶと表示されるフィールド一覧は、ダッシュボード モデルではなく、データ ソースのスキーマから直接生成されます。`$.ig.RevealSdkSettings.localizedStringsProvider` はダッシュボードにすでにバインドされている要素しか処理しないため、この一覧に対しては呼び出されず、ここから翻訳を返してもフィールド ピッカーには反映されません。 + +この一覧に表示されるフィールド名をカスタマイズするには、代わりに `revealView.onFieldsInitializing` イベントを使用します。このイベントは、ダッシュボード フィルターのフィールド ピッカーを含め、データ ソースのスキーマからフィールド一覧が生成されるたびに発生し、表示されるフィールドの名前変更、削除、並べ替えができます。 + +```js +revealView.onFieldsInitializing = function (args) { + var editedFields = args.fields; + // Spend フィールドの表示名を Spent に変更する + var fieldToChange = editedFields.find(f => f.name == "Spend"); + if (fieldToChange) { fieldToChange.label = "Spent"; } + args.fields = editedFields; +} +``` + +フィールドがダッシュボード フィルターとして選択された後も、フィルター コントロールはピッカーに表示されていたものと変わらず、`onFieldsInitializing` で設定したラベルを引き続き表示します。 ## 例: コンボ ボックスからロケールを選択する diff --git a/versioned_docs/version-1.8.4/web/localizing.md b/versioned_docs/version-1.8.4/web/localizing.md index cce6e926..ad777b79 100644 --- a/versioned_docs/version-1.8.4/web/localizing.md +++ b/versioned_docs/version-1.8.4/web/localizing.md @@ -52,7 +52,35 @@ $.ig.RevealSdkSettings.localizedStringsProvider = function (element, context) { ![](images/localization-test-visualization-fields.jpg) -You can use this way to customize the localization behavior for the following element types: `DashboardFilterTitle`, `DashboardTitle`, `FieldLabel`, `VisualizationFieldLabel` and `VisualizationTitle`. +`$.ig.RevealSdkSettings.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. + +| Element type | Raised for | +| --- | --- | +| `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 | +| `VisualizationFieldLabel` | A field that is being used in a visualization, and can have an aggregation applied to it | + +In other words, `FieldLabel` and `VisualizationFieldLabel` only cover fields that are already bound into a dashboard or a visualization — they are not raised for schema-driven pickers such as the field list shown when adding a dashboard filter. See [Localizing dashboard filter fields](#localizing-dashboard-filter-fields) below for how to localize that list. + +## Localizing dashboard filter fields {#localizing-dashboard-filter-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 `$.ig.RevealSdkSettings.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. + +```js +revealView.onFieldsInitializing = function (args) { + var editedFields = args.fields; + // change name to show to Spend field to Spent + var fieldToChange = editedFields.find(f => f.name == "Spend"); + if (fieldToChange) { fieldToChange.label = "Spent"; } + args.fields = editedFields; +} +``` + +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. ## Example: Selecting the locale from a combo box