The get_data_mapping() Method

The get_data_mapping() method defines how React displays and formats your custom data. This method returns a PHP array that is JSON encoded and passed to React, where it’s merged into the main mapping objects.

This method is optional. The base class WPDAI_Custom_Data_Source_Base provides a default implementation that returns an empty array. Override it only when you need to expose metrics, charts, or tables to the React UI (e.g. for metric cards, chart selectors, data table columns). If you do not override it, your entity will still be registered and fetch_data() will run, but the frontend will not have mapping metadata for your keys.

Method Signature

public function get_data_mapping()

Return Value

Returns an array with optional top-level keys. Each key corresponds to a data type in your fetch_data() return structure:

• totals – Maps metrics from fetch_data() ‘totals’ array
• data_by_date – Maps metrics from fetch_data() ‘data_by_date’ array
• categorized_data – Maps categories from fetch_data() ‘categorized_data’ array
• data_table – Maps tables from fetch_data() ‘data_table’ array

Important: The registry automatically keys this by your entity name (from get_entity_names()), so you return the mapping data directly – NOT wrapped in another entity key.

totals Mapping

Maps metrics in your fetch_data() ‘totals’ array. Structure:

'totals' => array(
    'label' => 'Display Name',        // Label shown in metric selectors
    'icon' => 'analytics',            // Material Icons name
    'totals' => array(                // Metric definitions
        'metric_key' => array(        // MUST match key in fetch_data() 'totals'
            'label' => 'Metric Label',
            'type' => 'currency',     // Data type: currency, number, integer, percentage, text, date
            'format' => 'currency',   // Display format: currency, integer, decimal, percentage
            'description' => 'Help text for tooltips',
        ),
        // More metrics...
    ),
)

Required keys for each metric:

• label (string): Display name shown in UI
• type (string): Data type (currency, number, integer, percentage, text, date)
• format (string): Display format (currency, integer, decimal, percentage)
• description (string, optional): Help text/tooltip

Example:

'totals' => array(
    'label' => 'Inventory Tracking',
    'icon' => 'inventory_2',
    'totals' => array(
        'total_inventory_value' => array(
            'label' => 'Total Inventory Value',
            'type' => 'currency',
            'format' => 'currency',
            'description' => 'Total value of all inventory items',
        ),
        'total_items_count' => array(
            'label' => 'Total Items',
            'type' => 'number',
            'format' => 'integer',
            'description' => 'Total number of inventory items',
        ),
    ),
)

data_by_date Mapping

Maps metrics in your fetch_data() ‘data_by_date’ array. This is a flat structure – metrics are directly under the entity.

'data_by_date' => array(
    'metric_key' => array(            // MUST match key in fetch_data() 'data_by_date'
        'label' => 'Metric Over Time',
        'type' => 'currency',         // Data type
        'format' => 'currency',       // Display format
        'description' => 'Time series description',
        'chart_calculation' => 'sum', // Optional: sum, average, max, min
    ),
    // More metrics...
)

Required keys:

• label (string): Display name in chart legends
• type (string): Data type
• format (string): Display format
• description (string, optional): Help text
• chart_calculation (string, optional): Aggregation method – ‘sum’, ‘average’, ‘max’, ‘min’

Example:

'data_by_date' => array(
    'inventory_value_by_date' => array(
        'label' => 'Inventory Value Over Time',
        'type' => 'currency',
        'format' => 'currency',
        'description' => 'Daily inventory value',
        'chart_calculation' => 'sum',
    ),
    'items_sold_by_date' => array(
        'label' => 'Items Sold Over Time',
        'type' => 'integer',
        'format' => 'integer',
        'chart_calculation' => 'sum',
    ),
)

categorized_data Mapping

Maps categories in your fetch_data() ‘categorized_data’ array. Used for pie charts, doughnut charts, bar charts, and tables.

'categorized_data' => array(
    'category_key' => array(          // MUST match key in fetch_data() 'categorized_data'
        'label' => 'Category Display Name',
        'description' => 'Category description',
        'color' => '#138fdd',         // Default hex color for charts
        'icon' => 'category',         // Material Icons name
        'metric_fields' => array(     // Metrics available for each category
            array(
                'label' => 'Metric Label',
                'value' => 'metric_key',  // MUST match key in categorized_data[category]
                'type' => 'currency',
            ),
            // More metric fields...
        ),
    ),
    // More categories...
)

Required keys:

