0
# Superset Handlebars Chart Plugin
1

2
Superset Chart plugin that enables dynamic data visualization through Handlebars template rendering. It allows users to create custom chart visualizations by writing Handlebars templates that process and display query data, offering complete flexibility in how data is presented within Superset dashboards.
3

4
## Package Information
5

6
- **Package Name**: @superset-ui/plugin-chart-handlebars
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @superset-ui/plugin-chart-handlebars`
10

11
## Core Imports
12

13
```typescript
14
import { default as HandlebarsChartPlugin } from '@superset-ui/plugin-chart-handlebars';
15
```
16

17
For CommonJS:
18

19
```javascript
20
const { default: HandlebarsChartPlugin } = require('@superset-ui/plugin-chart-handlebars');
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { default as HandlebarsChartPlugin } from '@superset-ui/plugin-chart-handlebars';
27

28
// Register the plugin with Superset
29
new HandlebarsChartPlugin().configure({ key: 'handlebars' }).register();
30
```
31

32
Use with SuperChart:
33

34
```typescript
35
<SuperChart
36
  chartType="handlebars"
37
  width={600}
38
  height={400}
39
  formData={{
40
    handlebarsTemplate: '<h1>{{data.[0].name}}</h1><p>Value: {{data.[0].value}}</p>',
41
    styleTemplate: 'h1 { color: blue; }'
42
  }}
43
  queriesData={[{
44
    data: [{ name: 'Example', value: 42 }],
45
  }]}
46
/>
47
```
48

49
## Architecture
50

51
The Handlebars Chart Plugin extends Superset's ChartPlugin system to provide:
52

53
- **Template Processing**: Compiles and renders Handlebars templates with data
54
- **Built-in Helpers**: Includes custom helpers for date formatting and JSON serialization
55
- **Error Handling**: Provides user-friendly error display for template compilation issues
56
- **Style Integration**: Supports custom CSS styling alongside templates
57
- **Control Panel**: Integrates with Superset's control system for template configuration
58

59
## Capabilities
60

61
### Plugin Registration
62

63
Main plugin class that registers the Handlebars chart with Superset's chart system.
64

65
```typescript { .api }
66
export default class HandlebarsChartPlugin extends ChartPlugin {
67
  constructor();
68
}
69
```
70

71
**Usage:**
72

73
```typescript
74
import { default as HandlebarsChartPlugin } from '@superset-ui/plugin-chart-handlebars';
75

76
// Create and configure the plugin
77
const plugin = new HandlebarsChartPlugin();
78
plugin.configure({ key: 'handlebars' });
79
plugin.register();
80
```
81

82
## Template Configuration
83

84
The plugin accepts configuration through the `formData` object passed to SuperChart:
85

86
### Required FormData Properties
87

88
```typescript { .api }
89
interface HandlebarsFormData {
90
  // Core template configuration
91
  handlebarsTemplate?: string;  // The Handlebars template string
92
  styleTemplate?: string;       // CSS styles to apply
93
  
94
  // Standard Superset chart properties
95
  width: number;               // Chart width in pixels
96
  height: number;              // Chart height in pixels
97
  
98
  // Data configuration (inherited from QueryFormData)
99
  metrics?: QueryFormMetric[] | null;
100
  groupby?: QueryFormMetric[] | null;
101
  all_columns?: QueryFormMetric[] | null;
102
  order_desc?: boolean;
103
  page_length?: string | number | null;
104
  // ... other standard Superset form data properties
105
}
106
```
107

108
## Built-in Handlebars Helpers
109

110
The plugin automatically registers several Handlebars helpers for enhanced template functionality:
111

112
### Date Formatting Helper
113

114
Formats dates using moment.js formatting strings.
115

116
```typescript { .api }
117
// Usage: {{dateFormat date_value format="YYYY-MM-DD"}}
118
Handlebars.registerHelper('dateFormat', function (context: any, block: any): string);
119
```
120

121
**Template Usage:**
122

123
```handlebars
124
<p>Created: {{dateFormat created_date format="YYYY-MM-DD"}}</p>
125
<p>Month: {{dateFormat updated_date format="MMMM YYYY"}}</p>
126
<p>Time: {{dateFormat timestamp format="HH:mm:ss"}}</p>
127
```
128

129
### JSON Stringify Helper
130

131
Converts objects to JSON strings for debugging or data display.
132

133
```typescript { .api }
134
// Usage: {{stringify object}}
135
Handlebars.registerHelper('stringify', function (obj: any, obj2: any): string);
136
```
137

138
**Template Usage:**
139

140
```handlebars
141
<pre>{{stringify data}}</pre>
142
<div data-config="{{stringify config}}">Content</div>
143
```
144

145
### External Helper Library
146

147
The plugin automatically registers helpers from the `just-handlebars-helpers` library, providing additional functionality for arrays, strings, numbers, and conditionals.
148

149
**Available Helper Categories:**
150
- Array helpers (each, map, filter, etc.)
151
- String helpers (capitalize, truncate, etc.)
152
- Math helpers (add, subtract, multiply, etc.)
153
- Comparison helpers (eq, gt, lt, etc.)
154
- Conditional helpers (if, unless, etc.)
155

156
## Usage Examples
157

158
### Basic Data Display
159

160
```handlebars
161
<div class="data-summary">
162
  <h2>Query Results</h2>
