0
# Event System
1

2
Comprehensive event handling for user interactions, data changes, and table lifecycle events with support for custom event dispatch.
3

4
## Capabilities
5

6
### Event Subscription and Management
7

8
Core methods for subscribing to and managing table events.
9

10
```javascript { .api }
11
/**
12
 * Subscribe to table event
13
 * @param event - Event name to listen for
14
 * @param callback - Function to execute when event fires
15
 */
16
on(event: string, callback: Function): void;
17

18
/**
19
 * Unsubscribe from table event
20
 * @param event - Event name to stop listening to
21
 * @param callback - Specific callback to remove (optional, removes all if not provided)
22
 */
23
off(event: string, callback?: Function): void;
24

25
/**
26
 * Dispatch custom event
27
 * @param event - Event name to dispatch
28
 * @param args - Arguments to pass to event handlers
29
 */
30
dispatchEvent(event: string, ...args: any[]): void;
31
```
32

33
**Usage Examples:**
34

35
```javascript
36
// Basic event subscription
37
table.on("rowClick", function(e, row) {
38
  console.log("Row clicked:", row.getData());
39
});
40

41
// Multiple event handlers
42
table.on("cellEdited", handleCellEdit);
43
table.on("cellEdited", logCellChanges);
44
table.on("cellEdited", validateCellData);
45

46
// Remove specific handler
47
table.off("cellEdited", logCellChanges);
48

49
// Remove all handlers for event
50
table.off("rowClick");
51

52
// Dispatch custom event
53
table.dispatchEvent("customDataUpdate", { source: "api", count: 50 });
54
```
55

56
## Table Lifecycle Events
57

58
Events related to table construction, destruction, and state changes.
59

60
```javascript { .api }
61
interface LifecycleEvents {
62
  /** Fired before table construction begins */
63
  "tableBuilding": () => void;
64
  /** Fired after table construction completes */
65
  "tableBuilt": () => void;
66
  /** Fired after table is completely destroyed */
67
  "tableDestroyed": () => void;
68
  /** Fired when table is redrawn */
69
  "tableRedraw": (force: boolean) => void;
70
}
71
```
72

73
**Usage Examples:**
74

75
```javascript
76
table.on("tableBuilding", function() {
77
  console.log("Starting table construction...");
78
  showLoadingIndicator();
79
});
80

81
table.on("tableBuilt", function() {
82
  console.log("Table ready!");
83
  hideLoadingIndicator();
84
  initializeCustomFeatures();
85
});
86

87
table.on("tableDestroyed", function() {
88
  console.log("Table cleanup complete");
89
  clearCustomEventListeners();
90
});
91
```
92

93
## Data Events
94

95
Events triggered by data loading, changes, and manipulation operations.
96

97
```javascript { .api }
98
interface DataEvents {
99
  /** Fired before data loading begins */
100
  "dataLoading": (data: any) => void;
101
  /** Fired after data is loaded and processed */
102
  "dataLoaded": (data: any[]) => void;
103
  /** Fired when data changes occur */
104
  "dataChanged": (data: any[]) => void;
105
  /** Fired after data processing completes */
106
  "dataProcessed": () => void;
107
  /** Fired before data sorting */
108
  "dataSorting": (sorters: any[]) => void;
109
  /** Fired after data is sorted */
110
  "dataSorted": (sorters: any[], rows: RowComponent[]) => void;
111
  /** Fired before data filtering */
112
  "dataFiltering": (filters: any[]) => void;
113
  /** Fired after data is filtered */
114
  "dataFiltered": (filters: any[], rows: RowComponent[]) => void;
115
}
116
```
117

118
**Usage Examples:**
119

120
```javascript
121
// Data loading events
122
table.on("dataLoading", function(data) {
123
  console.log("Loading data...", data);
124
  showProgressBar();
125
});
126

127
table.on("dataLoaded", function(data) {
128
  console.log(`Loaded ${data.length} records`);
129
  hideProgressBar();
130
  updateRecordCount(data.length);
131
});
132

133
// Data change tracking
134
table.on("dataChanged", function(data) {
135
  console.log("Data modified, auto-saving...");
136
  autoSaveData(data);
137
});
138

139
// Filter and sort events
140
table.on("dataFiltered", function(filters, rows) {
141
  updateStatusBar(`${rows.length} rows visible`);
142
});
143

144
table.on("dataSorted", function(sorters, rows) {
145
  console.log("Data sorted by:", sorters);
146
});
147
```
148

149
## Row Events
150

151
Events related to row operations, selection, and user interactions.
152

