Custom Data Sources

Alpha Insights allows you to extend the reporting system with custom data sources that integrate seamlessly with the React dashboard. This powerful feature lets you add your own metrics, charts, and data tables to reports using the same infrastructure as built-in data sources like orders, products, and expenses.

Overview

Custom data sources allow you to:

• Fetch data from custom database tables, external APIs, or third-party services
• Display custom metrics in metric cards and metric lists
• Create time-series charts from your custom data
• Build categorized charts (pie, doughnut, bar) from grouped data
• Display custom data in data table widgets
• Leverage automatic date range alignment and filtering
• Access the full data warehouse API for cross-entity data access

How It Works

The custom data source system uses a WordPress filter-based registration pattern. You create a PHP class that extends WPD_Alpha_Insights_Data_Source_Base, implement two methods, and instantiate the class. The plugin automatically:

• Registers your data source with the system
• Makes your metrics available in widget selectors
• Fetches your data only when needed (lazy loading)
• Merges your data mappings into the React frontend
• Handles all date range alignment automatically

Quick Start

The simplest implementation requires only three steps:

1. Set the $entity_name property (a unique identifier)
2. Implement fetch_data() to return your data
3. Implement get_data_mapping() to define how React displays your data
4. Instantiate your class to register it

All registration boilerplate is handled automatically by the base class.

File Location

Place your custom data source classes in one of these locations:

• Plugin extensions folder: wp-content/plugins/wp-davies-alpha-insights/includes/reports/extensions/ (auto-loaded)
• Theme folder: Your active theme’s functions.php or a separate file included from functions.php
• Custom plugin: Your own plugin’s PHP files

Classes in the extensions folder are automatically loaded. For other locations, ensure your file is included (e.g., via require_once in functions.php).

Data Structure

Your custom data source must return data in the same structure as the data warehouse. All keys are optional, but must match the format exactly if provided:

array(
    'totals'              => array(
        'metric_key' => 123.45,
        // Aggregated totals/metrics
    ),
    'categorized_data'    => array(
        'category_key' => array(
            'label' => 'Category Name',
            'metric_key' => 100,
            // Additional metrics...
        ),
        // Data grouped by categories for pie/bar charts
    ),
    'data_table'          => array(
        'table_key' => array(
            array(
                'column1' => 'value1',
                'column2' => 'value2',
                // Table rows...
            ),
        ),
        // Tabular data for data table widgets
    ),
    'data_by_date'        => array(
        'metric_key' => array(
            '2024-01-01' => 50,
            '2024-01-02' => 75,
            // Time-series data keyed by date
        ),
    ),
    'total_db_records'    => 100,    // Number of records fetched
    'execution_time'      => 0.25    // Execution time in seconds
)

Related Documentation

• Creating a Custom Data Source – Step-by-step guide
• The fetch_data() Method – Detailed reference
• The get_data_mapping() Method – Detailed reference
• Data Warehouse API Reference – Available helper methods
• Examples – Real-world implementation examples