Framework:Javascript Data GridReact Data GridAngular Data GridVue Data Grid

React Data Grid: SSRM Transactions

This section show how rows can be added, removed and updated using the Server-Side Transaction API.

Server-Side Transactions require row ID's to be supplied to grid via getRowId().

Transaction API

The SSRM Transaction API allows rows to be added, removed or updated in the grid:

applyServerSideTransaction
Function
Apply transactions to the server side row model.
applyServerSideTransaction = (
    transaction: ServerSideTransaction
) => ServerSideTransactionResult | undefined;

interface ServerSideTransaction {
  // The Row Store to apply the transaction to, ie what group level.
  // eg ['Ireland','2002'] to update the child store found after expanding Ireland and 2002 groups.
  // Passing in blank to empty applies the transaction to the top level.
  route?: string[];
  // Index position to add at. If missing, rows will be added to the end. 
  addIndex?: number;
  // Rows to add 
  add?: any[];
  // Rows to remove 
  remove?: any[];
  // Rows to update 
  update?: any[];
}

interface ServerSideTransactionResult {
  // The status of applying the transaction. 
  status: ServerSideTransactionResultStatus;
  // If rows were added, the newly created Row Nodes for those rows. 
  add?: IRowNode[];
  // If rows were removed, the deleted Row Nodes. 
  remove?: IRowNode[];
  // If rows were updated, the updated Row Nodes. 
  update?: IRowNode[];
}

enum ServerSideTransactionResultStatus {
  // Transaction was successfully applied 
  Applied = 'Applied'
  // Store was not found, transaction not applied.
  // Either invalid route, or the parent row has not yet been expanded.
  StoreNotFound = 'StoreNotFound'
  // Store is loading, transaction not applied.
  StoreLoading = 'StoreLoading'
  // Store is loading (as max loads exceeded), transaction not applied.
  StoreWaitingToLoad = 'StoreWaitingToLoad'
  // Store load attempt failed, transaction not applied.
  StoreLoadingFailed = 'StoreLoadingFailed'
  // Store is type Partial, which doesn't accept transactions
  StoreWrongType = 'StoreWrongType'
  // Transaction was cancelled, due to grid.
  // Callback isApplyServerSideTransaction() returning false
  Cancelled = 'Cancelled'
}

These operations are shown in the snippet below:

gridApi.applyServerSideTransaction({ 
    add: [ 
        { tradeId: 101, portfolio: 'Aggressive', product: 'Aluminium', book: 'GL-62472', current: 57969 }
    ],
    update: [
        { tradeId: 102,  portfolio: 'Aggressive', product: 'Aluminium', book: 'GL-624723', current: 58927 }
    ],
    remove: [
        { tradeId: 103 }
    ]
});

The following example demonstrates add / update and remove operations via the Server-Side Transaction API. Note the following:

  • Add Above Selected - adds a row above the selected row using theaddIndex property as rows are added at the end by default.
  • Updated Selected - updates the 'current' value on the selected row.
  • Removed Selected - removes the selected row.

Row Grouping

To use transactions while using row grouping, transactions need to be applied to the specific row group. This is done by providing a route when applying the transaction. It is also necessary to inform the grid when group rows are updated, added or removed.

The snippet below demonstrates creating a group row transaction for rows which are the first of their group, as the leaf rows will be requested via getRows when the group is expanded.

// create the group row at the root level (only if it's the first row for this group)
gridApi.applyServerSideTransaction({
 	route: [],
 	add: [{ portfolio: 'Aggressive' }]
 });

// otherwise, create the leaf node inside of the 'Aggressive' group
gridApi.applyServerSideTransaction({
 	route: ['Aggressive'],
 	add: [row]
 });

In the example below, note the following:

  • To add a new row, if the group didn't previously exist, then the route is omitted and the group row is added. If it did previously exist, then the group route is provided and the leaf node is added.
  • To delete a row, if the group row would be deleted then a transaction needs to be applied to remove this group row instead of the leaf row.
  • To move a row between groups, the row needs to be deleted from the old group with one transaction, and added to the new group with another.