153
```javascript { .api }
154
interface RowEvents {
155
  /** Fired when row is added to table */
156
  "rowAdded": (row: RowComponent) => void;
157
  /** Fired when row is deleted from table */
158
  "rowDeleted": (row: RowComponent) => void;
159
  /** Fired when row data is updated */
160
  "rowUpdated": (row: RowComponent) => void;
161
  /** Fired when row is moved */
162
  "rowMoved": (row: RowComponent) => void;
163
  /** Fired when row is clicked */
164
  "rowClick": (e: Event, row: RowComponent) => void;
165
  /** Fired when row is double-clicked */
166
  "rowDblClick": (e: Event, row: RowComponent) => void;
167
  /** Fired when row context menu is triggered */
168
  "rowContext": (e: Event, row: RowComponent) => void;
169
  /** Fired when row is selected */
170
  "rowSelected": (row: RowComponent) => void;
171
  /** Fired when row is deselected */
172
  "rowDeselected": (row: RowComponent) => void;
173
  /** Fired when row selection changes */
174
  "rowSelectionChanged": (data: any[], rows: RowComponent[]) => void;
175
  /** Fired when mouse enters row */
176
  "rowMouseEnter": (e: Event, row: RowComponent) => void;
177
  /** Fired when mouse leaves row */
178
  "rowMouseLeave": (e: Event, row: RowComponent) => void;
179
}
180
```
181

182
**Usage Examples:**
183

184
```javascript
185
// Row interaction events
186
table.on("rowClick", function(e, row) {
187
  const data = row.getData();
188
  if (data.id) {
189
    window.location.href = `/users/${data.id}`;
190
  }
191
});
192

193
table.on("rowDblClick", function(e, row) {
194
  row.getCell("name").edit(); // Start editing name field
195
});
196

197
// Row data change events
198
table.on("rowAdded", function(row) {
199
  console.log("New row added:", row.getData());
200
  row.getElement().style.backgroundColor = "lightgreen";
201
  setTimeout(() => {
202
    row.getElement().style.backgroundColor = "";
203
  }, 2000);
204
});
205

206
table.on("rowUpdated", function(row) {
207
  console.log("Row updated:", row.getData());
208
  markRowAsModified(row);
209
});
210

211
// Row selection events
212
table.on("rowSelectionChanged", function(data, rows) {
213
  const count = rows.length;
214
  document.getElementById("selected-count").textContent = `${count} selected`;
215
  
216
  // Enable/disable bulk action buttons
217
  toggleBulkActions(count > 0);
218
});
219
```
220

221
## Cell Events
222

223
Events for cell-level interactions, editing, and formatting.
224

225
```javascript { .api }
226
interface CellEvents {
227
  /** Fired when cell is clicked */
228
  "cellClick": (e: Event, cell: CellComponent) => void;
229
  /** Fired when cell is double-clicked */
230
  "cellDblClick": (e: Event, cell: CellComponent) => void;
231
  /** Fired when cell context menu is triggered */
232
  "cellContext": (e: Event, cell: CellComponent) => void;
233
  /** Fired when cell editing begins */
234
  "cellEditing": (cell: CellComponent) => void;
235
  /** Fired when cell editing is cancelled */
236
  "cellEditCancelled": (cell: CellComponent) => void;
237
  /** Fired when cell edit is completed */
238
  "cellEdited": (cell: CellComponent) => void;
239
  /** Fired when mouse enters cell */
240
  "cellMouseEnter": (e: Event, cell: CellComponent) => void;
241
  /** Fired when mouse leaves cell */
242
  "cellMouseLeave": (e: Event, cell: CellComponent) => void;
243
}
244
```
245

246
**Usage Examples:**
247

248
```javascript
249
// Cell editing events
250
table.on("cellEditing", function(cell) {
251
  console.log("Editing cell:", cell.getField());
252
  cell.getElement().style.backgroundColor = "lightyellow";
253
});
254

255
table.on("cellEdited", function(cell) {
256
  const field = cell.getField();
257
  const newValue = cell.getValue();
258
  const oldValue = cell.getOldValue();
259
  
260
  console.log(`${field} changed from "${oldValue}" to "${newValue}"`);
261
  
262
  // Validate and save
263
  if (validateCellValue(field, newValue)) {
264
    saveCellChange(cell.getRow().getData().id, field, newValue);
265
  } else {
266
    cell.restoreOldValue();
267
  }
268
});
269

270
// Cell interaction events
271
table.on("cellClick", function(e, cell) {
272
  if (cell.getField() === "email") {
273
    window.open(`mailto:${cell.getValue()}`);
274
  }
275
});
276
```
277

