tadabut 0.4.0 → 0.6.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 +291 -42
- package/dist/{index-mZisu7MG.d.ts → index-C_77p8Jv.d.ts} +274 -21
- package/dist/index.d.ts +8 -2
- package/dist/index.js +1 -1
- package/dist/react.d.ts +22 -7
- package/dist/react.js +56 -9
- package/dist/{src-DWwW61Yo.js → src-BxdYoViF.js} +647 -42
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -23,7 +23,7 @@ DataTables is great for showing data. Editing that data inside the table is a di
|
|
|
23
23
|
- Edit a row in place, then save or cancel. Saving can be async. If it fails, the row stays open with what the user typed, so nothing is lost.
|
|
24
24
|
- Add a row from your own button: it opens at the top of the table, with the same inputs and validation.
|
|
25
25
|
- Delete a row, with a question first, or your own popup.
|
|
26
|
-
- Text, number, date, checkbox and select inputs, with validation.
|
|
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
28
|
- Fully typed. The table knows what your rows look like, so a typo in a column name is a type error.
|
|
29
29
|
- No jQuery. It's built on DataTables 3, which doesn't need it anymore.
|
|
@@ -51,9 +51,20 @@ The core has no framework in it. Each framework gets a small adapter on top.
|
|
|
51
51
|
Install Tadabut with DataTables. `datatables.net-dt` is DataTables with its default look:
|
|
52
52
|
|
|
53
53
|
```sh
|
|
54
|
-
|
|
55
|
-
# or
|
|
54
|
+
# npm
|
|
56
55
|
npm install tadabut datatables.net-dt
|
|
56
|
+
|
|
57
|
+
# pnpm
|
|
58
|
+
pnpm add tadabut datatables.net-dt
|
|
59
|
+
|
|
60
|
+
# Yarn
|
|
61
|
+
yarn add tadabut datatables.net-dt
|
|
62
|
+
|
|
63
|
+
# Bun
|
|
64
|
+
bun add tadabut datatables.net-dt
|
|
65
|
+
|
|
66
|
+
# Deno
|
|
67
|
+
deno add npm:tadabut npm:datatables.net-dt
|
|
57
68
|
```
|
|
58
69
|
|
|
59
70
|
For the React adapter, you also need React 19, which your app most likely has already.
|
|
@@ -154,29 +165,110 @@ const columns: Column<Employee>[] = [
|
|
|
154
165
|
|
|
155
166
|
A select's values must have the same type as the column. `countryId` is a number, so `value: '1'` is a type error.
|
|
156
167
|
|
|
157
|
-
| Type | Value
|
|
158
|
-
| ---------- |
|
|
159
|
-
| `text` | `string`
|
|
160
|
-
| `number` | `number`
|
|
161
|
-
| `
|
|
162
|
-
| `
|
|
163
|
-
| `
|
|
168
|
+
| Type | Value | When empty | Options |
|
|
169
|
+
| ---------- | ---------------------- | ----------- | ---------------------------------------------- |
|
|
170
|
+
| `text` | `string` | `''` | `minLength`, `maxLength`, `pattern` |
|
|
171
|
+
| `number` | `number` | `null` | `min`, `max`, `step` |
|
|
172
|
+
| `money` | `number` | `null` | `min`, `max`, `decimals`, `separator`, `point` |
|
|
173
|
+
| `date` | `string` | `null` | `min`, `max`, `format`, `display` |
|
|
174
|
+
| `checkbox` | `boolean`, or `values` | never empty | `values` |
|
|
175
|
+
| `select` | same as the column | `null` | `options`, `dependsOn`, `labelProp` |
|
|
164
176
|
|
|
165
177
|
Every editor also takes `className`, for your own CSS classes.
|
|
166
178
|
|
|
167
179
|
A few things to know:
|
|
168
180
|
|
|
169
181
|
- An empty number or date gives `null`, not `0` or `NaN`. A select with nothing picked gives `null` too.
|
|
170
|
-
- A checkbox is
|
|
182
|
+
- 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.
|
|
171
183
|
- A `string | null` column gets the same editors as a `string` column. `null` shows as an empty input.
|
|
172
|
-
- Date columns
|
|
184
|
+
- Date columns hold `'YYYY-MM-DD'` unless you give a `format`. See [Dates](#dates).
|
|
185
|
+
|
|
186
|
+
#### Checkboxes with your own values
|
|
187
|
+
|
|
188
|
+
Many databases store yes/no as `'O'`/`'N'`, `'Y'`/`'N'` or `1`/`0`. Give the checkbox the two values to use:
|
|
189
|
+
|
|
190
|
+
```ts
|
|
191
|
+
type Employee = { id: number; active: 'O' | 'N' | null };
|
|
192
|
+
|
|
193
|
+
const columns: Column<Employee>[] = [
|
|
194
|
+
{
|
|
195
|
+
prop: 'active',
|
|
196
|
+
title: 'Active',
|
|
197
|
+
className: 'dt-center', // centers the cell and the checkbox
|
|
198
|
+
editor: { type: 'checkbox', values: { checked: 'O', unchecked: 'N' } },
|
|
199
|
+
render: (value) => (value === 'O' ? 'Yes' : value === 'N' ? 'No' : ''),
|
|
200
|
+
},
|
|
201
|
+
];
|
|
202
|
+
```
|
|
203
|
+
|
|
204
|
+
- The box is ticked only for the exact `checked` value. `'o'` isn't `'O'`, and `'1'` isn't `1`.
|
|
205
|
+
- Clicking writes `checked` or `unchecked`. A value that's neither, like `null` or an old `'X'`, shows unchecked and is kept as it is until the user clicks.
|
|
206
|
+
- `values` is required on `string` and `number` columns, and not allowed on `boolean` ones. Its values must fit the column, so `checked: 'Y'` on an `'O' | 'N'` column is a type error.
|
|
207
|
+
- The cell shows the raw value (`O`), like any column. Use `render` for "Yes"/"No", a ✓, or anything else.
|
|
208
|
+
|
|
209
|
+
#### Money
|
|
210
|
+
|
|
211
|
+
`money` is for `number` columns that hold amounts. It shows `12 500.00`, while typing and in the cells, but the row keeps a plain number (`12500`).
|
|
212
|
+
|
|
213
|
+
```ts
|
|
214
|
+
{ prop: 'salary', title: 'Salary', className: 'dt-right', editor: { type: 'money', min: 0 } }
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
- While typing, the thousands are grouped as you go, and the cursor stays where you're typing. The decimals are filled in when you leave the field: `12500` becomes `12 500.00`.
|
|
218
|
+
- Both `.` and `,` work as the decimal point. Letters are ignored, and a decimal too many is refused.
|
|
219
|
+
- The saved number is rounded to `decimals`, so `12.345` saves as `12.35`, never `12.345000001`.
|
|
220
|
+
- Empty gives `null`. `min`, `max` and `required` work like on `number`.
|
|
221
|
+
- The format is yours: `decimals` (default `2`), `separator` (default a space) and `point` (default `.`). For `12.500,00`, use `{ separator: '.', point: ',' }`. The separator and the point can't be the same: Tadabut throws an error if they are.
|
|
222
|
+
- The cells use the same format, without `render`. A `render` you write still wins, for a currency like `12 500.00 MAD`.
|
|
223
|
+
|
|
224
|
+
`formatMoney` and `defaultMoneyFormat` are exported, to show the same format in other places:
|
|
225
|
+
|
|
226
|
+
```ts
|
|
227
|
+
import { defaultMoneyFormat, formatMoney } from 'tadabut';
|
|
228
|
+
|
|
229
|
+
{ prop: 'bonus', title: 'Bonus', render: (value) => formatMoney(value, defaultMoneyFormat) }
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
#### Dates
|
|
233
|
+
|
|
234
|
+
`date` is for `string` columns. The input is the browser's date picker. By default, the rows hold `'2024-01-05'` (year first). If your server sends another order, say so with `format`, and pick what the cells show with `display`:
|
|
235
|
+
|
|
236
|
+
```ts
|
|
237
|
+
{
|
|
238
|
+
prop: 'hiredAt',
|
|
239
|
+
title: 'Hired',
|
|
240
|
+
editor: { type: 'date', format: 'dd/mm/yyyy', min: '01/01/2000' },
|
|
241
|
+
}
|
|
242
|
+
```
|
|
243
|
+
|
|
244
|
+
- `format` is how the date is written in your rows: what the server sends, and what `onSave` gets back. It defaults to `'yyyy-mm-dd'`.
|
|
245
|
+
- `display` is how the cells show it. It defaults to `format`. With ISO data and `display: 'dd/mm/yyyy'`, the cells show `05/01/2024`, but the rows keep `'2024-01-05'`.
|
|
246
|
+
- Both take `dd`, `mm` and `yyyy` in any order, with `/`, `-` or `.` between them: `'dd/mm/yyyy'`, `'mm-dd-yyyy'`, `'dd.mm.yyyy'`, and so on. TypeScript catches a typo like `'dd/mm-yyyy'`.
|
|
247
|
+
- `min` and `max` are written in `format` too. Tadabut throws an error if they aren't real dates in that format.
|
|
248
|
+
- Sorting uses the real date, whatever the format. `'12/01/2023'` comes before `'05/01/2024'`.
|
|
249
|
+
- A time after the date is dropped: `'2024-01-05T10:30:00'` shows the 5th, and saves as `'2024-01-05'`.
|
|
250
|
+
- A value that isn't a real date in `format`, like `'31/02/2024'`, shows as it is in the cell, so you can see it. The input shows it as empty, and saving turns it into `null`.
|
|
251
|
+
- The picker itself shows the date the way the computer's language does. A French computer shows `05/01/2024` and an American one `01/05/2024`. Browsers don't let a page change that.
|
|
252
|
+
|
|
253
|
+
`parseDate`, `formatDate` and `defaultDateFormat` are exported, to read and write the same formats elsewhere. `parseDate` gives `'yyyy-mm-dd'`, or `null` if it isn't a real date:
|
|
254
|
+
|
|
255
|
+
```ts
|
|
256
|
+
import { formatDate, parseDate } from 'tadabut';
|
|
257
|
+
|
|
258
|
+
parseDate('05/01/2024', 'dd/mm/yyyy'); // '2024-01-05'
|
|
259
|
+
formatDate('2024-01-05', 'dd.mm.yyyy'); // '05.01.2024'
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
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.
|
|
173
263
|
|
|
174
264
|
### What cells show
|
|
175
265
|
|
|
176
|
-
When a row isn't being edited, a cell shows its value as text.
|
|
266
|
+
When a row isn't being edited, a cell shows its value as text. These change that:
|
|
177
267
|
|
|
178
268
|
- A select with a fixed list shows the option's label. A `countryId` of `1` shows "Morocco", with nothing to write.
|
|
179
269
|
- A select with `labelProp` shows that field of the row, like `cityName`. See [Chained selects](#chained-selects).
|
|
270
|
+
- A `money` editor shows its format, like `12 500.00`.
|
|
271
|
+
- A `date` editor shows its `display`, like `05/01/2024`.
|
|
180
272
|
- `render` sets the text yourself, on any column:
|
|
181
273
|
|
|
182
274
|
```ts
|
|
@@ -185,12 +277,59 @@ When a row isn't being edited, a cell shows its value as text. Three things chan
|
|
|
185
277
|
|
|
186
278
|
A few things to know:
|
|
187
279
|
|
|
188
|
-
- The order is: `render`, then `labelProp`, then the fixed list's label, then the value itself.
|
|
280
|
+
- The order is: `render`, then the money or date format, then `labelProp`, then the fixed list's label, then the value itself.
|
|
189
281
|
- 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.
|
|
190
|
-
- Searching uses the text. Sorting uses the raw value, so `200 MAD` comes before `1000 MAD`. A city column sorts by id, not by name.
|
|
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.
|
|
191
283
|
- An empty value (`null` or `undefined`) shows an empty cell. On a nullable column, `render` gets `null` too.
|
|
192
284
|
- Editors always get the raw value. After saving or cancelling, the text is worked out again.
|
|
193
285
|
|
|
286
|
+
### Totals
|
|
287
|
+
|
|
288
|
+
Give a column a `total`, and the table gets a footer line with it:
|
|
289
|
+
|
|
290
|
+
```ts
|
|
291
|
+
const columns: Column<Employee>[] = [
|
|
292
|
+
{ prop: 'name', title: 'Name' },
|
|
293
|
+
{ prop: 'age', title: 'Age', render: (value) => `${value} years`, total: 'avg' },
|
|
294
|
+
{ prop: 'salary', title: 'Salary', editor: { type: 'money' }, total: 'sum' },
|
|
295
|
+
];
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
| Name | Age | Salary |
|
|
299
|
+
| ----- | ---------- | ---------- |
|
|
300
|
+
| … | … | … |
|
|
301
|
+
| Total | 32.5 years | 176 651.50 |
|
|
302
|
+
|
|
303
|
+
| `total` | Shows | Columns |
|
|
304
|
+
| ---------- | ------------------- | ------- |
|
|
305
|
+
| `'sum'` | everything added up | numbers |
|
|
306
|
+
| `'avg'` | the average | numbers |
|
|
307
|
+
| `'min'` | the smallest | numbers |
|
|
308
|
+
| `'max'` | the biggest | numbers |
|
|
309
|
+
| `'count'` | how many rows | any |
|
|
310
|
+
| a function | what it returns | any |
|
|
311
|
+
|
|
312
|
+
- The total looks like the cells: a `money` column shows `176 651.50`, and a `render` is used too (`32.5 years`). Numbers are rounded to 2 decimals. `count` is always a plain number.
|
|
313
|
+
- `render` gets the total and an empty object as its row, since a total isn't a row. A `render` that reads other fields of the row should use the function form instead.
|
|
314
|
+
- Empty values (`null`) are skipped. With no values, a sum is `0` and the others show nothing.
|
|
315
|
+
- A function gets the counted rows and returns the text, shown as text, not HTML:
|
|
316
|
+
|
|
317
|
+
```ts
|
|
318
|
+
{ prop: 'active', title: 'Active', total: (rows) => `${rows.filter((row) => row.active).length} active` }
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
- `Total` goes in the first cell, unless that column has a total of its own. Change it with `texts: { total: 'Somme' }`.
|
|
322
|
+
- The totals update by themselves after a search, a page change, a save, an add, a delete or `setData`.
|
|
323
|
+
- TypeScript only allows `sum`, `avg`, `min` and `max` on number columns.
|
|
324
|
+
|
|
325
|
+
**Which rows count,** with `totalRows`:
|
|
326
|
+
|
|
327
|
+
| `totalRows` | Counts |
|
|
328
|
+
| ---------------------- | ------------------------------------------------ |
|
|
329
|
+
| `'searched'` (default) | every row that matches the search, on every page |
|
|
330
|
+
| `'all'` | every row, whatever the search |
|
|
331
|
+
| `'page'` | only the rows on the page shown |
|
|
332
|
+
|
|
194
333
|
### Column options
|
|
195
334
|
|
|
196
335
|
A few more column settings, passed to DataTables:
|
|
@@ -272,22 +411,24 @@ texts: { ...fr, save: 'Valider' }
|
|
|
272
411
|
texts: { edit: 'Bearbeiten', save: 'Speichern', cancel: 'Abbrechen' }
|
|
273
412
|
```
|
|
274
413
|
|
|
275
|
-
| Key | English
|
|
276
|
-
| ------------------------ |
|
|
277
|
-
| `edit`, `save`, `cancel` | Edit, Save, Cancel
|
|
278
|
-
| `delete` | Delete
|
|
279
|
-
| `deleteQuestion` | Delete this row?
|
|
280
|
-
| `confirm`, `keep` | Yes, delete / No
|
|
281
|
-
| `loading` | Loading…
|
|
282
|
-
| `saveFailed` | Could not save.
|
|
283
|
-
| `addFailed` | Could not add.
|
|
284
|
-
| `deleteFailed` | Could not delete.
|
|
285
|
-
| `
|
|
286
|
-
| `
|
|
287
|
-
| `
|
|
288
|
-
| `
|
|
289
|
-
| `
|
|
290
|
-
| `
|
|
414
|
+
| Key | English |
|
|
415
|
+
| ------------------------ | -------------------------------------------------------------------- |
|
|
416
|
+
| `edit`, `save`, `cancel` | Edit, Save, Cancel |
|
|
417
|
+
| `delete` | Delete |
|
|
418
|
+
| `deleteQuestion` | Delete this row? |
|
|
419
|
+
| `confirm`, `keep` | Yes, delete / No |
|
|
420
|
+
| `loading` | Loading… |
|
|
421
|
+
| `saveFailed` | Could not save. |
|
|
422
|
+
| `addFailed` | Could not add. |
|
|
423
|
+
| `deleteFailed` | Could not delete. |
|
|
424
|
+
| `total` | Total |
|
|
425
|
+
| `selectRow`, `selectAll` | Select row / Select all (the checkboxes' labels, for screen readers) |
|
|
426
|
+
| `loadFailed` | Could not load the options. |
|
|
427
|
+
| `required` | This field is required. |
|
|
428
|
+
| `patternMismatch` | Wrong format. |
|
|
429
|
+
| `tooShort`, `tooLong` | Must be at least 2 characters. |
|
|
430
|
+
| `tooSmall`, `tooLarge` | Must be 18 or more. |
|
|
431
|
+
| `tooEarly`, `tooLate` | Must be on or after 2020-01-01. |
|
|
291
432
|
|
|
292
433
|
The messages with a number or a date are functions, so you can put the value where your language needs it:
|
|
293
434
|
|
|
@@ -312,6 +453,7 @@ Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you c
|
|
|
312
453
|
| `tdb-input` | every input |
|
|
313
454
|
| `tdb-input-text` | text inputs |
|
|
314
455
|
| `tdb-input-number` | number inputs |
|
|
456
|
+
| `tdb-input-money` | money inputs |
|
|
315
457
|
| `tdb-input-date` | date inputs |
|
|
316
458
|
| `tdb-input-checkbox` | checkboxes |
|
|
317
459
|
| `tdb-input-select` | selects |
|
|
@@ -321,6 +463,7 @@ Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you c
|
|
|
321
463
|
| `tdb-row-editing` | a row while it's being edited, and the new row |
|
|
322
464
|
| `tdb-row-saving` | a row while it's being saved, added or deleted |
|
|
323
465
|
| `tdb-row-new` | the new row `add()` opens |
|
|
466
|
+
| `tdb-totals` | the footer with the totals |
|
|
324
467
|
| `tdb-new-rows` | the `<tbody>` it lives in, above the others |
|
|
325
468
|
| `tdb-actions` | the column with the buttons, header too |
|
|
326
469
|
| `tdb-button` | every button |
|
|
@@ -331,6 +474,10 @@ Tadabut doesn't ship any CSS. Everything it creates gets these classes, so you c
|
|
|
331
474
|
| `tdb-delete-question` | the "Delete this row?" text |
|
|
332
475
|
| `tdb-button-confirm` | the "Yes, delete" button |
|
|
333
476
|
| `tdb-button-keep` | the "No" button |
|
|
477
|
+
| `tdb-select` | the checkbox column, header too |
|
|
478
|
+
| `tdb-select-row` | a row's checkbox |
|
|
479
|
+
| `tdb-select-all` | the "check all" checkbox |
|
|
480
|
+
| `tdb-row-selected` | a selected row |
|
|
334
481
|
|
|
335
482
|
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:
|
|
336
483
|
|
|
@@ -367,6 +514,7 @@ const table = new Tadabut(container, {
|
|
|
367
514
|
| `delete` | the Delete button only |
|
|
368
515
|
| `confirm` | the "Yes, delete" button only |
|
|
369
516
|
| `keep` | the "No" button only |
|
|
517
|
+
| `select` | the selection checkboxes |
|
|
370
518
|
|
|
371
519
|
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.
|
|
372
520
|
|
|
@@ -447,6 +595,11 @@ Error messages and the rows being edited need a few lines of your own CSS:
|
|
|
447
595
|
vertical-align: top;
|
|
448
596
|
}
|
|
449
597
|
|
|
598
|
+
/* A checkbox is smaller than the inputs: move it down to their middle. */
|
|
599
|
+
.table > tbody > tr.tdb-row-editing .tdb-input-checkbox {
|
|
600
|
+
margin-top: 0.5rem;
|
|
601
|
+
}
|
|
602
|
+
|
|
450
603
|
.tdb-row-saving {
|
|
451
604
|
opacity: 0.5;
|
|
452
605
|
}
|
|
@@ -555,6 +708,7 @@ Built-in rules:
|
|
|
555
708
|
| -------- | ----------------------------------- |
|
|
556
709
|
| text | `minLength`, `maxLength`, `pattern` |
|
|
557
710
|
| number | `min`, `max` |
|
|
711
|
+
| money | `min`, `max` |
|
|
558
712
|
| date | `min`, `max` |
|
|
559
713
|
| checkbox | none |
|
|
560
714
|
| select | none |
|
|
@@ -772,6 +926,89 @@ confirmDelete: async (row) => {
|
|
|
772
926
|
|
|
773
927
|
Leave it out for the question in the row. To only change its words, use `texts` (`deleteQuestion`, `confirm`, `keep`). To style it, use `classNames` (`delete`, `confirm`, `keep`).
|
|
774
928
|
|
|
929
|
+
### Selecting rows
|
|
930
|
+
|
|
931
|
+
Turn on `selection`, and the table gets a checkbox column at the start, with a "check all" box in the header:
|
|
932
|
+
|
|
933
|
+
```ts
|
|
934
|
+
const table = new Tadabut(container, {
|
|
935
|
+
data: employees,
|
|
936
|
+
rowId: 'id',
|
|
937
|
+
columns,
|
|
938
|
+
selection: true,
|
|
939
|
+
onSelect: (rows) => console.log(`${rows.length} selected`),
|
|
940
|
+
});
|
|
941
|
+
|
|
942
|
+
table.getSelected(); // the selected rows
|
|
943
|
+
```
|
|
944
|
+
|
|
945
|
+
- Ticks are kept by row id, so they stay when you change page, sort or search.
|
|
946
|
+
- `onSelect` gets every selected row each time the selection changes, from a click or from code.
|
|
947
|
+
- The header box is ticked when every row it takes is selected, and shows a dash when only some are.
|
|
948
|
+
- A selected row gets the `tdb-row-selected` class. Tadabut doesn't color it: that's your CSS.
|
|
949
|
+
- Rows that leave the table, after a delete or `setData`, are unselected.
|
|
950
|
+
- The new row `add()` opens has no checkbox until it's saved.
|
|
951
|
+
- `selection` needs a `rowId`, and Tadabut throws an error without one.
|
|
952
|
+
|
|
953
|
+
**Which rows "check all" takes,** with `checkAll`:
|
|
954
|
+
|
|
955
|
+
```ts
|
|
956
|
+
selection: { checkAll: 'page' },
|
|
957
|
+
```
|
|
958
|
+
|
|
959
|
+
| `checkAll` | Takes |
|
|
960
|
+
| ---------------------- | ------------------------------------------------ |
|
|
961
|
+
| `'searched'` (default) | every row that matches the search, on every page |
|
|
962
|
+
| `'all'` | every row, whatever the search |
|
|
963
|
+
| `'page'` | only the rows on the page shown |
|
|
964
|
+
|
|
965
|
+
Rows you ticked that "check all" doesn't take stay ticked: unticking it only unselects the rows it takes.
|
|
966
|
+
|
|
967
|
+
Your `order` in `dataTables` still counts your own columns: `[[0, 'asc']]` is your first column, not the checkboxes.
|
|
968
|
+
|
|
969
|
+
### Events
|
|
970
|
+
|
|
971
|
+
Six callbacks tell you what happened. Each one gets the row:
|
|
972
|
+
|
|
973
|
+
| Option | When | Gets |
|
|
974
|
+
| ------------------ | -------------------------------------- | --------------------- |
|
|
975
|
+
| `onEditStart` | a row opens for editing | `(row)` |
|
|
976
|
+
| `onSaved` | after a save worked and the row closed | `(row, { previous })` |
|
|
977
|
+
| `onAdded` | after a new row joined the table | `(row)` |
|
|
978
|
+
| `onDeleted` | after a row left the table | `(row)` |
|
|
979
|
+
| `onRowClick` | a row is clicked | `(row, event)` |
|
|
980
|
+
| `onRowDoubleClick` | a row is double-clicked | `(row, event)` |
|
|
981
|
+
|
|
982
|
+
```ts
|
|
983
|
+
const table = new Tadabut(container, {
|
|
984
|
+
data: employees,
|
|
985
|
+
rowId: 'id',
|
|
986
|
+
columns,
|
|
987
|
+
onSave: saveEmployee,
|
|
988
|
+
onEditStart: (row) => row.status !== 'validated', // false keeps the row closed
|
|
989
|
+
onSaved: (row, { previous }) => toast(`${previous.name} saved`),
|
|
990
|
+
onRowClick: (row) => showDetails(row),
|
|
991
|
+
});
|
|
992
|
+
```
|
|
993
|
+
|
|
994
|
+
- `onSave`, `onAdd` and `onDelete` do the work and can fail. `onSaved`, `onAdded` and `onDeleted` come after, once it worked and the table changed. They're never called when it failed.
|
|
995
|
+
- They're called the same way from the buttons and from code: `table.edit(1)` calls `onEditStart`, and `await table.save(1)` calls `onSaved`.
|
|
996
|
+
- `onEditStart` can return `false` to keep the row closed, for rows a user can't change. `edit()` then returns `false`. It's not called for the new row `add()` opens, and it can't be async.
|
|
997
|
+
- `onSaved` gets the row as it now is in the table (what `onSave` returned, if anything), and the row before editing.
|
|
998
|
+
- Tadabut doesn't wait for the "after" callbacks, so async is fine. If one throws, the table is already done: the error goes to the console, and `save()` or `saveNew()` rejects.
|
|
999
|
+
|
|
1000
|
+
**Which clicks count:** clicks on buttons, inputs, checkboxes, labels and links don't, and neither do clicks in the checkbox and buttons cells (a click that just missed a button). Clicks in a row being edited, the new row, the header, the footer or an error line don't count either. `onRowClick` works without `rowId` and without editors.
|
|
1001
|
+
|
|
1002
|
+
**Double clicks:** the browser fires two clicks before a double click, so `onRowClick` runs twice before `onRowDoubleClick`. Tadabut doesn't wait to tell them apart, because that would make every single click feel slow.
|
|
1003
|
+
|
|
1004
|
+
**Double click to edit:**
|
|
1005
|
+
|
|
1006
|
+
```ts
|
|
1007
|
+
editing: { doubleClick: true },
|
|
1008
|
+
```
|
|
1009
|
+
|
|
1010
|
+
Double-clicking a row then opens it, the same as its Edit button: `onEditStart` and the `'single'` mode still apply. `onRowDoubleClick` still fires, after the row opened.
|
|
1011
|
+
|
|
775
1012
|
### Editing options
|
|
776
1013
|
|
|
777
1014
|
When at least one column has an `editor`, the table gets one more column at the end, with an Edit button in each row. While a row is being edited, its Edit button is replaced by Save and Cancel. The labels can be changed with `texts`.
|
|
@@ -787,13 +1024,15 @@ const table = new Tadabut(container, {
|
|
|
787
1024
|
editing: {
|
|
788
1025
|
mode: 'multiple', // default: 'single'
|
|
789
1026
|
button: false, // default: true. false hides the edit button
|
|
1027
|
+
doubleClick: true, // default: false. true opens a row on double click
|
|
790
1028
|
},
|
|
791
1029
|
});
|
|
792
1030
|
```
|
|
793
1031
|
|
|
794
1032
|
- `'single'` mode: one row at a time. You can't start a new edit while another row is open.
|
|
795
1033
|
- `'multiple'` mode: several rows can be open. Each one saves on its own, so `onSave` runs once per row.
|
|
796
|
-
- `
|
|
1034
|
+
- `doubleClick: true`: double-clicking a row opens it. See [Events](#events).
|
|
1035
|
+
- `button: false`: no Edit button. Start edits from your own code, or with `doubleClick`. <kbd>Enter</kbd> and <kbd>Escape</kbd> still work. With `onDelete`, the column stays, with only the Delete button.
|
|
797
1036
|
|
|
798
1037
|
### Controlling it from code
|
|
799
1038
|
|
|
@@ -809,11 +1048,17 @@ await table.saveNew(); // validate it and call onAdd
|
|
|
809
1048
|
table.cancelNew(); // throw the new row away
|
|
810
1049
|
table.isAdding(); // true while the new row is open
|
|
811
1050
|
|
|
1051
|
+
table.select([1, 2]); // tick rows 1 and 2
|
|
1052
|
+
table.deselect([2]); // untick row 2
|
|
1053
|
+
table.clearSelection(); // untick every row
|
|
1054
|
+
table.isSelected(1); // true while row 1 is ticked
|
|
1055
|
+
table.getSelected(); // the ticked rows
|
|
1056
|
+
|
|
812
1057
|
table.setData(newEmployees); // replace all rows, keeps sorting and search
|
|
813
1058
|
table.destroy(); // remove everything Tadabut created
|
|
814
1059
|
```
|
|
815
1060
|
|
|
816
|
-
`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, 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.
|
|
1061
|
+
`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.
|
|
817
1062
|
|
|
818
1063
|
`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.
|
|
819
1064
|
|
|
@@ -823,6 +1068,8 @@ table.destroy(); // remove everything Tadabut created
|
|
|
823
1068
|
|
|
824
1069
|
`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.
|
|
825
1070
|
|
|
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 `[]`.
|
|
1072
|
+
|
|
826
1073
|
`setData` and `destroy` cancel any row being edited, and the new row, first. Unsaved changes are lost.
|
|
827
1074
|
|
|
828
1075
|
<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.
|
|
@@ -926,10 +1173,12 @@ export default function Employees() {
|
|
|
926
1173
|
```
|
|
927
1174
|
|
|
928
1175
|
- When `employees` changes, the table updates in place. It doesn't get rebuilt.
|
|
929
|
-
- `onSave`, `onAdd`, `onDelete
|
|
1176
|
+
- `onSave`, `onAdd`, `onDelete`, `confirmDelete`, `onSelect` and the [events](#events) can be new functions on every render. The table always calls the latest ones.
|
|
930
1177
|
- 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.
|
|
931
|
-
- `
|
|
932
|
-
-
|
|
1178
|
+
- `totalRows` is a plain string, so writing it inline is fine. Changing it rebuilds the table, to count other rows.
|
|
1179
|
+
- `selection={{ checkAll: 'page' }}` inline is fine too: only turning it on or off, or changing `checkAll`, rebuilds the table. A rebuild clears the selection.
|
|
1180
|
+
- `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 `clearSelection`. Before the table is built, or after it's gone, the methods that return something give `false` (`[]` for `getSelected`), and the others do nothing.
|
|
933
1182
|
- There is no `setData` on the ref. To change the rows, change `data`.
|
|
934
1183
|
|
|
935
1184
|
## Roadmap
|
|
@@ -952,15 +1201,15 @@ Done:
|
|
|
952
1201
|
- [x] Translations for Tadabut's own texts (buttons and error messages), French built in
|
|
953
1202
|
- [x] Deleting rows, with a question first that you can replace (`confirmDelete`)
|
|
954
1203
|
- [x] Adding new rows, at the top of the table (`add()` and `onAdd`)
|
|
1204
|
+
- [x] Checkboxes with your own values, like `'O'` and `'N'` instead of `true` and `false`
|
|
1205
|
+
- [x] Money inputs, formatted while typing (`12 500.00`)
|
|
1206
|
+
- [x] Totals in the footer: sum, average, min, max, count or your own
|
|
1207
|
+
- [x] A checkbox column to select rows, with "check all"
|
|
1208
|
+
- [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
|
+
- [x] Dates in any format (`dd/mm/yyyy`…), in the data and the cells, and sorting by the real date
|
|
955
1210
|
|
|
956
1211
|
Next, roughly in this order:
|
|
957
1212
|
|
|
958
|
-
- [ ] Checkboxes with your own values, like `'O'` and `'N'` instead of `true` and `false`
|
|
959
|
-
- [ ] Money inputs, formatted while typing (`12 500.00`)
|
|
960
|
-
- [ ] Dates as `dd/mm/yyyy`, in the input and when sorting
|
|
961
|
-
- [ ] Totals in the footer
|
|
962
|
-
- [ ] A checkbox column to select rows, with "check all"
|
|
963
|
-
- [ ] More events: when editing starts, after saving, row click and double click
|
|
964
1213
|
- [ ] Detail rows that open under a row
|
|
965
1214
|
- [ ] Time and read-only inputs
|
|
966
1215
|
- [ ] Methods to read rows (`getData`, `getRow`), put a row in directly without opening it, and reach the DataTables API
|