Skip to main content

​
Widget

A widget visualizes a single Indicator inside a Dashboard. Widgets support unified filters (sites, years, statuses), multiple visualization types, aggregation and display options, dataset mappings, and optional targets overlay.

​
Types

  • line_chart: multi-series time trends
  • bar_chart: categorical or time-based comparisons (default/stacked/percent)
  • pie_chart: proportional breakdowns
  • value: single KPI number
  • periodic_values: calendar/periodic summaries
  • table: hierarchical indicator breakdown table

​
Data Shape

// apps/azalt/src/server/db/types/dashboard.ts (simplified)
type DashboardWidgetType =
  | "line_chart" | "bar_chart" | "pie_chart" | "value" | "table" | "periodic_values";

interface DashboardFilter { siteIds?: string[]; startYear?: number; endYear?: number; statuses?: ("APPROVED"|"COMPLETED"|"REJECTED")[] }

interface DashboardWidgetSettings {
  indicatorDatasetMappings?: Record<string, {
    useDatasetValue: boolean;
    datasetId?: string;
    name?: string;
    field?: string;
  }> | null;
  aggregator?: "sum" | "avg" | "ratio";
  period?: "MONTHLY" | "QUARTERLY" | "YEARLY" | "TIMESTAMP";
  displayMode?: "sites" | "aggregated" | "groups";
  chartSettings?: "default" | "stacked" | "percent"; // bar charts
  showNumbers?: boolean;
  showIndicatorName?: boolean;
  angle?: number;              // pie charts
  siteGroups?: Array<{ id: string; name: string; siteIds: string[] }>;
  decimalPlaces: number;
  selectedTargetEntries?: string[];
  showTargets?: boolean;
}

interface DashboardWidget {
  id: string; dashboardId: string; indicatorId: string; name: string;
  type: DashboardWidgetType; x: number; y: number; w: number; h: number;
  settings: DashboardWidgetSettings; filter: DashboardFilter | null;
}

​
Filters & Precedence

  • Per-widget filter can specify siteIds, startYear, endYear, statuses.
  • If omitted, the Dashboard globalFilter applies.
  • Statuses fallback to organization defaults, else APPROVED.
  • Public dashboards accept per-widget temporary overrides (not saved) when using the public API.

​
Settings

  • Aggregation: sum, avg, or ratio
  • Period: MONTHLY, QUARTERLY, YEARLY (timestamp normalized to monthly for charts)
  • Display mode: sites (per-site series), aggregated (single series), groups (custom site groups)
  • Bar chart: default, stacked, percent
  • Formatting: decimalPlaces, showNumbers, showIndicatorName, angle (pie)
  • Dataset mappings: select dataset/field per indicator input; UI surfaces mapping issues (missing field/no data per year)
  • Targets: show target lines and select target entries where available
  • Contribution shares: enable per-site/group shares on line/bar/pie widgets (when display mode is sites or groups)
Contribution Shares
  • Toggle Show contribution shares to replace raw KPI values with the contribution payload that includes each site/group’s share. This is available for line/bar/pie widgets whenever the display mode is sites or groups; the option is disabled in aggregated mode because contributions would always read 100%.
  • Shares are computed at the same period you pick in the widget (MONTHLY, QUARTERLY, or YEARLY) and honor the selected aggregator (sum, avg, ratio). The backend aggregates contribution basis totals so the shares always sum to ~100% for the bucket.
  • Use the Contribution scope selector to decide the denominator:
    • Organization – ignores the widget’s site filter and reflects the indicator’s true global share (useful for allocating costs across sites even if the widget is filtered).
    • Visible data – limits the denominator to the currently visible site set (respecting widget/global filters).
  • KPI expressions can still reference SITE_SHARE, GROUP_SHARE, or GLOBAL_SHARE operators directly. The widget-level toggle simply controls how charts render the contribution data returned by widgets.getData.

​
Data & API

Internal (app): dashboardWidgets.getData returns computed values for the widget’s indicator, respecting merged filters and settings. Public: dashboards.getWithData returns a combined payload for all widgets (dashboard, widgets, datasets, indicators, widgetData). Public view can pass per-widget viewOptions (e.g., type) and filter overrides.

