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.

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_name()), 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