addResultCellListener
The addResultCellListener
method registers a listener function with the Queries
object that will be called whenever data in a result Cell
changes.
addResultCellListener(
queryId: IdOrNull,
rowId: IdOrNull,
cellId: IdOrNull,
listener: ResultCellListener,
): string
Type | Description | |
---|---|---|
queryId | IdOrNull | The |
rowId | IdOrNull | The |
cellId | IdOrNull | The |
listener | ResultCellListener | The function that will be called whenever data in the matching result |
returns | string | A unique Id for the listener that can later be used to remove it. |
The provided listener is a ResultCellListener
function, and will be called with a reference to the Queries
object, the Id
of the Table
that changed (which is also the query Id
), the Id
of the Row
that changed, the Id
of the Cell
that changed, the new Cell
value, the old Cell
value, and a GetCellChange
function in case you need to inspect any changes that occurred.
You can either listen to a single result Row
(by specifying a query Id
, Row
Id
, and Cell
Id
as the method's first three parameters) or changes to any result Cell
(by providing null
wildcards).
All, some, or none of the queryId
, rowId
, and cellId
parameters can be wildcarded with null
. You can listen to a specific Cell
in a specific result Row
in a specific query, any Cell
in any result Row
in any query, for example - or every other combination of wildcards.
This example registers a listener that responds to any changes to a specific result Cell
.
const store = createStore().setTable('pets', {
fido: {species: 'dog', color: 'brown'},
felix: {species: 'cat', color: 'black'},
cujo: {species: 'dog', color: 'black'},
});
const queries = createQueries(store).setQueryDefinition(
'dogColors',
'pets',
({select, where}) => {
select('color');
where('species', 'dog');
},
);
const listenerId = queries.addResultCellListener(
'dogColors',
'fido',
'color',
(queries, tableId, rowId, cellId, newCell, oldCell, getCellChange) => {
console.log(
'color cell in fido row in dogColors result table changed',
);
console.log([oldCell, newCell]);
console.log(getCellChange('dogColors', 'fido', 'color'));
},
);
store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'color cell in fido row in dogColors result table changed'
// -> ['brown', 'walnut']
// -> [true, 'brown', 'walnut']
store.delListener(listenerId);
This example registers a listener that responds to any changes to any result Cell
.
const store = createStore().setTable('pets', {
fido: {species: 'dog', color: 'brown', price: 5},
felix: {species: 'cat', color: 'black', price: 4},
cujo: {species: 'dog', color: 'black', price: 5},
});
const queries = createQueries(store)
.setQueryDefinition('dogColors', 'pets', ({select, where}) => {
select('color');
where('species', 'dog');
})
.setQueryDefinition('catColors', 'pets', ({select, where}) => {
select('color');
select('price');
where('species', 'cat');
});
const listenerId = queries.addResultCellListener(
null,
null,
null,
(queries, tableId, rowId, cellId) => {
console.log(
`${cellId} cell in ${rowId} row in ${tableId} result table changed`,
);
},
);
store.setCell('pets', 'fido', 'color', 'walnut');
// -> 'color cell in fido row in dogColors result table changed'
store.setCell('pets', 'felix', 'price', 3);
// -> 'price cell in felix row in catColors result table changed'
store.delListener(listenerId);
v2.0.0