Ajax states

Remote storage of states is fundamental for a state management system, allowing an end user to define a state while using one computer, and then having access to all of their states when using a different computer (when using a login system to identify users of course!). StateRestore makes this possible through its stateRestore.ajax option.

Furthermore, when using remote storage and user management, the option of sharing states between users is opened up. This is enabled automatically when using Ajax storage for state with StateRestore (configurable with stateRestore.sharing), with users able to check a box that will let others see a state, and when loaded to see if others are sharing a state with them.

Server-side libraries

The server-side libraries that we support for DataTables have full support for StateRestore's Ajax capabilities - please see the documentation for each at:

• Node.js
• .NET
• PHP
• Python

On the client-side when using Ajax state storage, all you need to do is set the stateRestore.ajax property to point at the end point you create with the above libraries. Optionally, the property can be defined as an object if you need to configure the Ajax request over the default - e.g. to add a csrf property. See the stateRestore.ajax documentation and DataTable.AjaxOptions for further details.

Ajax protocol

If you have your own server-side processes and don't wish to use the provided DataTables libraries, the following documents the parameters used by StateRestore for its various remote request operations.

Common properties

By default, StateRestore's Ajax requests are all POST requests. As part of the data that StateRestore sends to the server for each request, the following properties are always sent.

Parameter name	Type	Description
action	string	Indicates the action being requested from the server. This will be state-read, state-create, state-edit or state-remove.
path	string	The path name of the web-page.
table	string or The id of the DataTable. Combined withpath` this allows unique identification of each table so saved states can be separated by table.

On return, JSON data is always expected. StateRestore will look for an error property, which, if found, will be displayed to the end user.

Read

When StateRestore requests the states to display to the end user (which it will do when enabled at table initialisation table), the common properties detailed above will be sent to the server with action set to state-read. No other properties are sent (unless otherwise manually configured).

The response expected from the server is a JSON object that contains a data property which is an array of StateRestore.State objects. Please note that the id property in the state is particularly important when using an Ajax data source for the states, as this allows editing actions to take place.

Create

When a new state is created the action parameter will be set to state-create and the following properties will be set in addition to the common ones above:

Parameter name	Type	Description
isDefault	string	Will be true or false (as a string since it is an HTTP parameter) and indicates if the end user has selected this state as their default state or not.
isSharedOut	string	Will be true or false to indicate if the end user wishes to share this state with other users or not.
name	string	The name given to the state.
state	string	The state object itself. Please note that this is a JSON string (JSON.stringify()) rather than an actual object. This is so it can be written into a regular text field in a database, although you can parse the JSON and store in a JSON column if you prefer.

On return, the JSON data should contain a data property which is an array containing the StateRestore.State object for the newly created state. As above, make sure that the id property is set.

Edit

An edit action will be sent when the end user updates either the properties of the state (name, sharing, etc), or replaces the state object itself. In this case, the action parameter will be state-edit and the following parameters are sent in addition to the common parameters above:

Parameter name	Type	Description
id	string	State ID property
isDefault	string	Will be true or false (as a string since it is an HTTP parameter) and indicates if the end user has selected this state as their default state or not.
isSharedOut	string	Will be true or false to indicate if the end user wishes to share this state with other users or not.
name	string	The name given to the state.
state	string	The state object itself. Please note that this is a JSON string (JSON.stringify()) rather than an actual object. This is so it can be written into a regular text field in a database, although you can parse the JSON and store in a JSON column if you prefer.

As with the creation action, the JSON return for an edit action, should contain a data property which is an array containing the StateRestore.State object for the edited state.

Delete

For the delete action, the client-side will send action as state-remove along with an array of the state ids to be removed:

Parameter name	Type	Description
ids	array	IDs of the states that are to be deleted.

In this case, the JSON response from the server can be an empty object. The error property can be set if an error occurs.