​
Security & Permissions

  • Read: Viewer or public link (for public dashboards)
  • Create/Update/Delete widgets: Manager or higher

​
Typical Operations

  • Add a widget: choose indicator, type, and layout (x,y,w,h)
  • Adjust settings: period, aggregation, display mode, decimals
  • Apply a per-widget filter to override dashboard defaults
  • Map datasets for indicator inputs; resolve mapping issues
  • Remove or move a widget via drag-and-drop
  • Dashboard — container and global filter
  • Indicator — the metric a widget visualizes
  • Dataset — coefficients and reference values for indicator calculations
  • Average: Mean values across sites or time periods
  • Ratio: Calculate ratios and percentages
  • Weighted Average: Account for site size or other factors
Filtering and Grouping:
  • Override Dashboard Filters: Widget-specific site/year ranges
  • Custom Site Groups: Organize sites beyond your organizational hierarchy
  • Tag-Based Filtering: Filter by site tags or characteristics
Dataset Mappings: Connect indicators to specific emission factors or benchmarks
  • Reference specific dataset versions
  • Compare performance against industry standards
  • Show methodology and data sources

​
Real-World Widget Examples

Carbon Footprint Line Chart:
  • Data Source: Total Emissions indicator
  • Period: Monthly aggregation
  • Display: 12-month trend line
  • Sites: All manufacturing facilities
  • Visual: Line chart with target line overlay
Energy Source Pie Chart:
  • Data Source: Energy consumption form data
  • Breakdown: By energy source type
  • Display: Percentage breakdown with values
  • Sites: Corporate headquarters only
  • Visual: Donut chart with legend
Facilities Comparison Bar Chart:
  • Data Source: Emissions intensity indicator
  • Period: Annual data
  • Display: Horizontal bars ranked by performance
  • Sites: Top 10 facilities by emissions
  • Visual: Color-coded performance bands
KPI Value Widget:
  • Data Source: Total cost savings indicator
  • Period: Year-to-date
  • Display: Large number with trend arrow
  • Sites: All sites aggregated
  • Visual: Green/red color coding based on target
Monthly Performance Table:
  • Data Source: Multiple indicators (energy, emissions, waste)
  • Period: Monthly breakdown
  • Display: Tabular format with all metrics
  • Sites: Regional breakdown
  • Visual: Conditional formatting for target achievement

​
Widget Interaction Features

Drill-Down Capabilities: Click on data points to see detailed breakdowns Export Options: Download widget data or images Real-Time Updates: Automatic refresh when underlying data changes Responsive Design: Adapt to different screen sizes and orientations

​
Site Grouping

Create custom groups beyond your organizational hierarchy: Manufacturing Sites: All production facilities regardless of geographic location High Energy Users: Sites with consumption above certain thresholds Pilot Program Participants: Sites participating in specific initiatives Retail Locations: All customer-facing facilities Office Buildings: All administrative locations

​
Performance Optimization

Data Caching: Frequently accessed data is cached for faster loading Lazy Loading: Complex visualizations load progressively Smart Refresh: Only update when underlying data actually changes Pagination: Handle large datasets efficiently in table widgets

​
Configuration Best Practices

Choose Appropriate Visualization Types:
  • Use line charts for trends over time
  • Use bar charts for comparisons between entities
  • Use pie charts for proportional data (limit to 5-7 categories)
  • Use value widgets for key performance indicators
Optimize for Your Audience:
  • Executive dashboards: Focus on high-level KPIs and trends
  • Operational dashboards: Show detailed breakdowns and actionable data
  • External stakeholder dashboards: Emphasize transparency and compliance
Maintain Consistency:
  • Use consistent color schemes across related widgets
  • Apply similar time periods for meaningful comparisons
  • Maintain consistent decimal precision for related metrics

​
Operational Benefits

Focused Analysis: Each widget addresses a specific question or metric Flexible Display: Choose the best visualization for each type of data Interactive Exploration: Drill down from high-level views to detailed data Real-Time Monitoring: Track performance as data is collected and calculated Stakeholder Communication: Professional visualizations for different audiences