From ec5b6a195e1e60b7d965b045bb68a50a9a4ef392 Mon Sep 17 00:00:00 2001 From: Brian Lagunas <835562+brianlagunas@users.noreply.github.com> Date: Fri, 15 May 2026 21:33:58 -0600 Subject: [PATCH 1/2] Reshuffle webSidebar to scenario-led IA + rename customizing/ to scenarios/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructures the Web SDK sidebar around customer goals (per industry convention from Tableau, Power BI, Sisense, ThoughtSpot, QuickSight, Looker). The previous feature-bucket IA (Dashboards / Visualizations / Customizing the Reveal View) dissolves; existing pages slot into their future homes as transitional placeholders awaiting per-page migration in upcoming sub-PRs. New top-level groups: - Get Started (unchanged) - Embedding (Loading/Creating/Saving as transitional; will merge into Embed a Dashboard + Embed a Single Visualization) - Common Patterns (top-level — promoted from Customizing sub-cat. Holds the 4 existing scenarios + 5 transitional feature pages awaiting scenario rewrite: Filtering, Linking, Click Events, Theming, Localization) - Connect Data (renamed from "Working with Data Sources"; unchanged) - Export and Share (renamed from "Exporting"; unchanged) - Server Configuration (unchanged) - Reference (Editor Events, Custom Visualizations, Custom Menu Items, Customizing Map Tiles, Tooltips, Maximizing, Chart Types — feature topics that are reference-shaped. Plus Data Limits, Beta Features, Accessibility, Known Issues, Third-Party Software.) - Releases (unchanged) The "Customizing the Reveal View" group dissolves entirely. Visualizations dissolves; its members go to Reference (or migrate to scenarios in later PRs). Folder rename: docs/web/customizing/ → docs/web/scenarios/ (EN + JA). "Customizing" was too narrow once Common Patterns grew to cover non- customization scenarios (read-only embed, multi-dashboard navigation, drill-through). "scenarios" is generic and future-proof. Redirects added for all 5 customizing/* paths and the customizing/ root. The /web/editing-dashboards redirect target updated from /web/customizing to /web/scenarios. Cross-link in editor-events.md (EN + JA) updated to point at new path. Known follow-ups (per IA-v2 plan): - Sub-PR #2: Concepts page - Sub-PR #3: Embed a Dashboard + Embed a Single Visualization (replaces Embedding section's transitional Loading/Creating/Saving) - Sub-PRs #4-7: Migrate Click Events, Filtering, Linking, Theming, Localization to proper Common Patterns scenarios - Sub-PRs #10-12: Multi-Tenant, RLS, Custom Viz Library Solutions guides Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/web/editor-events.md | 2 +- .../custom-save-workflow.md | 0 .../editor-on-load-kiosk.md | 0 docs/web/{customizing => scenarios}/index.md | 0 .../locked-down-export.md | 0 .../view-only-embed.md | 0 docusaurus.config.ts | 17 +++- .../current/web/editor-events.md | 2 +- .../custom-save-workflow.md | 0 .../editor-on-load-kiosk.md | 0 .../web/{customizing => scenarios}/index.md | 0 .../locked-down-export.md | 0 .../view-only-embed.md | 0 sidebars.ts | 80 ++++++++++--------- 14 files changed, 57 insertions(+), 44 deletions(-) rename docs/web/{customizing => scenarios}/custom-save-workflow.md (100%) rename docs/web/{customizing => scenarios}/editor-on-load-kiosk.md (100%) rename docs/web/{customizing => scenarios}/index.md (100%) rename docs/web/{customizing => scenarios}/locked-down-export.md (100%) rename docs/web/{customizing => scenarios}/view-only-embed.md (100%) rename i18n/ja/docusaurus-plugin-content-docs/current/web/{customizing => scenarios}/custom-save-workflow.md (100%) rename i18n/ja/docusaurus-plugin-content-docs/current/web/{customizing => scenarios}/editor-on-load-kiosk.md (100%) rename i18n/ja/docusaurus-plugin-content-docs/current/web/{customizing => scenarios}/index.md (100%) rename i18n/ja/docusaurus-plugin-content-docs/current/web/{customizing => scenarios}/locked-down-export.md (100%) rename i18n/ja/docusaurus-plugin-content-docs/current/web/{customizing => scenarios}/view-only-embed.md (100%) diff --git a/docs/web/editor-events.md b/docs/web/editor-events.md index 5f2941f5..c3d3793b 100644 --- a/docs/web/editor-events.md +++ b/docs/web/editor-events.md @@ -2,7 +2,7 @@ The Visualization Editor exposes four lifecycle events you can hook into to run code before or after the editor opens or closes. Each event is paired below with a realistic example beyond the basic signature. -For property-level customization (`canX` / `showX` toggles for menu items and buttons), see [Common Patterns](customizing/index.md). For the full property surface, see the [`RevealView` API reference](https://help.revealbi.io/api/javascript/latest/classes/RevealView.html). +For property-level customization (`canX` / `showX` toggles for menu items and buttons), see [Common Patterns](scenarios/index.md). For the full property surface, see the [`RevealView` API reference](https://help.revealbi.io/api/javascript/latest/classes/RevealView.html). ## onVisualizationEditorOpening diff --git a/docs/web/customizing/custom-save-workflow.md b/docs/web/scenarios/custom-save-workflow.md similarity index 100% rename from docs/web/customizing/custom-save-workflow.md rename to docs/web/scenarios/custom-save-workflow.md diff --git a/docs/web/customizing/editor-on-load-kiosk.md b/docs/web/scenarios/editor-on-load-kiosk.md similarity index 100% rename from docs/web/customizing/editor-on-load-kiosk.md rename to docs/web/scenarios/editor-on-load-kiosk.md diff --git a/docs/web/customizing/index.md b/docs/web/scenarios/index.md similarity index 100% rename from docs/web/customizing/index.md rename to docs/web/scenarios/index.md diff --git a/docs/web/customizing/locked-down-export.md b/docs/web/scenarios/locked-down-export.md similarity index 100% rename from docs/web/customizing/locked-down-export.md rename to docs/web/scenarios/locked-down-export.md diff --git a/docs/web/customizing/view-only-embed.md b/docs/web/scenarios/view-only-embed.md similarity index 100% rename from docs/web/customizing/view-only-embed.md rename to docs/web/scenarios/view-only-embed.md diff --git a/docusaurus.config.ts b/docusaurus.config.ts index a0dd0085..8858d8ce 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -62,10 +62,19 @@ const config: Config = { { from: '/web/web-component-wrappers/reveal-view/loading-dashboards', to: '/web-components/reveal-view/loading-dashboards' }, { from: '/web/web-component-wrappers/visualization-viewer', to: '/web-components/visualization-viewer' }, { from: '/web/web-component-wrappers/visualization-viewer/options', to: '/web-components/visualization-viewer/options' }, - // editing-dashboards.md replaced by scenario-driven Common Patterns under - // /web/customizing/* plus per-event examples in /web/editor-events. Old URL - // points at the Common Patterns overview as the most natural landing. - { from: '/web/editing-dashboards', to: '/web/customizing' }, + // editing-dashboards.md replaced by scenario-driven Common Patterns + // plus per-event examples in /web/editor-events. Old URL points at the + // Common Patterns overview as the most natural landing. + { from: '/web/editing-dashboards', to: '/web/scenarios' }, + // /web/customizing/* renamed to /web/scenarios/* in the scenario-led + // sidebar reshuffle. Original "Customizing" framing was too narrow once + // the section grew to cover non-customization patterns (read-only embed, + // multi-dashboard navigation, drill-through, etc.). + { from: '/web/customizing', to: '/web/scenarios' }, + { from: '/web/customizing/view-only-embed', to: '/web/scenarios/view-only-embed' }, + { from: '/web/customizing/custom-save-workflow', to: '/web/scenarios/custom-save-workflow' }, + { from: '/web/customizing/locked-down-export', to: '/web/scenarios/locked-down-export' }, + { from: '/web/customizing/editor-on-load-kiosk', to: '/web/scenarios/editor-on-load-kiosk' }, ], }], ], diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/editor-events.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/editor-events.md index 5f2941f5..c3d3793b 100644 --- a/i18n/ja/docusaurus-plugin-content-docs/current/web/editor-events.md +++ b/i18n/ja/docusaurus-plugin-content-docs/current/web/editor-events.md @@ -2,7 +2,7 @@ The Visualization Editor exposes four lifecycle events you can hook into to run code before or after the editor opens or closes. Each event is paired below with a realistic example beyond the basic signature. -For property-level customization (`canX` / `showX` toggles for menu items and buttons), see [Common Patterns](customizing/index.md). For the full property surface, see the [`RevealView` API reference](https://help.revealbi.io/api/javascript/latest/classes/RevealView.html). +For property-level customization (`canX` / `showX` toggles for menu items and buttons), see [Common Patterns](scenarios/index.md). For the full property surface, see the [`RevealView` API reference](https://help.revealbi.io/api/javascript/latest/classes/RevealView.html). ## onVisualizationEditorOpening diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/custom-save-workflow.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/custom-save-workflow.md similarity index 100% rename from i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/custom-save-workflow.md rename to i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/custom-save-workflow.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/editor-on-load-kiosk.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/editor-on-load-kiosk.md similarity index 100% rename from i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/editor-on-load-kiosk.md rename to i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/editor-on-load-kiosk.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/index.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/index.md similarity index 100% rename from i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/index.md rename to i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/index.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/locked-down-export.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/locked-down-export.md similarity index 100% rename from i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/locked-down-export.md rename to i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/locked-down-export.md diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/view-only-embed.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/view-only-embed.md similarity index 100% rename from i18n/ja/docusaurus-plugin-content-docs/current/web/customizing/view-only-embed.md rename to i18n/ja/docusaurus-plugin-content-docs/current/web/scenarios/view-only-embed.md diff --git a/sidebars.ts b/sidebars.ts index 21f55d01..2988708e 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -35,33 +35,44 @@ const sidebars: SidebarsConfig = { ] }, - /* -------------------- Dashboards -------------------- */ + /* -------------------- Embedding -------------------- + * Future home of unified "Embed a Dashboard" + "Embed a Single Visualization" + * topics. Loading/Creating/Saving live here as transitional placeholders + * and will be merged into those topics in upcoming sub-PRs. + */ { - type: "category", label: "Dashboards", collapsed: false, collapsible: false, className: "sidebar__header", items: [ + type: "category", label: "Embedding", collapsed: false, collapsible: false, className: "sidebar__header", items: [ { type: "doc", label: "Loading", id: "web/loading-dashboards" }, { type: "doc", label: "Creating", id: "web/creating-dashboards" }, { type: "doc", label: "Saving", id: "web/saving-dashboards" }, - { type: "doc", label: "Linking", id: "web/linking-dashboards" }, - { type: "doc", label: "Filtering", id: "web/filtering-dashboards" }, ] }, - /* -------------------- Visualizations -------------------- */ + /* -------------------- Common Patterns -------------------- + * Scenario recipes (1-page each). Files under docs/web/scenarios/. + * Existing feature pages (Click Events, Filtering, Linking, Theming, + * Localization) live here as transitional placeholders and will be + * rewritten as scenarios in upcoming sub-PRs. + */ { - type: "category", label: "Visualizations", collapsed: false, collapsible: false, className: "sidebar__header", items: [ - { type: "doc", label: "Chart Types", id: "web/chart-types" }, - { type: "doc", label: "Custom Visualizations", id: "web/custom-visualizations" }, - { type: "doc", label: "Custom Menu Items", id: "web/custom-menu-items" }, - { type: "doc", label: "Customizing Map Tiles", id: "web/customizing-map-tiles" }, - { type: "doc", label: "Maximizing", id: "web/maximizing-visualizations" }, - { type: "doc", label: "Tooltips", id: "web/tooltips" }, + type: "category", label: "Common Patterns", collapsed: false, collapsible: false, className: "sidebar__header", + link: { type: "doc", id: "web/scenarios/index" }, + items: [ + { type: "doc", label: "Read-only Embed", id: "web/scenarios/view-only-embed" }, + { type: "doc", label: "Editor on Load (Kiosk)", id: "web/scenarios/editor-on-load-kiosk" }, + { type: "doc", label: "Custom Save Destination", id: "web/scenarios/custom-save-workflow" }, + { type: "doc", label: "Locked-down Export Menu", id: "web/scenarios/locked-down-export" }, + { type: "doc", label: "Filtering", id: "web/filtering-dashboards" }, + { type: "doc", label: "Linking", id: "web/linking-dashboards" }, { type: "doc", label: "Click Events", id: "web/click-events" }, + { type: "doc", label: "Theming", id: "web/theming-dashboards" }, + { type: "doc", label: "Localization", id: "web/localizing" }, ] }, - /* -------------------- Data Sources -------------------- */ + /* -------------------- Connect Data -------------------- */ { - type: "category", label: "Data Sources", collapsed: false, collapsible: false, className: "sidebar__header", items: [ + type: "category", label: "Connect Data", collapsed: false, collapsible: false, className: "sidebar__header", items: [ { type: "doc", label: "Overview", key: "data-sources-overview", id: "web/datasources" }, { type: "doc", label: "Authentication", id: "web/authentication" }, { type: "doc", label: "User Context", id: "web/user-context" }, @@ -94,28 +105,9 @@ const sidebars: SidebarsConfig = { ] }, - /* -------------------- Customizing the Reveal View -------------------- */ + /* -------------------- Export and Share -------------------- */ { - type: "category", label: "Customizing the Reveal View", collapsed: false, collapsible: false, className: "sidebar__header", items: [ - { - type: "category", label: "Common Patterns", key: "customizing-common-patterns", - link: { type: "doc", id: "web/customizing/index" }, - items: [ - { type: "doc", label: "View-only Embed", id: "web/customizing/view-only-embed" }, - { type: "doc", label: "Custom Save Workflow", id: "web/customizing/custom-save-workflow" }, - { type: "doc", label: "Locked-down Export Menu", id: "web/customizing/locked-down-export" }, - { type: "doc", label: "Editor-on-Load Kiosk", id: "web/customizing/editor-on-load-kiosk" }, - ] - }, - { type: "doc", label: "Editor Events", id: "web/editor-events" }, - { type: "doc", label: "Theming", id: "web/theming-dashboards" }, - { type: "doc", label: "Localization", id: "web/localizing" }, - ] - }, - - /* -------------------- Exporting -------------------- */ - { - type: "category", label: "Exporting", collapsed: false, collapsible: false, className: "sidebar__header", items: [ + type: "category", label: "Export and Share", collapsed: false, collapsible: false, className: "sidebar__header", items: [ { type: "doc", label: "End-User Export", id: "web/exporting-dashboards" }, { type: "doc", label: "Server-Side Export", id: "web/server-export" }, { type: "doc", label: "Configure Server Export", id: "web/configure-export" }, @@ -130,12 +122,24 @@ const sidebars: SidebarsConfig = { ] }, - /* -------------------- Reference -------------------- */ + /* -------------------- Reference -------------------- + * Lookup-shaped content. Custom Visualizations, Custom Menu Items, + * Customizing Map Tiles, Tooltips, Maximizing, Editor Events, and + * Chart Types all live here as feature topics — the kind of thing + * a developer comes to look up rather than read end-to-end. + */ { type: "category", label: "Reference", collapsed: false, collapsible: false, className: "sidebar__header", items: [ - { type: "doc", label: "Accessibility", id: "web/accessibility" }, - { type: "doc", label: "Beta Features", id: "web/beta-features" }, + { type: "doc", label: "Editor Events", id: "web/editor-events" }, + { type: "doc", label: "Chart Types", id: "web/chart-types" }, + { type: "doc", label: "Custom Visualizations", id: "web/custom-visualizations" }, + { type: "doc", label: "Custom Menu Items", id: "web/custom-menu-items" }, + { type: "doc", label: "Customizing Map Tiles", id: "web/customizing-map-tiles" }, + { type: "doc", label: "Tooltips", id: "web/tooltips" }, + { type: "doc", label: "Maximizing", id: "web/maximizing-visualizations" }, { type: "doc", label: "Data Limits", id: "web/data-size-limits" }, + { type: "doc", label: "Beta Features", id: "web/beta-features" }, + { type: "doc", label: "Accessibility", id: "web/accessibility" }, { type: "doc", label: "Known Issues", id: "web/known-issues" }, { type: "doc", label: "Third-Party Software", id: "web/third-party-software" }, ] From d26aec0775212fe29db0d3c41309d5de16a3e444 Mon Sep 17 00:00:00 2001 From: Brian Lagunas <835562+brianlagunas@users.noreply.github.com> Date: Fri, 15 May 2026 22:01:51 -0600 Subject: [PATCH 2/2] Add Concepts page + Embed a Dashboard + Embed a Single Visualization MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three foundational topics for the new IA: - docs/web/concepts.md — mental model for client/server split, .rdash files, the four provider interfaces, and how a request flows through the SDK. Read once; the rest of the docs assume this vocabulary. - docs/web/embedding/dashboard.md — the canonical "embed a full dashboard" topic. Minimum code, variations (new empty dashboard, JSON source, embedded resource), and what's-next links into Common Patterns scenarios. Replaces the role of Loading/Creating as the primary embedding starting point. - docs/web/embedding/single-visualization.md — net-new content (was a documented gap). Covers Single Visualization Mode (locked) and Maximized Visualization (with navigation), plus dynamic switching between visualizations. Sidebar: - Concepts added under Get Started, right after Overview. - Embedding section now leads with the two new Embed topics. Loading, Creating, Saving remain below as transitional pages — they cover server-side IRVDashboardProvider patterns that move to a dedicated Dashboard Provider topic under Connect Data in a later sub-PR. JA placeholders mirrored for all three new pages. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/web/concepts.md | 64 +++++++++++ docs/web/embedding/dashboard.md | 77 +++++++++++++ docs/web/embedding/single-visualization.md | 104 ++++++++++++++++++ docusaurus.config.ts | 9 -- .../current/web/concepts.md | 64 +++++++++++ .../current/web/embedding/dashboard.md | 77 +++++++++++++ .../web/embedding/single-visualization.md | 104 ++++++++++++++++++ sidebars.ts | 10 +- 8 files changed, 497 insertions(+), 12 deletions(-) create mode 100644 docs/web/concepts.md create mode 100644 docs/web/embedding/dashboard.md create mode 100644 docs/web/embedding/single-visualization.md create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/web/concepts.md create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/web/embedding/dashboard.md create mode 100644 i18n/ja/docusaurus-plugin-content-docs/current/web/embedding/single-visualization.md diff --git a/docs/web/concepts.md b/docs/web/concepts.md new file mode 100644 index 00000000..71f33779 --- /dev/null +++ b/docs/web/concepts.md @@ -0,0 +1,64 @@ +# Concepts + +A short mental model for how the Reveal SDK fits together. Read this once; the rest of the docs assume this vocabulary. + +## Two pieces: client and server + +The Reveal SDK is split between a **client SDK** that runs in the browser and a **server SDK** that runs in your backend. + +| Piece | Runs in | Job | +|---|---|---| +| Client SDK | The browser, inside your web app | Renders the `RevealView` component, handles user interactions, sends data and dashboard requests to the server | +| Server SDK | Your backend (ASP.NET, Node.js, NestJS, Spring Boot) | Stores and serves dashboards, answers data queries, holds connection credentials | + +The client never talks to your data sources directly. It always goes through the server SDK, which is where credentials and connection strings live. This is what makes embedded analytics secure — sensitive details never reach the browser. + +## Dashboards as files + +A Reveal dashboard is a **`.rdash` file**. It's a binary container that holds the dashboard's layout, visualizations, filters, and references to data sources. Dashboards are typically saved on the server and loaded into the `RevealView` on demand. + +By convention, the server SDK looks for `.rdash` files in a folder named `Dashboards` in the working directory. You can override that convention by implementing a custom dashboard provider (see below). + +## The provider pattern + +The server SDK is configured by implementing a small set of **provider interfaces**. Each provider gives you a hook into one part of the SDK's behavior: + +| Provider | What it controls | +|---|---| +| **`IRVDashboardProvider`** | Where dashboards are loaded from and saved to (file system, database, blob storage, etc.) | +| **`IRVDataSourceProvider`** | The connection details for each data source (host, database, table, schema) — mutated per request based on user context | +| **`IRVAuthenticationProvider`** | The credentials used when connecting to a data source (username/password, token, key pair) | +| **`IRVUserContextProvider`** | The current user's identity and metadata, available to the other providers | + +Most embedded scenarios involve customizing one or more of these. For example: serving different dashboards to different tenants combines a custom `IRVDashboardProvider` (to scope dashboards by tenant) with a custom `IRVUserContextProvider` (to identify the tenant from the request). End-to-end multi-provider patterns will live under the upcoming **Solutions & Advanced Guides** section. + +## How a request flows + +A typical request from the moment a user opens a dashboard: + +1. **Client** — your app instantiates a `RevealView`, calls `RVDashboard.loadDashboard("Sales")`. +2. **Network** — the client sends an HTTP request to the server SDK. +3. **Server** — `IRVUserContextProvider.GetUserContext` runs to identify the user. +4. **Server** — `IRVDashboardProvider.GetDashboardAsync` runs to retrieve the `.rdash` file (from disk, database, wherever you've configured). +5. **Server** — the dashboard is sent back to the client. +6. **Client** — `RevealView` renders the dashboard. + +When a visualization needs data: + +7. **Client** — sends a query request to the server. +8. **Server** — `IRVDataSourceProvider.ChangeDataSourceAsync` runs to mutate connection details (e.g., swap in the tenant-specific database). +9. **Server** — `IRVAuthenticationProvider.ResolveCredentialsAsync` runs to attach credentials. +10. **Server** — query executes against the data source; results return to the client. + +Most of the SDK's customization surface boils down to overriding behavior in one of these provider methods. + +## Dashboard editing + +Dashboards can be **viewed**, **edited**, and **created** by end-users — not just embedded as static reports. The `RevealView` includes a built-in editor that supports adding visualizations, configuring filters, and reorganizing layout. Whether your end-users see the editor (and what they can do in it) is controlled by properties on the `RevealView`. See [Common Patterns](scenarios/index.md) for typical configurations. + +## Where to go next + +- Install: [Installation](install-server-sdk.md) +- See it work: [Embed a Dashboard](embedding/dashboard.md) +- Show one chart inline: [Embed a Single Visualization](embedding/single-visualization.md) +- Wire it to your data: [Connect Data](datasources.md) diff --git a/docs/web/embedding/dashboard.md b/docs/web/embedding/dashboard.md new file mode 100644 index 00000000..f9593af2 --- /dev/null +++ b/docs/web/embedding/dashboard.md @@ -0,0 +1,77 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Embed a Dashboard + +The most common Reveal embed: drop a full dashboard into your app, with all of its visualizations, filters, and interactions. Three lines of client-side code plus a `.rdash` file on your server. + +## Before you start + +- The Reveal **Server SDK** must be installed and running. See [Install Server SDK](../install-server-sdk.md). +- The Reveal **Client SDK** must be installed in your web app. See [Install Client SDK](../install-client-sdk.md). +- A `.rdash` file must be available to the server. By default, the server looks for it in a folder named `Dashboards` in the working directory. + +If any of those is unfamiliar, read [Concepts](../concepts.md) first — it explains the client/server split and where dashboards live. + +## Minimum code + +In your HTML, add a `
` to host the `RevealView`: + +```html +
+``` + +In JavaScript, point the SDK at your server, load the dashboard by name, and assign it to a new `RevealView`: + +```js +RevealSdkSettings.setBaseUrl("https://localhost:5111/"); + +RVDashboard.loadDashboard("Sales").then(dashboard => { + const revealView = new RevealView("#revealView"); + revealView.dashboard = dashboard; +}); +``` + +That's the entire embed. The dashboard renders with full editing, filtering, and export enabled by default. + +`RevealSdkSettings.setBaseUrl` only needs to be called once per page. Skip it if your client and server are served from the same origin. + +## Variations + +### Start with a new, empty dashboard + +When you want users to author from scratch instead of opening an existing file, instantiate `RVDashboard` directly: + +```js +const revealView = new RevealView("#revealView"); +revealView.dashboard = new RVDashboard(); +``` + +The user gets an empty canvas with the **+ Visualization** button ready. For a kiosk-style flow that opens directly into the new-visualization picker, see [Editor on Load (Kiosk)](../scenarios/editor-on-load-kiosk.md). + +### Load from a JSON-serialized dashboard + +If your server stores dashboards as JSON (`.json`) instead of binary (`.rdash`), use `Dashboard.FromJsonString` (or the equivalent in your server stack) inside your `IRVDashboardProvider`. The client-side code is the same — `loadDashboard("Sales")` either way. + +:::caution + +Manipulating dashboard JSON directly can break the file's integrity. Treat the JSON as opaque unless you have a specific reason to inspect or modify it. + +::: + +### Load from an embedded resource + +Your server's `IRVDashboardProvider` can return a `.rdash` stream from anywhere — a file path, an embedded resource in your assembly, blob storage, a database. The client-side `loadDashboard` call doesn't change. + +For the full set of provider patterns (custom file paths, embedded resources, JSON, custom storage), see [Loading Dashboards](../loading-dashboards.md). *(Will move to a dedicated **Dashboard Provider** topic under Connect Data in an upcoming docs change.)* + +## What's next + +Most embeds need more than the default behavior. Pick the scenario closest to your goal: + +- [Read-only Embed](../scenarios/view-only-embed.md) — disable editing for view-only users. +- [Custom Save Destination](../scenarios/custom-save-workflow.md) — route saves to your own REST endpoint instead of the server SDK's default. +- [Locked-down Export Menu](../scenarios/locked-down-export.md) — hide specific export formats for compliance. +- [Editor on Load (Kiosk)](../scenarios/editor-on-load-kiosk.md) — start in edit mode with the new-visualization picker open. + +Need to show just one chart instead of a full dashboard? See [Embed a Single Visualization](single-visualization.md). diff --git a/docs/web/embedding/single-visualization.md b/docs/web/embedding/single-visualization.md new file mode 100644 index 00000000..ed8be24b --- /dev/null +++ b/docs/web/embedding/single-visualization.md @@ -0,0 +1,104 @@ +# Embed a Single Visualization + +Show a single chart inline in your app — a KPI on a homepage, a sales chart in a product page, a metric in a sidebar. The Reveal SDK supports this directly: load a dashboard, pick the visualization you want, and the rest of the dashboard stays out of the way. + +## Before you start + +The setup is identical to embedding a full dashboard — server SDK installed, client SDK installed, a `.rdash` file on the server. See [Embed a Dashboard](dashboard.md) for the basics. The only difference is the two extra lines that pick a single visualization. + +## Two ways to do it + +| | Single Visualization Mode | Maximized Visualization | +|---|---|---| +| **What it does** | Locks the view to one chart. The dashboard menu and other visualizations are inaccessible. | Opens the dashboard zoomed in on one chart, but the user can navigate back to the full dashboard. | +| **Use when** | You want a permanent single-chart embed (KPI tile, inline metric, kiosk). | You want a focused initial view but full dashboard navigation. | +| **Property** | `revealView.singleVisualizationMode = true` | (no extra property — just set `maximizedVisualization`) | + +Both patterns use the same `maximizedVisualization` property to specify *which* visualization. Single Visualization Mode just adds the lock. + +## Single Visualization Mode (locked) + +Most common pattern for embedding a chart inline: + +```html +
+``` + +```js +RVDashboard.loadDashboard("AllDivisions").then(dashboard => { + const revealView = new RevealView("#revealView"); + revealView.singleVisualizationMode = true; + revealView.dashboard = dashboard; + revealView.maximizedVisualization = dashboard.visualizations.getByTitle("Sales"); +}); +``` + +The user sees only the "Sales" visualization. Filters, the dashboard header, and other visualizations are hidden. + +![](../images/maximize-three_divisions_dashboard_maximized.png) + +## Maximized Visualization (with navigation) + +Same code, minus the `singleVisualizationMode` line: + +```js +RVDashboard.loadDashboard("AllDivisions").then(dashboard => { + const revealView = new RevealView("#revealView"); + revealView.dashboard = dashboard; + revealView.maximizedVisualization = dashboard.visualizations.getByTitle("Sales"); +}); +``` + +The dashboard opens on the "Sales" visualization, but a back button lets the user expand to the full dashboard. + +## Variations + +### Switch which visualization is shown, dynamically + +In a single-page app where the user picks which chart to view (e.g., a button bar of departments), update `maximizedVisualization` on the existing `RevealView`: + +```html +
+
+ + + +
+
+
+``` + +```js +let revealView; + +RVDashboard.loadDashboard("AllDivisions").then(dashboard => { + revealView = new RevealView("#revealView"); + revealView.singleVisualizationMode = true; + revealView.dashboard = dashboard; + revealView.maximizedVisualization = dashboard.visualizations.getByTitle("Sales"); +}); + +function showVisualization(title) { + revealView.maximizedVisualization = revealView.dashboard.visualizations.getByTitle(title); +} +``` + +No reload, no flicker — the view swaps in place. + +### Pick the visualization by index instead of title + +If the visualization titles aren't stable, use the index: + +```js +revealView.maximizedVisualization = dashboard.visualizations[0]; +``` + +### Customize the chart's appearance + +The same property toggles that work on a full dashboard work here — for example, hiding the menu (`showMenu = false`) or specific export formats. See [Common Patterns](../scenarios/index.md). + +## What's next + +- [Embed a Dashboard](dashboard.md) — the full-dashboard alternative. +- [Common Patterns](../scenarios/index.md) — customizations that apply to either embed mode (read-only, locked-down export, etc.). +- [`RevealView` API reference](https://help.revealbi.io/api/javascript/latest/classes/RevealView.html) — full property and event surface. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index 8858d8ce..8935c9fa 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -66,15 +66,6 @@ const config: Config = { // plus per-event examples in /web/editor-events. Old URL points at the // Common Patterns overview as the most natural landing. { from: '/web/editing-dashboards', to: '/web/scenarios' }, - // /web/customizing/* renamed to /web/scenarios/* in the scenario-led - // sidebar reshuffle. Original "Customizing" framing was too narrow once - // the section grew to cover non-customization patterns (read-only embed, - // multi-dashboard navigation, drill-through, etc.). - { from: '/web/customizing', to: '/web/scenarios' }, - { from: '/web/customizing/view-only-embed', to: '/web/scenarios/view-only-embed' }, - { from: '/web/customizing/custom-save-workflow', to: '/web/scenarios/custom-save-workflow' }, - { from: '/web/customizing/locked-down-export', to: '/web/scenarios/locked-down-export' }, - { from: '/web/customizing/editor-on-load-kiosk', to: '/web/scenarios/editor-on-load-kiosk' }, ], }], ], diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/concepts.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/concepts.md new file mode 100644 index 00000000..71f33779 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/web/concepts.md @@ -0,0 +1,64 @@ +# Concepts + +A short mental model for how the Reveal SDK fits together. Read this once; the rest of the docs assume this vocabulary. + +## Two pieces: client and server + +The Reveal SDK is split between a **client SDK** that runs in the browser and a **server SDK** that runs in your backend. + +| Piece | Runs in | Job | +|---|---|---| +| Client SDK | The browser, inside your web app | Renders the `RevealView` component, handles user interactions, sends data and dashboard requests to the server | +| Server SDK | Your backend (ASP.NET, Node.js, NestJS, Spring Boot) | Stores and serves dashboards, answers data queries, holds connection credentials | + +The client never talks to your data sources directly. It always goes through the server SDK, which is where credentials and connection strings live. This is what makes embedded analytics secure — sensitive details never reach the browser. + +## Dashboards as files + +A Reveal dashboard is a **`.rdash` file**. It's a binary container that holds the dashboard's layout, visualizations, filters, and references to data sources. Dashboards are typically saved on the server and loaded into the `RevealView` on demand. + +By convention, the server SDK looks for `.rdash` files in a folder named `Dashboards` in the working directory. You can override that convention by implementing a custom dashboard provider (see below). + +## The provider pattern + +The server SDK is configured by implementing a small set of **provider interfaces**. Each provider gives you a hook into one part of the SDK's behavior: + +| Provider | What it controls | +|---|---| +| **`IRVDashboardProvider`** | Where dashboards are loaded from and saved to (file system, database, blob storage, etc.) | +| **`IRVDataSourceProvider`** | The connection details for each data source (host, database, table, schema) — mutated per request based on user context | +| **`IRVAuthenticationProvider`** | The credentials used when connecting to a data source (username/password, token, key pair) | +| **`IRVUserContextProvider`** | The current user's identity and metadata, available to the other providers | + +Most embedded scenarios involve customizing one or more of these. For example: serving different dashboards to different tenants combines a custom `IRVDashboardProvider` (to scope dashboards by tenant) with a custom `IRVUserContextProvider` (to identify the tenant from the request). End-to-end multi-provider patterns will live under the upcoming **Solutions & Advanced Guides** section. + +## How a request flows + +A typical request from the moment a user opens a dashboard: + +1. **Client** — your app instantiates a `RevealView`, calls `RVDashboard.loadDashboard("Sales")`. +2. **Network** — the client sends an HTTP request to the server SDK. +3. **Server** — `IRVUserContextProvider.GetUserContext` runs to identify the user. +4. **Server** — `IRVDashboardProvider.GetDashboardAsync` runs to retrieve the `.rdash` file (from disk, database, wherever you've configured). +5. **Server** — the dashboard is sent back to the client. +6. **Client** — `RevealView` renders the dashboard. + +When a visualization needs data: + +7. **Client** — sends a query request to the server. +8. **Server** — `IRVDataSourceProvider.ChangeDataSourceAsync` runs to mutate connection details (e.g., swap in the tenant-specific database). +9. **Server** — `IRVAuthenticationProvider.ResolveCredentialsAsync` runs to attach credentials. +10. **Server** — query executes against the data source; results return to the client. + +Most of the SDK's customization surface boils down to overriding behavior in one of these provider methods. + +## Dashboard editing + +Dashboards can be **viewed**, **edited**, and **created** by end-users — not just embedded as static reports. The `RevealView` includes a built-in editor that supports adding visualizations, configuring filters, and reorganizing layout. Whether your end-users see the editor (and what they can do in it) is controlled by properties on the `RevealView`. See [Common Patterns](scenarios/index.md) for typical configurations. + +## Where to go next + +- Install: [Installation](install-server-sdk.md) +- See it work: [Embed a Dashboard](embedding/dashboard.md) +- Show one chart inline: [Embed a Single Visualization](embedding/single-visualization.md) +- Wire it to your data: [Connect Data](datasources.md) diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/embedding/dashboard.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/embedding/dashboard.md new file mode 100644 index 00000000..f9593af2 --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/web/embedding/dashboard.md @@ -0,0 +1,77 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Embed a Dashboard + +The most common Reveal embed: drop a full dashboard into your app, with all of its visualizations, filters, and interactions. Three lines of client-side code plus a `.rdash` file on your server. + +## Before you start + +- The Reveal **Server SDK** must be installed and running. See [Install Server SDK](../install-server-sdk.md). +- The Reveal **Client SDK** must be installed in your web app. See [Install Client SDK](../install-client-sdk.md). +- A `.rdash` file must be available to the server. By default, the server looks for it in a folder named `Dashboards` in the working directory. + +If any of those is unfamiliar, read [Concepts](../concepts.md) first — it explains the client/server split and where dashboards live. + +## Minimum code + +In your HTML, add a `
` to host the `RevealView`: + +```html +
+``` + +In JavaScript, point the SDK at your server, load the dashboard by name, and assign it to a new `RevealView`: + +```js +RevealSdkSettings.setBaseUrl("https://localhost:5111/"); + +RVDashboard.loadDashboard("Sales").then(dashboard => { + const revealView = new RevealView("#revealView"); + revealView.dashboard = dashboard; +}); +``` + +That's the entire embed. The dashboard renders with full editing, filtering, and export enabled by default. + +`RevealSdkSettings.setBaseUrl` only needs to be called once per page. Skip it if your client and server are served from the same origin. + +## Variations + +### Start with a new, empty dashboard + +When you want users to author from scratch instead of opening an existing file, instantiate `RVDashboard` directly: + +```js +const revealView = new RevealView("#revealView"); +revealView.dashboard = new RVDashboard(); +``` + +The user gets an empty canvas with the **+ Visualization** button ready. For a kiosk-style flow that opens directly into the new-visualization picker, see [Editor on Load (Kiosk)](../scenarios/editor-on-load-kiosk.md). + +### Load from a JSON-serialized dashboard + +If your server stores dashboards as JSON (`.json`) instead of binary (`.rdash`), use `Dashboard.FromJsonString` (or the equivalent in your server stack) inside your `IRVDashboardProvider`. The client-side code is the same — `loadDashboard("Sales")` either way. + +:::caution + +Manipulating dashboard JSON directly can break the file's integrity. Treat the JSON as opaque unless you have a specific reason to inspect or modify it. + +::: + +### Load from an embedded resource + +Your server's `IRVDashboardProvider` can return a `.rdash` stream from anywhere — a file path, an embedded resource in your assembly, blob storage, a database. The client-side `loadDashboard` call doesn't change. + +For the full set of provider patterns (custom file paths, embedded resources, JSON, custom storage), see [Loading Dashboards](../loading-dashboards.md). *(Will move to a dedicated **Dashboard Provider** topic under Connect Data in an upcoming docs change.)* + +## What's next + +Most embeds need more than the default behavior. Pick the scenario closest to your goal: + +- [Read-only Embed](../scenarios/view-only-embed.md) — disable editing for view-only users. +- [Custom Save Destination](../scenarios/custom-save-workflow.md) — route saves to your own REST endpoint instead of the server SDK's default. +- [Locked-down Export Menu](../scenarios/locked-down-export.md) — hide specific export formats for compliance. +- [Editor on Load (Kiosk)](../scenarios/editor-on-load-kiosk.md) — start in edit mode with the new-visualization picker open. + +Need to show just one chart instead of a full dashboard? See [Embed a Single Visualization](single-visualization.md). diff --git a/i18n/ja/docusaurus-plugin-content-docs/current/web/embedding/single-visualization.md b/i18n/ja/docusaurus-plugin-content-docs/current/web/embedding/single-visualization.md new file mode 100644 index 00000000..ed8be24b --- /dev/null +++ b/i18n/ja/docusaurus-plugin-content-docs/current/web/embedding/single-visualization.md @@ -0,0 +1,104 @@ +# Embed a Single Visualization + +Show a single chart inline in your app — a KPI on a homepage, a sales chart in a product page, a metric in a sidebar. The Reveal SDK supports this directly: load a dashboard, pick the visualization you want, and the rest of the dashboard stays out of the way. + +## Before you start + +The setup is identical to embedding a full dashboard — server SDK installed, client SDK installed, a `.rdash` file on the server. See [Embed a Dashboard](dashboard.md) for the basics. The only difference is the two extra lines that pick a single visualization. + +## Two ways to do it + +| | Single Visualization Mode | Maximized Visualization | +|---|---|---| +| **What it does** | Locks the view to one chart. The dashboard menu and other visualizations are inaccessible. | Opens the dashboard zoomed in on one chart, but the user can navigate back to the full dashboard. | +| **Use when** | You want a permanent single-chart embed (KPI tile, inline metric, kiosk). | You want a focused initial view but full dashboard navigation. | +| **Property** | `revealView.singleVisualizationMode = true` | (no extra property — just set `maximizedVisualization`) | + +Both patterns use the same `maximizedVisualization` property to specify *which* visualization. Single Visualization Mode just adds the lock. + +## Single Visualization Mode (locked) + +Most common pattern for embedding a chart inline: + +```html +
+``` + +```js +RVDashboard.loadDashboard("AllDivisions").then(dashboard => { + const revealView = new RevealView("#revealView"); + revealView.singleVisualizationMode = true; + revealView.dashboard = dashboard; + revealView.maximizedVisualization = dashboard.visualizations.getByTitle("Sales"); +}); +``` + +The user sees only the "Sales" visualization. Filters, the dashboard header, and other visualizations are hidden. + +![](../images/maximize-three_divisions_dashboard_maximized.png) + +## Maximized Visualization (with navigation) + +Same code, minus the `singleVisualizationMode` line: + +```js +RVDashboard.loadDashboard("AllDivisions").then(dashboard => { + const revealView = new RevealView("#revealView"); + revealView.dashboard = dashboard; + revealView.maximizedVisualization = dashboard.visualizations.getByTitle("Sales"); +}); +``` + +The dashboard opens on the "Sales" visualization, but a back button lets the user expand to the full dashboard. + +## Variations + +### Switch which visualization is shown, dynamically + +In a single-page app where the user picks which chart to view (e.g., a button bar of departments), update `maximizedVisualization` on the existing `RevealView`: + +```html +
+
+ + + +
+
+
+``` + +```js +let revealView; + +RVDashboard.loadDashboard("AllDivisions").then(dashboard => { + revealView = new RevealView("#revealView"); + revealView.singleVisualizationMode = true; + revealView.dashboard = dashboard; + revealView.maximizedVisualization = dashboard.visualizations.getByTitle("Sales"); +}); + +function showVisualization(title) { + revealView.maximizedVisualization = revealView.dashboard.visualizations.getByTitle(title); +} +``` + +No reload, no flicker — the view swaps in place. + +### Pick the visualization by index instead of title + +If the visualization titles aren't stable, use the index: + +```js +revealView.maximizedVisualization = dashboard.visualizations[0]; +``` + +### Customize the chart's appearance + +The same property toggles that work on a full dashboard work here — for example, hiding the menu (`showMenu = false`) or specific export formats. See [Common Patterns](../scenarios/index.md). + +## What's next + +- [Embed a Dashboard](dashboard.md) — the full-dashboard alternative. +- [Common Patterns](../scenarios/index.md) — customizations that apply to either embed mode (read-only, locked-down export, etc.). +- [`RevealView` API reference](https://help.revealbi.io/api/javascript/latest/classes/RevealView.html) — full property and event surface. diff --git a/sidebars.ts b/sidebars.ts index 2988708e..e0545aa6 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -7,6 +7,7 @@ const sidebars: SidebarsConfig = { { type: "category", label: "Get Started", collapsed: false, collapsible: false, className: "sidebar__header", items: [ { type: "doc", label: "Overview", key: "web-overview", id: "web/overview" }, + { type: "doc", label: "Concepts", id: "web/concepts" }, { type: "category", label: "Installation", key: "installation", items: [ { type: "doc", label: "System Requirements", id: "web/system-requirements" }, @@ -36,12 +37,15 @@ const sidebars: SidebarsConfig = { }, /* -------------------- Embedding -------------------- - * Future home of unified "Embed a Dashboard" + "Embed a Single Visualization" - * topics. Loading/Creating/Saving live here as transitional placeholders - * and will be merged into those topics in upcoming sub-PRs. + * Embed a Dashboard and Embed a Single Visualization are the canonical + * topics. Loading/Creating/Saving remain as transitional pages for now — + * they cover server-side IRVDashboardProvider patterns that will move + * to a dedicated Dashboard Provider topic under Connect Data. */ { type: "category", label: "Embedding", collapsed: false, collapsible: false, className: "sidebar__header", items: [ + { type: "doc", label: "Embed a Dashboard", id: "web/embedding/dashboard" }, + { type: "doc", label: "Embed a Single Visualization", id: "web/embedding/single-visualization" }, { type: "doc", label: "Loading", id: "web/loading-dashboards" }, { type: "doc", label: "Creating", id: "web/creating-dashboards" }, { type: "doc", label: "Saving", id: "web/saving-dashboards" },