Upgrading to ag-Grid v25 server-side row model

Kiril Matev -

ag-Grid v25 delivers many improvements in the server-side row model, as described in the What's New in ag-Grid v25 post. This post covers what has changed and how to update your code to migrate to ag-Grid v25 server-side row model.

Note: This list of breaking changes *only* applies if you’re using the ag-Grid server-side row model. If you’re using the client-side row model or the infinite row model you do not need to make any of the changes listed below.

Change in the default server-side row model loading strategy

There is a new property serverSideStoreType which sets the type of row store (data loading strategy) the server-side row model is using at a particular level of grouping. Server-side row stores are a new concept and there are two store types, partial (equivalent to the old server-side row model) and full (new behavior), as described in the documentation.

It was decided to make the full store the default behavior of the server-side row model (in v25) despite creating a breaking change in the way data is loaded by default. The reason is that the full store offers much more functionality and is easier to learn before moving to a partial store, thus it's a breaking change for all current users with the value of simplifying how the server-side row model works.

See a detailed comparison between full and partial stores here.

Changes needed:

If you’d like to upgrade to v25 keeping the previous (pre-ag-Grid v25) server-side row model behavior, you’ll need to set the new property serverSideStoreType to partial. I'd highly recommend this as a first step to allow you to benefit from all the improvements we've made and still be able to deploy your application without significant re-testing due to the new default server-side row model behavior.

If you do not explicitly set serverSideStoreType to partial, the new default server-side row model behavior in ag-Grid v25 will load all records on that level in one go instead of in blocks as before. This will give you significant benefits in functionality such as transaction updates and local sorting/filtering that's not possible if you load the rows in blocks setting serverSideStoreType to partial. However as a result of this, you may see an increase in the initial loading time due to the larger number of records loaded initially.

If the resulting increase of loading time affects the user experience, please revert to the previous server-side row model behavior – loading data in blocks, by setting new property serverSideStoreType to partial.

childrenCache property renamed to childStore

The property RowNode.childrenCache is now called RowNode.childStore. This is an undocumented property, and we strongly recommend against using it. However if you are using it, please update your code accordingly.

Changes needed:

Any references to RowNode.childrenCache should be changed to RowNode.childStore.

Changes in IServerSideGetRowsParams

In IServerSideGetRowsParams we've added the success and fail callbacks alongside the successCallback and failCallback members respectively. Note that the parameters of success are different from those of successCallback as follows:

The old (pre v25) successCallback had the following prototype:

successCallback(rowsThisPage: any[], lastRow: number): void;

The new (v25) success callback has the prototype below with a new parameter type LoadSuccessParams:

success(params: LoadSuccessParams): void;

For additional information on the LoadSuccessParams, please take a look at the documentation for the success callback and the fail callback.

Changes needed:

No code changes are absolutely required at this point - successCallback and failCallback will work as before.

However, in a future release we will deprecate and eventually remove successCallback and failCallback and only the success and fail callbacks will be available.

This is why we recommend to change your code to use success instead of successCallback with the new LoadSuccessParams, as documented here.

Also, we recommend to change any references to failCallback to fail. No further changes needed on this as the prototypes of these two callbacks are the same.

purgeServerSideCache method is deprecated

The purgeServerSideCache method is deprecated and calling it has no effect - you'll get a console warning about that. This method is now replaced with refreshServerSideStore which provides the same functionality as purgeServerSideCache when used with purge=true as an optional argument. When using refreshServerSideStore without setting the purge parameter, this will perform a silent data refresh without showing the loading indicator, but instead updating the data in place. Please see more about server-side row model refresh here.

Changes needed:

Change all references to purgeServerSideCache to refreshServerSideStore. This will now perform in-place (silent) refreshes to the grid data, unlike the previous behavior which displayed loading indicators during the data loading. We hope this will improve the user experience so your users won't have to see loading indicators until you get the new data.

If you’d like to keep the previous behavior and completely reset the data, reload it from the server while displaying loading indicators, change the call like this:
refreshServerSideStore({ route: route, purge: true}).

Summary

I hope this is useful to help you migrate to ag-Grid v25. We're excited about the many improvements this release offers and we're keen to assist with any questions you have during the migration process.

Suggested resources

ag-Grid v25 is a release with a lot of improvements to the server-side row model and beyond. Learn about all the improvements with examples in the What's New in ag-Grid v25 post.

Happy coding!