StateRestore 2
StateRestore 2.0 is here! This extension adds state management controls to DataTables, with an easy-to-use UI for the end user, letting them select between different table states with a simple button click. StateRestore is the third library released in the DataTables Plus suite - a premium set of extensions that enhance the capabilities of DataTables.
Example
As always, an example is worth a thousand words. In the example below stateCreate and statesTable are used to create the buttons for the state management UI, with StateRestore in its default configuration:
| Name | Position | Office | Salary |
|---|---|---|---|
| Tiger Nixon | System Architect | Edinburgh | $320,800 |
| Garrett Winters | Accountant | Tokyo | $170,750 |
| Ashton Cox | Junior Technical Author | San Francisco | $86,000 |
| Cedric Kelly | Senior JavaScript Developer | Edinburgh | $433,060 |
| Airi Satou | Accountant | Tokyo | $162,700 |
| Brielle Williamson | Integration Specialist | New York | $372,000 |
| Herrod Chandler | Sales Assistant | San Francisco | $137,500 |
| Rhona Davidson | Integration Specialist | Tokyo | $327,900 |
| Colleen Hurst | JavaScript Developer | San Francisco | $205,500 |
| Sonya Frost | Software Engineer | Edinburgh | $103,600 |
| Jena Gaines | Office Manager | London | $90,560 |
| Quinn Flynn | Support Lead | Edinburgh | $342,000 |
| Charde Marshall | Regional Director | San Francisco | $470,600 |
| Haley Kennedy | Senior Marketing Designer | London | $313,500 |
| Tatyana Fitzpatrick | Regional Director | London | $385,750 |
| Michael Silva | Marketing Designer | London | $198,500 |
| Paul Byrd | Chief Financial Officer (CFO) | New York | $725,000 |
| Gloria Little | Systems Administrator | New York | $237,500 |
| Bradley Greer | Software Engineer | London | $132,000 |
| Dai Rios | Personnel Lead | Edinburgh | $217,500 |
| Jenette Caldwell | Development Lead | New York | $345,000 |
| Yuri Berry | Chief Marketing Officer (CMO) | New York | $675,000 |
| Caesar Vance | Pre-Sales Support | New York | $106,450 |
| Doris Wilder | Sales Assistant | Sydney | $85,600 |
| Angelica Ramos | Chief Executive Officer (CEO) | London | $1,200,000 |
| Gavin Joyce | Developer | Edinburgh | $92,575 |
| Jennifer Chang | Regional Director | Singapore | $357,650 |
| Brenden Wagner | Software Engineer | San Francisco | $206,850 |
| Fiona Green | Chief Operating Officer (COO) | San Francisco | $850,000 |
| Shou Itou | Regional Marketing | Tokyo | $163,000 |
| Michelle House | Integration Specialist | Sydney | $95,400 |
| Suki Burks | Developer | London | $114,500 |
| Prescott Bartlett | Technical Author | London | $145,000 |
| Gavin Cortez | Team Leader | San Francisco | $235,500 |
| Martena Mccray | Post-Sales support | Edinburgh | $324,050 |
| Unity Butler | Marketing Designer | San Francisco | $85,675 |
| Howard Hatfield | Office Manager | San Francisco | $164,500 |
| Hope Fuentes | Secretary | San Francisco | $109,850 |
| Vivian Harrell | Financial Controller | San Francisco | $452,500 |
| Timothy Mooney | Office Manager | London | $136,200 |
| Jackson Bradshaw | Director | New York | $645,750 |
| Olivia Liang | Support Engineer | Singapore | $234,500 |
| Bruno Nash | Software Engineer | London | $163,500 |
| Sakura Yamamoto | Support Engineer | Tokyo | $139,575 |
| Thor Walton | Developer | New York | $98,540 |
| Finn Camacho | Support Engineer | San Francisco | $87,500 |
| Serge Baldwin | Data Coordinator | Singapore | $138,575 |
| Zenaida Frank | Software Engineer | New York | $125,250 |
| Zorita Serrano | Software Engineer | San Francisco | $115,000 |
| Jennifer Acosta | Junior JavaScript Developer | Edinburgh | $75,650 |
| Cara Stevens | Sales Assistant | New York | $145,600 |
| Hermione Butler | Regional Director | London | $356,250 |
| Lael Greer | Systems Administrator | London | $103,500 |
| Jonas Alexander | Developer | San Francisco | $86,500 |
| Shad Decker | Regional Director | Edinburgh | $183,000 |
| Michael Bruce | JavaScript Developer | Singapore | $183,000 |
| Donna Snider | Customer Support | New York | $112,000 |
As you will be able to see, the "Saved states" button will show a modal with the state management UI. You can also use statesList if you prefer a dropdown list of states (example here).
The initialisation code for the above table simply defines the buttons to show in a specific location, and enables the stateRestore option:
new DataTable('#blog-sr-demo', {
layout: {
topStart: {
buttons: ['stateCreate', 'statesTable']
}
},
stateRestore: true
});
New features
StateRestore 2.0 is a complete rewrite of the library with the following headline new features:
- Ajax as first class storage for states
- Ability to set a default state
- Central configuration with a
stateRestoreoption - Table view for state management
- Smaller size
A primary focus for 2.0 was adding Ajax state storage as a first class part of the software. Fundamentally, states are most useful in a multi-user system where each user can define their own states. The ability to share states between users also falls out of this option, and when Ajax storage is used for StateRestore (stateRestore.ajax), users now have the option of selecting to share a state or not.
The server-side libraries for DataTables have all been updated to provide support for StateRestore with a new StateRestore class. An Ajax example is available and is part of the demo apps, along with full documentation for the Ajax data used.
Another goal of the rewrite was to architect it such that a state could be designated as a default state - that is, one which the table will be placed into when the table is initialised. As part of this work, the centralised stateRestore option was introduced for easy and consistent configuration.
The dropdown list view for states is simple and attractive, but it can become crowded if you expect your end users to have a large number of states. For this reason, a new table-based UI has been added (statesTable - shown in the example above), which has all the benefits of DataTables (ordering, search) allowing easy navigation of a large number of states.
Finally, for the headline features, all of this is provided in a 23K (minified, not gzipped) library, almost half the size of v1. As with all DataTables extensions, StateRestore is written in Typescript and dependency free, other than DataTables itself.
Upgrading
If you are updating from StateRestore v1, please be aware that there is a good chance you will need to make some changes to how the software is configured - you certainly will if you are using Ajax storage or any other options beyond the defaults. This is due to the introduction of the new stateRestore option, which significantly simplifies configuration for StateRestore.
An update note with further details is available. If you run into any issues upgrading, please get in touch.
Feedback welcome
As always with DataTables and its extensions, I very much welcome feedback. Often the software is used for cases which I didn't necessarily expect, and features that might be useful to you weren't immediately apparent to be during development! Please get in touch if you have any feedback on StateRestore and how you would like to see it develop.