## 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