WooNooW/DASHBOARD_API_INTEGRATION.md

🔌 Dashboard Analytics - API Integration Guide

Created: Nov 4, 2025 9:21 AM (GMT+7)

---

🎯 Overview

Dashboard now supports real data from API with a toggle to switch between real and dummy data for development/testing.

Default: Real data (dummy data toggle OFF)

---

📁 Files Created

1. Analytics API Module

File: /admin-spa/src/lib/analyticsApi.ts

Defines all analytics endpoints:

export const AnalyticsApi = {
  overview: (params?: AnalyticsParams) => api.get('/woonoow/v1/analytics/overview', params),
  revenue: (params?: AnalyticsParams) => api.get('/woonoow/v1/analytics/revenue', params),
  orders: (params?: AnalyticsParams) => api.get('/woonoow/v1/analytics/orders', params),
  products: (params?: AnalyticsParams) => api.get('/woonoow/v1/analytics/products', params),
  customers: (params?: AnalyticsParams) => api.get('/woonoow/v1/analytics/customers', params),
  coupons: (params?: AnalyticsParams) => api.get('/woonoow/v1/analytics/coupons', params),
  taxes: (params?: AnalyticsParams) => api.get('/woonoow/v1/analytics/taxes', params),
};

2. Analytics Hooks

File: /admin-spa/src/hooks/useAnalytics.ts

React Query hooks for each endpoint:

// Generic hook
useAnalytics(endpoint, dummyData, additionalParams)

// Specific hooks
useRevenueAnalytics(dummyData, granularity?)
useOrdersAnalytics(dummyData)
useProductsAnalytics(dummyData)
useCustomersAnalytics(dummyData)
useCouponsAnalytics(dummyData)
useTaxesAnalytics(dummyData)
useOverviewAnalytics(dummyData)

---

🔄 How It Works

1. Context State

// DashboardContext.tsx
const [useDummyData, setUseDummyData] = useState(false); // Default: real data

2. Hook Logic

// useAnalytics.ts
const { data, isLoading, error } = useQuery({
  queryKey: ['analytics', endpoint, period, additionalParams],
  queryFn: async () => {
    const params = { period: period === 'all' ? undefined : period, ...additionalParams };
    return await AnalyticsApi[endpoint](params);
  },
  enabled: !useDummy, // Only fetch when NOT using dummy data
  staleTime: 5 * 60 * 1000, // 5 minutes
});

// Return dummy data if toggle is on, otherwise return API data
return {
  data: useDummy ? dummyData : (data || dummyData),
  isLoading: useDummy ? false : isLoading,
  error: useDummy ? null : error,
};

3. Component Usage

// Before (old way)
const { period, useDummy } = useDashboardPeriod();
const data = useDummy ? DUMMY_DATA : DUMMY_DATA; // Always dummy!

// After (new way)
const { period } = useDashboardPeriod();
const { data, isLoading, error } = useCustomersAnalytics(DUMMY_CUSTOMERS_DATA);

// Loading state
if (isLoading) return <LoadingSpinner />;

// Error state
if (error) return <ErrorMessage error={error} />;

// Use data normally

---

📊 API Endpoints Required

Backend PHP REST API Routes

All endpoints should be registered under /woonoow/v1/analytics/:

1. Overview - GET /woonoow/v1/analytics/overview

Query Params:

• period: '7', '14', '30', or omit for all-time
• start_date: ISO date (for custom range)
• end_date: ISO date (for custom range)

Response: Same structure as DUMMY_DATA in Dashboard/index.tsx

---

2. Revenue - GET /woonoow/v1/analytics/revenue

Query Params:

• period: '7', '14', '30', or omit for all-time
• granularity: 'day', 'week', 'month'

Response: Same structure as DUMMY_REVENUE_DATA

---

3. Orders - GET /woonoow/v1/analytics/orders

Query Params:

• period: '7', '14', '30', or omit for all-time

Response: Same structure as DUMMY_ORDERS_DATA

---

4. Products - GET /woonoow/v1/analytics/products

Query Params:

• period: '7', '14', '30', or omit for all-time

Response: Same structure as DUMMY_PRODUCTS_DATA

---

5. Customers - GET /woonoow/v1/analytics/customers

Query Params:

• period: '7', '14', '30', or omit for all-time

Response: Same structure as DUMMY_CUSTOMERS_DATA

---

6. Coupons - GET /woonoow/v1/analytics/coupons

Query Params:

• period: '7', '14', '30', or omit for all-time

Response: Same structure as DUMMY_COUPONS_DATA

---

7. Taxes - GET /woonoow/v1/analytics/taxes

Query Params:

• period: '7', '14', '30', or omit for all-time

Response: Same structure as DUMMY_TAXES_DATA

---

🔧 Backend Implementation Guide

Step 1: Register REST Routes

// includes/Admin/Analytics/AnalyticsController.php

namespace WooNooW\Admin\Analytics;

