Skip to content

Commit 766c5d2

Browse files
pballaipballai
authored
Merge pull request #87 from sigmacomputing/plugin_use_cases_setup
Draft1
2 parents 8831bc0 + 96ef667 commit 766c5d2

23 files changed

Lines changed: 6818 additions & 0 deletions

‎plugin_use_cases/.env.example‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# =============================================================================
2+
# SIGMA PLUGIN HOST APPLICATION CONFIGURATION
3+
# =============================================================================
4+
# This file contains all configuration for the Sigma Plugin Host Application
5+
# Copy this file to .env and update the values below to match your Sigma instance
6+
# =============================================================================
7+
8+
# =============================================================================
9+
# SIGMA API CONFIGURATION
10+
# =============================================================================
11+
# Your Sigma API credentials - obtain from Sigma Administration > Developer Access
12+
SIGMA_CLIENT_ID=your-client-id-here
13+
SIGMA_CLIENT_SECRET=your-client-secret-here
14+
SIGMA_API_BASE_URL=https://aws-api.sigmacomputing.com
15+
16+
# =============================================================================
17+
# APPLICATION SETTINGS
18+
# =============================================================================
19+
# Port for the Express server (default: 3000)
20+
PORT=3000
21+
22+
# Enable debug logging (true/false)
23+
DEBUG=false
24+
25+
# =============================================================================
26+
# USER CONFIGURATION
27+
# =============================================================================
28+
# Email addresses for different user types in your Sigma organization
29+
BUILD_EMAIL=build.user@example.com
30+
VIEW_EMAIL=view.user@example.com
31+
ADMIN_EMAIL=admin.user@example.com
32+
33+
# Account types for different users
34+
BUILD_ACCOUNT_TYPE=Build
35+
VIEW_ACCOUNT_TYPE=View
36+
37+
# =============================================================================
38+
# WORKBOOK CONFIGURATION
39+
# =============================================================================
40+
# Your Sigma organization slug (found in your Sigma URL)
41+
ORG_SLUG=your-org-slug
42+
43+
# The name of your workbook containing the dashboard elements
44+
WORKBOOK_NAME=Your-Workbook-Name
45+
46+
# Base URL for embed links (usually your Sigma domain)
47+
EMBED_URL_BASE=https://app.sigmacomputing.com
48+
49+
# =============================================================================
50+
# PLUGIN CONFIGURATION
51+
# =============================================================================
52+
# Name of your plugin for display purposes
53+
PLUGIN_NAME=Dashboard Builder
54+
55+
# Plugin-specific embed parameters (true/false values)
56+
PLUGIN_MODE=true
57+
DISABLE_AUTO_REFRESH=false
58+
DISABLE_MOBILE_VIEW=false
59+
HIDE_FOLDER_NAVIGATION=false
60+
HIDE_MENU=false
61+
HIDE_PAGE_CONTROLS=false
62+
HIDE_RELOAD_BUTTON=false
63+
HIDE_TITLE=false
64+
HIDE_TOOLTIP=false
65+
HIDE_VIEW_SELECT=false
66+
67+
# Language and display settings
68+
LNG=en
69+
MENU_POSITION=top
70+
RESPONSIVE_HEIGHT=true
71+
THEME=light

