🔄 Realtime Tables Plugin¶

🎯 Overview¶

The Realtime Tables Plugin (picnic/plugin-realtime-table) extends NocoBase 1.6.33 with WebSocket-based live table updates, enabling automatic data synchronization across multiple clients when database changes occur. This system-wide plugin enhances user experience across all modules by providing instant visual feedback for data modifications.

🔗 Backend Integration¶

📊 Related Modules¶

System-Wide Integration¶

This plugin integrates with all modules that display tabular data:

• Email Marketing: Live campaign status updates
• Multi-Engine Render Farm: Real-time job queue monitoring
• Analytics & Optimization: Live metric updates
• Core Operations: User activity, system logs, audit trails
• Planning & Strategy: Campaign planning updates
• Interaction & Collaboration: Client communications tracking

Core Systems¶

• Event Manager: WebSocket event distribution
• Central Database: Change detection and notifications
• API Gateway: WebSocket connection management

💡 Benefits to Backend Modules¶

For All Data-Driven Modules¶

• Instant Updates: No manual refresh required
• Multi-client Sync: All users see changes simultaneously
• Reduced Server Load: WebSocket vs polling efficiency
• Better UX: Real-time collaboration experience

For Render Farm¶

• Job Status Tracking: Live queue position updates
• Worker Activity: Real-time worker status changes
• Progress Monitoring: Instant completion notifications

For Email Marketing¶

• Campaign Monitoring: Live send statistics
• Agent Activity: Real-time virtual agent updates
• Contact Changes: Instant list modifications

✨ Key Features¶

🔧 Core Functionality¶

• ✅ Automatic Updates: Tables refresh on create/update/delete
• ✅ Native WebSocket: Uses NocoBase WebSocket infrastructure
• ✅ Visual Notifications: Toast messages for changes
• ✅ Status Indicator: Live connection status display
• ✅ Selective Subscription: Per-collection opt-in
• ✅ Auto-reconnection: Automatic WebSocket recovery
• ✅ Custom Filters: Configurable update filtering
• ✅ Custom Hook: React hook for advanced usage

🎨 Status Indicator¶

The compact status indicator shows connection state: - 🟢 Green (Active): WebSocket connected + subscribed - 🟡 Yellow (Not Subscribed): Connected but not subscribed - ⚫ Gray (Disconnected): WebSocket offline

Tooltip Information: - Connection status - Collection name - Update count - Last action performed

📊 Update Notifications¶

Visual feedback for changes: - Create: "New record added" - Update: "Record updated" - Delete: "Record deleted" - Customizable duration and placement

🛠️ Technical Architecture¶

🏗️ Component Structure¶

Realtime Tables Plugin
├── RealtimeProvider (Context)
│   ├── WebSocket Connection
│   ├── Subscription Manager
│   ├── Event Listener
│   └── State Management
├── RealtimeTableBlock (Component)
│   ├── Data Fetcher
│   ├── Update Handler
│   └── Notification Manager
├── RealtimeStatusIndicator (Component)
│   ├── Connection Status Badge
│   ├── Tooltip Info Display
│   └── Visual State Indicator
└── useRealtimeData (Hook)
    ├── Subscribe/Unsubscribe
    ├── Change Callbacks
    └── Filter Logic

🔧 Technologies Used¶

• WebSocket API: Native NocoBase WebSocket integration
• React Context: Global state management
• React Hooks: useContext, useEffect, useState
• Ant Design v5: Badge, Tooltip, notification components
• NocoBase Framework: Block system, schema settings

📡 WebSocket Events¶

// Client → Server
'realtime:subscribe'    // Subscribe to collection
'realtime:unsubscribe'  // Unsubscribe from collection

// Server → Client
'realtime:dataChange'   // Data modification notification
{
  collection: string,
  action: 'create' | 'update' | 'destroy',
  timestamp: string,
  record: object
}

📦 Installation & Setup¶

1️⃣ Installation¶

# Enable from NocoBase admin
# Settings → Plugin Manager → Realtime Table → Enable

2️⃣ Using Realtime Table Block¶

1. Add Block: Page Editor → Data Blocks → Realtime Table
2. Select Collection: Choose data source
3. Configure Columns: Set displayed fields
4. Add Status Indicator (optional):
5. Click action bar gear icon (⚙️)
6. Select "Realtime Indicator"
7. Indicator appears in action bar

3️⃣ Adding Indicator to Existing Tables¶