Asynchronous Updates

When processing many updates rapidly, the grid will perform more smoothly if the changes are batched (as this can prevent excessive rendering). The grid can batch these changes for you without negatively impacting the user experience, and in most cases improving it.

applyServerSideTransactionAsync
Function
Batch apply transactions to the server side row model.
applyServerSideTransactionAsync = (
    transaction: ServerSideTransaction,
    callback?: (res: ServerSideTransactionResult) => void
) => void;

interface ServerSideTransaction {
  // The Row Store to apply the transaction to, ie what group level.
  // eg ['Ireland','2002'] to update the child store found after expanding Ireland and 2002 groups.
  // Passing in blank to empty applies the transaction to the top level.
  route?: string[];
  // Index position to add at. If missing, rows will be added to the end. 
  addIndex?: number;
  // Rows to add 
  add?: any[];
  // Rows to remove 
  remove?: any[];
  // Rows to update 
  update?: any[];
}

interface ServerSideTransactionResult {
  // The status of applying the transaction. 
  status: ServerSideTransactionResultStatus;
  // If rows were added, the newly created Row Nodes for those rows. 
  add?: IRowNode[];
  // If rows were removed, the deleted Row Nodes. 
  remove?: IRowNode[];
  // If rows were updated, the updated Row Nodes. 
  update?: IRowNode[];
}

enum ServerSideTransactionResultStatus {
  // Transaction was successfully applied 
  Applied = 'Applied'
  // Store was not found, transaction not applied.
  // Either invalid route, or the parent row has not yet been expanded.
  StoreNotFound = 'StoreNotFound'
  // Store is loading, transaction not applied.
  StoreLoading = 'StoreLoading'
  // Store is loading (as max loads exceeded), transaction not applied.
  StoreWaitingToLoad = 'StoreWaitingToLoad'
  // Store load attempt failed, transaction not applied.
  StoreLoadingFailed = 'StoreLoadingFailed'
  // Store is type Partial, which doesn't accept transactions
  StoreWrongType = 'StoreWrongType'
  // Transaction was cancelled, due to grid.
  // Callback isApplyServerSideTransaction() returning false
  Cancelled = 'Cancelled'
}

When using asynchronous transactions, the grid delays any transactions received within a time window (specified using asyncTransactionWaitMillis) and executes them together when the window has passed.

The snippet below demonstrates three asynchronous transactions applied sequentially, however because these transactions are asynchronously batched, the grid would only update the DOM once.

// due to asynchronous batching, the following transactions are applied together preventing unnecessary DOM updates
gridApi.applyServerSideTransactionAsync({ 
    add: [{ tradeId: 101, portfolio: 'Aggressive', product: 'Aluminium', book: 'GL-62472', current: 57969 }],
});

gridApi.applyServerSideTransactionAsync({ 
    update: [{ tradeId: 102,  portfolio: 'Aggressive', product: 'Aluminium', book: 'GL-624723', current: 58927 }],
});

gridApi.applyServerSideTransactionAsync({ 
    remove: [{ tradeId: 103 }],
});

In the example below, note the following:

  • After starting the updates, 1 row is created, 10 rows are updated, and 1 rows is deleted every 10 milliseconds.
  • The transactions are batched, and only executed once every second.

Showcase Example

The following demonstrates a more complex example of transactions, it shows subscribing to a source of updates to provide the changes, while using dynamic row grouping, aggregation, and child counts. All of which react to the changes caused by the transactions.

In the example below, note the following:

  • After starting the updates, 2 rows are created, 5 rows are updated, and 2 rows are deleted once every second.
  • Groups are created or destroyed when necessary by using transactions.
  • The group panel has been enabled, allowing a dynamic configuration of groups.
  • The group child counts and aggregations update in sync with changes to the leaf rows.

Next Up

Continue to the next section to learn about Load Retry with the SSRM.