‎plugin_use_cases/.gitignore‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# Dependencies
2+
node_modules/
3+
npm-debug.log*
4+
yarn-debug.log*
5+
yarn-error.log*
6+
7+
# Environment variables (contains sensitive API credentials)
8+
.env
9+
.env.local
10+
.env.development.local
11+
.env.test.local
12+
.env.production.local
13+
14+
# Database files (contains user data and bookmarks)
15+
data/
16+
*.json
17+
!package.json
18+
!package-lock.json
19+
20+
# Logs
21+
logs
22+
*.log
23+
24+
# Runtime data
25+
pids
26+
*.pid
27+
*.seed
28+
*.pid.lock
29+
30+
# Coverage directory used by tools like istanbul
31+
coverage/
32+
33+
# nyc test coverage
34+
.nyc_output
35+
36+
# Dependency directories
37+
node_modules/
38+
jspm_packages/
39+
40+
# Optional npm cache directory
41+
.npm
42+
43+
# Optional REPL history
44+
.node_repl_history
45+
46+
# Output of 'npm pack'
47+
*.tgz
48+
49+
# Yarn Integrity file
50+
.yarn-integrity
51+
52+
# dotenv environment variables file
53+
.env
54+
55+
# IDE files
56+
.vscode/
57+
.idea/
58+
*.swp
59+
*.swo
60+
*~
61+
62+
# OS generated files
63+
.DS_Store
64+
.DS_Store?
65+
._*
66+
.Spotlight-V100
67+
.Trashes
68+
ehthumbs.db
69+
Thumbs.db
70+
71+
# Temporary files
72+
*.tmp
73+
*.temp

