Skip to content

Persist State

A common requirement for web apps is to save the user customization and settings when interacting with your app, and then restore them once he/she logs back at some point in the future.

The Guriddo jqGrid exposes the capability to save and restore settings that were previously applied to its structure using the $.jgrid.saveState and $.jgrid.loadState methods from its API. These methods allow you to serialize the grid current state, when needed, and then recover it at certain point in time.

Saving State

The method saves the current state of the grid using the Storage JavaScript feature. If the Storage is not present the grid can return the state as string.

Calling conventions:

...
$.jgrid.saveState( grid_id, [options]);
...

parameters

  • string grid_id is id of the grid. The string should not begin with '#'
  • object options - a set of options for saving the state.

return
The method return string describing the current state of the grid, but not the data.

Warning

When a saveSate method is planed to be implemented and navigator is present it is needed to set the grid option storeNavOptions to true in order to save the build in and custom actions in the navigator

To save everthing it is needed to do:

$("#jqGrid").jqGrid({
  ...
  storeNavOptions : true,
  pager: "Pager"
  ...
});
$("#jqGrid").jqGrid("navGrid", "Pager", {...});
...
$.jgrid.saveState( 'jqGrid');

Saving options

The object options have the following properties with default values:

options = {
  useStorage : true,
  storageType : "localStorage",
  beforeSetItem : null,
  compression: false,
  compressionModule :  'LZString',
  compressionMethod : 'compressToUTF16',
  debug : false,
  saveData : true
}
  • useStorage - boolean - default true. Enable/disable saving the sate to Storage. If set to false use the return string which is the state of the grid without data.
  • storageType - string - default 'localStorage'. Set the storage type. Can be loacalStorage or sessionStorage. For difference between these see here
  • beforeSetItem - function - function to execute before to store the state to the Storage. Parameter passed to this function is the grid state as json string.
  • compression - boolean - default false. Enable/disable compression of the state before to be saved into the Storage. In order to use this it is needed to load the plugin which do the compression. See parameters below.
  • compressionModule - string - default 'LZString'. The module responsible for the compression. This module can be gzip, zip or LZString. We preffer to use LZString since it is designed to compress the data in Storage.
  • compressionMethod - string - default 'compressToUTF16' the method from compressionModule which compress the data. Actually using the compressionModule and compressionMethod we execute the following to compress the grid sate: window[compressionModule][compressionMethod](gridstate), where gridstate is a string.
  • debug - boolean - default false. This option is used for support purposes. When set to true a save dialog appear with the data and state of the grid. Save this to a file and it can be send to the support.
  • saveData - boolean - default true. If set to false the data is not saved into the storage and when restoring a empty data is inserted to the grid.

Loading State

The method restores a Guriddo jqGrid state saved with loadState . The method can be applied either on existing grid or on grid (table) definition.

Calling convention:

...
$.jgrid.loadState( grid_id, [json_string], [options]);
...

parameters

  • string grid_id is id of the grid to be restored. The string should not begin with '#'. Th
  • string json_string - optitional string to be restored.
  • object options - optional - a set of options for restoring the grid state.

return
none

Loading options

The object options have the following properties with default values:

options = {
  useStorage : true,
  storageType : "localStorage",
  clearAfterLoad: false,  
  beforeSetGrid : null,
  afterSetGrid : null,
  decompression: false,
  decompressionModule :  'LZString',
  decompressionMethod : 'decompressFromUTF16',
  restoreData : true
}
  • useStorage - boolean - default true. Enable/disable loading the sate from Storage. If set to false a json_string parameter should be set. If use a Storeage the string can be empty.
  • storageType - string - default 'localStorage'. Set the storage type for loading, previously set with loadState. Can be loacalStorage or sessionStorage. For difference between these see here
  • clearAfterLoad - boolean - default false. If set to true clears the jqGrid localStorage items aftre load.
  • beforeSetGrid - function - function to execute before to restore the state from the Storage. Parameter passed to this function is the grid options as object. The event should return the new grid parameters. This is a way to modify some parameters before the creation of the grid.
  • afterSetGrid - function - function to be executed after the grid is restored. Parameters passed to this function is the grid object.
  • decompression - boolean - default false. Enable/disable decompression of the grid state before to be restored. In order to use this it is needed to load the plugin which do the decompression compressed with method in saveState. See parameters below.
  • decompressionModule - string - default 'LZString'. The module responsible for the decompression. This module can be gzip, zip or LZString. We preffer to use LZString since it is designed to compress/decompress data in Storage.
  • compressionMethod - string - default 'ecompressFromUTF16' the method from decompressionModule which decompress the data. Actually using the decompressionModule and decompressionMethod we execute the following to decompress the grid sate: window[decompressionModule][decompressionMethod](grid_string), where grid_string is a compressed string.
  • restoreData - boolean - default true. If set to false the data is not restored into the grid.

