|
461 | 461 | * used to query which Ids changed during the transaction. |
462 | 462 | * |
463 | 463 | * @param store A reference to the Store that changed. |
464 | | - * @param getIdChanges A function that returns information Id changes, since |
465 | | - * 3.3. |
| 464 | + * @param getIdChanges A function that returns information about the Id changes, |
| 465 | + * since v3.3. |
466 | 466 | * @category Listener |
467 | 467 | */ |
468 | 468 | /// TableIdsListener |
|
488 | 488 | * @category Listener |
489 | 489 | */ |
490 | 490 | /// TableListener |
| 491 | +/** |
| 492 | + * The TableCellIdsListener type describes a function that is used to listen to |
| 493 | + * changes to the Cell Ids that appear anywhere in a Table. |
| 494 | + * |
| 495 | + * A TableCellIdsListener is provided when using the addTableCellIdsListener |
| 496 | + * method. See that method for specific examples. |
| 497 | + * |
| 498 | + * When called, a TableCellIdsListener is given a reference to the Store, the Id |
| 499 | + * of the Table whose Cell Ids changed, and a GetIdChanges function that can be |
| 500 | + * used to query which Ids changed during the transaction. |
| 501 | + * |
| 502 | + * @param store A reference to the Store that changed. |
| 503 | + * @param tableId The Id of the Table that changed. |
| 504 | + * @param getIdChanges A function that returns information about the Id changes. |
| 505 | + * @category Listener |
| 506 | + * @since v3.3 |
| 507 | + */ |
| 508 | +/// TableCellIdsListener |
491 | 509 | /** |
492 | 510 | * The RowIdsListener type describes a function that is used to listen to |
493 | 511 | * changes to the Row Ids in a Table. |
|
503 | 521 | * |
504 | 522 | * @param store A reference to the Store that changed. |
505 | 523 | * @param tableId The Id of the Table that changed. |
506 | | - * @param getIdChanges A function that returns information Id changes, since |
507 | | - * 3.3. |
| 524 | + * @param getIdChanges A function that returns information about the Id changes, |
| 525 | + * since v3.3. |
508 | 526 | * @category Listener |
509 | 527 | */ |
510 | 528 | /// RowIdsListener |
|
573 | 591 | * @param store A reference to the Store that changed. |
574 | 592 | * @param tableId The Id of the Table that changed. |
575 | 593 | * @param rowId The Id of the Row that changed. |
576 | | - * @param getIdChanges A function that returns information Id changes, since |
577 | | - * 3.3. |
| 594 | + * @param getIdChanges A function that returns information about the Id changes, |
| 595 | + * since v3.3. |
578 | 596 | * @category Listener |
579 | 597 | */ |
580 | 598 | /// CellIdsListener |
|
641 | 659 | * used to query which Ids changed during the transaction. |
642 | 660 | * |
643 | 661 | * @param store A reference to the Store that changed. |
644 | | - * @param getIdChanges A function that returns information Id changes, since |
645 | | - * 3.3. |
| 662 | + * @param getIdChanges A function that returns information about the Id changes, |
| 663 | + * since v3.3. |
646 | 664 | * @category Listener |
647 | 665 | */ |
648 | 666 | /// ValueIdsListener |
|
3533 | 3551 | * @category Listener |
3534 | 3552 | */ |
3535 | 3553 | /// Store.addTableListener |
| 3554 | + /** |
| 3555 | + * The addTableCellIdsListener method registers a listener function with the |
| 3556 | + * Store that will be called whenever the Cell Ids that appear anywhere in a |
| 3557 | + * Table change. |
| 3558 | + * |
| 3559 | + * The provided listener is a TableCellIdsListener function, and will be |
| 3560 | + * called with a reference to the Store and the Id of the Table that changed. |
| 3561 | + * |
| 3562 | + * By default, such a listener is only called when a Cell Id is added or |
| 3563 | + * removed from the whole of the Table. To listen to all changes in the Table, |
| 3564 | + * use the addTableListener method. |
| 3565 | + * |
| 3566 | + * You can either listen to a single Table (by specifying its Id as the |
| 3567 | + * method's first parameter) or changes to any Table (by providing a `null` |
| 3568 | + * wildcard). |
| 3569 | + * |
| 3570 | + * Use the optional mutator parameter to indicate that there is code in the |
| 3571 | + * listener that will mutate Store data. If set to `false` (or omitted), such |
| 3572 | + * mutations will be silently ignored. All relevant mutator listeners (with |
| 3573 | + * this flag set to `true`) are called _before_ any non-mutator listeners |
| 3574 | + * (since the latter may become relevant due to changes made in the former). |
| 3575 | + * The changes made by mutator listeners do not fire other mutating listeners, |
| 3576 | + * though they will fire non-mutator listeners. |
| 3577 | + * |
| 3578 | + * @param tableId The Id of the Table to listen to, or `null` as a wildcard. |
| 3579 | + * @param listener The function that will be called whenever the Cell Ids that |
| 3580 | + * appear anywhere in a Table change. |
| 3581 | + * @param mutator An optional boolean that indicates that the listener mutates |
| 3582 | + * Store data. |
| 3583 | + * @returns A unique Id for the listener that can later be used to call it |
| 3584 | + * explicitly, or to remove it. |
| 3585 | + * @example |
| 3586 | + * This example registers a listener that responds to any change to the Cell |
| 3587 | + * Ids that appear anywhere in a Table. |
| 3588 | + * |
| 3589 | + * ```js |
| 3590 | + * const store = createStore().setTables({ |
| 3591 | + * pets: {fido: {species: 'dog', color: 'brown'}}, |
| 3592 | + * }); |
| 3593 | + * const listenerId = store.addTableCellIdsListener('pets', (store) => { |
| 3594 | + * console.log('Cell Ids in pets table changed'); |
| 3595 | + * console.log(store.getTableCellIds('pets')); |
| 3596 | + * }); |
| 3597 | + * |
| 3598 | + * store.setRow('pets', 'felix', {species: 'cat', legs: 4}); |
| 3599 | + * // -> 'Cell Ids in pets table changed' |
| 3600 | + * // -> ['species', 'color', 'legs'] |
| 3601 | + * |
| 3602 | + * store.delListener(listenerId); |
| 3603 | + * ``` |
| 3604 | + * @example |
| 3605 | + * This example registers a listener that responds to any change to the Cell |
| 3606 | + * Ids that appear anywhere in any Table. |
| 3607 | + * |
| 3608 | + * ```js |
| 3609 | + * const store = createStore().setTables({ |
| 3610 | + * pets: {fido: {species: 'dog', color: 'brown'}}, |
| 3611 | + * species: {dog: {price: 5}, } |
| 3612 | + * }); |
| 3613 | + * const listenerId = store.addTableCellIdsListener( |
| 3614 | + * null, |
| 3615 | + * (store, tableId) => { |
| 3616 | + * console.log(`Cell Ids in ${tableId} table changed`); |
| 3617 | + * console.log(store.getTableCellIds(tableId)); |
| 3618 | + * }, |
| 3619 | + * ); |
| 3620 | + * |
| 3621 | + * store.setRow('pets', 'felix', {species: 'cat', legs: 4}); |
| 3622 | + * // -> 'Cell Ids in pets table changed' |
| 3623 | + * // -> ['species', 'color', 'legs'] |
| 3624 | + * |
| 3625 | + * store.setRow('species', 'cat', {price: 4, friendly: true}); |
| 3626 | + * // -> 'Cell Ids in species table changed' |
| 3627 | + * // -> ['price', 'friendly'] |
| 3628 | + * |
| 3629 | + * store.delListener(listenerId); |
| 3630 | + * ``` |
| 3631 | + * @example |
| 3632 | + * This example registers a listener that responds to the Cell Ids that appear |
| 3633 | + * anywhere in a Table, and which also mutates the Store itself. |
| 3634 | + * |
| 3635 | + * ```js |
| 3636 | + * const store = createStore().setTables({ |
| 3637 | + * pets: {fido: {species: 'dog', color: 'brown'}}, |
| 3638 | + * }); |
| 3639 | + * const listenerId = store.addTableCellIdsListener( |
| 3640 | + * 'pets', |
| 3641 | + * (store, tableId) => store.setCell('meta', 'update', tableId, true), |
| 3642 | + * true, // mutator |
| 3643 | + * ); |
| 3644 | + * |
| 3645 | + * store.setRow('pets', 'felix', {species: 'cat', legs: 4}); |
| 3646 | + * console.log(store.getTable('meta')); |
| 3647 | + * // -> {update: {pets: true}} |
| 3648 | + * |
| 3649 | + * store.delListener(listenerId); |
| 3650 | + * ``` |
| 3651 | + * @category Listener |
| 3652 | + */ |
| 3653 | + /// Store.addTableCellIdsListener |
3536 | 3654 | /** |
3537 | 3655 | * The addRowIdsListener method registers a listener function with the Store |
3538 | 3656 | * that will be called whenever the Row Ids in a Table change. |
|
3702 | 3820 | * store.delListener(listenerId); |
3703 | 3821 | * ``` |
3704 | 3822 | * @example |
3705 | | - * This 111example registers a listener that responds to any change to a |
| 3823 | + * This example registers a listener that responds to any change to a |
3706 | 3824 | * paginated section of the sorted Row Ids of a specific Table. |
3707 | 3825 | * |
3708 | 3826 | * ```js |
|
0 commit comments