tadabut 0.6.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +207 -31
- package/dist/{index-C_77p8Jv.d.ts → index-Cm0OsNb6.d.ts} +241 -21
- package/dist/index.d.ts +2 -2
- package/dist/index.js +1 -1
- package/dist/react.d.ts +33 -12
- package/dist/react.js +50 -25
- package/dist/{src-BxdYoViF.js → src-D6zL6H0B.js} +653 -65
- package/package.json +9 -5
package/README.md
CHANGED
|
@@ -25,6 +25,7 @@ DataTables is great for showing data. Editing that data inside the table is a di
|
|
|
25
25
|
- Delete a row, with a question first, or your own popup.
|
|
26
26
|
- Text, number, money, date, checkbox and select inputs, with validation.
|
|
27
27
|
- Selects that depend on another field, like country and city. Old requests get cancelled when the user changes their mind.
|
|
28
|
+
- Detail rows that open under a row, loaded from your server if you like, with JSX in React.
|
|
28
29
|
- Fully typed. The table knows what your rows look like, so a typo in a column name is a type error.
|
|
29
30
|
- No jQuery. It's built on DataTables 3, which doesn't need it anymore.
|
|
30
31
|
|
|
@@ -43,7 +44,7 @@ The core has no framework in it. Each framework gets a small adapter on top.
|
|
|
43
44
|
## Requirements
|
|
44
45
|
|
|
45
46
|
- DataTables 3: `datatables.net`, or one of its styling packages like `datatables.net-dt`
|
|
46
|
-
- React 19
|
|
47
|
+
- React 19 and `react-dom`, only if you use the React adapter
|
|
47
48
|
- A modern browser
|
|
48
49
|
|
|
49
50
|
## Installation
|
|
@@ -67,7 +68,7 @@ bun add tadabut datatables.net-dt
|
|
|
67
68
|
deno add npm:tadabut npm:datatables.net-dt
|
|
68
69
|
```
|
|
69
70
|
|
|
70
|
-
For the React adapter, you also need React 19
|
|
71
|
+
For the React adapter, you also need React 19 and `react-dom`, which your app most likely has already.
|
|
71
72
|
|
|
72
73
|
Then import DataTables and its CSS once, before you create a table:
|
|
73
74
|
|
|
@@ -171,18 +172,35 @@ A select's values must have the same type as the column. `countryId` is a number
|
|
|
171
172
|
| `number` | `number` | `null` | `min`, `max`, `step` |
|
|
172
173
|
| `money` | `number` | `null` | `min`, `max`, `decimals`, `separator`, `point` |
|
|
173
174
|
| `date` | `string` | `null` | `min`, `max`, `format`, `display` |
|
|
175
|
+
| `time` | `string` | `null` | `min`, `max`, `seconds` |
|
|
176
|
+
| `datetime` | `string` | `null` | `min`, `max`, `format`, `display`, `seconds` |
|
|
174
177
|
| `checkbox` | `boolean`, or `values` | never empty | `values` |
|
|
175
178
|
| `select` | same as the column | `null` | `options`, `dependsOn`, `labelProp` |
|
|
176
179
|
|
|
177
|
-
Every editor also takes `className`, for your own CSS classes.
|
|
180
|
+
Every editor also takes `className`, for your own CSS classes, and `readOnly`. See [Read-only fields](#read-only-fields).
|
|
178
181
|
|
|
179
182
|
A few things to know:
|
|
180
183
|
|
|
181
|
-
- An empty number or
|
|
184
|
+
- An empty number, date or time gives `null`, not `0` or `NaN`. A select with nothing picked gives `null` too.
|
|
182
185
|
- A checkbox shows `null` as unchecked, but keeps it: an untouched `null` is still `null` after saving. It only becomes `true` or `false` once the user clicks it.
|
|
183
186
|
- A `string | null` column gets the same editors as a `string` column. `null` shows as an empty input.
|
|
184
187
|
- Date columns hold `'YYYY-MM-DD'` unless you give a `format`. See [Dates](#dates).
|
|
185
188
|
|
|
189
|
+
#### Read-only fields
|
|
190
|
+
|
|
191
|
+
Add `readOnly: true` to any editor, and the field shows in a locked input while the row is edited:
|
|
192
|
+
|
|
193
|
+
```ts
|
|
194
|
+
{ prop: 'code', title: 'Code', editor: { type: 'text', readOnly: true } }
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
- The user sees the value but can't change it. The browser greys the input out, and Tab skips it.
|
|
198
|
+
- Saving keeps the value the row had, even one the input can't show, like a date with a time.
|
|
199
|
+
- It's never checked: `required`, `min`, `validate` and the others are skipped, since the user couldn't fix it anyway.
|
|
200
|
+
- In the new row from `add()`, it shows the value you passed to `add()`, or nothing, and stays locked. Good for fields your server fills in, like a reference number. The cursor starts in the first field that isn't read-only.
|
|
201
|
+
- It works on every editor, `custom` too: your `create` gets `context.readOnly`, and should disable its input.
|
|
202
|
+
- The cell keeps the editor's format, so a read-only `date` or `money` column still shows and sorts like the others.
|
|
203
|
+
|
|
186
204
|
#### Checkboxes with your own values
|
|
187
205
|
|
|
188
206
|
Many databases store yes/no as `'O'`/`'N'`, `'Y'`/`'N'` or `1`/`0`. Give the checkbox the two values to use:
|
|
@@ -261,6 +279,48 @@ formatDate('2024-01-05', 'dd.mm.yyyy'); // '05.01.2024'
|
|
|
261
279
|
|
|
262
280
|
A column you can't edit has no date editor, so for now, show its dates with `render`: `render: (value) => formatDate(value, 'dd/mm/yyyy')`. It sorts by the raw value, which is right for ISO dates.
|
|
263
281
|
|
|
282
|
+
#### Times
|
|
283
|
+
|
|
284
|
+
`time` is for `string` columns that hold a time of day, like `'14:30'`. The input is the browser's time picker.
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
{ prop: 'starts', title: 'Starts', editor: { type: 'time', min: '08:00', max: '18:00' } }
|
|
288
|
+
```
|
|
289
|
+
|
|
290
|
+
- It reads `'9:05'`, `'09:05'` and `'09:05:00'`. What comes after the seconds is ignored, like `.000` from some servers.
|
|
291
|
+
- It saves `'hh:mm'`. With `seconds: true`, the picker shows the seconds and it saves `'hh:mm:ss'`.
|
|
292
|
+
- The cells show `hh:mm` (or `hh:mm:ss`), and sorting uses the real time: `9:05` comes before `14:30`.
|
|
293
|
+
- `min` and `max` are times too. Tadabut throws an error if they aren't real times.
|
|
294
|
+
- A value that isn't a time, like `'25:00'`, shows as it is in the cell, and as empty in the input.
|
|
295
|
+
|
|
296
|
+
#### Dates with a time
|
|
297
|
+
|
|
298
|
+
`datetime` is for `string` columns that hold a date and a time. The input is the browser's date-and-time picker.
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
{
|
|
302
|
+
prop: 'lastLogin',
|
|
303
|
+
title: 'Last login',
|
|
304
|
+
editor: { type: 'datetime', format: 'dd/mm/yyyy', min: '01/01/2020 08:00' },
|
|
305
|
+
}
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
- The rows hold the date in `format`, a space, then the time: `'05/01/2024 14:30'`. With the default ISO `format`, a `T` goes between them instead, as servers send it: `'2024-01-05T14:30'`.
|
|
309
|
+
- `format`, `display` and `seconds` work like for [dates](#dates) and [times](#times). The cells always use a space: `05/01/2024 14:30`.
|
|
310
|
+
- When reading, a `T` and a space both work, and a date with no time counts as midnight.
|
|
311
|
+
- What comes after the seconds is ignored, a time zone too: `'2024-01-05T14:30:00Z'` shows 14:30, as written, not converted to the user's time.
|
|
312
|
+
- `min` and `max` are written like the data. Tadabut throws an error if they aren't real, or aren't in `format`.
|
|
313
|
+
- Sorting uses the real date and time, whatever `display` is.
|
|
314
|
+
|
|
315
|
+
`parseTime`, `formatTime`, `parseDateTime` and `formatDateTime` are exported, like the date helpers:
|
|
316
|
+
|
|
317
|
+
```ts
|
|
318
|
+
import { parseDateTime, parseTime } from 'tadabut';
|
|
319
|
+
|
|
320
|
+
parseTime('9:05'); // '09:05:00'
|
|
321
|
+
parseDateTime('05/01/2024 14:30', 'dd/mm/yyyy'); // '2024-01-05T14:30:00'
|
|
322
|
+
```
|
|
323
|
+
|
|
264
324
|
### What cells show
|
|
265
325
|
|
|
266
326
|
When a row isn't being edited, a cell shows its value as text. These change that:
|
|
@@ -269,6 +329,7 @@ When a row isn't being edited, a cell shows its value as text. These change that
|
|
|
269
329
|
- A select with `labelProp` shows that field of the row, like `cityName`. See [Chained selects](#chained-selects).
|
|
270
330
|
- A `money` editor shows its format, like `12 500.00`.
|
|
271
331
|
- A `date` editor shows its `display`, like `05/01/2024`.
|
|
332
|
+
- A `time` editor shows `09:05`, even when the data says `9:05:00`. A `datetime` editor shows its `display`, then the time, like `05/01/2024 14:30`.
|
|
272
333
|
- `render` sets the text yourself, on any column:
|
|
273
334
|
|
|
274
335
|
```ts
|
|
@@ -279,7 +340,7 @@ A few things to know:
|
|
|
279
340
|
|
|
280
341
|
- The order is: `render`, then the money or date format, then `labelProp`, then the fixed list's label, then the value itself.
|
|
281
342
|
- What `render` returns is shown as plain text, never as HTML. `<b>` shows as `<b>`, so text from a server can't break the page or run code.
|
|
282
|
-
- Searching uses both the text and the raw value, so `12500` finds `12 500.00`, and a country's id finds "Morocco". Sorting uses the raw value, so `200 MAD` comes before `1000 MAD`. Dates are the exception: they sort by the real date. A city column sorts by id, not by name.
|
|
343
|
+
- Searching uses both the text and the raw value, so `12500` finds `12 500.00`, and a country's id finds "Morocco". Sorting uses the raw value, so `200 MAD` comes before `1000 MAD`. Dates and times are the exception: they sort by the real date and time. A city column sorts by id, not by name.
|
|
283
344
|
- An empty value (`null` or `undefined`) shows an empty cell. On a nullable column, `render` gets `null` too.
|
|
284
345
|
- Editors always get the raw value. After saving or cancelling, the text is worked out again.
|
|
285
346
|
|
|
@@ -411,24 +472,28 @@ texts: { ...fr, save: 'Valider' }
|
|
|
411
472
|
texts: { edit: 'Bearbeiten', save: 'Speichern', cancel: 'Abbrechen' }
|
|
412
473
|
```
|
|
413
474
|
|
|
414
|
-
| Key
|
|
415
|
-
|
|
|
416
|
-
| `edit`, `save`, `cancel`
|
|
417
|
-
| `delete`
|
|
418
|
-
| `deleteQuestion`
|
|
419
|
-
| `confirm`, `keep`
|
|
420
|
-
| `loading`
|
|
421
|
-
| `saveFailed`
|
|
422
|
-
| `addFailed`
|
|
423
|
-
| `deleteFailed`
|
|
424
|
-
| `total`
|
|
425
|
-
| `selectRow`, `selectAll`
|
|
426
|
-
| `
|
|
427
|
-
| `
|
|
428
|
-
| `
|
|
429
|
-
| `
|
|
430
|
-
| `
|
|
431
|
-
| `
|
|
475
|
+
| Key | English |
|
|
476
|
+
| ----------------------------- | --------------------------------------------------------------------------------- |
|
|
477
|
+
| `edit`, `save`, `cancel` | Edit, Save, Cancel |
|
|
478
|
+
| `delete` | Delete |
|
|
479
|
+
| `deleteQuestion` | Delete this row? |
|
|
480
|
+
| `confirm`, `keep` | Yes, delete / No |
|
|
481
|
+
| `loading` | Loading… |
|
|
482
|
+
| `saveFailed` | Could not save. |
|
|
483
|
+
| `addFailed` | Could not add. |
|
|
484
|
+
| `deleteFailed` | Could not delete. |
|
|
485
|
+
| `total` | Total |
|
|
486
|
+
| `selectRow`, `selectAll` | Select row / Select all (the checkboxes' labels, for screen readers) |
|
|
487
|
+
| `showDetail`, `hideDetail` | Show details / Hide details (the ▸ button's label, for screen readers) |
|
|
488
|
+
| `detailLoading` | Loading… (while a detail loads) |
|
|
489
|
+
| `detailFailed` | Couldn't load the details. (when `detail` throws something that isn't an `Error`) |
|
|
490
|
+
| `loadFailed` | Could not load the options. |
|
|
491
|
+
| `required` | This field is required. |
|
|
492
|
+
| `patternMismatch` | Wrong format. |
|
|
493
|
+
| `tooShort`, `tooLong` | Must be at least 2 characters. |
|
|
494
|
+
| `tooSmall`, `tooLarge` | Must be 18 or more. |
|
|
495
|
+
| `tooEarly`, `tooLate` | Must be on or after 2020-01-01. |
|
|
496
|
+
| `timeTooEarly`, `timeTooLate` | Must be at or after 08:00. |
|
|
432
497
|
|
|
433
498
|
The messages with a number or a date are functions, so you can put the value where your language needs it:
|
|
434
499
|
|
|
@@ -478,6 +543,10 @@ Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you c
|
|
|
478
543
|
| `tdb-select-row` | a row's checkbox |
|
|
479
544
|
| `tdb-select-all` | the "check all" checkbox |
|
|
480
545
|
| `tdb-row-selected` | a selected row |
|
|
546
|
+
| `tdb-detail` | the ▸ column, header too |
|
|
547
|
+
| `tdb-detail-toggle` | the ▸ / ▾ button |
|
|
548
|
+
| `tdb-detail-open` | a row whose detail is open |
|
|
549
|
+
| `tdb-row-detail` | the line under a row with its detail |
|
|
481
550
|
|
|
482
551
|
To use Bootstrap, Tailwind or anything else, add your own classes. They always go next to the `tdb-` ones, never instead of them. There are two places:
|
|
483
552
|
|
|
@@ -515,6 +584,7 @@ const table = new Tadabut(container, {
|
|
|
515
584
|
| `confirm` | the "Yes, delete" button only |
|
|
516
585
|
| `keep` | the "No" button only |
|
|
517
586
|
| `select` | the selection checkboxes |
|
|
587
|
+
| `detail` | the ▸ button |
|
|
518
588
|
|
|
519
589
|
All of them are optional. Tadabut doesn't know any CSS framework: it adds the classes you give it, and nothing else. If you use Tailwind: it only keeps classes it finds in your own files. Classes in your column config count, so they work.
|
|
520
590
|
|
|
@@ -966,6 +1036,53 @@ Rows you ticked that "check all" doesn't take stay ticked: unticking it only uns
|
|
|
966
1036
|
|
|
967
1037
|
Your `order` in `dataTables` still counts your own columns: `[[0, 'asc']]` is your first column, not the checkboxes.
|
|
968
1038
|
|
|
1039
|
+
### Detail rows
|
|
1040
|
+
|
|
1041
|
+
Give `detail` a function, and each row gets a ▸ button at the start. Clicking it opens a line under the row with what the function returns:
|
|
1042
|
+
|
|
1043
|
+
```ts
|
|
1044
|
+
const table = new Tadabut(container, {
|
|
1045
|
+
data: orders,
|
|
1046
|
+
rowId: 'id',
|
|
1047
|
+
columns,
|
|
1048
|
+
detail: async (row, { signal }) => {
|
|
1049
|
+
const res = await fetch(`/api/orders/${row.id}/lines`, { signal });
|
|
1050
|
+
const lines: { label: string }[] = await res.json();
|
|
1051
|
+
|
|
1052
|
+
const list = document.createElement('ul');
|
|
1053
|
+
|
|
1054
|
+
for (const line of lines) {
|
|
1055
|
+
const item = document.createElement('li');
|
|
1056
|
+
item.textContent = line.label;
|
|
1057
|
+
list.append(item);
|
|
1058
|
+
}
|
|
1059
|
+
|
|
1060
|
+
return list;
|
|
1061
|
+
},
|
|
1062
|
+
});
|
|
1063
|
+
```
|
|
1064
|
+
|
|
1065
|
+
- It returns an element, or a string. A string is shown as plain text, never as HTML, so text from a server can't break the page. To show HTML, build the elements yourself.
|
|
1066
|
+
- It can be async. "Loading…" shows while it waits. If it throws, the error message shows in the line.
|
|
1067
|
+
- Pass `signal` to `fetch`. It's aborted when the detail closes before it finished loading, so a slow request stops instead of showing up late.
|
|
1068
|
+
- Several details can be open at once.
|
|
1069
|
+
- The ▸ button comes after the selection checkboxes and before your columns. Your `order` in `dataTables` still counts from your first column.
|
|
1070
|
+
- `detail` needs a `rowId`, and Tadabut throws an error without one.
|
|
1071
|
+
|
|
1072
|
+
**What happens to an open detail when…**
|
|
1073
|
+
|
|
1074
|
+
- **You sort, search or change page:** it stays open, and comes back when its row is shown again.
|
|
1075
|
+
- **The row is being edited:** it stays open.
|
|
1076
|
+
- **The row is saved:** `detail` runs again, so it shows the new values.
|
|
1077
|
+
- **A save or delete fails:** the error shows under the detail. Neither one replaces the other.
|
|
1078
|
+
- **The row is deleted, `setData` runs, or the table is destroyed:** it closes, and a load still running is stopped.
|
|
1079
|
+
|
|
1080
|
+
**Open it on a row click** instead of, or as well as, the button:
|
|
1081
|
+
|
|
1082
|
+
```ts
|
|
1083
|
+
onRowClick: (row) => table.toggleDetail(row.id),
|
|
1084
|
+
```
|
|
1085
|
+
|
|
969
1086
|
### Events
|
|
970
1087
|
|
|
971
1088
|
Six callbacks tell you what happened. Each one gets the row:
|
|
@@ -1054,10 +1171,17 @@ table.clearSelection(); // untick every row
|
|
|
1054
1171
|
table.isSelected(1); // true while row 1 is ticked
|
|
1055
1172
|
table.getSelected(); // the ticked rows
|
|
1056
1173
|
|
|
1174
|
+
table.openDetail(1); // open row 1's detail
|
|
1175
|
+
table.closeDetail(1); // close it
|
|
1176
|
+
table.toggleDetail(1); // open it if closed, close it if open
|
|
1177
|
+
table.isDetailOpen(1); // true while it's open, or loading
|
|
1178
|
+
|
|
1057
1179
|
table.setData(newEmployees); // replace all rows, keeps sorting and search
|
|
1058
1180
|
table.destroy(); // remove everything Tadabut created
|
|
1059
1181
|
```
|
|
1060
1182
|
|
|
1183
|
+
See [Reading and changing rows](#reading-and-changing-rows) for `getData`, `insertRow` and the others.
|
|
1184
|
+
|
|
1061
1185
|
`edit` returns `true` if editing started. It returns `false` when the row doesn't exist, it's already open, another row is open in `'single'` mode, no column has an editor, `onEditStart` returned `false`, or the row is on a page that hasn't been shown yet. DataTables only builds a row's cells once it's shown, so go to that page first.
|
|
1062
1186
|
|
|
1063
1187
|
`save` returns a promise of `true` if the row was saved and closed, `false` if it wasn't: a field is invalid, `onSave` failed, the row isn't being edited, or it's already saving.
|
|
@@ -1068,12 +1192,58 @@ table.destroy(); // remove everything Tadabut created
|
|
|
1068
1192
|
|
|
1069
1193
|
`add` returns `true` if the new row opened, `false` if one is already open, no column has an editor, or a row is being edited in `'single'` mode. `saveNew` works like `save`, and throws if the saved row has no id. `cancelNew` does nothing while `onAdd` runs.
|
|
1070
1194
|
|
|
1071
|
-
`select` skips ids that aren't in the table. `onSelect` is only called when something really changed. `getSelected` gives the rows in the order they were added, including rows hidden by the search or on other pages. Without `selection`, these do nothing, and `getSelected` gives `[]`.
|
|
1195
|
+
`select` skips ids that aren't in the table. `onSelect` is only called when something really changed. `getSelected` gives the rows in the order they were added, including rows hidden by the search or on other pages. Without `selection`, these do nothing, and `getSelected` gives `[]`. The detail methods do nothing without `detail`, and `isDetailOpen` gives `false`.
|
|
1072
1196
|
|
|
1073
1197
|
`setData` and `destroy` cancel any row being edited, and the new row, first. Unsaved changes are lost.
|
|
1074
1198
|
|
|
1075
1199
|
<kbd>Enter</kbd> saves the row you're in. <kbd>Escape</kbd> cancels it. If something else already used the key, like Select2 picking an option with <kbd>Enter</kbd>, Tadabut leaves it alone.
|
|
1076
1200
|
|
|
1201
|
+
### Reading and changing rows
|
|
1202
|
+
|
|
1203
|
+
```ts
|
|
1204
|
+
table.getData(); // every row, in the order shown
|
|
1205
|
+
table.getData('searched'); // only the rows that match the search ('page': only this page)
|
|
1206
|
+
table.getRow(5); // the row with id 5, or undefined
|
|
1207
|
+
|
|
1208
|
+
table.insertRow(rowFromServer); // put a row in, or an array of rows
|
|
1209
|
+
table.updateRow({ ...table.getRow(5), name: 'Nadia' }); // replace row 5
|
|
1210
|
+
table.removeRow(5); // take row 5 out
|
|
1211
|
+
|
|
1212
|
+
table.getTotals(); // { salary: 176651.5, age: 32.5 }
|
|
1213
|
+
table.getOptions('countryId'); // [{ value: 1, label: 'Morocco' }, …]
|
|
1214
|
+
table.getApi(); // DataTables itself
|
|
1215
|
+
```
|
|
1216
|
+
|
|
1217
|
+
**Reading**
|
|
1218
|
+
|
|
1219
|
+
- `getData` and `getRow` give **copies**. Changing them changes nothing in the table: use `updateRow` for that.
|
|
1220
|
+
- `getData` follows the sorting. Its scope works like `totalRows`: `'all'` (the default), `'searched'` or `'page'`.
|
|
1221
|
+
- `getRow` gives the saved row. While a row is being edited, what's typed isn't in it until Save.
|
|
1222
|
+
|
|
1223
|
+
**Changing**
|
|
1224
|
+
|
|
1225
|
+
`insertRow`, `updateRow` and `removeRow` change the table from your code, for example when your server pushes a change. They skip the server callbacks and their events: no `onAdd`/`onAdded`, `onSave`/`onSaved`, `onDelete`/`onDeleted`, and `removeRow` never asks. Everything else follows:
|
|
1226
|
+
|
|
1227
|
+
- The totals update.
|
|
1228
|
+
- An open detail reloads after `updateRow`, and closes after `removeRow`.
|
|
1229
|
+
- A removed row leaves the selection, and `onSelect` is called.
|
|
1230
|
+
- The table stays on the page it's on.
|
|
1231
|
+
|
|
1232
|
+
When they can't:
|
|
1233
|
+
|
|
1234
|
+
- `updateRow` and `removeRow` return `false`, and change nothing, when no row has that id, or the row is being edited or deleted. That way, a change from the server never wipes what the user is typing.
|
|
1235
|
+
- `insertRow` throws if a row has no id, or its id is already in the table (or twice in the array). Either every row goes in, or none.
|
|
1236
|
+
- `updateRow` takes a whole row. To change one field, spread the current one: `{ ...table.getRow(5), name: 'Nadia' }`.
|
|
1237
|
+
|
|
1238
|
+
**Totals and options**
|
|
1239
|
+
|
|
1240
|
+
- `getTotals` gives the footer's totals by field: plain numbers for `sum`, `avg`, `min`, `max` and `count`, rounded like the footer but not formatted, or your function's text. They count the same rows as the footer.
|
|
1241
|
+
- `getOptions` gives a select's options. With a fixed list, that list. With an `options` function, the list it last loaded in an open row, or `undefined` before any row was opened. It gives `undefined` for a column that isn't a select.
|
|
1242
|
+
|
|
1243
|
+
**DataTables itself**
|
|
1244
|
+
|
|
1245
|
+
`getApi` gives the DataTables API, for anything Tadabut doesn't do, like `table.getApi().order([2, 'desc']).draw()`. Don't add or remove rows through it: that skips Tadabut, so the selection, details and open rows won't know. Use the methods above, or `setData`.
|
|
1246
|
+
|
|
1077
1247
|
### React
|
|
1078
1248
|
|
|
1079
1249
|
Same options, as props. Keep `columns` outside your component, or in a `useMemo`, so it doesn't change on every render.
|
|
@@ -1143,17 +1313,17 @@ export default function Employees() {
|
|
|
1143
1313
|
|
|
1144
1314
|
return (
|
|
1145
1315
|
<>
|
|
1146
|
-
<button type=
|
|
1316
|
+
<button type='button' onClick={() => tableRef.current?.edit(1)}>
|
|
1147
1317
|
Edit Amina
|
|
1148
1318
|
</button>
|
|
1149
|
-
<button type=
|
|
1319
|
+
<button type='button' onClick={() => tableRef.current?.add()}>
|
|
1150
1320
|
Add an employee
|
|
1151
1321
|
</button>
|
|
1152
1322
|
|
|
1153
1323
|
<Tadabut
|
|
1154
1324
|
ref={tableRef}
|
|
1155
1325
|
data={employees}
|
|
1156
|
-
rowId=
|
|
1326
|
+
rowId='id'
|
|
1157
1327
|
columns={columns}
|
|
1158
1328
|
editing={{ mode: 'multiple' }}
|
|
1159
1329
|
onSave={(row) => saveEmployee(row)}
|
|
@@ -1177,8 +1347,10 @@ export default function Employees() {
|
|
|
1177
1347
|
- In `onAdd` and `onDelete`, update your state too, like above. Otherwise the next time `data` changes, the new row disappears, or the deleted one comes back.
|
|
1178
1348
|
- `totalRows` is a plain string, so writing it inline is fine. Changing it rebuilds the table, to count other rows.
|
|
1179
1349
|
- `selection={{ checkAll: 'page' }}` inline is fine too: only turning it on or off, or changing `checkAll`, rebuilds the table. A rebuild clears the selection.
|
|
1350
|
+
- `detail` can return JSX, async or not: `detail={(row) => <OrderLines orderId={row.id} />}`. React draws it under the row, so your components, hooks and state work inside it, and it's cleaned up when the detail closes. It can be a new function on every render: only turning it on or off rebuilds the table. This needs `react-dom`, which every React app already has.
|
|
1180
1351
|
- `editing` can be a new object on every render too. The table is only rebuilt when `mode`, `button` or `doubleClick` really change. Changing `columns`, `rowId` or `editing` closes any row being edited.
|
|
1181
|
-
- The ref has the same methods as the core: `edit`, `save`, `cancel`, `delete`, `isEditing`, `add`, `saveNew`, `cancelNew`, `isAdding`, `getSelected`, `isSelected`, `select`, `deselect` and `
|
|
1352
|
+
- The ref has the same methods as the core: `edit`, `save`, `cancel`, `delete`, `isEditing`, `add`, `saveNew`, `cancelNew`, `isAdding`, `getSelected`, `isSelected`, `select`, `deselect`, `clearSelection`, `openDetail`, `closeDetail`, `toggleDetail`, `isDetailOpen`, `getData`, `getRow`, `getApi`, `insertRow`, `updateRow`, `removeRow`, `getTotals` and `getOptions`. Before the table is built, or after it's gone, the methods that return something give `false`, `[]`, `{}` or `undefined`, and the others do nothing.
|
|
1353
|
+
- `insertRow`, `updateRow` and `removeRow` change the table, but not your `data`. The next time `data` changes, the table shows `data` again. So in React, it's usually better to change your state instead.
|
|
1182
1354
|
- There is no `setData` on the ref. To change the rows, change `data`.
|
|
1183
1355
|
|
|
1184
1356
|
## Roadmap
|
|
@@ -1207,12 +1379,16 @@ Done:
|
|
|
1207
1379
|
- [x] A checkbox column to select rows, with "check all"
|
|
1208
1380
|
- [x] More events: when editing starts (and stopping it), after saving, adding and deleting, row click and double click, and double click to edit
|
|
1209
1381
|
- [x] Dates in any format (`dd/mm/yyyy`…), in the data and the cells, and sorting by the real date
|
|
1382
|
+
- [x] Detail rows that open under a row, async and with JSX in React
|
|
1383
|
+
- [x] Read-only, time and date-with-time inputs
|
|
1384
|
+
- [x] Reading and changing rows from code: `getData`, `getRow`, `insertRow`, `updateRow`, `removeRow`, `getTotals`, `getOptions` and the DataTables API
|
|
1210
1385
|
|
|
1211
1386
|
Next, roughly in this order:
|
|
1212
1387
|
|
|
1213
|
-
- [ ]
|
|
1214
|
-
- [ ]
|
|
1215
|
-
- [ ]
|
|
1388
|
+
- [ ] Totals of the ticked rows only (`totalRows: 'selected'`)
|
|
1389
|
+
- [ ] A current row: clicking a row highlights it, one at a time, apart from the checkboxes
|
|
1390
|
+
- [ ] Turning editing on and off while the table is shown
|
|
1391
|
+
- [ ] A new row that opens by itself after each `setData`, and a new row that starts with what's typed in the search box
|
|
1216
1392
|
- [ ] Keyboard navigation and theming
|
|
1217
1393
|
|
|
1218
1394
|
Later: popup editing, changing many rows in one go, server-side mode, Vue and jQuery adapters.
|