diff --git a/modules/ROOT/pages/api-changelog.adoc b/modules/ROOT/pages/api-changelog.adoc index 056d814bf..84dbbcae0 100644 --- a/modules/ROOT/pages/api-changelog.adoc +++ b/modules/ROOT/pages/api-changelog.adoc @@ -8,6 +8,34 @@ This changelog lists only the changes introduced in the Visual Embed SDK. For information about new features and enhancements available for embedded analytics, see xref:whats-new.adoc[What's New]. +== Version 1.44.x, January 2026 + +[width="100%" cols="1,4"] +|==== + +|[tag redBackground]#DEPRECATED# |**`defaultHeight` replaced with `minimumHeight` ** + + +The `defaultHeight` parameter is deprecated in Visual Embed SDK v1.44.2 and later. +To set the minimum height of the embed container for ThoughtSpot components such as a Liveboard, use the `minimumHeight` attribute instead. + +|[tag greenBackground]#NEW FEATURE# a| *Intercepting API calls* + +The SDK provides the following attributes to intercept API calls and handle interception via events and custom workflows: + +//* `enableApiIntercept` + +//When set to true, enables the feature on your ThoughtSpot embed. +* `interceptUrls` + +Allows configuring which API calls to intercept. +* `interceptTimeout` + +Sets the timeout duration for handling interception. +* `isOnBeforeGetVizDataInterceptEnabled` + +When set to true, it enables the use of `EmbedEvent.OnBeforeGetVizDataIntercept` event to emit and intercept search execution calls initiated by the users and implement custom logic or workflow to allow or restrict search execution. +* `EmbedEvent.ApiIntercept` + +Emits when an API call matching the conditions defined in `interceptUrls` is detected. + +For more information, see xref:api-intercept.adoc[Intercept API calls and search requests]. +|==== + + == Version 1.43.0, November 2025 [width="100%" cols="1,4"] |==== diff --git a/modules/ROOT/pages/common/nav.adoc b/modules/ROOT/pages/common/nav.adoc index 724a9c015..bf410e150 100644 --- a/modules/ROOT/pages/common/nav.adoc +++ b/modules/ROOT/pages/common/nav.adoc @@ -255,4 +255,3 @@ include::generated/typedoc/CustomSideNav.adoc[] ** link:https://training.thoughtspot.com/page/developer[Training resources, window=_blank] ** link:https://docs.thoughtspot.com[Product Documentation, window=_blank] ** link:{{navprefix}}/rest-apiv2-beta-reference[REST API v2 ^Beta^ Reference (Deprecated)] - diff --git a/modules/ROOT/pages/full-app-customize.adoc b/modules/ROOT/pages/full-app-customize.adoc index 8474cd352..9b21acf4b 100644 --- a/modules/ROOT/pages/full-app-customize.adoc +++ b/modules/ROOT/pages/full-app-customize.adoc @@ -6,20 +6,73 @@ :page-pageid: full-app-customize :page-description: Customize full application embedding -== UI and navigation experience -In full application embedding, the ThoughtSpot UI and navigation are available in the following modes: +The Visual Embed SDK provides several controls to customize the embedded view, including setting the default landing page, navigation style, visibility of modules and menu items, and more. -* Classic experience (default) -* xref:full-app-customize.adoc#_new_modular_home_page_with_a_sliding_navigation_panel[New modular home page with sliding navigation panel] [earlyAccess eaBackground]#Early Access# -* xref:full-app-customize.adoc#_new_navigation_and_home_page_experience_without_the_sliding_panel[New modular home page and navigation without the sliding panel] [earlyAccess eaBackground]#Early Access# +== UI experience modes -=== New modular home page with a sliding navigation panel +The ThoughtSpot application interface supports the following UI experience modes: -The new navigation and modular home page experience provides an intuitive and efficient navigation structure. It organizes the application menu into persona-based modules designed specifically to address users' needs. Each module has a menu selector with a visual icon, to allow users to switch between contexts easily. Users can slide out the left navigation panel by clicking the hamburger icon in the header. +* xref:full-app-customize.adoc#_v3_experience[V3 experience] [earlyAccess eaBackground]#Early Access# + +Includes a sliding left navigation panel that dynamically adjusts its menu based on the application context. In this experience mode, the home page includes the same customizable modules as the V2 experience. +* xref:full-app-customize.adoc#_v2_experience[V2 experience] + +Includes a modular home page with customizable components, an application selector menu, and a left navigation panel for each application context. +* V1 Classic experience (__Default experience__) + +Includes a standard top navigation and a static home page with limited customization options. -If your application instance has classic experience, you'll notice the following changes when the new experience is enabled: +=== V3 experience +The V3 experience introduces the following changes: + +* Navigation and UI layout: +** A redesigned top navigation bar with a modern and simplified layout. +** Persona-based navigation with app selector icons. The app selection icons are organized into contextual sections, each with its own left navigation. +** Admin settings in the user profile dropdown. +** A hamburger menu for toggling left navigation. ++ +To customize the navigation experience, use the xref:full-app-customize.adoc#_customize_navigation_experience[navigation attributes] in the SDK. + +* Home page: + +The V3 experience includes a modular home page, similar to the V2 experience. You can xref:full-app-customize.adoc#_customize_home_page_experience[customize the visibility and order of the home page components] using the properties available in the SDK. + +The following figure shows the UI layout in the V3 experience: + +[.bordered] +[.widthAuto] +image::./images/new-nav3.png[New home page] + +==== Enable V3 experience +The V3 experience is an Early Access feature that ThoughtSpot administrators can enable at the instance level. It is disabled by default + +When it is enabled on your ThoughtSpot instance, you can upgrade the UI experience in your embed using the `discoveryExperience` object in the SDK. This object supports the following properties: + +* `primaryNavbarVersion` + +Enables the V3 experience. The valid setting for the V3 experience is `PrimaryNavbarVersion.Sliding`. +* `homePage` + +Enables a modular home page that is similar to the V2 modular home page experience. The supported value is `HomePage.Modular`. + +[source,JavaScript] +---- + +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + PrimaryNavbarVersion // Enum for V3 navigation experience + HomePage, // Enum for home page experience settings +} from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + // Enable V3 navigation and home page experience + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enables V3 sliding navigation + homePage: HomePage.Modular, // modular home page + }, + // Show navigation panels + showPrimaryNavbar: true, + //... other view configuration attributes +}); +---- + +//// * A redesigned UI with a sliding navigation panel. * The app selector icons for *Insights*, *Data workspace*, and *Develop* appear in the header section of the left navigation panel. This selector provides access to persona-based apps, replacing the old top navigation menu. The left navigation panel provides quick access to different modules and can be customized. * The *Admin* module is available under the user settings section in the top right corner. @@ -32,248 +85,133 @@ If your application instance has classic experience, you'll notice the following ** Help icon to access documentation ** Org switcher to switch between Org contexts ** Access to *Profile*, *Admin settings* (if the user has administrator privilege), and *Sign out* options. +//// -The following figure shows the new navigation panel and modular Home page: - -[.bordered] -[.widthAuto] -image::./images/new-nav3.png[New home page] - -==== Modular Home page -The customizable home page in ThoughtSpot’s new experience is available in the *Insights* section. It allows users to personalize the layout and content modules. Users can reorder sections, such as watchlist, favorites, library, trending charts, and more. For full app embedding application users, developers can set a default layout to include only the modules they want. - -==== Configure new experience -The navigation and home page experience is turned off by default. Administrators can enable it on their instance at the cluster level for all users. When this feature is enabled on the instance, users can switch between classic and new experience by turning off or enabling the experience in their profile settings. On embedded applications, you'll need to enable this experience using the `discoveryExperience` property as shown in this example: - -[source,JavaScript] ----- -const embed = new AppEmbed('#tsEmbed', { - // Enable the new modular home page and navigation experience - modularHomeExperience: true, - // Set the top navigation bar in the embedded view - showPrimaryNavbar: true, - discoveryExperience: { - // Set the navigation bar to use the new sliding (icon-based) style - primaryNavbarVersion: PrimaryNavbarVersion.Sliding, - // Set the home page to use the modular layout - homePage: 'Modular', - }, - //other options -}); ----- +=== V2 experience -=== New navigation and Home page experience without the sliding panel +The V2 experience provides the following features: -In the new navigation and Home page experience, the app selector image:./images/app_switcher.png[the app switcher menu] appears on the top header bar. The app selector consists of different persona-based contextual elements to allow users to switch between contexts. Clicking an app in the app selector menu opens the corresponding application page. Each application module has a separate left navigation panel. +* Navigation experience: + +** The top navigation includes an app selector menu, which consists of different persona-based menu elements to allow users to switch between different application contexts. +** Each application context has its own left navigation menu. ++ +You can customize the navigation experience using the xref:full-app-customize.adoc#_customize_navigation_controls[navigation controls] available in the SDK. +* Home page experience: + +The home page includes customizable modules such as watchlist, favorites, library, trending charts, and more. You can xref:full-app-customize.adoc#_customize_home_page_experience[customize the visibility and order of the home page components] using the properties available in the SDK. -If your application instance has classic experience, you'll notice the following changes in the UI: +//// +The following figure shows the UI layout in the V2 experience: [.bordered] [.widthAuto] image::./images/homepage.png[New home page] +//// -The new navigation and Home page experience introduces several UI changes. - -.View UI changes -[%collapsible] -==== -[width="100%", cols="3,7,7"] -[options='header'] -|===== -||Classic experience |New navigation and Home page experience -|Navigation a|Top navigation menu with the following buttons: - -* **Home** + -Opens Home page + -* **Answers** + -Opens Answers page + -* **Liveboards** + -Opens Liveboards page + -* **SpotIQ** + -Opens SpotIQ analyses page + -* **Monitor** + -Opens subscription alerts page + -* **Data** + -Opens the Data workspace page (Requires data management privilege) + -* **Admin** + -Opens Admin page (Requires administration privilege) + -* **Develop** + -Opens **Develop** page (Requires developer privilege) + -* **Search data** + -Opens Search data page - -a| App selector image:./images/app_switcher.png[the app switcher menu] with the following apps: - -* **Insights** + -Opens the Insights page. Note that the Answers, Liveboards, SpootIQ, and Monitor Subscriptions are grouped as Insights in the new Home page experience. + -** **Insights** > **Home** + -Opens Home page -** **Insights** > **Search Data** + -Opens the Search Data page. -** **Insights** > **Answers** + -Opens the Answers page. -** **Insights** > **Liveboards** + -Opens the Liveboards page. -** **Insights** > **SpotIQ Analysis** + -Opens the SpotIQ page. -** **Insights** > **Monitor Subscriptions** + -Opens Monitor alerts page. + -The **Insights** page also includes **Help** and **Chat with Support** menu options. -* **Data workspace** + -Opens the Data workspace page (Requires data management privilege) -* **Admin** + -Opens Admin page (Requires administration privilege) -* **Developer** + -Opens **Develop** page (Requires developer privilege) -* **Search Data** + -Opens Search data page -* **View all Liveboards** + -Opens Liveboards page -* **View all Answers** + -Opens Answers page -|Home page experience |In the classic experience mode, the **Home** page shows the Natural Language Search panel, a list of Answers and Liveboards, and trending charts. | The **Insights** page in new experience mode shows a customizable home page with features such as Natural Language Search panel, watchlist, favorites, a library of Answers and Liveboards, trending charts, and more. With the new left-hand navigation, users can navigate to your Liveboards, Answers, SpotIQ analysis, and Monitor subscriptions. -|Application page URLs a| -* **Liveboards** + -`\https://{ThoughtSpot-Host}/#/pinboards` -* **Answers** + -`\https://{ThoughtSpot-Host}/#/answers` -* **SpotIQ** + -`\https://{ThoughtSpot-Host}/#/insights` -* **Monitor** + -`\https://{ThoughtSpot-Host}/#/monitor` -a| -* **Liveboards** + -`\https://{ThoughtSpot-Host}/#/home/liveboards` -* **Answers** + -`\https://{ThoughtSpot-Host}/#/home/answers` -* **SpotIQ** + -`\https://{ThoughtSpot-Host}/#/home/spotiq-analysis` -* **Monitor** + -`\https://{ThoughtSpot-Host}/#/home/monitor-alerts` -|Liveboards and Answers| In the classic experience mode, users can use All, Yours, and Favorites tabs to filter the Liveboards and Answers list| In new experience, the Liveboard and Answers list page provides filters for each column. For example, to view their favorite Liveboards, users can click the star icon in the column head and apply a filter to show only their starred (favorite) Liveboards. Similarly, users can filter the list by author to view only their Liveboards or Answers. -|===== -[%collapsible] -==== - -==== Enable new experience mode without the sliding panel -By default, the new navigation and home page experience is turned off on ThoughtSpot embedding applications. To enable the new experience mode for embedding application users, set `modularHomeExperience` to `true` in the `AppEmbed` component. +==== Using the V2 experience +The V2 experience is disabled by default on ThoughtSpot embedding applications. +Setting `modularHomeExperience` to `true` in the SDK enables the V2 experience. [source,javascript] ---- const embed = new AppEmbed("#embed", { - pageId: Page.Home, + // Enable the V2 experience modularHomeExperience: true, - frameParams: { - height: '100%', - width: '100%' - } + //... other view config attributes }); ---- -== Choose the default page to load -When embedding the full app, you can use either `pageId` or `path` parameter to specify the page to load when the embedded component loads. If both `path` and `pageId` properties are defined, the `path` definition takes precedence. +[NOTE] +==== +The V2 experience will be deprecated in an upcoming release. ThoughtSpot strongly recommends upgrading to the V3 experience to ensure continued support and access to the latest features. +==== -=== pageId -The `pageId` parameter of the `AppEmbed` xref:full-embed#_create_an_instance_of_the_appembed_object[parameters object] lets you specify the ThoughtSpot page in the `Page` enumeration that the AppEmbed component loads to. Valid values for this attribute are: -* `Page.Home` for the ThoughtSpot *Home* page + -* `Page.Search` for the ThoughtSpot *Search* page + -* `Page.Answers` for the *Answers* page + -* `Page.Liveboards` for the *Liveboards* page + -* `Page.Data` for the *Data* page + -* `Page.SpotIQ` for the *SpotIQ* analyses page +//// +==== Enable AI Search +To set AI Search as the default search experience on the Home page, use the settings shown in the following examples. + +==== Enable AI Search with Spotter (Recommended) +To set Spotter as the default search experience on the Home page, use the settings shown in the following examples. + +===== New Home page experience [source,javascript] ---- const embed = new AppEmbed("#embed", { - pageId: Page.Liveboards, - showPrimaryNavbar: false, - frameParams: { - height: '100%', - width: '100%' - } + isUnifiedSearchExperienceEnabled: "false", + homePageSearchBarMode: "aiAnswer", }); ---- -=== path -The URL path of the ThoughtSpot application page that you want your embed application users to navigate to. + +Home page search experience:: + + +Spotter page;; +[.bordered] +[.widthAuto] +image::./images/spotter-fullApp2.png[] + +===== Home page classic experience [source,javascript] ---- const embed = new AppEmbed("#embed", { - path: 'pinboard/96a1cf0b-a159-4cc8-8af4-1a297c492ff9', - frameParams: { - height: '100%', - width: '100%' - } + isUnifiedSearchExperienceEnabled: "false", + homePageSearchBarMode: "aiAnswer", }); ---- -The following examples show valid strings for `path`: -[width="100%", cols="3,6,6"] -[options='header'] -|===== -|Page| Classic experience | New navigation and Home page experience -|Home| `path: "home"` | `path: "home"` -|Answers| `path: "answers"`| `path: "home/answers"` -|Saved Answer| `path: "saved-answer/"` |`path: "saved-answer/"` -|Liveboards| `path: "pinboards"`| `path: "home/liveboards"` -|Liveboard| `path: "pinboard/"`| `path: "pinboard/"` -|SpotIQ analysis list|`path: "insights"`| `path: "home/spotiq-analysis"` -|SpotIQ analysis page| `path: "insight/"`| `path: "insight/"` -|Data| `path: "data/tables/"`| `path: "data/tables/"` -|Model, tables, views|`path: "data/tables/"`| `path: "data/tables/"` -|Monitor| `path: "monitor"` | `path: "monitor"` + -or + -`path: "home/monitor-alerts"` -|===== -=== navigateToPage() +Spotter page;; +[.bordered] +[.widthAuto] +image::./images/spotter-fullApp2.png[] -The `AppEmbed` object has a method called `navigateToPage()` that will switch the currently loaded page in the ThoughtSpot embedded application. The `navigateToPage()` method accepts the values that work for `pageId` or `path` parameters. +==== Enable AI Search (legacy) +To enable Natural Language Search (legacy), use the settings shown in these examples: -The new navigation menu should call `navigateToPage` for the various pages you want to provide access to: +===== New Home page experience -[source,JavaScript] +[source,javascript] ---- -embed.navigateToPage(Page.Answers); -// with noReload option -embed.navigateToPage(Page.Answers, true); +const embed = new AppEmbed("#embed", { + homePageSearchBarMode: "aiAnswer", +}); ---- +Home page search experience:: +[.widthAuto] +[.bordered] +image::./images/sage-search-new-exp.png[] -=== history.back() -Page changes within the `AppEmbed` component register as part of the embedding app's history to the web browser. - -The standard JavaScript `history.back()` function will cause the `AppEmbed` component to go to the previously loaded page up until the very first ThoughtSpot page loaded within the component. - -[#_search_experience_on_home_page] -== Customize Search experience in full app embed +AI Search page:: -// ** Create a xref:embed-nls.adoc[Natural Language Search page using SageEmbed] and build a navigation to this page from your embedding application. +[.widthAuto] +[.bordered] +image::./images/sage-search-home.png[] -The search components available for full application embed and the configuration settings required for these components are listed in the following table: +===== Home page classic experience -[width="100%", cols="4,8"] -[options='header'] -|===== -|Type| Description -|Object Search a| Allows finding popular Liveboards and Answers from the recommended suggestions. +[source,javascript] +---- +const embed = new AppEmbed("#embed", { + homePageSearchBarMode: "aiAnswer", +}); +---- -On instances running 10.1.0.cl or lower, the Home page provides a combined interface with Object Search and Natural Language Search. On instances running 10.3.0.cl or later, with split search experience enabled, the Object Search will be the default search experience on the Home page. +Home page search experience:: -The Object Search bar also appears on the top navigation bar if the top navigation bar visibility is enabled ( `showPrimaryNavbar: true`) in the SDK. +[.widthAuto] +[.bordered] +image::./images/sage_search-home-classic.png[] -|Spotter Search | In addition to AI Search capabilities, Spotter provides a conversation interface for queries and follow-up questions. + -If Spotter is enabled on your instance, and `homePageSearchBarMode: "aiAnswer"` property is set in the SDK along with split search enabled (`isUnifiedSearchExperienceEnabled: false`), the search experience on the Home page switches to Spotter in full application embed. +AI Search page:: -For more information, see xref:full-app-customize.adoc#_enable_ai_search_with_spotter[Enable AI Search with Spotter]. -| Search data a| Allows searching a data source using keywords and search tokens. This experience is available if you have set the `pageId` attribute to `Page.Search` or enabled navigation to the Search page of your ThoughtSpot application. -|Natural Language Search (legacy interface) a| Allows searching a data source using a natural language query string and get AI-generated Answers. -On instances running 10.3.0.cl or earlier, with split search experience disabled, the Search interface on the Home page provides a combined view of Natural Language Search (legacy interface) and Object Search. However, on instances running 10.3.0.cl or later, split search is enabled by default. Due to this, the Home page will not show Natural Language Search as the default search experience. +[.widthAuto] +[.bordered] +image::./images/sage-search-home.png[] -Note that the legacy Natural Language Search option is deprecated and replaced with Spotter Search. You can enable Natural Language Search with Spotter, by setting `homePageSearchBarMode` to `aiAnswer` in the SDK. -|===== +//// @@ -291,7 +229,7 @@ By default, the Object Search bar is displayed on the embedded **Home** page. [.bordered] image::./images/sageDisabledwithNav_classic.png[] //// - +//// === Home page search experience options Developers can customize the Search experience by setting the `homePageSearchBarMode` property in the SDK to a desired value: @@ -394,108 +332,203 @@ AI Search page:: [.widthAuto] [.bordered] image::./images/sage-search-home.png[] +//// + +== Customize navigation experience +The Visual Embed SDK provides several parameters to hide or customize navigation controls. -== Customize navigation controls -The `AppEmbed` package in the Visual Embed SDK provides several parameters to hide or customize navigation controls. +=== Customize top navigation +The top navigation menu bar (classic experience), app selector image:./images/app_switcher.png[the app switcher menu] (V2 experience), and left navigation panel on the home page (V3 experience) are hidden by default in the embedded view. To show these elements in the embedded view, set `showPrimaryNavbar` to `true`. -The top navigation menu bar (classic experience), app selector image:./images/app_switcher.png[the app switcher menu] (New experience), and left navigation panel on the home page (New experience) are hidden by default in the embedded view. To show these elements in the embedded view, set `showPrimaryNavbar` to `true`. If the navigation panel is visible in the embedded view, you can use the following parameters in the `AppEmbed` component for additional customization: +If the navigation panel is visible in the embedded view, you can use the following customization settings in the SDK: * `hideOrgSwitcher` + -Hides the Orgs drop-down. Applicable to only Orgs-enabled clusters. +To show or hide the Orgs drop-down. * `hideApplicationSwitcher` + -Hides the app selector image:./images/app_switcher.png[the app switcher menu]. The app selector is available only in the new navigation and Home page experience mode. +To show or hide the application switcher in V2 experience) and application selector icons in the V3 experience. In the V3 experience, it also hides the *Admin settings* menu in the user settings drop-down. * `disableProfileAndHelp` + -** To hide help and profile icons (Classic experience) + -** To hide help and profile icons, Help and Chat with Support menu options on the Home page (New Experience). +To show or hide the help and profile icons. + +In V2 experience, this parameter also controls the visibility of *Help* menu in the left navigation panel of the home page. + +In the V3 experience, the profile icon includes the *Admin settings* menu, which is also hidden when the profile icon is disabled via `disableProfileAndHelp`. +* `hideObjectSearch` + +To show or hide the Object search bar in the top navigation in V2 and V3 experience modes. +* `hideNotification` + +To show or hide the alert icon in the V3 experience. +* `hideHamburger` + +To show or hide the hamburger icon in the V3 experience. + +The following example hides the icons in top navigation and the application selection menu: -=== Help menu customization -On ThoughtSpot instances running 10.8.0.cl and later, a unified help and support experience is available. The new information center experience provides access to ThoughtSpot documentation and support and allows administrators to link:https://docs.thoughtspot.com/cloud/latest/customize-help[add custom links]. +[source,JavaScript] +---- +const embed = new AppEmbed("#embed", { + //... other attributes + showPrimaryNavbar: true, // Show navigation bar + hideApplicationSwitcher: true, // Hide application selector + disableProfileAndHelp: true, // Hide Help and Profile icons in top navigation + hideObjectSearch: true, // Hide the object search bar in top navigation +}); +---- -If you have embedded the full ThoughtSpot application with the top navigation bar and Help (?) icon with the `showPrimaryNavbar: true` and `disableProfileAndHelp: false` settings in the Visual Embed SDK and if you want to try the new information center experience, use the xref:AppViewConfig.adoc#_enablependohelp[enablePendoHelp] attribute in the SDK. +=== Customize the left navigation panel on home page -By default, the `enablePendoHelp` attribute is set to `true` for customer environments using the legacy information center generated by Pendo. To enable the new experience, you need to set `enablePendoHelp` to `false`. +In the V2 and V3 experience modes, the left navigation panel on the *Insights* > *Home* page includes menu items such as *Answers*, *Liveboards*, *SpotIQ Analysis*, *Monitor Subscriptions*, and more. You can hide this navigation panel by setting the `hideHomepageLeftNav` property to `true` in the SDK. Note that this attribute hides only the left navigation on the home page. + +If you want to include the left navigation, but hide only a specific section in the *Insights* panel, use the `hiddenHomeLeftNavItems` property and specify the menu items to hide: [source,JavaScript] ---- const embed = new AppEmbed("#embed", { - ... // other options - showPrimaryNavbar: true, - disableProfileAndHelp: false, - enablePendoHelp: false, + //... V2 or V3 experience attributes + //Show left navigation panel on the home page + hideHomepageLeftNav: false, + hiddenHomeLeftNavItems: [ + HomeLeftNavItem.MonitorSubscription, + HomeLeftNavItem.SpotIQAnalysis + ], // Hide SpotIQ analysis and Monitor subscriptions menu items }); ---- -=== Customize the left navigation panel on Home page (New experience) -If the new navigation and Home page experience is enabled and `showPrimaryNavbar` to `true`, the home page displays a navigation panel on the left side of the Insights page. The panel consists of menu items such as Answers, Liveboards, SpotIQ Analysis, Monitor Subscriptions, and so on. +== Customize home page experience +The modular home in V2 and V3 experience include modules such as watchlist, favorites, a library of Answers and Liveboards, trending charts and more. -To hide the left navigation panel in the embedded view, set `hideHomepageLeftNav` to `true`. +To show or hide specific modules on the home page, use the xref:AppViewConfig.adoc#_hiddenhomepagemodules[`hiddenHomepageModules`] parameter. +To reorder the home page components, use the xref:AppViewConfig.adoc#_reorderedhomepagemodules[ `reorderedHomepageModules`] array. + +The following example hides several home page components and specifies the order in which the remaining components appear on the home page: [source,javascript] ---- const embed = new AppEmbed("#embed", { - ... // other attributes - modularHomeExperience: true, - showPrimaryNavbar: true, - hideApplicationSwitcher: true, - hideHomepageLeftNav: true, - disableProfileAndHelp: true, + //... + // Hide modules from the home page + hiddenHomepageModules: [ + HomepageModule.Learning, + HomepageModule.Trending + ], + // Custom order for visible modules + reorderedHomepageModules: [ + HomepageModule.Search, + HomepageModule.Favorite, + HomepageModule.Watchlist, + HomepageModule.MyLibrary + ], + //...other view configuration properties }); ---- -If you don't want to hide the left navigation panel, but show only a select few menu items, use xref:AppViewConfig.adoc#_hiddenhomeleftnavitems [`hiddenHomeLeftNavItems`] array. +[#_search_experience_on_home_page] +=== Customize the search experience on home page +You can set the search experience on the home page to function as an object search bar that allows finding popular objects, or as an AI search interface that allows natural language queries or Spotter sessions. You can also choose to hide it from the home page. +To configure your preference, specify the following values in the `homePageSearchBarMode` attribute. + +[width="100%", cols="4,8"] +[options='header'] +|===== +|Search bar mode|Description +|`HomePageSearchBarMode.AI_ANSWER` | +Sets the natural language search bar that allows queries in natural language. +If Spotter is enabled on your instance, you can use this setting to set the Spotter search bar on the home page. +|`HomePageSearchBarMode.OBJECT_SEARCH` |Enables object search that allows users to find objects from the library. +|`HomePageSearchBarMode.NONE` a| Hides the search bar on the home page. Note that it only hides the Search bar on the **Home** page and doesn't affect the Object Search bar visibility on the top navigation bar. +|| +|===== + + +[NOTE] +==== +If your instance is using the V1 classic experience and the `homePageSearchBarMode` parameter does not set the search context defined in your code, set `isUnifiedSearchExperienceEnabled` to `false`. +==== + +The following examples show the code snippets to set the home page search bar mode to Spotter or AI search in different experience modes: + +V3 experience:: [source,javascript] ---- +import { + AppEmbed, + PrimaryNavbarVersion // Enum for V3 navigation experience + HomePage, // Enum for home page experience settings + HomePageSearchBarMode // Import the enum for search bar mode options +} from '@thoughtspot/visual-embed-sdk'; + const embed = new AppEmbed("#embed", { - modularHomeExperience: true, - showPrimaryNavbar: true, - hiddenHomeLeftNavItems: [HomeLeftNavItem.Home,HomeLeftNavItem.Liveboards], + discoveryExperience: { + primaryNavbarVersion: PrimaryNavbarVersion.Sliding, // Enable v3 experience + homePage: HomePage.Modular // modular home page experience + }, + // Set the home page search bar to show the Spotter / AI search bar + homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER + // Other view configuration attributes }); ---- -== Customize Home page modules (New experience) -If the new navigation and Home page experience is enabled on your ThoughtSpot instance, the Home page shows modules such as watchlist, favorites, a library of Answers and Liveboards, trending charts and more. To customize these modules and the Home page experience, use the xref:AppViewConfig.adoc#_hiddenhomepagemodules[`hiddenHomepageModules`] array. +V2 experience:: [source,javascript] ---- +import { + AppEmbed, + HomePageSearchBarMode // Import the enum for search bar mode options +} from '@thoughtspot/visual-embed-sdk'; + const embed = new AppEmbed("#embed", { - modularHomeExperience: true, - hiddenHomepageModules : [HomepageModule.Learning,HomepageModule.MyLibrary] + modularHomeExperience: true, // Enable v2 modular home page experience + // Set the home page search bar to show the Spotter / AI search bar + homePageSearchBarMode: HomePageSearchBarMode.AI_ANSWER + // Other view configuration attributes }); ---- -To reorder Home page modules, use the xref:AppViewConfig.adoc#_reorderedhomepagemodules[ `reorderedHomepageModules`] array. +V1 classic experience:: [source,javascript] ---- +import { + AppEmbed, + HomePageSearchBarMode // Import the enum for search bar mode options +} from '@thoughtspot/visual-embed-sdk'; + const embed = new AppEmbed("#embed", { - modularHomeExperience: true, - reorderedHomepageModules:[HomepageModule.Search,HomepageModule.Favorite,HomepageModule.Trending] + // Set the home page search bar to show the Spotter / AI search bar + homePageSearchBarMode: HomePageSearchBarMode.aiAnswer, + // Disable the unified search experience + isUnifiedSearchExperienceEnabled: false, + //... other view configuration attributes }); ---- -== Hide columns on list pages -You can hide the following columns on the *Liveboards* and *Answers* listing pages using the xref:AppViewConfig#_hiddenlistcolumns[hiddenListColumns] array: -* Author -* Favorite -* Last modified -* Tags -* Share +== Customize list pages + +A list page in ThoughtSpot refers to a page that displays a list of objects, such as Answers, Liveboards, and Liveboard schedules. The list pages include columns for sorting, filtering, tagging, and performing bulk actions such as marking favorites, sharing, or deleting objects. + +To customize the columns in list pages such as *Liveboards* and *Answers*, use the xref:AppViewConfig.adoc#_hiddenlistcolumns[hiddenListColumns] attribute. Valid values that correspond to the column names on the list pages are: -To hide one or several columns on the list pages, pass the relevant list page column enumerations in the `hiddenListColumns` array: +* `ListPageColumns.Author` to show or hide the *Author* column +* `ListPageColumns.Favourite` to show or hide the *Favourite* column +* `ListPageColumns.DateSort` to show or hide the *Last modified* column +* `ListPageColumns.Tags` to show or hide the *Tags* column +* `ListPageColumns.Share` to show or hide the *Share* links in the column -* `ListPageColumns.Author` -* `ListPageColumns.Favourite` -* `ListPageColumns.DateSort` -* `ListPageColumns.Tags` -* `ListPageColumns.Share` +The following example hides specific columns using the `hiddenListColumns` array: [source,javascript] ---- +import { + AppEmbed, // Main class to embed the full ThoughtSpot app + ListPageColumns // Enum for columns on list pages +} from '@thoughtspot/visual-embed-sdk'; + const embed = new AppEmbed("#embed", { - // hide Author, Share, and Tags columns on Answers and Liveboards list page - hiddenListColumns: [ListPageColumns.Author,ListPageColumns.Share,ListPageColumns.Tags] + // hide Author, Share, and Tags columns on Answers and Liveboards listing pages + hiddenListColumns: [ + ListPageColumns.Author, + ListPageColumns.Share + ], + //... other view config attributes + }); ---- @@ -504,15 +537,150 @@ const embed = new AppEmbed("#embed", { The `hiddenListColumns: [ListPageColumns.Share]` hides the *Share* column, but doesn't remove the *Share* button above the list. To hide both the column and the *Share* (xref:Action.adoc#_share[Action.Share]) button above the list, use the `hiddenActions` or `visibleActions` array. ==== -== Detect changes in the currently loaded page -Various actions the user takes within the embedded ThoughtSpot application may cause navigation within ThoughtSpot. +== Customize the default page and navigation routes +In full application embedding, the home page is set as the default landing page when the embedded app loads. + +To change the default settings, you can use either the `pageId` or `path` parameter in the Visual Embed SDK. If both `path` and `pageId` properties are specified, the `path` definition takes precedence. + +=== Set the default page using pageId +The `pageId` parameter in `AppEmbed` sets the default ThoughtSpot page to load using a value from the xref:Page.adoc[Page enumeration]. + +Valid values for this attribute are: + +* `Page.Home` for the ThoughtSpot *Home* page + +* `Page.Search` for the ThoughtSpot *Search* page + +* `Page.Answers` for the *Answers* page + +* `Page.Liveboards` for the *Liveboards* page + +* `Page.Data` for the *Data* page + +* `Page.SpotIQ` for the *SpotIQ* analyses page + +==== Example +[source,javascript] +---- +//Import Page enumeration +import { AppEmbed, Page } from '@thoughtspot/visual-embed-sdk'; + +const embed = new AppEmbed("#embed", { + // Set the initial page + pageId: Page.Liveboards, + //... other view configuration attributes +}); +---- + +=== Set the default page via path +The `path` parameter allows setting the default ThoughtSpot application page using a URL path. + +Valid strings for the `path` parameter are: + +[width="100%", cols="3,6,6"] +[options='header'] +|===== +|Page| Classic experience | V2 and v3 experience +|Home| `path: "home"` | `path: "home"` + +`path: "insights/home"` +|Insights| `path: "home"` | `path: "home"` + +`path: "insights/home"` +|Liveboards list page| `path: "pinboards"`| `path: "pinboards"` + +`path: "home/liveboards"` + +`path: "insights/liveboards"` +|Liveboard page| `path: "pinboard/"`| `path: "pinboard/"` +|Answers list page| `path: "answers"`| `path: "answers"` + +`path: "home/answers"` + +`path: "insights/answers"` +|Saved Answer page| `path: "saved-answer/"` |`path: "saved-answer/"` +|Spotter| `path: "conv-assist"` |`path: "conv-assist"` + +`path: "insights/conv-assist"` +|Search data| `path: "answer"` | `path: "answer"` + +`path: "insights/answer"` +|Data| `path: "data/tables/"`| `path: "data/tables/"` +|Model, tables, views|`path: "data/tables/"`| `path: "data/tables/"` +|SpotIQ analysis list page|`path: "insights"`| `path: "insights"` + +`path: "insights/spotiq-analysis"` +|SpotIQ analysis page | `path: "insight/"`| `path: "insight/"` +|Monitor| `path: "monitor"` a| Supported settings include: + +* `path: "monitor"` + +* `path: "home/monitor-alerts"` + +* `path: "insights/monitor-alerts"` +|===== + +==== Example + +[source,javascript] +---- +const embed = new AppEmbed("#embed", { + // Set the initial page + path: 'pinboard/96a1cf0b-a159-4cc8-8af4-1a297c492ff9', + //... other view configuration attributes +}); +---- + +=== Customize navigation between pages within the app +To programmatically control navigation between the pages within the embedded app, you can use the `navigateToPage()` method and custom actions. + + +==== Using navigateToPage() + +The `AppEmbed` object includes a `navigateToPage()` method that can switch the currently loaded page in the embedded view. + +The `navigateToPage()` method accepts the same string values used for the `pageId` or `path` attributes. When customizing the menu, use `navigateToPage` to create a route to the desired page. + +[source,JavaScript] +---- +// Navigate to the Answers page +embed.navigateToPage(Page.Answers); + +// Navigate to the Answers page without reloading the iframe (noReload = true) +embed.navigateToPage(Page.Answers, true); +---- + +==== Using navigateToPage() with a custom action +To add a custom action for in-app navigation, create a xref:custom-actions-callback.adoc[callback custom action] and define the navigation path. + +In this example, the **view-report ** action on a Liveboard page calls the `navigateTo` method to open a specific Answer page when the user clicks the **View report** button. + +[source,JavaScript] +---- +// Listen for the CustomAction event triggered from the embedded ThoughtSpot app +appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => { + // Check if the custom action ID is 'view-report' + if (payload.payload.id === 'view-report') { + // Navigate to the specific saved Answer page using its GUID + appEmbed.navigateToPage( + 'saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e' + ); + } +}); +---- + +To navigate to a specific application page without initiating a reload, you can set the `noReload` attribute to `true` as shown in this example: + +[source,javascript] +---- +// Listen for the CustomAction event triggered from the embedded ThoughtSpot app +appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => { + // Check if the custom action ID is 'view-report' + if (payload.payload.id === 'view-report') { + // Navigate to the specific saved Answer page using its GUID, + // and set noReload to true to avoid reloading the iframe + appEmbed.navigateToPage('saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e', true); + } +}); +---- + +==== Using history.back() +Page changes within the `AppEmbed` component register as part of the embedding app's history to the web browser. + +The standard JavaScript `history.back()` function will cause the `AppEmbed` component to go to the previously loaded page up until the very first ThoughtSpot page loaded within the component. + +=== Detect changes in the currently loaded page +Various actions the user takes within the embedded ThoughtSpot application may cause navigation within ThoughtSpot. The embedding web application can listen for the `EmbedEvent.RouteChange` event by attaching an event listener to the `AppEmbed` object. The response has a `currentPath` property which is the path after the ThoughtSpot domain, for example: ---- pinboard/96a1cf0b-a159-4cc8-8af4-1a297c492ff9 ---- -To parse the `currentPath` into varying useful components, this `tsAppState` object code can be created in the global scope for use by any other web application code: +To parse the `currentPath` into varying useful components, you can include this `tsAppState` object code in the global scope for use by any other web application code: [source,JavaScript] ---- @@ -520,7 +688,7 @@ To parse the `currentPath` into varying useful components, this `tsAppState` obj let tsAppState = { currentPath: startPath, currentDatasources: [], // Can be set later when detected from TML or other events - // return back what is being viewed at the moment, in the form that will translate to the pageId property if captialized, or path property if not + // return what is being viewed at the moment, in the form that will translate to the pageId property if capitalized, or path property if not get pageType() { if (this.currentPath.includes('/saved-answer/')){ return 'answer'; @@ -576,7 +744,7 @@ let tsAppState = { } ---- -The following example shows the event listener code updating the global `tsAppState` object above whenever there is a change within the embedded ThoughtSpot app: +The following example shows the event listener code updating the global `tsAppState` object above whenever a change is detected within the embedded ThoughtSpot app: [source,JavaScript] ---- @@ -586,50 +754,39 @@ embed.on(EmbedEvent.RouteChange, (response) => { // tsAppState object has currentPath property, which allows its other methods to parse out pageId, object type, GUIDs etc. tsAppState.currentPath = response.data.currentPath; console.log("TS App page is now: ", tsAppState.currentPath); - + // Update elements within your web application based on the new state of ThoughtSpot (adjust menu selections, etc.) }) ---- -== Navigate using a custom action -To add a custom action for in-app navigation, follow these steps: - -. xref:custom-actions-callback.adoc[Add a custom action]. -. Define the navigation path -In this example, the **view-report ** action on a Liveboard page calls the `navigateTo` method to open a specific saved Answer page when a user clicks the **View report** button in the embedded app. +== Customize Help menu +If you want to include the help menu and link:https://docs.thoughtspot.com/cloud/latest/customize-help[add custom links, window=_blank] to it, ensure that the top navigation bar is visible and `disableProfileAndHelp` is set to `false`. -[source,JavaScript] ----- -appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => { - if (payload.payload.id === 'view-report') { - appEmbed.navigateToPage( - 'saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e' - ); - } -}) ----- +By default, the help menu in the embedded view shows the legacy information center controlled using Pendo. To enable the new information center and add custom links, set `enablePendoHelp` to `false`. -If you want to navigate to a specific application page without initiating a reload, you can set the `noReload` attribute to `true` as shown here: +To add custom links to the help menu, use the customization settings available on the **Admin settings** > **Help customization** page. For more information, see link:https://docs.thoughtspot.com/cloud/latest/customize-help[ThoughtSpot Product Documentation]. -[source,javascript] +[source,JavaScript] ---- -appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => { - if (payload.payload.id === 'view-report') { - appEmbed.navigateToPage('saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e', true); - } -}) +const embed = new AppEmbed("#embed", { + // Display the top navigation bar + showPrimaryNavbar: true, + // Show the profile and help icons in the navigation bar. + disableProfileAndHelp: false, + // Use the new ThoughtSpot information center for help and support. + enablePendoHelp: false, + // ... other view config attributes +}); ---- -== CSS customization and hiding page elements -xref:css-customization.adoc[CSS customization] allows overriding the default styles from the ThoughtSpot application, including the application pages. - -If there is an element of a page that you dislike and cannot hide with any combination of other options in ThoughtSpot, you can often use CSS customization to target the element and apply either `display: none;`, `visibility: hidden;` or `height: 0px;` and make it functionally disappear to the end user. +== Additional customization controls +xref:css-customization.adoc[CSS customization] allows overriding default styles in ThoughtSpot application pages. -Specifying a direct element using the direct CSS selectors vs. the ThoughtSpot provided variables. To discover the appropriate selector, use the *Inspect* functionality of your browser to bring up the *Elements* portion of the browser's Developer Tools, then look at the *Styles* information. +//You can also use xref:_theme_builder[Theme Builder] to explore the available CSS variables. -An example of using direct selectors in a file is available in the link:https://github.com/thoughtspot/custom-css-demo/blob/main/complete.css[complete.css, target=_blank]. +If there is a page element you cannot hide using ThoughtSpot or Visual Embed SDK options, you can use a CSS selector to target the element and apply CSS properties such as `display: none`;, `visibility: hidden`;, or `height: 0px` to hide it from the UI. To find the appropriate selector, use your browser’s *Inspect* tool to examine the style element in the *Elements* section of the browser's Developer Tools. [source,css] ---- @@ -639,13 +796,16 @@ An example of using direct selectors in a file is available in the link:https:// } ---- -Direct selectors can also be declared using xref:css-customization.adoc#rules[rules] in the Visual Embed SDK code. This is useful for real-time testing, particularly in the Visual Embed SDK playground. Note the format for encoding CSS rules into the JavaScript object format used by for rules. +An example of using direct selectors in a file is available in the link:https://github.com/thoughtspot/custom-css-demo/blob/main/complete.css[complete.css sample, target=_blank] on the ThoughtSpot GitHub repository. + +You can also declare direct selectors using the xref:css-customization.adoc#rules[rules] property in the Visual Embed SDK configuration. This is useful for real-time testing, especially in the Visual Embed SDK playground. Note the required format for encoding CSS rules as JavaScript objects. == Additional resources * xref:full-embed.adoc[Embed full application] +* xref:page-navigation.adoc[Create dynamic menus and navigation] * xref:AppViewConfig.adoc[AppViewConfig reference page] * xref:HostEvent.adoc[Host events] * xref:EmbedEvent.adoc[Embed Events] -* xref:Action.adoc[Actions] + diff --git a/modules/ROOT/pages/full-embed.adoc b/modules/ROOT/pages/full-embed.adoc index c19166a7e..47f726e05 100644 --- a/modules/ROOT/pages/full-embed.adoc +++ b/modules/ROOT/pages/full-embed.adoc @@ -316,7 +316,7 @@ const appEmbed = new AppEmbed( appEmbed.render(); ---- -For customizing speicific components, you can include the xref:AppViewConfig.adoc[View configuration properties] available for full application embedding in the SDK. +For customizing specific components, you can include the xref:AppViewConfig.adoc[View configuration properties] available for full application embedding in the SDK. You may also want to import the xref:https://developers.thoughtspot.com/docs/Enumeration[Enumeration] objects and use the enums that represent values for the configuration properties in your code. For example, to show, hide, or disable specific menu actions, you may want to import the `Action` object and include the enumerated members representing specific menu actions in the `visibleActions`, `disabledActions`, or `hiddenActions` array. diff --git a/modules/ROOT/pages/getting-started.adoc b/modules/ROOT/pages/getting-started.adoc index 68af996cc..7be193d7c 100644 --- a/modules/ROOT/pages/getting-started.adoc +++ b/modules/ROOT/pages/getting-started.adoc @@ -41,27 +41,31 @@ For more information, see xref:user-roles.adoc[Developer access]. The Visual Embed SDK is available for installation as a Node Package Manager (NPM) package. The latest version of the Visual Embed SDK is available at link:https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk[https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk, window=_blank]. +//// To get started with embedding, install the SDK: [source,console] ---- npm install @thoughtspot/visual-embed-sdk ---- +//// -=== Import embed package +=== Import the embed package +The SDK is written in TypeScript and is also provided both as ES Module (ESM) and Universal Module Definition (UMD) modules, allowing you to use it in a variety of environments. The SDK is written in TypeScript and is also provided both as ES Module (ESM) and Universal Module Definition (UMD) modules, allowing you to use it in a variety of environments. Import one of the following modules into your app: * **LiveboardEmbed** + -Use the **LiveboardEmbed** component to xref:embed-a-viz.adoc[embed a single visualization] or a full Liveboard with multiple visualizations: +To xref:embed-a-viz.adoc[embed a single visualization] or a xref:embed-pinboard.adoc[full Liveboard with multiple visualizations]. + + +* **SpotterEmbed** + +To embed xref:embed-ai-analytics.adoc[embed Spotter AI search and analytics]. -+ -++++ -Embed a Liveboard -++++ +//// * **SageEmbed** + Use the `SageEmbed` package to embed Natural Language Search interface. @@ -69,29 +73,15 @@ Use the `SageEmbed` package to embed Natural Language Search interface. ++++ Embed Natural Language Search ++++ - +//// * **AppEmbed** + -Use the `AppEmbed` library to embed full ThoughtSpot application in your app. - -+ -++++ -Embed full ThoughtSpot application -++++ +To xref:full-embed.adoc[embed full ThoughtSpot application] experience or specific application pages. * **SearchEmbed** + -Use the `SearchEmbed` package to embed the ThoughtSpot search page with a pre-selected data source. -+ -++++ -Embed Search page -++++ +To xref:embed-search.adoc[embed ThoughtSpot Search page] with a pre-selected data source. * **SearchBarEmbed** + -Use the `SearchBarEmbed` component to embed only the ThoughtSpot Search bar and data panel. - -+ -++++ -Embed Search bar -++++ +To xref:embed-searchbar.adoc[embed only the ThoughtSpot Search bar] and data panel. ==== Example @@ -183,30 +173,38 @@ import { HostEvent } from '@thoughtspot/visual-embed-sdk'; +// Create a new LiveboardEmbed instance, targeting the DOM element with id 'container'. + const lb = new LiveboardEmbed('#container', { + // Set the frame size to 100% width and height frameParams: { width: '100%', height: '100%', }, - liveboardId: '<%=liveboardGUID%>', - runtimeFilters: [], + liveboardId: '<%=liveboardGUID%>', // ID of the Liveboard + runtimeFilters: [{ + columnName: 'Color', + operator: RuntimeFilterOp.EQ, + values: ['red'], + }, ], }); -// [Optional]: Register event listeners. + +// [Optional]: Register an event listener for the LiveboardRendered event. +// This allows you to execute custom logic when the Liveboard has finished rendering. lb.on(EmbedEvent.LiveboardRendered, (e) => { /* handler */ }); -// Do not forget to call render. +// Render the embedded Liveboard inside the specified container. +// This step is required to display the Liveboard in your application. lb.render(); -// [Optional]: Trigger events on the lb -lb.trigger(HostEvent.UpdateRuntimeFilters, [ - { - columnName: 'col1', - operator: RuntimeFilterOp.EQ, - values: ['val1'], - }, -]); +// Programmatically trigger a HostEvent to update runtime filters on the embedded Liveboard. +lb.trigger(HostEvent.UpdateRuntimeFilters, [{ + columnName: 'Color', + operator: RuntimeFilterOp.EQ, + values: ['amber'], +}, ]); ---- `#container` is a selector for the DOM node which the code assumes is already attached to DOM. The SDK will render the ThoughtSpot component inside this container element. @@ -216,24 +214,32 @@ ThoughtSpot provides React components for embedding Search, Liveboard, and the f [source,TypeScript] ---- +// Import the LiveboardEmbed React component from the ThoughtSpot Visual Embed SDK import { LiveboardEmbed } from '@thoughtspot/visual-embed-sdk/react'; const App = () => { + // Create a ref to interact with the embedded Liveboard instance const embedRef = useEmbedRef(); + + // Event handler called when the Liveboard has finished rendering const onLiveboardRendered = () => { + // Trigger a HostEvent to update runtime filters on the embedded Liveboard + // This filter sets the 'col1' column to only show rows where the value is 'val1' embedRef.current.trigger(HostEvent.UpdateRuntimeFilters, [ { - columnName: 'col1', + columnName: 'Color', operator: RuntimeFilterOp.EQ, - values: ['val1'], + values: ['amber'], }, ]); }; + + // Render the LiveboardEmbed component with the specified Liveboard ID and event handler return ( ); }; diff --git a/modules/ROOT/pages/onboarding-guide.adoc b/modules/ROOT/pages/onboarding-guide.adoc index 94a0726fb..7a812bff1 100644 --- a/modules/ROOT/pages/onboarding-guide.adoc +++ b/modules/ROOT/pages/onboarding-guide.adoc @@ -42,31 +42,42 @@ image::./images/lb-image.png[Liveboard] If you want to embed other ThoughtSpot components and explore the additional capabilities of the Visual Embed SDK, see the xref:getting-started.adoc[embedding components guide] or the resources listed in the xref:onboarding-guide.adoc#addResources[Explore more] section. -=== Step 1: Install the Visual Embed SDK +=== Step 1: Import the Visual Embed SDK The latest version of the Visual Embed SDK is available at link:https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk[https://www.npmjs.com/package/@thoughtspot/visual-embed-sdk, window=_blank]. -[source,console] ----- -npm install @thoughtspot/visual-embed-sdk ----- - -=== Step 2: Import the SDK into your project +The SDK is written in TypeScript and is also provided both as ES Module (ESM) and Universal Module Definition (UMD) modules, allowing you to use it in a variety of environments. -Import the SDK package into your application environment. Let's import the `LiveboardEmbed` SDK package to embed a Liveboard. +In this example, we'll import the `LiveboardEmbed` SDK package to embed a Liveboard. +**npm** [source,JavaScript] ---- import { LiveboardEmbed, AuthType, init, -} from '@thoughtspot/visual-embed-sdk'; + prefetch, + EmbedEvent +} +from '@thoughtspot/visual-embed-sdk'; ---- +**ES6** +[source,JavaScript] +---- +