class AnalyticsController {
    public function register_routes() {
        register_rest_route('woonoow/v1', '/analytics/overview', [
            'methods' => 'GET',
            'callback' => [$this, 'get_overview'],
            'permission_callback' => [$this, 'check_permission'],
        ]);
        
        register_rest_route('woonoow/v1', '/analytics/revenue', [
            'methods' => 'GET',
            'callback' => [$this, 'get_revenue'],
            'permission_callback' => [$this, 'check_permission'],
        ]);
        
        // ... register other endpoints
    }
    
    public function check_permission() {
        return current_user_can('manage_woocommerce');
    }
    
    public function get_overview(\WP_REST_Request $request) {
        $period = $request->get_param('period');
        $start_date = $request->get_param('start_date');
        $end_date = $request->get_param('end_date');
        
        // Calculate date range
        $dates = $this->calculate_date_range($period, $start_date, $end_date);
        
        // Fetch data from WooCommerce
        $data = [
            'metrics' => $this->get_overview_metrics($dates),
            'salesChart' => $this->get_sales_chart($dates),
            'orderStatusDistribution' => $this->get_order_status_distribution($dates),
            'lowStock' => $this->get_low_stock_products(),
        ];
        
        return rest_ensure_response($data);
    }
    
    private function calculate_date_range($period, $start_date, $end_date) {
        if ($start_date && $end_date) {
            return ['start' => $start_date, 'end' => $end_date];
        }
        
        if (!$period) {
            // All time
            return ['start' => null, 'end' => null];
        }
        
        $days = intval($period);
        $end = current_time('Y-m-d');
        $start = date('Y-m-d', strtotime("-{$days} days"));
        
        return ['start' => $start, 'end' => $end];
    }
    
    // ... implement other methods
}

Step 2: Query WooCommerce Data

private function get_overview_metrics($dates) {
    global $wpdb;
    
    $where = $this->build_date_where_clause($dates);
    
    // Use HPOS tables
    $orders_table = $wpdb->prefix . 'wc_orders';
    
    $query = "
        SELECT 
            COUNT(*) as total_orders,
            SUM(total_amount) as total_revenue,
            AVG(total_amount) as avg_order_value
        FROM {$orders_table}
        WHERE status IN ('wc-completed', 'wc-processing')
        {$where}
    ";
    
    $results = $wpdb->get_row($query);
    
    // Calculate comparison with previous period
    $previous_metrics = $this->get_previous_period_metrics($dates);
    
    return [
        'revenue' => [
            'today' => floatval($results->total_revenue),
            'yesterday' => floatval($previous_metrics->total_revenue),
            'change' => $this->calculate_change_percent(
                $results->total_revenue,
                $previous_metrics->total_revenue
            ),
        ],
        // ... other metrics
    ];
}

---

🎨 Frontend Implementation

Example: Update Revenue.tsx

import { useRevenueAnalytics } from '@/hooks/useAnalytics';
import { DUMMY_REVENUE_DATA } from './data/dummyRevenue';

export default function RevenueAnalytics() {
  const { period } = useDashboardPeriod();
  const [granularity, setGranularity] = useState<'day' | 'week' | 'month'>('day');
  
  // Fetch real data or use dummy data
  const { data, isLoading, error } = useRevenueAnalytics(DUMMY_REVENUE_DATA, granularity);
  
  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage error={error} />;
  
  // Use data normally...
}

---

🔀 Toggle Behavior

When Dummy Data Toggle is OFF (default):

1. ✅ Fetches real data from API
2. ✅ Shows loading spinner while fetching
3. ✅ Shows error message if API fails
4. ✅ Caches data for 5 minutes (React Query)
5. ✅ Automatically refetches when period changes

When Dummy Data Toggle is ON:

1. ✅ Uses dummy data immediately (no API call)
2. ✅ No loading state
3. ✅ No error state
4. ✅ Perfect for development/testing

---

📋 Migration Checklist

Frontend (React):

• Create analyticsApi.ts with all endpoints
• Create useAnalytics.ts hooks
• Update DashboardContext default to false
• Update Customers.tsx as example
• Update Revenue.tsx
• Update Orders.tsx
• Update Products.tsx
• Update Coupons.tsx
• Update Taxes.tsx
• Update Dashboard/index.tsx (overview)

Backend (PHP):

• Create AnalyticsController.php
• Register REST routes
• Implement /analytics/overview
• Implement /analytics/revenue
• Implement /analytics/orders
• Implement /analytics/products
• Implement /analytics/customers
• Implement /analytics/coupons
• Implement /analytics/taxes
• Add permission checks
• Add data caching (transients)
• Add error handling

---

🚀 Benefits

1. Real-time Data: Dashboard shows actual store data
2. Development Friendly: Toggle to dummy data for testing
3. Performance: React Query caching reduces API calls
4. Error Handling: Graceful fallback to dummy data
5. Type Safety: TypeScript interfaces match API responses
6. Maintainable: Single source of truth for API endpoints

---

🔮 Future Enhancements

1. Custom Date Range: Add date picker for custom ranges
2. Export Data: Download analytics as CSV/PDF
3. Real-time Updates: WebSocket for live data
4. Comparison Mode: Compare multiple periods side-by-side
5. Scheduled Reports: Email reports automatically

---

Status: ✅ Frontend ready - Backend implementation needed!