Docs

Grid State Persistence

ZingGrid has the ability to preserve its state between page loads. This feature can easily be enabled by adding the preserve-state-id to your grid!

Specify which states in preserve with preserve-state-options. Some of the states preserved are:

  • Column position - columnposition
  • Column visibility - columnvisibility
  • Column width - columnwidth
  • Filter - filter
  • Frozen columns - columnfrozen
  • Frozen rows - rowfrozen
  • Layout - layout
  • Page - page
  • Page size - pagesize
  • Row group - rowgroup
  • Row Selector - rowselector
  • Search - search
  • Selector - selector
  • Sort - sort
  • More Coming!

Enabling State Persistence

To state preserving state on your grid, add the preserve-state-id attribute to the <zing-grid> tag. Set this attribute to a unique string that will be used as the ID to store the grid's state in. Grids with the same preserve-state-id will share states.

<zing-grid preserve-state-id="featuresGridState"></zing-grid>

Grid with State

Here is a complete grid with state preserved:

Top

Saving Specific States

You may not want to preserve all state in your grid. Use the preserve-state-options attribute to specify which state(s) to preserve:

<zing-grid
  preserve-state-id="featuresGridState2"
  preserve-state-options="columnvisibility,filter,sort">
</zing-grid>
Top

Custom State Functions

To trigger an action after the state changes, is to set the following attributes to the name of the function.

The attribute preserve-state-save executes the specified function when the grid saves the state. The function should contain two arguments:

  • id - the id assigned to preserve-state-id
  • data - the state of the grid

There is also the preserve-state-load attribute, which executes the function when state is loaded into the grid. The function takes in one argument:

  • id - the id assigned to preserve-state-id
<zing-grid
  preserve-state-id="featuresGridState3"
  preserve-state-load="loadMe"
  preserve-state-save="saveMe">
</zing-grid>
<script>
  function loadMe(id) {
    console.log('id: ', id);
  };
  function saveMe(id, data) {
    console.log('id: ', id);
    console.log('data: ', data);
  };
</script>
Top

Setting State

To update the state of the grid, use either of the API methods:

  • setState(data) - Sets the current (all) states
  • setStateField(field, data) - Sets the specified state

The best way to get the state data for loading into the grid is by using preserve-state-load to retrieve the data.

<zing-grid preserve-state-id="featuresGridState4"></zing-grid>
<script>
  // Set sort state
  let zgRef = document.querySelector('zing-grid');
  zgRef.executeOnLoad(() => {
    zgRef.setState({"sort":{"index":"director","order":1}});
    // alternatively
    // zgRef.setStateField('sort', {"index":"director","order":1});
  });
</script>
Top

[features: grid state persistence]