Customize full application embedding

Customize full application embedding

The AppEmbed component embeds the entire ThoughtSpot application experience within another page.

UI and navigation experience🔗

The ThoughtSpot UI and navigation experience is available in two modes:

  • Classic experience (default)

  • New navigation and homepage experience Early Access

New navigation and homepage experience🔗

In the new navigation and homepage experience, the app selector the app switcher menu appears on the header bar instead of the top navigation menu. The app selector consists of different persona-based contextual elements called apps. On clicking an app from the application, the page corresponding to that app opens. Each application module has a separate left navigation panel.

New home page

The new navigation and homepage experience introduces the following changes:

Classic experienceNew navigation and homepage experience

Navigation

Top navigation menu with the following buttons:

  • Home
    Opens Homepage

  • 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

App selector the app switcher menu with the following apps:

  • Insights
    Opens the Insights homepage. Note that the Answers, Liveboards, SpootIQ, and Monitor Subscriptions are grouped as Insights in the new homepage experience.

    • Insights > Home
      Opens homepage

    • 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 homepage 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

Homepage 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 homepage 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

  • Liveboards
    https://{ThoughtSpot-Host}/#/pinboards

  • Answers
    https://{ThoughtSpot-Host}/#/answers

  • SpotIQ
    https://{ThoughtSpot-Host}/#/insights

  • Monitor
    https://{ThoughtSpot-Host}/#/monitor

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

Enable new experience mode for ThoughtSpot embedding🔗

By default, the new navigation and homepage 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.

const embed = new AppEmbed("#embed", {
    pageId: Page.Home,
    modularHomeExperience: true,
    frameParams: {
        height: '100%',
        width: '100%'
    }
});

Choose the 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.

pageId🔗

The pageId parameter of the AppEmbed 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

const embed = new AppEmbed("#embed", {
    pageId: Page.Liveboards,
    showPrimaryNavbar: false,
    frameParams: {
        height: '100%',
        width: '100%'
    }
});

path🔗

The URL path of the ThoughtSpot application page that you want your embed application users to navigate to.

const embed = new AppEmbed("#embed", {
    path: 'pinboard/96a1cf0b-a159-4cc8-8af4-1a297c492ff9',
    frameParams: {
        height: '100%',
        width: '100%'
    }
});

The following examples show valid strings for path:

PageClassic experienceNew navigation and homepage experience

Answers

path: "answers"

path: "home/answers"

Saved Answer

path: "saved-answer/<answer-GUID>"

path: "saved-answer/<Answer-GUID>"

Liveboards

path: "pinboards"

path: "home/liveboards"

Liveboard

path: "pinboard/<Liveboard-GUID>"

path: "pinboard/<Liveboard-GUID>"

SpotIQ analysis list

path: "insights"

path: "home/spotiq-analysis"

SpotIQ analysis page

path: "insight/<spotIQ-analysis-GUID>"

path: "insight/<spotIQ-analysis-GUID>"

Data

path: "data/tables/"

path: "data/tables/"

Worksheet, tables, views

path: "data/tables/<object-GUID>"

path: "data/tables/<object-GUID>"

Monitor

path: "monitor"

path: "monitor"
or
path: "home/monitor-alerts"

navigateToPage()🔗

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.

The new navigation menu should call navigateToPage for the various pages you want to provide access to:

embed.navigateToPage(Page.Answers);
// with noReload option
embed.navigateToPage(Page.Answers, true);

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🔗

ThoughtSpot application supports the following types of search:

  • Object Search

    Allows finding popular Liveboards and Answers from the recommended suggestions. The Object Search bar appears on the top navigation bar if the top navigation bar visibility is enabled (that is, if showPrimaryNavbar is set to true).
    Starting from 10.3.0.cl, the Object Search experience will be the default search experience on the Home page.

  • Natural Language Search

    Allows searching a data source using a natural language query string and get AI-generated Answers. Starting from 10.3.0.cl release, the Natural Language Search experience on the ThoughtSpot application Home page is disabled by default.

    To enable access to Natural Language Search feature for your end users, you can do one of the following:

  • Search data

    Allows searching a data source using keywords and search tokens. This experience is available if you have embedded the Search page using appEmbed or SearchEmbed.

Customize search experience for Home page🔗

In full application embedding, the Object Search bar is available in the following locations:

  • Top navigation bar
    Optional. The top navigation bar visibility is controlled via showPrimaryNavbar parameter in the Visual Embed SDK. If your embedding includes the top navigation bar, note that the Object Search bar is available in the navigation bar.

  • Home page
    Starting from 10.3.0.cl, the Object Search bar will appear on the embedded Home page as the default Search experience. You can switch the Search experience by setting the homePageSearchBarMode property to one of the following values:

    • objectSearch (default)
      Displays Object Search bar on the Home page.

    • aiAnswer
      Displays the search bar for Natural Language Search

    • none 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.

In the Classic experience mode

By default, the Object Search bar is displayed on the embedded Home page.

sageDisabledwithNav classic

If you want to use the Natural Language Search experience, enable Sage Search bar as shown in this code snippet:

const embed = new AppEmbed("#embed", {
    showPrimaryNavbar: true,
    homePageSearchBarMode: "aiAnswer",
});
sageEnabledwithNav classic
In the New modular experience mode

By default, the Object Search bar is displayed in the Search module on the embedded Home page:

objSearchNav modularExp

If you want to use the Natural Language Search experience, enable Sage Search bar as shown in this code snippet:

