`addHasTableCellListener`

The addHasTableCellListener method registers a listener function with the Store that will be called when a Cell is added to or removed from anywhere in a Table as a whole.

addHasTableCellListener(
  tableId: IdOrNull,
  cellId: IdOrNull,
  listener: HasTableCellListener<Store>,
  mutator?: boolean,
): string

	Type	Description
`tableId`	`IdOrNull`	The `Id` of the `Table` to listen to, or `null` as a wildcard.
`cellId`	`IdOrNull`	The `Id` of the `Cell` to listen to, or `null` as a wildcard.
`listener`	`HasTableCellListener<Store>`	The function that will be called whenever the matching `Cell` is added to or removed from anywhere in the `Table`.
`mutator?`	`boolean`	An optional boolean that indicates that the listener mutates `Store` data.
returns	`string`	A unique `Id` for the listener that can later be used to call it explicitly, or to remove it.

The provided listener is a HasTableCellListener function, and will be called with a reference to the Store, the Id of the Table that changed, and the Id of the Table Cell that changed. It is also given a flag to indicate whether the Cell now exists anywhere in the Table (having not done previously), or does not (having done so previously).

You can either listen to a single Table Cell being added or removed (by specifying the Table Id and Cell Id, as the method's first two parameters) or changes to any Table Cell (by providing null wildcards).

Both, either, or neither of the tableId and cellId parameters can be wildcarded with null. You can listen to a specific Row in a specific Table, any Row in a specific Table, a specific Row in any Table, or any Row in any Table.

Use the optional mutator parameter to indicate that there is code in the listener that will mutate Store data. If set to false (or omitted), such mutations will be silently ignored. All relevant mutator listeners (with this flag set to true) are called before any non-mutator listeners (since the latter may become relevant due to changes made in the former). The changes made by mutator listeners do not fire other mutating listeners, though they will fire non-mutator listeners.

Examples

This example registers a listener that responds to a specific Cell being added to or removed from the Table as a whole.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addHasTableCellListener(
  'pets',
  'color',
  (store, tableId, cellId, hasTableCell) => {
    console.log(
      'color cell in pets table ' + (hasTableCell ? 'added' : 'removed'),
    );
  },
);

store.delCell('pets', 'fido', 'color');
// -> 'color cell in pets table removed'

store.setRow('pets', 'felix', {species: 'cat', color: 'brown'});
// -> 'color cell in pets table added'

store.delListener(listenerId);

This example registers a listener that responds to any Cell being added to or removed from the Table as a whole.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addHasTableCellListener(
  null,
  null,
  (store, tableId, cellId, hasTableCell) => {
    console.log(
      `${cellId} cell in ${tableId} table ` +
        (hasTableCell ? 'added' : 'removed'),
    );
  },
);

store.delCell('pets', 'fido', 'color');
// -> 'color cell in pets table removed'
store.setTable('species', {dog: {price: 5}});
// -> 'price cell in species table added'

store.delListener(listenerId);

This example registers a listener that responds to a specific Cell being added or removed, and which also mutates the Store itself.

import {createStore} from 'tinybase';

const store = createStore().setTables({
  pets: {fido: {species: 'dog', color: 'brown'}},
});
const listenerId = store.addHasTableCellListener(
  'pets',
  'color',
  (store, tableId, cellId) =>
    store.setCell('meta', 'update', `${tableId}_${cellId}`, true),
  true,
);

store.delRow('pets', 'fido');
console.log(store.getTable('meta'));
// -> {update: {pets_color: true}}

store.delListener(listenerId);

Since

v4.4.0