Skip to content

Commit 34d6da2

Browse files
yinstardevyinstardev
committed
SCAL-320501 Actions Example
1 parent a7bdb56 commit 34d6da2

11 files changed

Lines changed: 1794 additions & 0 deletions

File tree

‎visual-embed/actions/.gitignore‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# Logs
2+
logs
3+
*.log
4+
npm-debug.log*
5+
yarn-debug.log*
6+
yarn-error.log*
7+
pnpm-debug.log*
8+
lerna-debug.log*
9+
10+
node_modules
11+
dist
12+
dist-ssr
13+
*.local
14+
15+
# Editor directories and files
16+
.vscode/*
17+
!.vscode/extensions.json
18+
.idea
19+
.DS_Store
20+
*.suo
21+
*.ntvs*
22+
*.njsproj
23+
*.sln
24+
*.sw?

‎visual-embed/actions/.stackblitzrc‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"installDependencies": true,
3+
"startCommand": "npm run dev",
4+
"env": {
5+
"VITE_TS_HOST": "https://training.thoughtspot.cloud",
6+
"VITE_TS_USERNAME": "code-sandbox",
7+
"VITE_TS_PASSWORD": "3mbed+#3xplz",
8+
"VITE_LIVEBOARD_ID": "b504e160-3025-4508-a76a-1beb1f4b5eed"
9+
}
10+
}

‎visual-embed/actions/README.md‎

Lines changed: 192 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,192 @@
1+
<!-- search-meta
2+
tags: [Action, actions, menu actions, visibleActions, hiddenActions, disabledActions, disabledActionReason, LiveboardEmbed, AppEmbed, SearchEmbed, SpotterEmbed, allow-list, deny-list, toolbar, context menu, TypeScript, Web, Visual Embed SDK]
3+
apis: [init, AuthType, LiveboardEmbed, Action, visibleActions, hiddenActions, disabledActions, disabledActionReason, EmbedEvent, ViewConfig, LiveboardViewConfig]
4+
questions:
5+
- How do I show only specific actions in an embedded ThoughtSpot view?
6+
- How do I hide actions like Share or Edit in a LiveboardEmbed?
7+
- What is the difference between hiddenActions and disabledActions?
8+
- When should I use visibleActions vs hiddenActions?
9+
- How do I grey out (disable) an action and show a reason on hover?
10+
- What is the Action enum in the Visual Embed SDK?
11+
- How do I use visibleActions as an allow-list to restrict the toolbar?
12+
- How do I remove the Download or Share button from an embedded Liveboard?
13+
- Why is my action still showing even though I added it to hiddenActions?
14+
- Do visibleActions and hiddenActions work together?
15+
- How do I hide a child action like Download as PDF?
16+
- How do I control the action menu in AppEmbed, SearchEmbed, or SpotterEmbed?
17+
-->
18+
19+
# actions
20+
21+
A TypeScript + Vite example that shows how to control the **built-in action menu** of an embedded ThoughtSpot view using the [`Action`](https://developers.thoughtspot.com/docs/Enumeration_Action) enum. The demo embeds a Liveboard and lets you flip between allow-list, deny-list, and disabled modes so you can watch the toolbar and `...` (more) menu change live.
22+
23+
## What are "actions"?
24+
25+
Every user-initiated command in a ThoughtSpot view — **Download**, **Share**, **Edit**, **Drill down**, **Schedule**, **Pin**, **SpotIQ analyze**, and so on — is a menu/toolbar item that the Visual Embed SDK represents as a member of the `Action` enum (e.g. `Action.Download`, `Action.Share`, `Action.Edit`). These appear in the top toolbar, the per-visualization `...` menu, and right-click context menus.
26+
27+
When you embed ThoughtSpot inside your own app you usually want to **curate** which of these the end user sees — for example, expose only **Download** and **Drill down** to viewers, or hide **Edit** and **Delete** so users can't modify content. You do that declaratively through three view-config options. No CSS hacks, no DOM surgery.
28+
29+
## The three controls
30+
31+
| Option | Type | Behaviour |
32+
| --- | --- | --- |
33+
| `visibleActions` | `Action[]` | **Allow-list.** Only the listed actions are shown; every other action is hidden. Use when you want a tightly-scoped toolbar. |
34+
| `hiddenActions` | `Action[]` | **Deny-list.** The listed actions are removed from the UI entirely. Use when you want the full menu *minus a few* items. |
35+
| `disabledActions` | `Action[]` | The listed actions stay **visible but greyed-out and non-clickable**. Pair with `disabledActionReason` to show a tooltip explaining why. |
36+
| `disabledActionReason` | `string` | Tooltip text shown when a user hovers a disabled action. |
37+
38+
> ⚠️ **`visibleActions` and `hiddenActions` are mutually exclusive.** Provide one or the other — never both on the same embed. If you set both, behaviour is undefined and the SDK logs a warning.
39+
40+
### Which one should I use?
41+
42+
- **Show a small, fixed set of actions** → `visibleActions` (allow-list). Safest for locked-down viewer experiences because new actions added in future ThoughtSpot releases stay hidden by default.
43+
- **Keep almost everything, drop a few** → `hiddenActions` (deny-list). Convenient, but remember that future releases may introduce new actions you didn't explicitly hide.
44+
- **Signal that an action exists but isn't available right now** (entitlement, role, demo) → `disabledActions` + `disabledActionReason`.
45+
46+
## Key Usage
47+
48+
```typescript
49+
import { init, AuthType, LiveboardEmbed, Action, EmbedEvent } from "@thoughtspot/visual-embed-sdk";
50+
51+
// Initialize once for the whole app.
52+
// NOTE: AuthType.Basic with username/password is for DEMO only.
53+
// In production use trusted auth or SSO — never ship credentials to the browser.
54+
init({
55+
thoughtSpotHost: import.meta.env.VITE_TS_HOST,
56+
authType: AuthType.Basic,
57+
username: import.meta.env.VITE_TS_USERNAME,
58+
password: import.meta.env.VITE_TS_PASSWORD,
59+
});
60+
61+
const embed = new LiveboardEmbed(document.getElementById("ts-embed")!, {
62+
frameParams: { width: "100%", height: "100%" },
63+
liveboardId: import.meta.env.VITE_LIVEBOARD_ID,
64+
65+
// --- pick ONE of the following strategies ---
66+
67+
// 1) Allow-list: ONLY these actions are shown.
68+
visibleActions: [Action.DownloadAsPdf, Action.Share, Action.DrillDown],
69+
70+
// 2) Deny-list (don't combine with visibleActions): remove from the UI.
71+
// hiddenActions: [Action.Share, Action.Edit, Action.Schedule],
72+
73+
// 3) Greyed-out but visible, with a hover reason.
74+
// disabledActions: [Action.DownloadAsPdf, Action.Share],
75+
// disabledActionReason: "Not available in this demo",
76+
});
77+
78+
embed.on(EmbedEvent.Error, (e) => console.error("Embed error:", e));
79+
embed.render();
80+
```
81+
82+
## Commonly used `Action` enum members
83+
84+
A quick reference of frequently-curated actions (the enum has 150+ members — see the full reference link below):
85+
86+
| `Action` member | UI command |
87+
| --- | --- |
88+
| `Action.Save` | Save an Answer / Liveboard |
89+
| `Action.Edit` | Open in edit mode |
90+
| `Action.Share` | Share with users/groups |
91+
| `Action.Download` | Download (parent action) |
92+
| `Action.DownloadAsPdf` | Download → PDF |
93+
| `Action.DownloadAsCsv` | Download → CSV |
94+
| `Action.DownloadAsXlsx` | Download → XLSX |
95+
| `Action.DownloadAsPng` | Download → PNG |
96+
| `Action.DrillDown` | Drill down on a data point |
97+
| `Action.Pin` | Pin an Answer to a Liveboard |
98+
| `Action.Schedule` | Schedule a Liveboard job |
99+
| `Action.SpotIQAnalyze` | Run SpotIQ analysis |
100+
| `Action.ShowUnderlyingData` | Show underlying raw data |
101+
| `Action.Explore` | Explore a visualization |
102+
| `Action.AddFilter` | Add a filter to a Liveboard |
103+
| `Action.Present` | Present mode |
104+
| `Action.MakeACopy` | Make a copy |
105+
| `Action.AskAi` / `Action.SpotterViz` | Spotter entry points |
106+
107+
## Features
108+
109+
- Plain **TypeScript + Vite** — no framework, minimal dependencies.
110+
- One-click switching between `all`, `visibleActions`, `hiddenActions`, and `disabledActions` modes.
111+
- Re-renders the `LiveboardEmbed` on each switch so the toolbar/menu visibly updates.
112+
- Shows the live view-config snippet for the selected mode above the embed.
113+
- Listens for `EmbedEvent.Error` and logs to the console.
114+
115+
## How It Works
116+
117+
1. `init(...)` is called once at module load to configure the host and auth.
118+
2. `buildConfig(mode)` returns a `LiveboardViewConfig` for the selected mode — adding `visibleActions`, `hiddenActions`, or `disabledActions` (with `disabledActionReason`) as appropriate.
119+
3. `renderEmbed(mode)` clears the container, constructs a fresh `LiveboardEmbed` with that config, and calls `render()`.
120+
4. The mode buttons call `selectMode(...)`, which updates the active button, swaps the displayed code snippet, and triggers a re-render.
121+
122+
## Project Structure
123+
124+
- `index.html` — Vite entry; mounts `#app` and loads `src/main.ts`.
125+
- `src/main.ts` — SDK `init`, the mode/config logic (`buildConfig`), the embed render logic (`renderEmbed`), and the UI wiring.
126+
- `src/style.css` — light-theme styling for the controls, code snippet, and embed frame.
127+
- `src/vite-env.d.ts` — typed `import.meta.env` for the `VITE_*` variables.
128+
- `.env` / `.stackblitzrc` — connection + auth values for the public demo instance.
129+
130+
## Works with other embed types
131+
132+
`visibleActions` / `hiddenActions` / `disabledActions` are part of the shared `ViewConfig`, so the same pattern applies to:
133+
134+
- `LiveboardEmbed` (this example)
135+
- `AppEmbed` (full-app embedding)
136+
- `SearchEmbed` (Search / Answer)
137+
- `SpotterEmbed` (Spotter conversational analytics)
138+
139+
Just pass the same options to whichever embed component you're constructing.
140+
141+
## Gotchas
142+
143+
- **Don't combine** `visibleActions` and `hiddenActions` on the same embed — pick one strategy.
144+
- **Parent vs child actions.** Some actions are children of a parent menu. To control a child like `Action.DownloadAsPdf`, the parent (`Action.Download`) generally needs to be present too. For TML options, the parent `Action.TML` must be included for the cascading menu items to appear.
145+
- **Allow-list is future-proof, deny-list is not.** New ThoughtSpot releases add new actions; with `visibleActions` they stay hidden automatically, with `hiddenActions` they will appear unless you add them.
146+
- **An action only shows if the user has permission and the feature is enabled** — hiding it in the SDK is a UI control, not a security boundary. Enforce real authorization server-side / via ThoughtSpot roles.
147+
148+
## Environment
149+
150+
The committed `.env` points at the public ThoughtSpot training instance. To run against your own, set:
151+
152+
```
153+
VITE_TS_HOST=https://your-instance.thoughtspot.cloud
154+
VITE_TS_USERNAME=your-username
155+
VITE_TS_PASSWORD=your-password
156+
VITE_LIVEBOARD_ID=your-liveboard-id
157+
```
158+
159+
## Technologies Used
160+
161+
- TypeScript
162+
- Vite
163+
- ThoughtSpot Visual Embed SDK (`@thoughtspot/visual-embed-sdk`)
164+
165+
## Demo
166+
167+
Open in [StackBlitz](https://stackblitz.com/github/thoughtspot/developer-examples/tree/main/visual-embed/actions)
168+
169+
## Documentation
170+
171+
- [Action enum reference](https://developers.thoughtspot.com/docs/Enumeration_Action)
172+
- [Show or hide UI actions](https://developers.thoughtspot.com/docs/embed-actions)
173+
- [Embed a Liveboard](https://developers.thoughtspot.com/docs/embed-liveboard)
174+
- [Visual Embed SDK getting started](https://developers.thoughtspot.com/docs/getting-started)
175+
176+
## Run locally
177+
178+
```
179+
$ git clone https://github.com/thoughtspot/developer-examples
180+
$ cd visual-embed/actions
181+
```
182+
```
183+
$ npm i
184+
```
185+
```
186+
$ npm run dev
187+
```
188+
189+
### Technology labels
190+
191+
- TypeScript
192+
- Web

‎visual-embed/actions/index.html‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
<!doctype html>
2+
<html lang="en">
3+
<head>
4+
<meta charset="UTF-8" />
5+
<link rel="icon" type="image/svg+xml" href="/ts-logo.svg" />
6+
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
7+
<title>ThoughtSpot Actions — Visual Embed SDK</title>
8+
</head>
9+
<body>
10+
<div id="app"></div>
11+
<script type="module" src="/src/main.ts"></script>
12+
</body>
13+
</html>

0 commit comments

Comments
 (0)