‎plugin_use_cases/README.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# 🚀 Sigma Dashboard Builder - Multi-Area KPI Placement System
2+
3+
A sophisticated host application for Sigma's Dashboard Builder plugin that enables users to place different KPIs across three independent dashboard areas with persistent bookmark management.
4+
5+
## ✨ Key Features
6+
7+
- **🎯 Multi-Area KPI Placement**: Place different KPIs in 3 independent dashboard areas
8+
- **💾 Persistent Bookmarks**: Save and restore complete multi-area configurations
9+
- **🔄 Incremental Building**: Add KPIs to existing bookmarks without losing current state
10+
- **🛡️ Cross-Contamination Prevention**: Each area operates independently
11+
- **⚡ Real-time Synchronization**: ExploreKey sync across all areas
12+
- **🔐 Secure Authentication**: JWT-based authentication with automatic token refresh
13+
14+
## 🏗️ Architecture
15+
16+
### Dual Storage System
17+
- **Sigma Bookmarks**: Store exploreKey and workbook state (single-state, cloud)
18+
- **LowDB Database**: Store multi-area configurations (multi-state, local)
19+
- **Combined**: Complete bookmark restoration across all dashboard areas
20+
21+
This project provides host application examples for Sigma plugins, demonstrating advanced multi-area plugin integration and persistent state management.
22+
23+
## Project Structure
24+
25+
```
26+
plugin_use_cases/
27+
├── .env # Configuration file (copy from .env.example)
28+
├── package.json # Node.js dependencies
29+
├── server/
30+
│ └── server.js # Express server for hosting
31+
├── helpers/
32+
│ └── create-jwt.js # JWT generation utilities
33+
├── routes/
34+
│ └── api/
35+
│ └── jwt.js # JWT API endpoints
36+
└── public/
37+
├── styles/ # Shared CSS styles
38+
└── dashboard-builder/ # Dashboard Builder plugin host
39+
└── index.html # Host application
40+
```
41+
42+
## Quick Start
43+
44+
### Prerequisites
45+
46+
1. **Sigma Instance Access**: You need a Sigma instance with:
47+
- API credentials (Client ID and Secret)
48+
- A registered plugin (e.g., "Dashboard Builder")
49+
- A workbook configured for the plugin
50+
51+
2. **Node.js**: Version 14 or higher
52+
53+
### Setup
54+
55+
1. **Clone and Navigate**:
56+
```bash
57+
cd plugin_use_cases
58+
```
59+
60+
2. **Install Dependencies**:
61+
```bash
62+
npm install
63+
```
64+
65+
3. **Configure Environment**:
66+
- Copy `.env` to create your configuration
67+
- Update the following required fields:
68+
```
69+
ORG_SLUG=your-sigma-org
70+
CLIENT_ID=your-client-id
71+
SECRET=your-client-secret
72+
ADMIN_EMAIL=your-admin-email@company.com
73+
```
74+
75+
4. **Start the Server**:
76+
```bash
77+
npm start
78+
```
79+
80+
5. **Access the Application**:
81+
- Open http://localhost:3000
82+
- Navigate to the Dashboard Builder example
83+
84+
## Dashboard Builder Plugin Host
85+
86+
The Dashboard Builder host application demonstrates:
87+
88+
- **Plugin Integration**: Embedding a Sigma plugin in a host application
89+
- **Bidirectional Communication**: Messages between host and plugin
90+
- **Element Selection**: UI for selecting dashboard elements
91+
- **JWT Authentication**: Secure embedding with proper tokens
92+
93+
### Usage
94+
95+
1. **Select User**: Choose between View or Build user
96+
2. **Enter Workbook ID**: Provide the ID of your Dashboard Builder workbook
97+
3. **Connect Plugin**: Click to establish the connection
98+
4. **Select Elements**: Use the gallery to choose dashboard elements
99+
5. **Add to Dashboard**: Send selected elements to the plugin
100+
101+
### Plugin Communication
102+
103+
The host application communicates with the plugin via `postMessage`:
104+
105+
**Messages sent to plugin**:
106+
- `CONFIGURE`: Initial plugin configuration
107+
- `ADD_ELEMENTS`: Selected elements to add to dashboard
108+
109+
**Messages received from plugin**:
110+
- `PLUGIN_READY`: Plugin has loaded and is ready
111+
- `ELEMENT_SELECTED`: User selected an element in the plugin
112+
- `DASHBOARD_UPDATED`: Dashboard configuration changed
113+
114+
## Configuration
115+
116+
### Environment Variables
117+
118+
| Variable | Description | Required |
119+
|----------|-------------|----------|
120+
| `ORG_SLUG` | Your Sigma organization identifier | Yes |
121+
| `CLIENT_ID` | Sigma API client ID | Yes |
122+
| `SECRET` | Sigma API client secret | Yes |
123+
| `ADMIN_EMAIL` | Admin user email for API calls | Yes |
124+
| `PLUGIN_NAME` | Name of your registered plugin | No |
125+
| `WORKBOOK_NAME` | Default workbook name | No |
126+
| `PORT` | Server port (default: 3000) | No |
127+
| `DEBUG` | Enable debug logging (default: true) | No |
128+
129+
### Plugin-Specific Settings
130+
131+
Additional configuration for plugin behavior:
132+
- `HIDE_FOLDER_NAVIGATION`: Hide folder navigation in embed
133+
- `HIDE_MENU`: Hide Sigma menu
134+
- `MENU_POSITION`: Menu position (top/bottom/none)
135+
- `THEME`: Plugin theme (light/dark)
136+
137+
## Extending to Other Plugins
138+
139+
To add support for additional plugins:
140+
141+
1. **Create Plugin Directory**:
142+
```bash
143+
mkdir public/your-plugin-name
144+
```
145+
146+
2. **Copy Template**:
147+
Use `dashboard-builder/index.html` as a starting point
148+
149+
3. **Customize Communication**:
150+
- Update message types in JavaScript
151+
- Modify UI elements for your plugin's needs
152+
- Add plugin-specific configuration
153+
154+
4. **Update Server Routes**:
155+
Add any plugin-specific API endpoints if needed
156+
157+
## Development
158+
159+
### Adding New Features
160+
161+
1. **Plugin Communication**: Extend the `postMessage` handlers
162+
2. **UI Elements**: Add new controls in the sidebar
163+
3. **API Endpoints**: Create additional routes in `routes/api/`
164+
4. **Configuration**: Add new environment variables
165+
166+
### Debugging
167+
168+
- Set `DEBUG=true` in `.env` for verbose logging
169+
- Use browser developer tools to inspect plugin messages
170+
- Check server logs for API errors
171+
172+
## Security Notes
173+
174+
- Never commit `.env` files with real credentials
175+
- JWT tokens are short-lived (5 minutes) for security
176+
- Validate all plugin communications
177+
- Use HTTPS in production environments
178+
179+
## Support
180+
181+
For issues with:
182+
- **Sigma Platform**: Contact Sigma support
183+
- **Plugin Development**: Refer to Sigma plugin documentation
184+
- **This Host Application**: Check the issues in this repository

0 commit comments

Comments
 (0)