163
  <ul>
164
  {{#each data}}
165
    <li><strong>{{this.name}}:</strong> {{this.value}}</li>
166
  {{/each}}
167
  </ul>
168
</div>
169
```
170

171
### Chart with Custom Styling
172

173
**Handlebars Template:**
174
```handlebars
175
<div class="custom-chart">
176
  <h1 class="chart-title">Sales Dashboard</h1>
177
  {{#each data}}
178
    <div class="data-row">
179
      <span class="label">{{this.category}}</span>
180
      <span class="value">${{this.amount}}</span>
181
      <span class="date">{{dateFormat this.date format="MMM DD"}}</span>
182
    </div>
183
  {{/each}}
184
  <div class="total">
185
    Total Records: {{data.length}}
186
  </div>
187
</div>
188
```
189

190
**Style Template:**
191
```css
192
.custom-chart {
193
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
194
  padding: 20px;
195
  background: #f8f9fa;
196
  border-radius: 8px;
197
}
198

199
.chart-title {
200
  color: #2c3e50;
201
  font-size: 24px;
202
  margin-bottom: 20px;
203
  text-align: center;
204
}
205

206
.data-row {
207
  display: flex;
208
  justify-content: space-between;
209
  padding: 10px;
210
  margin: 5px 0;
211
  background: white;
212
  border-radius: 4px;
213
  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
214
}
215

216
.label { font-weight: 600; }
217
.value { color: #27ae60; font-weight: bold; }
218
.date { color: #7f8c8d; font-size: 0.9em; }
219
.total { margin-top: 20px; font-weight: bold; text-align: center; }
220
```
221

222
### Advanced Template with Conditional Logic
223

224
```handlebars
225
<div class="report">
226
  <h2>Sales Report - {{dateFormat report_date format="MMMM YYYY"}}</h2>
227
  
228
  {{#if data}}
229
    {{#each data}}
230
      <div class="sale-record {{#if (gt this.amount 1000)}}high-value{{/if}}">
231
        <h3>{{this.product_name}}</h3>
232
        <div class="details">
233
          <p><strong>Amount:</strong> ${{this.amount}}</p>
234
          <p><strong>Date:</strong> {{dateFormat this.sale_date format="YYYY-MM-DD"}}</p>
235
          
236
          {{#if this.metadata}}
237
            <details>
238
              <summary>Additional Information</summary>
239
              <pre>{{stringify this.metadata}}</pre>
240
            </details>
241
          {{/if}}
242
        </div>
243
      </div>
244
    {{/each}}
245
  {{else}}
246
    <p class="no-data">No sales data available for this period.</p>
247
  {{/if}}
248
</div>
249
```
250

251
## Error Handling
252

253
The plugin provides comprehensive error handling for template issues:
254

255
- **Template Compilation Errors**: Displayed when Handlebars cannot parse the template
256
- **Runtime Errors**: Shown when template execution fails (missing data, helper errors, etc.)
257
- **Data Errors**: Handled gracefully when query data is malformed or missing
258

259
Errors are displayed in a formatted pre-element with clear error messages to help with debugging.
260

261
## Integration with Superset
262

263
### Plugin Registration
264

265
```typescript
266
import { default as HandlebarsChartPlugin } from '@superset-ui/plugin-chart-handlebars';
267

268
// Register with a specific key
269
new HandlebarsChartPlugin().configure({ key: 'handlebars' }).register();
270

271
// The plugin will then be available as chartType="handlebars" in SuperChart
272
```
273

274
### Control Panel Integration
275

276
The plugin integrates with Superset's control panel system to provide:
277
- Template editor with syntax highlighting
278
- Style editor for CSS customization
279
- Standard Superset data controls (metrics, grouping, filtering)
280
- Query configuration options
281

282
### Data Flow
283

284
1. **Query Execution**: Superset executes the configured query
285
2. **Data Processing**: Query results are passed to the plugin via `queriesData`
286
3. **Template Compilation**: Handlebars compiles the user-provided template
287
4. **Rendering**: Template is rendered with query data and helpers
288
5. **Style Application**: Custom CSS is applied to the rendered output
289
6. **Display**: Final HTML is displayed in the dashboard
290

291
## Dependencies
292

293
The plugin requires the following peer dependencies to be available in the host application:
294

295
- **@superset-ui/chart-controls**: Chart control components
296
- **@superset-ui/core**: Core Superset UI utilities  
297
- **react** (^16.13.1): React framework
298
- **react-dom** (^16.13.1): React DOM rendering
299
- **ace-builds** (^1.4.14): Code editor component
300
- **react-ace** (^10.1.0): React wrapper for Ace editor
301
- **lodash** (^4.17.11): Utility functions
302
- **moment** (^2.26.0): Date manipulation library
303

304
Direct dependencies (automatically installed):
305
- **handlebars** (^4.7.7): Template engine
306
- **just-handlebars-helpers** (^1.0.19): Additional template helpers