• label (string): Display name in widget selectors
• description (string, optional): Help text
• color (string, optional): Default hex color for charts (e.g., ‘#138fdd’)
• icon (string, optional): Material Icons name
• metric_fields (array): Array of metric field definitions

Metric field keys:

• label (string): Display name
• value (string): MUST match a key in your categorized_data[category] array
• type (string): Data type (currency, number, integer, percentage, text, date)

Example:

'categorized_data' => array(
    'inventory_by_location' => array(
        'label' => 'Inventory by Location',
        'description' => 'Inventory broken down by warehouse location',
        'color' => '#4caf50',
        'icon' => 'warehouse',
        'metric_fields' => array(
            array(
                'label' => 'Total Value',
                'value' => 'total_inventory_value',
                'type' => 'currency',
            ),
            array(
                'label' => 'Item Count',
                'value' => 'total_items_count',
                'type' => 'number',
            ),
        ),
    ),
)

data_table Mapping

Maps tables in your fetch_data() ‘data_table’ array. Defines the structure of table columns for data table widgets.

'data_table' => array(
    'table_key' => array(             // MUST match key in fetch_data() 'data_table'
        'label' => 'Table Display Name',
        'description' => 'Table description',
        'icon' => 'table_chart',      // Material Icons name
        'columns' => array(           // Column definitions
            'column_key' => array(
                'label' => 'Column Header',
                'type' => 'number',   // Data type
                'format' => 'integer', // Display format
            ),
            // More columns...
        ),
    ),
    // More tables...
)

Required keys:

• label (string): Display name in table selector
• description (string, optional): Help text
• icon (string, optional): Material Icons name
• columns (array): Column definitions (keys must match column keys in your table rows)

Column keys:

• label (string): Column header text
• type (string): Data type (currency, number, integer, percentage, text, date)
• format (string, optional): Display format (currency, integer, decimal, percentage)

Example:

'data_table' => array(
    'inventory_items' => array(
        'label' => 'Inventory Items',
        'description' => 'Detailed list of inventory items',
        'icon' => 'inventory_2',
        'columns' => array(
            'id' => array(
                'label' => 'ID',
                'type' => 'number',
                'format' => 'integer',
            ),
            'name' => array(
                'label' => 'Item Name',
                'type' => 'text',
            ),
            'quantity' => array(
                'label' => 'Quantity',
                'type' => 'number',
                'format' => 'integer',
            ),
            'value' => array(
                'label' => 'Value',
                'type' => 'currency',
                'format' => 'currency',
            ),
            'location' => array(
                'label' => 'Location',
                'type' => 'text',
            ),
        ),
    ),
)

Data Types and Formats

Type Options

• currency – Monetary values
• number – Numeric values (floats)
• integer – Whole numbers
• percentage – Percentage values (0-100)
• text – Text/string values
• date – Date values

Format Options

• currency – Format as currency with symbol
• integer – Display as whole number
• decimal – Display with decimal places
• percentage – Display with % symbol

Material Icons

Icons use Material Icons naming. Common examples:

• analytics – Analytics/statistics
• inventory_2 – Inventory
• category – Categories
• table_chart – Tables
• warehouse – Warehouse/storage
• shopping_cart – Shopping
• people – People/customers
• trending_up – Growth/trends

Browse all icons at: Google Material Icons

Key Matching Requirements

CRITICAL: Metric keys in your mapping MUST exactly match keys in your fetch_data() return array:

• totals: Keys in ‘totals’ > ‘totals’ array must match keys in fetch_data() ‘totals’ array
• data_by_date: Keys in ‘data_by_date’ array must match keys in fetch_data() ‘data_by_date’ array
• categorized_data: Category keys must match keys in fetch_data() ‘categorized_data’ array, and metric field ‘value’ keys must match keys in each category array
• data_table: Table keys must match keys in fetch_data() ‘data_table’ array, and column keys must match keys in table rows

Complete Example

public function get_data_mapping() {
    return array(
        'totals' => array(
            'label' => 'Inventory Tracking',
            'icon' => 'inventory_2',
            'totals' => array(
                'total_inventory_value' => array(
                    'label' => 'Total Inventory Value',
                    'type' => 'currency',
                    'format' => 'currency',
                    'description' => 'Total value of all inventory',
                ),
                'total_items_count' => array(
                    'label' => 'Total Items',
                    'type' => 'number',
                    'format' => 'integer',
                ),
            ),
        ),
        'data_by_date' => array(
            'inventory_value_by_date' => array(
                'label' => 'Inventory Value Over Time',
                'type' => 'currency',
                'format' => 'currency',
                'chart_calculation' => 'sum',
            ),
        ),
        'categorized_data' => array(
            'inventory_by_location' => array(
                'label' => 'Inventory by Location',
                'description' => 'Breakdown by warehouse',
                'color' => '#4caf50',
                'icon' => 'warehouse',
                'metric_fields' => array(
                    array(
                        'label' => 'Total Value',
                        'value' => 'total_inventory_value',
                        'type' => 'currency',
                    ),
                ),
            ),
        ),
        'data_table' => array(
            'inventory_items' => array(
                'label' => 'Inventory Items',
                'icon' => 'table_chart',
                'columns' => array(
                    'id' => array(
                        'label' => 'ID',
                        'type' => 'number',
                        'format' => 'integer',
                    ),
                    'name' => array(
                        'label' => 'Name',
                        'type' => 'text',
                    ),
                    'value' => array(
                        'label' => 'Value',
                        'type' => 'currency',
                        'format' => 'currency',
                    ),
                ),
            ),
        ),
    );
}

Related Documentation

• The fetch_data() Method – Return data structure
• Creating a Custom Data Source – Step-by-step guide