278
## Column Events
279

280
Events related to column operations and interactions.
281

282
```javascript { .api }
283
interface ColumnEvents {
284
  /** Fired when column header is clicked */
285
  "columnClick": (e: Event, column: ColumnComponent) => void;
286
  /** Fired when column header is double-clicked */
287
  "columnDblClick": (e: Event, column: ColumnComponent) => void;
288
  /** Fired when column context menu is triggered */
289
  "columnContext": (e: Event, column: ColumnComponent) => void;
290
  /** Fired when column is moved */
291
  "columnMoved": (column: ColumnComponent, columns: ColumnComponent[]) => void;
292
  /** Fired when column is resized */
293
  "columnResized": (column: ColumnComponent) => void;
294
  /** Fired when column visibility changes */
295
  "columnVisibilityChanged": (column: ColumnComponent, visible: boolean) => void;
296
  /** Fired when column title is changed */
297
  "columnTitleChanged": (column: ColumnComponent) => void;
298
}
299
```
300

301
## Page Events
302

303
Events for pagination operations and navigation.
304

305
```javascript { .api }
306
interface PageEvents {
307
  /** Fired when page is loaded */
308
  "pageLoaded": (pageno: number) => void;
309
  /** Fired when page changes */
310
  "pageChanged": (pageno: number) => void;
311
}
312
```
313

314
## Advanced Event Patterns
315

316
### Event Chaining and Validation
317

318
```javascript { .api }
319
// Prevent default behavior with validation
320
table.on("cellEditing", function(cell) {
321
  const field = cell.getField();
322
  const rowData = cell.getRow().getData();
323
  
324
  if (field === "salary" && rowData.role !== "manager") {
325
    cell.cancelEdit();
326
    alert("Only managers can edit salaries");
327
    return false; // Prevent editing
328
  }
329
});
330

331
// Chain events for complex workflows
332
table.on("rowAdded", function(row) {
333
  // Auto-assign ID for new rows
334
  if (!row.getData().id) {
335
    row.update({ id: generateUniqueId() });
336
  }
337
});
338

339
table.on("rowUpdated", function(row) {
340
  // Auto-update modified timestamp
341
  row.update({ lastModified: new Date().toISOString() });
342
});
343
```
344

345
### Custom Event Creation
346

347
```javascript { .api }
348
// Define custom events for application logic
349
class TableManager {
350
  constructor(table) {
351
    this.table = table;
352
    this.setupCustomEvents();
353
  }
354
  
355
  setupCustomEvents() {
356
    // Custom validation event
357
    this.table.on("customValidation", (data, callback) => {
358
      fetch("/api/validate", {
359
        method: "POST",
360
        body: JSON.stringify(data)
361
      })
362
      .then(response => response.json())
363
      .then(result => callback(result.isValid, result.errors));
364
    });
365
    
366
    // Custom save event
367
    this.table.on("customSave", (data) => {
368
      this.saveToServer(data);
369
    });
370
  }
371
  
372
  triggerValidation(data) {
373
    this.table.dispatchEvent("customValidation", data, (isValid, errors) => {
374
      if (isValid) {
375
        this.table.dispatchEvent("customSave", data);
376
      } else {
377
        this.displayErrors(errors);
378
      }
379
    });
380
  }
381
}
382
```
383

384
### Event Performance Optimization
385

386
```javascript { .api }
387
// Debounce rapid events
388
let saveTimeout;
389
table.on("cellEdited", function(cell) {
390
  clearTimeout(saveTimeout);
391
  saveTimeout = setTimeout(() => {
392
    saveAllData();
393
  }, 1000); // Save 1 second after last edit
394
});
395

396
// Batch event processing
397
const batchProcessor = {
398
  events: [],
399
  timeout: null,
400
  
401
  add(event, data) {
402
    this.events.push({ event, data, timestamp: Date.now() });
403
    
404
    if (!this.timeout) {
405
      this.timeout = setTimeout(() => {
406
        this.processBatch();
407
      }, 100);
408
    }
409
  },
410
  
411
  processBatch() {
412
    console.log(`Processing ${this.events.length} events`);
413
    // Process all events together
414
    this.events = [];
415
    this.timeout = null;
416
  }
417
};
418

419
table.on("cellEdited", (cell) => batchProcessor.add("cellEdited", cell));
420
table.on("rowUpdated", (row) => batchProcessor.add("rowUpdated", row));
421
```