const embed = new AppEmbed("#embed", {
    modularHomeExperience: true,
    showPrimaryNavbar: true,
    homePageSearchBarMode: "aiAnswer",
});
sageEnabledNav modularExp
Note

If you need additional help or assistance with customization, contact ThoughtSpot Support.

Include Spotter interface🔗

To integrate Spotter Beta capabilities and conversation interface in full app embedding, make sure Spotter is enabled on your instance and then set the homePageSearchBarMode to aiAnswer in the SDK.

const embed = new AppEmbed("#embed", {
    modularHomeExperience: true,
    homePageSearchBarMode: "aiAnswer",
});

Customize navigation controls🔗

The AppEmbed package in the Visual Embed SDK provides several parameters to hide or customize navigation controls.

The top navigation menu bar (classic experience), app selector 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:

  • hideOrgSwitcher
    Hides the Orgs drop-down. Applicable to only Orgs-enabled clusters.

  • hideApplicationSwitcher
    Hides the app selector the app switcher menu. The app selector is available only in the new navigation and homepage experience mode.

  • disableProfileAndHelp

    • To hide help and profile icons (Classic experience)

    • To hide help and profile icons, Help and Chat with Support menu options on the homepage (New Experience).

Customize the left navigation panel on homepage (New experience)🔗

If the new navigation and homepage experience is enabled and showPrimaryNavbar to true, the home page displays a navigation panel on the left side of the Insights homepage. The panel consists of menu items such as Answers, Liveboards, SpotIQ Analysis, Monitor Subscriptions, and so on.

To hide the left navigation panel in the embedded view, set hideHomepageLeftNav to true.

const embed = new AppEmbed("#embed", {
    modularHomeExperience: true,
    showPrimaryNavbar: true,
    hideApplicationSwitcher: true,
    hideHomepageLeftNav: true,
    disableProfileAndHelp: true,
});

If you don’t want to hide the left navigation panel, but show only a select few menu items, use hiddenHomeLeftNavItems array.

const embed = new AppEmbed("#embed", {
    modularHomeExperience: true,
    showPrimaryNavbar: true,
    hiddenHomeLeftNavItems: [HomeLeftNavItem.Home,HomeLeftNavItem.Liveboards],
});

Customize homepage modules (New experience)🔗

If the new navigation and homepage experience is enabled on your ThoughtSpot instance, the homepage shows modules such as watchlist, favorites, a library of Answers and Liveboards, trending charts and more. To customize these modules and the homepage experience, use the hiddenHomepageModules array.

const embed = new AppEmbed("#embed", {
    modularHomeExperience: true,
    hiddenHomepageModules : [HomepageModule.Learning,HomepageModule.MyLibrary]
});

To reorder homepage modules, use the reorderedHomepageModules array.

const embed = new AppEmbed("#embed", {
    modularHomeExperience: true,
    reorderedHomepageModules:[HomepageModule.Search,HomepageModule.Favorite,HomepageModule.Trending]
});

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:

// Simple global object to handle details about what is visible in the AppEmbed component at a given moment
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
  get pageType() {
      if (this.currentPath.includes('/saved-answer/')){
          return 'answer';
      }
      else if (this.currentPath.includes('/pinboard/')){
          return 'liveboard';
      }
      /*
      * Others are meant to match the exact pageId from SDK
      */
      else if(this.currentPath.includes('/answer/')){
          return 'Search';
      }
      else if(this.currentPath.includes('/answers')){
          return 'Answers';
      }
      else if (this.currentPath.includes('/pinboards')){
          return 'Liveboards';
      }
      else if(this.currentPath.includes('/insights')){
          return 'SpotIQ';
      }
      else if(this.currentPath.includes('/monitor')){
          return 'Monitor';
      }
      else if(this.currentPath.includes('/data')){
          return 'Data';
      }
      else {
          return 'Home';
      }
  },
  // If viewing an Answer or Liveboard, returns the GUID of that object from the parsed URL
  get objectId() {
      let pathParts = this.currentPath.split('/');
      // '/saved-answer/' is path for Answers (vs. /answer/)
      if (this.currentPath.includes('/saved-answer/')){
          answerGUID = pathParts[2];
          return pathParts[2];
      }
      // '/pinboard/' is path for saved Liveboards
      else if (this.currentPath.includes('/pinboard/')){
          let pathParts = this.currentPath.split('/');
          // May need adjustment for tabbed views to add in current Tab
          liveboardGUID = pathParts[2];
          return pathParts[2];
      }
      else{
          return null;
      }
  }

}

The following example shows the event listener code updating the global tsAppState object above whenever there is a change within the embedded ThoughtSpot app:

embed.on(EmbedEvent.RouteChange, (response) => {
  // console.log("RouteChange fires");
  // console.log(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:

  1. Add a custom action.

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

appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => {
    if (payload.payload.id === 'view-report') {
        appEmbed.navigateToPage(
            'saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e'
        );
    }
})

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:

appEmbed.on(EmbedEvent.CustomAction, async (payload: any) => {
    if (payload.payload.id === 'view-report') {
        appEmbed.navigateToPage('saved-answer/3da14030-11e4-42b2-8e56-5ee042a8de9e', true);
    }
})

CSS customization and hiding page elements🔗

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.

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.

An example of using direct selectors in a file is available in the complete.css.

.bk-data-scope .left-pane .header-lt {
  display: none !important;
  visibility: hidden !important;
}

Direct selectors can also be declared using 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.

Additional resources🔗