1. Open any table in edit mode
2. Click action bar configuration (⚙️)
3. Add "Realtime Indicator"
4. Customize appearance:
5. Button title
6. Icon
7. Background color
8. Drag to reposition in action bar

🔄 Data Flow¶

Update Propagation¶

Database Change → 
Database Trigger → 
Event Manager → 
WebSocket Server → 
All Subscribed Clients → 
Table Re-fetch → 
UI Update + Notification

Subscription Management¶

Component Mount → 
Check Collection → 
Subscribe to Updates → 
Listen for Events → 
Component Unmount → 
Unsubscribe

🎯 Use Cases by Module¶

🎬 Render Farm Monitoring¶

Scenario: Monitoring render job queue - Table: Render jobs collection - Updates: Job status changes, queue position - Benefit: Instant visibility of render progress

📧 Email Campaign Tracking¶

Scenario: Tracking email campaign sends - Table: Campaign messages collection - Updates: Send count, delivery status - Benefit: Real-time campaign performance

👥 Team Collaboration¶

Scenario: Multiple users editing content - Table: Content collection - Updates: Create, edit, delete by team members - Benefit: Instant conflict awareness

📊 Analytics Dashboard¶

Scenario: Live metrics display - Table: Analytics data collection - Updates: New data points, metric changes - Benefit: Always-current dashboards

🚀 Advanced Usage¶

🔧 Custom Hook¶

import { useRealtimeData } from '@picnic/plugin-realtime-table';

function CustomComponent() {
  const { 
    isSubscribed, 
    lastUpdate, 
    updateCount, 
    subscribe, 
    unsubscribe 
  } = useRealtimeData({
    collectionName: 'renderJobs',
    autoSubscribe: true,
    onDataChange: (data) => {
      console.log('Job updated:', data);
      // Custom logic here
    },
    filter: (data) => data.action === 'update' // Only updates
  });

  return (
    <div>
      <p>Status: {isSubscribed ? 'Live' : 'Offline'}</p>
      <p>Updates: {updateCount}</p>
    </div>
  );
}

📋 Configuration¶

// Exclude collections from realtime updates
const excludedCollections = [
  'auditLogs',    // High-frequency, low-priority
  'migrations',   // System-only
  'sessions'      // Sensitive data
];

🎨 Custom Notifications¶

// Customize notification appearance
notification.success({
  message: 'Custom Title',
  description: 'Custom message',
  duration: 5,
  placement: 'bottomRight',
  icon: <CustomIcon />
});

📚 Documentation References¶

Related Plugin Documentation¶

• Frontend Plugins Overview
• Email Inbox - Could benefit from realtime updates
• Render Submit Action - Monitor submitted jobs

Backend Module Documentation¶

• Event Manager - WebSocket infrastructure
• Email Marketing
• Multi-Engine Render Farm

Legacy Documentation¶

• Source: OLD_Docs/Front_End_Plugins/Real_Time_Tables/
• Technical Details: OLD_Docs/Front_End_Plugins/Real_Time_Tables/README_dev.md

🔗 Cross-References¶

This Plugin Enhances¶

• All table-based displays across the platform
• Render Queue Manager - Live queue monitoring
• Campaign Analytics - Live dashboards

Related Plugins¶

• All data display plugins benefit from realtime capabilities

📊 Quality Attributes¶

🎯 Performance¶

• Efficient WebSocket: Single connection for all subscriptions
• Selective Updates: Only subscribed collections trigger refreshes
• Debounced Refreshes: Prevents excessive re-renders
• Minimal Overhead: Lightweight event payload

🔒 Security¶

• Permission-based: Respects NocoBase ACL
• Secure WebSocket: Authenticated connections only
• Data Filtering: Server-side permission checks

✨ User Experience¶

• Instant Feedback: No perceived delay
• Visual Clarity: Clear status indicators
• Non-intrusive: Optional notifications
• Collaborative: Multi-user awareness

🐛 Troubleshooting¶

Table Not Updating¶

1. Check WebSocket connection (indicator should be green)
2. Verify collection not in excluded list
3. Check browser console for errors
4. Confirm server WebSocket enabled

Too Many Notifications¶

// Add filter to reduce noise
const { lastUpdate } = useRealtimeData({
  collectionName: 'myCollection',
  filter: (data) => {
    // Only show creates and deletes
    return data.action === 'create' || data.action === 'destroy';
  }
});

Performance Issues¶

• Limit displayed records per page
• Use filters to reduce data volume
• Consider debouncing custom callbacks
• Disable notifications for high-frequency collections