or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-superset-ui--plugin-chart-handlebars

Superset Chart plugin that enables dynamic data visualization through Handlebars template rendering

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@superset-ui/plugin-chart-handlebars@0.18.x

To install, run

npx @tessl/cli install tessl/npm-superset-ui--plugin-chart-handlebars@0.18.0

index.mddocs/

Superset Handlebars Chart Plugin

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.

Package Information

  • Package Name: @superset-ui/plugin-chart-handlebars
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @superset-ui/plugin-chart-handlebars

Core Imports

import { default as HandlebarsChartPlugin } from '@superset-ui/plugin-chart-handlebars';

For CommonJS:

const { default: HandlebarsChartPlugin } = require('@superset-ui/plugin-chart-handlebars');

Basic Usage

import { default as HandlebarsChartPlugin } from '@superset-ui/plugin-chart-handlebars';

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

Use with SuperChart:

<SuperChart
  chartType="handlebars"
  width={600}
  height={400}
  formData={{
    handlebarsTemplate: '<h1>{{data.[0].name}}</h1><p>Value: {{data.[0].value}}</p>',
    styleTemplate: 'h1 { color: blue; }'
  }}
  queriesData={[{
    data: [{ name: 'Example', value: 42 }],
  }]}
/>

Architecture

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

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

Capabilities

Plugin Registration

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

export default class HandlebarsChartPlugin extends ChartPlugin {
  constructor();
}

Usage:

import { default as HandlebarsChartPlugin } from '@superset-ui/plugin-chart-handlebars';

// Create and configure the plugin
const plugin = new HandlebarsChartPlugin();
plugin.configure({ key: 'handlebars' });
plugin.register();

Template Configuration

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

Required FormData Properties

interface HandlebarsFormData {
  // Core template configuration
  handlebarsTemplate?: string;  // The Handlebars template string
  styleTemplate?: string;       // CSS styles to apply
  
  // Standard Superset chart properties
  width: number;               // Chart width in pixels
  height: number;              // Chart height in pixels
  
  // Data configuration (inherited from QueryFormData)
  metrics?: QueryFormMetric[] | null;
  groupby?: QueryFormMetric[] | null;
  all_columns?: QueryFormMetric[] | null;
  order_desc?: boolean;
  page_length?: string | number | null;
  // ... other standard Superset form data properties
}

Built-in Handlebars Helpers

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

Date Formatting Helper

Formats dates using moment.js formatting strings.

// Usage: {{dateFormat date_value format="YYYY-MM-DD"}}
Handlebars.registerHelper('dateFormat', function (context: any, block: any): string);

Template Usage:

<p>Created: {{dateFormat created_date format="YYYY-MM-DD"}}</p>
<p>Month: {{dateFormat updated_date format="MMMM YYYY"}}</p>
<p>Time: {{dateFormat timestamp format="HH:mm:ss"}}</p>

JSON Stringify Helper

Converts objects to JSON strings for debugging or data display.

// Usage: {{stringify object}}
Handlebars.registerHelper('stringify', function (obj: any, obj2: any): string);

Template Usage:

<pre>{{stringify data}}</pre>
<div data-config="{{stringify config}}">Content</div>

External Helper Library

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

Available Helper Categories:

  • Array helpers (each, map, filter, etc.)
  • String helpers (capitalize, truncate, etc.)
  • Math helpers (add, subtract, multiply, etc.)
  • Comparison helpers (eq, gt, lt, etc.)
  • Conditional helpers (if, unless, etc.)

Usage Examples

Basic Data Display

<div class="data-summary">
  <h2>Query Results</h2>
  <ul>
  {{#each data}}
    <li><strong>{{this.name}}:</strong> {{this.value}}</li>
  {{/each}}
  </ul>
</div>

Chart with Custom Styling

Handlebars Template:

<div class="custom-chart">
  <h1 class="chart-title">Sales Dashboard</h1>
  {{#each data}}
    <div class="data-row">
      <span class="label">{{this.category}}</span>
      <span class="value">${{this.amount}}</span>
      <span class="date">{{dateFormat this.date format="MMM DD"}}</span>
    </div>
  {{/each}}
  <div class="total">
    Total Records: {{data.length}}
  </div>
</div>

Style Template:

.custom-chart {
  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  padding: 20px;
  background: #f8f9fa;
  border-radius: 8px;
}

.chart-title {
  color: #2c3e50;
  font-size: 24px;
  margin-bottom: 20px;
  text-align: center;
}

.data-row {
  display: flex;
  justify-content: space-between;
  padding: 10px;
  margin: 5px 0;
  background: white;
  border-radius: 4px;
  box-shadow: 0 1px 3px rgba(0,0,0,0.1);
}

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

Advanced Template with Conditional Logic

<div class="report">
  <h2>Sales Report - {{dateFormat report_date format="MMMM YYYY"}}</h2>
  
  {{#if data}}
    {{#each data}}
      <div class="sale-record {{#if (gt this.amount 1000)}}high-value{{/if}}">
        <h3>{{this.product_name}}</h3>
        <div class="details">
          <p><strong>Amount:</strong> ${{this.amount}}</p>
          <p><strong>Date:</strong> {{dateFormat this.sale_date format="YYYY-MM-DD"}}</p>
          
          {{#if this.metadata}}
            <details>
              <summary>Additional Information</summary>
              <pre>{{stringify this.metadata}}</pre>
            </details>
          {{/if}}
        </div>
      </div>
    {{/each}}
  {{else}}
    <p class="no-data">No sales data available for this period.</p>
  {{/if}}
</div>

Error Handling

The plugin provides comprehensive error handling for template issues:

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

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

Integration with Superset

Plugin Registration

import { default as HandlebarsChartPlugin } from '@superset-ui/plugin-chart-handlebars';

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

// The plugin will then be available as chartType="handlebars" in SuperChart

Control Panel Integration

The plugin integrates with Superset's control panel system to provide:

  • Template editor with syntax highlighting
  • Style editor for CSS customization
  • Standard Superset data controls (metrics, grouping, filtering)
  • Query configuration options

Data Flow

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

Dependencies

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

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

Direct dependencies (automatically installed):

  • handlebars (^4.7.7): Template engine
  • just-handlebars-helpers (^1.0.19): Additional template helpers