Note

To restore from string set the useStorage option to false and json_string parameter to non empty string. To restore from localStorage or sessionStorage set the useStorage to true in options and json_string parameter to empty string

Other methods

The methods below are used in saveState and loadState methods, but actually they can be used separately to meet certain requirements.

$.jgrid.isGridInStorage( grid_id, options )

Determine if the grid is saved in the sessionStorage or localStorage.

parameters

  • string grid_id - the id of the grid without '#'.
  • object options - the only property is 'storageType' with default value localStorage. Can be sessionStorage.

return
true if the grid is in storage, otherwise false.

Example:
To check the grid in session storage do:

if( $.jgrid.isGridInStorage('grid', {storageType:'sessionStorage'}) ) {
  // do something
} else {
  alert('grid is not in session storage');
}

$.jgrid.setRegional( grid_id, [options] )

Change the language in grid dynamically. This method uses Storage to perform its action. For more information refer Change language dynamically

parameters

  • string grid_id - the id of the grid. This should be the id of a table element.
  • object options - a set of options for saving the grid state and restore it. Actually the options can contain any valid options from loadSate and saveState methods above, and the option regional to change the last used language language.

return
none

$.jgrid.jqGridImport( grid_id, options )

Create a jqGrid from json or xml string, created with jqGridExport method (see below) with possibility to load the parameter data via ajax.

parameters

  • string grid_id - the id of the grid. This should be the id of a table element.
  • object options - a set of options for creating jqgrid. See the default values and description below.

return
none

The options parameter have the following properties and default values:

options = {
  imptype : "xml",
  impstring: "",
  impurl: "",
  mtype: "GET",
  impData : {},
  xmlGrid :{
    config : "root>grid",
    data: "root>rows"
  },
  jsonGrid :{
    config : "grid",
    data: "data"
  },
  ajaxOptions :{},
  importComplete : null
}
  • string imptype. Default is 'xml'. Determine how the data parameters ar obtained to construct the grid. Can be 'xml', 'json', 'xmlstring', 'jsonstring'. If a xml or json is set a ajax call is set to obtain the data. If 'xmlstring' or 'jsonstring' is used a local string should be used. See below.
  • string impstring. This parameter should be set if imptype is 'xmlstring' or 'jsonstring' and is actually the string exported with jqGridExport.
  • string impurl - valid url to the configuration when imptype xml or json. The data is obtained via ajax request
  • sting mtype - default 'GET'. Determines the type of request. Can be GET or POST
  • object impData - default empty object. Additional data that can be passed to the url in pair name:value
  • object xmlGrid - describes from where to read the xml configuration and from where the data if any. See the default values above. The option config describes the configuration (jqGrid options) tag. The option data describes the data tag.
  • object jsonGrid - describes from where to read the json configuration and from where the data if any. See the default values above. The option config describes the configuration (jqGrid options) tag. The option data describes the data tag.
  • object ajaxOptions - Additional options which can be passed to the ajax request
  • function importComplete. This event is called after the successfully import and when the grid is constructed. To this event we pas the request from server. Use this event to set additional parameters in the grid or to construct the navigator.

jqGridExport( options )

Export the current grid configuration as string.

Calling convention:

("#grid_id").jqGrid('jqGridExport', options);

Where

  • string grid_id is the id of the already constructed grid
  • object options is object of pair name:value to set different configuration listed bellow

Note

Please take in account how this method is called in difference to the previous one.

options = {
  exptype : "xmlstring",
  root: "grid",
  ident: "\t",
  addOptions : {}
}
  • string exptype. Determines the type of the export. Two possible values are accepted - xmlstring - the grid configuration is exported as xml string and jsonstring - the configuration is exported as jsonstring xmlstring
  • string root . This element set the name of the root element when we export the data - i.e. the grid configuration is enclosed in this element. For xmlstring the exported data can look like this: <rootelement>jqgrid_configuration </rootelement>. For json string we have {rootelement:{grid_configuration}}. Deafult is 'grid'
  • string ident. Tab or indent string for pretty output formatting Default \t

Since some columns in the grid are created dynamically (row numbers, subgrids and etc) the export method intelligently removes all the not needed data and make the string configuration ready for use in jqGridImport

Warning

When using these methods the pager parameter in grid options should not be set as :
pager: jQuery(""#mypager")
but as
pager : "#mypager"
or
pager : "mypager"
otherwise the import or export will not work.

Note

The export respectivley the import methods have some limitations. When the export is called, exported is only the grid configuration and the related events. The navigator is not exported. In order to do this you should manually construct the navigator in the jqGridImport using the importComplete event.