It is possible to get the grid to refresh its rows. In other words reload previously loaded rows. This is useful when the data has changed at the source (typically on the server) and the UI needs refresh.
The grid has the following API's to assist with refreshing:
Refresh a server-side store. If you pass no parameters, then the top level cache is purged. To purge a child cache, pass in the string of keys to get to the child cache.
Returns an object representing the state of the cache. This is useful for debugging and understanding how the cache is working.
The following example demonstrates the refresh API. The following can be noted:
- Button Refresh Top Level refreshes the top level store. Note the Version column has changed its value.
- Button Refresh [Canada] refreshes the Canada cache only. To see this in action, make sure you have Canada expanded. Note the Version column has changed it's value.
- Button Refresh [Canada,2002] refreshes the 2002 cache under Canada only. To see this in action, make sure you have Canada and then 2002 expanded. Note the Version column has changed it's value.
- Button Print Block State prints the state of the blocks in the cache to the console.
- Toggle Purge to change whether loading rows are shown or not during the refresh.
When a purge is executed (
params.purge=true) then the data is replaced with loading rows
while the data is refreshed. There are a few more subtle differences between purging and
refreshing which are as follows:
- While purging, the loading icons prevent the user from interacting with the data while the rows are re-fetched.
- When purging, all open groups will always get closed and children destroyed. This is explained in more detail
in the section Maintaining Open Groups below.
- When Partial Store is used (i.e. data is loaded in blocks), purging will destroy all blocks
and remove them from the cache and only re-create blocks needed to show data the user is looking at.
For example if the user had scrolled down and 5 blocks are in the cache, after a purge it could be only 1 block exists in the cache after purging. This means only one block request is sent to the server.
Refreshing however will refresh all existing blocks. Thus if 5 blocks exist in the cache, all blocks will get refreshed resulting in 5 requests sent to the server.
It is possible to have open groups remain open during a refresh, thus maintaining the context of open groups.
Maintaining open groups is achieved when all of the following are configured:
- Full Store (
serverSideStoreType=full). When using Partial Store, groups and children will be lost.
- Refreshing (
params.purge=false). When using a purge, groups and children will be lost.
- Row IDs are provided (
getRowId()implemented, see Row IDs). If not providing Row IDs, groups and children will be lost
When all the above is true, when a refresh is done, open groups will remain open and children will be kept.
The example below shows refreshing using the Full Store and keeping group state. The example is similar to the
previous example with the addition
getRowId() is implemented. Note the following:
- When 'Purge' is not checked, refreshing using any refresh button will maintain any open groups and children at that level.
For example expand 'United States' and hit 'Refresh Top Level' - note that the top level countries are refreshed (the version column changes once the load is complete) and the open 'United States' group is left open and the child rows (displaying year groups) are left intact.
- When 'Purge' is checked, refreshing using any refresh button will close all open groups and destroy all children at that level.
For example expand 'United States' and hit 'Refresh Top Level' - note that the list of countries is reset, including closing 'United States' and losing all child rows to 'United States'. When 'United States' is expanded again, the child rows are loaded again from scratch.
Because the grid is getting provided ID's with via
getRowId() it allows the grid to update rows rather than
replace rows. This also means when grid property
enableCellChangeFlash = true the cells will flash when their data
getRowId() is not implemented, rows are replaced and cells are re-created from scratch, no flashing
If using the Partial Store, the grid does not provide for keeping open groups. Refreshing a Partial Store will always reset groups and destroy children.
This is because the Partial Store loads rows in blocks, so it's unreliable to expect rows that existed before to exist in the new load, as the row could appear in a different block.
If you are using the Partial Store and need to restore groups to their previously open state, then this logic can be implemented in your application using the Open by Default API.
Continue to the next section to learn how to perform Pivoting.