PersistentState

Table of contents

• Description
• Options
  • persistentState
• Methods
  • destroy
  • disablePlugin
  • enablePlugin
  • isEnabled
  • loadValue
  • resetValue
  • saveValue
  • updatePlugin

Description

Save the state of column sorting, column positions and column sizes in local storage to preserve table state between page reloads.

In order to enable data storage mechanism, Options#persistentState option must be set to true.

When persistentState is enabled it exposes 3 hooks:

• Hooks#persistentStateSave - Saves value under given key in browser local storage.
• Hooks#persistentStateLoad - Loads value, saved under given key, from browser local storage. The loaded value will be saved in saveTo.value.
• Hooks#persistentStateReset - Clears the value saved under key. If no key is given, all values associated with table will be cleared.

Options

persistentState

Source code (opens new window)

persistentState.persistentState : boolean

Turns on saving the state of column sorting, column positions and column sizes in local storage.

You can save any sort of data in local storage to preserve table state between page reloads. In order to enable data storage mechanism, persistentState option must be set to true (you can set it either during Handsontable initialization or using the updateSettings method). When persistentState is enabled it exposes 3 hooks:

persistentStateSave (key: String, value: Mixed).

• Saves value under given key in browser local storage.

persistentStateLoad (key: String, valuePlaceholder: Object).

• Loads value, saved under given key, form browser local storage. The loaded value will be saved in valuePlaceholder.value (this is due to specific behaviour of Hooks.run() method). If no value have been saved under key valuePlaceholder.value will be undefined.

persistentStateReset (key: String).

• Clears the value saved under key. If no key is given, all values associated with table will be cleared.

Note: The main reason behind using persistentState hooks rather than regular LocalStorage API is that it ensures separation of data stored by multiple Handsontable instances. In other words, if you have two (or more) instances of Handsontable on one page, data saved by one instance won't be accessible by the second instance. Those two instances can store data under the same key and no data would be overwritten.

Important: In order for the data separation to work properly, make sure that each instance of Handsontable has a unique id.

Default: false Example

// enable the persistent state plugin
persistentState: true,

Methods

destroy

Source code (opens new window)

persistentState.destroy()

Destroys the plugin instance.

disablePlugin

Source code (opens new window)

persistentState.disablePlugin()

Disables the plugin functionality for this Handsontable instance.

enablePlugin

Source code (opens new window)

persistentState.enablePlugin()

Enables the plugin functionality for this Handsontable instance.

isEnabled

Source code (opens new window)

persistentState.isEnabled() ⇒ boolean

Checks if the plugin is enabled in the handsontable settings. This method is executed in Hooks#beforeInit hook and if it returns true than the PersistentState#enablePlugin method is called.

loadValue

Source code (opens new window)

persistentState.loadValue(key, saveTo)

Loads the value from local storage.

Param	Type	Description
key	string	Storage key.
saveTo	object	Saved value from local storage.

resetValue

Source code (opens new window)

persistentState.resetValue(key)

Resets the data or all data from local storage.

Param	Type	Description
key	string	[optional] Storage key.

saveValue

Source code (opens new window)

persistentState.saveValue(key, value)

Saves the data to local storage.

Param	Type	Description
key	string	Storage key.
value	Mixed	Value to save.

updatePlugin

Source code (opens new window)

persistentState.updatePlugin()

Updates the plugin state. This method is executed when Core#updateSettings is invoked.