charts

A Saltcorn plugin that renders interactive charts using Apache ECharts.

Chart types

| Type | Description | |------|-------------| | Line | Line chart with optional smooth curves. Supports single series, multiple series, or group-by-field. | | Area | Filled area chart. Same options as line. | | Scatter | Scatter plot. Supports single or multiple series. | | Bar | Vertical or horizontal bar chart. Supports multiple outcome fields, stacking, and axis title/limits. | | Pie | Pie or donut chart. Label position: inside, outside (rich label), or legend. | | Histogram | Histogram using ECharts statistical transforms. | | Funnel | Funnel chart with descending sort and percentage labels. | | Gauge | Gauge chart in arc or pointer style. Supports single value, multiple named values, or group-by-field. | | Heatmap | 2D heatmap with a continuous or stepped color scale. |

Configuration options

Common options

| Option | Description | |--------|-------------| | Plot title | Optional title rendered above the chart. | | Row inclusion formula | JavaScript expression to filter rows (e.g. status === "active"). In scope: all table fields plus user, year, month, day, today(). | | Show missing values | Include rows where the factor field is null/empty. | | Label for missing values | Display label used for null/empty factor values when "Show missing values" is on. | | Margins | Left / right / top / bottom margins in pixels. |

Line / Area / Scatter

| Option | Description | |--------|-------------| | Plot series | Single series, multiple series (pick Y fields), or group by a field. | | X field | Field for the X axis. | | Y field | Field for the Y axis (single / group-by mode). | | Smooth line | Enable curve smoothing (line and area only). | | Show legend | Show series legend. |

Bar

| Option | Description | |--------|-------------| | Factor field | Categorical field whose distinct values become the bars. | | Outcomes | One or more numeric fields (or "Row count") to aggregate. Each becomes a series. | | Statistic | Aggregation: Count, Avg, Sum, Max, or Min. | | Stack series | Stack outcome series on top of each other. | | Orientation | Vertical (default) or horizontal. | | Value axis title | Label on the value axis. | | Lower / Upper value limit | Clamp the value axis range. | | Show legend | Show series legend. |

Pie

| Option | Description | |--------|-------------| | Factor field | Categorical field whose distinct values become slices. | | Outcome field | Numeric field (or "Row count") to aggregate per slice. | | Statistic | Aggregation: Count, Avg, Sum, Max, or Min. | | Donut | Render as a donut. | | Ring width (%) | Thickness of the donut ring (1–100). | | Label position | Inside, outside (rich callout labels), or legend. |

Histogram

| Option | Description | |--------|-------------| | Data field | Numeric field to compute the histogram over. |

Funnel

| Option | Description | |--------|-------------| | Factor field | Categorical field whose distinct values become funnel stages. | | Outcome field | Numeric field (or "Row count") to aggregate per stage. | | Statistic | Aggregation: Count, Avg, Sum, Max, or Min. |

Gauge

| Option | Description | |--------|-------------| | Outcome field | Numeric field (or "Row count") to aggregate. | | Statistic | Aggregation: Count, Avg, Sum, Max, or Min. | | Min / Max value | Value range for the gauge arc. Max defaults to automatic. | | Gauge style | Arcs (concentric progress rings) or Pointer (classic needle). | | Gauge type | Single value, multiple named values (FieldRepeat), or group-by-field. | | Group field | Field whose distinct values each get their own gauge (group-by mode). | | Gauge label | Display name for the single-value gauge. |

Heatmap

| Option | Description | |--------|-------------| | X axis field | Categorical or FK field for the X axis. | | Y axis field | Categorical or FK field for the Y axis. | | Value field | Numeric field whose value determines cell color. | | Color scale min | Minimum value for the color scale (defaults to 0). | | Color scale max | Maximum value for the color scale (defaults to automatic). | | Color scale type | Gradient (smooth continuous transition) or Steps (discrete equal-width bands). |

State / filtering integration

When a Factor field is configured on a bar or pie chart, clicking a bar segment or pie slice calls set_state_field with the factor value. Clicking the same item again calls unset_state_field to deselect. This integrates with Saltcorn's PJAX state so that other views on the same page can react to the selection.

The chart itself always shows all data — the factor field is excluded from its own WHERE clause so the full dataset is visible. The selected value is only used for highlighting (opacity dimming on bars, slice offset on pie).

For foreign-key factor fields, set_state_field is called with the raw FK integer ID (not the display label), so other views that filter by the same FK field receive the correct value.

Foreign key fields

Fields that reference another table via a foreign key are resolved to their summary field automatically:

• Heatmap X/Y axis: resolved via a JOIN in getJoinedRows.
• Bar / Pie / Funnel factor field: resolved via a two-step lookup — aggregationQuery groups by raw FK ID, then the reference table is queried to build an ID → label map.

Technical notes

• Charts are rendered client-side using the bundled echarts.min.js and ecStat.min.js in public/.
• When the underlying table supports aggregationQuery (normal tables, not external), bar/pie/funnel/gauge use it for efficient DB-level aggregation. Other plot types always use getJoinedRows.
• Zero values in heatmap cells are displayed as "-" and rendered in dark gray (via ECharts outOfRange) so they do not skew the color scale.