New: Init option - fnStateLoad.

New: Init option - fnStateLoadParams
New: Init option - fnStateLoaded
New: Init option - fnStateSave
New: Init option - fnStateSaveParams
New: Event - stateSaveParams
New: Event - stateLoadParams
New: Event - stateLoaded
Removed: Init option - fnStateLoadCallback
Removed: Init option - fnStateSaveCallback
Updated: Documentation and code tidy up of the updated state saving methods.

media/js/jquery.dataTables.js

@@ -4679,38 +4679,57 @@
 		}
 		
 		
-		function _fnJsonString( obj )
+		/**
+		 * JSON stringify. If JSON.stringify it provided by the browser, json2.js or any other
+		 * library, then we use that as it is fast, safe and accurate. If the function isn't 
+		 * available then we need to built it ourselves - the insperation for this function comes
+		 * from Craig Buckler ( http://www.sitepoint.com/javascript-json-serialization/ ). It is
+		 * not perfect and absolutely should not be used as a replacement to json2.js - but it does
+		 * do what we need, without requiring a dependency for DataTables.
+		 *  @param {object} o JSON object to be converted
+		 *  @returns {string} JSON string
+		 *  @memberof DataTable#oApi
+		 */
+		var _fnJsonString = (JSON.stringify) ? JSON.stringify : function( o )
 		{
-			if ( JSON.stringify )
+			/* Not an object or array */
+			var sType = typeof o;
+			if (sType !== "object" || o === null)
 			{
-				return JSON.stringify( obj );
+				// simple data type
+				if (sType === "string")
+				{
+					o = '"'+o+'"';
+				}
+				return o+"";
 			}
 		
-			var t = typeof (obj);
+			/* If object or array, need to recurse over it */
-			if (t != "object" || obj === null) {
+			var
-				// simple data type
+				sProp, mValue,
-				if (t == "string") {
+				json = [],
-					obj = '"'+obj+'"';
+				bArr = $.isArray(o);
+			
+			for (sProp in o)
+			{
+				mValue = o[sProp];
+				sType = typeof mValue;
+		
+				if (sType === "string")
+				{
+					mValue = '"'+mValue+'"';
 				}
-				return String(obj);
+				else if (sType === "object" && mValue !== null)
-			}
+				{
-			else {
+					mValue = _fnJsonString(mValue);
-				// recurse array or object
-				var n, v, json = [], arr = (obj && obj.constructor == Array);
-				for (n in obj) {
-					v = obj[n]; t = typeof(v);
-					if (t == "string") {
-						v = '"'+v+'"';
-					}
-					else if (t == "object" && v !== null) {
-						v = _fnJsonString(v);
-					}
-					json.push((arr ? "" : '"' + n + '":') + String(v));
-				}
-				return (arr ? "[" : "{") + String(json) + (arr ? "]" : "}");
 				}
+		
+				json.push((bArr ? "" : '"'+sProp+'":') + mValue);
 			}
 		
+			return (bArr ? "[" : "{") + json + (bArr ? "]" : "}");
+		};
+		
 
 		
 		
@@ -8260,94 +8279,151 @@
 	
 	
 		/**
-		 * State saving in DataTables is very useful, but it does a blanket save on
+		 * Load the table state. With this function you can define from where, and how, the
-		 * all properties that the user can modify, so the table is restored. This
+		 * state of a table is loaded. By default DataTables will load from its state saving
-		 * callback method can be used to modify the saved properties as you require,
+		 * cookie, but you might wish to use local storage (HTML5) or a server-side database.
-		 * just prior to them being loaded. This method can also be used to override
-		 * the state loading altogether by returning false.
 		 *  @type function
 		 *  @param {object} oSettings DataTables settings object
-		 *  @param {object} oData Object containing information retrieved from the
+		 *  @param {object} oData The state object to be saved
-		 *    state saving cookie which should be restored. For the exact properties
-		 *    please refer to the DataTables code.
-		 *  @returns {boolean} false if the state should not be loaded, true otherwise
 		 * 
 		 *  @example
-		 *    // Remove a previously saved filter
+		 *    $(document).ready(function() {
-		 *    $(document).ready( function () {
 		 *      $('#example').dataTable( {
 		 *        "bStateSave": true,
-		 *        "fnStateLoadCallback": function ( oSettings, oData ) {
+		 *        "fnStateSave": function (oSettings, oData) {
-		 *          oData.sFilter = "";
+		 *          var o;
-		 *          return true;
+		 *          
+		 *          // Send an Ajax request to the server to get the data. Note that
+		 *          // this is a synchronous request.
+		 *          $.ajax( {
+		 *            "url": "/state_load",
+		 *            "async": false,
+		 *            "dataType": "json",
+		 *            "success": function (json) {
+		 *              o = json;
 		 *            }
 		 *          } );
-		 *    } );
 		 *          
-		 *  @example
+		 *          return o;
-		 *    // Override state loading
-		 *    $(document).ready( function () {
-		 *      $('#example').dataTable( {
-		 *        "bStateSave": true,
-		 *        "fnStateLoadCallback": function ( oSettings, oData ) {
-		 *          return false;
 		 *        }
 		 *      } );
 		 *    } );
 		 */
-		"fnStateLoadCallback": null,
+		"fnStateLoad": function ( oSettings ) {
+			var sData = this.oApi._fnReadCookie( oSettings.sCookiePrefix+oSettings.sInstance );
+			var oData;
+	
+			try {
+				oData = (typeof $.parseJSON === 'function') ? 
+					$.parseJSON(sData) : eval( '('+sData+')' );
+			} catch (e) {
+				oData = null;
+			}
+	
+			return oData;
+		},
 	
 	
 		/**
-		 * When using state saving it can be useful to store your own custom
+		 * Callback which allows modification of the saved state prior to loading that state.
-		 * parameters in the state saving cookie that DataTables uses, or to modify
+		 * This callback is called when the table is loading state from the stored data, but
-		 * the settings that DataTables uses. Note that this function can be quite
+		 * prior to the settings object being modified by the saved state. Note that for 
-		 * involved to use since it uses JSON notation in a string, given that jQuery
+		 * plug-in authors, you should use the 'stateLoadParams' event to load parameters for 
-		 * does not provide a "stringify" option for JSON objects.
+		 * a plug-in.
 		 *  @type function
 		 *  @param {object} oSettings DataTables settings object
-		 *  @param {string} sValue a JSON string (without the final closing brace)
+		 *  @param {object} oData The state object that is to be loaded
-		 *    which should be stored in the state saving cookie.
-		 *  @returns {string} The full string that should be used to save the state
 		 * 
 		 *  @example
-		 *    // Add a custom parameter
+		 *    // Remove a saved filter, so filtering is never loaded
-		 *    $(document).ready( function () {
+		 *    $(document).ready(function() {
 		 *      $('#example').dataTable( {
 		 *        "bStateSave": true,
-		 *        "fnStateSaveCallback": function ( oSettings, sValue ) {
+		 *        "fnStateLoadParams": function (oSettings, oData) {
-		 *          sValue += ',"myCustomParameter": "myValue"';
+		 *          oData.oFilter.sSearch = "";
-		 *          return sValue;
-		 *        }
 		 *      } );
 		 *    } );
+		 */
+		"fnStateLoadParams": null,
+	
+	
+		/**
+		 * Callback that is called when the state has been loaded from the state saving method
+		 * and the DataTables settings object has been modified as a result of the loaded state.
+		 *  @type function
+		 *  @param {object} oSettings DataTables settings object
+		 *  @param {object} oData The state object that was loaded
 		 * 
 		 *  @example
-		 *    // Modify saved filter to be blank
+		 *    // Show an alert with the filtering value that was saved
-		 *    $(document).ready( function () {
+		 *    $(document).ready(function() {
 		 *      $('#example').dataTable( {
 		 *        "bStateSave": true,
-		 *        "fnStateSaveCallback": function ( oSettings, sValue ) {
+		 *        "fnStateLoaded": function (oSettings, oData) {
-		 *          sValue = sValue.replace( /"sFilter":".*?"/, '"sFilter":""' );
+		 *          alert( 'Saved filter was: '+oData.oFilter.sSearch );
-		 *          return sValue;
-		 *        }
 		 *      } );
 		 *    } );
+		 */
+		"fnStateLoaded": null,
+	
+	
+		/**
+		 * Save the table state. This function allows you to define where and how the state
+		 * information for the table is stored - by default it will use a cookie, but you
+		 * might want to use local storage (HTML5) or a server-side database.
+		 *  @type function
+		 *  @param {object} oSettings DataTables settings object
+		 *  @param {object} oData The state object to be saved
 		 * 
 		 *  @example
-		 *    // Modify saved filter to be blank - using JSON2.js
+		 *    $(document).ready(function() {
-		 *    $(document).ready( function () {
 		 *      $('#example').dataTable( {
 		 *        "bStateSave": true,
-		 *        "fnStateSaveCallback": function ( oSettings, sValue ) {
+		 *        "fnStateSave": function (oSettings, oData) {
-		 *          var oData = JSON.parse( sValue+"}" );
+		 *          // Send an Ajax request to the server with the state object
-		 *          oData.sFilter = "";
+		 *          $.ajax( {
-		 *          return JSON.stringify( oData ).slice( 0, -1 );
+		 *            "url": "/state_save",
+		 *            "data": oData,
+		 *            "dataType": "json",
+		 *            "method": "POST"
+		 *            "success": function () {}
+		 *          } );
 		 *        }
 		 *      } );
 		 *    } );
 		 */
-		"fnStateSaveCallback": null,
+		"fnStateSave": function ( oSettings, oData ) {
+			this.oApi._fnCreateCookie( 
+				oSettings.sCookiePrefix+oSettings.sInstance, 
+				this.oApi._fnJsonString(oData), 
+				oSettings.iCookieDuration, 
+				oSettings.sCookiePrefix, 
+				oSettings.fnCookieCallback
+			);
+		},
+	
+	
+		/**
+		 * Callback which allows modification of the state to be saved. Called when the table 
+		 * has changed state a new state save is required. This method allows modification of
+		 * the state saving object prior to actually doing the save, including addition or 
+		 * other state properties or modification. Note that for plug-in authors, you should 
+		 * use the 'stateSaveParams' event to save parameters for a plug-in.
+		 *  @type function
+		 *  @param {object} oSettings DataTables settings object
+		 *  @param {object} oData The state object to be saved
+		 * 
+		 *  @example
+		 *    // Remove a saved filter, so filtering is never saved
+		 *    $(document).ready(function() {
+		 *      $('#example').dataTable( {
+		 *        "bStateSave": true,
+		 *        "fnStateLoadParams": function (oSettings, oData) {
+		 *          oData.oFilter.sSearch = "";
+		 *      } );
+		 *    } );
+		 */
+		"fnStateSaveParams": null,
 	
 	
 		/**
@@ -9102,36 +9178,7 @@
 		 *      } );
 		 *    } );
 		 */
-		"sServerMethod": "GET",
+		"sServerMethod": "GET"
-	
-	
-		"fnStateSave": function ( oSettings, oData ) {
-			this.oApi._fnCreateCookie( 
-				oSettings.sCookiePrefix+oSettings.sInstance, 
-				this.oApi._fnJsonString(oData), 
-				oSettings.iCookieDuration, 
-				oSettings.sCookiePrefix, 
-				oSettings.fnCookieCallback
-			);
-		},
-	
-		"fnStateLoad": function ( oSettings ) {
-			var sData = this.oApi._fnReadCookie( oSettings.sCookiePrefix+oSettings.sInstance );
-			var oData;
-	
-			try {
-				oData = (typeof $.parseJSON === 'function') ? 
-					$.parseJSON(sData) : eval( '('+sData+')' );
-			} catch (e) {
-				oData = null;
-			}
-	
-			return oData;
-		},
-	
-		"fnStateSaveParams": null,
-		"fnStateLoadParams": null,
-		"fnStateLoaded": null
 	};
 	
 	
@@ -10189,8 +10236,29 @@
 		 */
 		"aoInitComplete": [],
 	
+		
+		/**
+		 * Callbacks for modifying the settings to be stored for state saving, prior to
+		 * saving state.
+		 *  @type array
+		 *  @default []
+		 */
 		"aoStateSaveParams": [],
+		
+		/**
+		 * Callbacks for modifying the settings that have been stored for state saving
+		 * prior to using the stored values to restore the state.
+		 *  @type array
+		 *  @default []
+		 */
 		"aoStateLoadParams": [],
+		
+		/**
+		 * Callbacks for operating on the settings object once the saved state has been
+		 * loaded
+		 *  @type array
+		 *  @default []
+		 */
 		"aoStateLoaded": [],
 		
 		/**
@@ -11209,13 +11277,36 @@
 	 */
 
 	/**
-	 * State load event, fired when DataTables loads the saved table state. Can be used
+	 * State save event, fired when the table has changed state a new state save is required.
-	 * to add, remove or override saved information
+	 * This method allows modification of the state saving object prior to actually doing the
-	 *  @name DataTable#stateLoad
+	 * save, including addition or other state properties (for plug-ins) or modification
+	 * of a DataTables core property.
+	 *  @name DataTable#stateSaveParams
 	 *  @event
 	 *  @param {event} e jQuery event object
 	 *  @param {object} oSettings DataTables settings object
-	 *  @param {object} json The saved infromation from the local cookie
+	 *  @param {object} json The state information to be saved
+	 */
+
+	/**
+	 * State load event, fired when the table is loading state from the stored data, but
+	 * prior to the settings object being modified by the saved state - allowing modification
+	 * of the saved state is required or loading of state for a plug-in.
+	 *  @name DataTable#stateLoadParams
+	 *  @event
+	 *  @param {event} e jQuery event object
+	 *  @param {object} oSettings DataTables settings object
+	 *  @param {object} json The saved state information
+	 */
+
+	/**
+	 * State loaded event, fired when state has been loaded from stored data and the settings
+	 * object has been modified by the loaded data.
+	 *  @name DataTable#stateLoaded
+	 *  @event
+	 *  @param {event} e jQuery event object
+	 *  @param {object} oSettings DataTables settings object
+	 *  @param {object} json The saved state information
 	 */
 
 	/**

media/src/DataTables.js

@@ -190,13 +190,36 @@
 	 */
 
 	/**
-	 * State load event, fired when DataTables loads the saved table state. Can be used
+	 * State save event, fired when the table has changed state a new state save is required.
-	 * to add, remove or override saved information
+	 * This method allows modification of the state saving object prior to actually doing the
-	 *  @name DataTable#stateLoad
+	 * save, including addition or other state properties (for plug-ins) or modification
+	 * of a DataTables core property.
+	 *  @name DataTable#stateSaveParams
 	 *  @event
 	 *  @param {event} e jQuery event object
 	 *  @param {object} oSettings DataTables settings object
-	 *  @param {object} json The saved infromation from the local cookie
+	 *  @param {object} json The state information to be saved
+	 */
+
+	/**
+	 * State load event, fired when the table is loading state from the stored data, but
+	 * prior to the settings object being modified by the saved state - allowing modification
+	 * of the saved state is required or loading of state for a plug-in.
+	 *  @name DataTable#stateLoadParams
+	 *  @event
+	 *  @param {event} e jQuery event object
+	 *  @param {object} oSettings DataTables settings object
+	 *  @param {object} json The saved state information
+	 */
+
+	/**
+	 * State loaded event, fired when state has been loaded from stored data and the settings
+	 * object has been modified by the loaded data.
+	 *  @name DataTable#stateLoaded
+	 *  @event
+	 *  @param {event} e jQuery event object
+	 *  @param {object} oSettings DataTables settings object
+	 *  @param {object} json The saved state information
 	 */
 
 	/**

media/src/core/core.support.js

@@ -262,35 +262,54 @@ function _fnCallbackFire( oSettings, sStore, sTrigger, aArgs )
 }
 
 
-function _fnJsonString( obj )
+/**
+ * JSON stringify. If JSON.stringify it provided by the browser, json2.js or any other
+ * library, then we use that as it is fast, safe and accurate. If the function isn't 
+ * available then we need to built it ourselves - the insperation for this function comes
+ * from Craig Buckler ( http://www.sitepoint.com/javascript-json-serialization/ ). It is
+ * not perfect and absolutely should not be used as a replacement to json2.js - but it does
+ * do what we need, without requiring a dependency for DataTables.
+ *  @param {object} o JSON object to be converted
+ *  @returns {string} JSON string
+ *  @memberof DataTable#oApi
+ */
+var _fnJsonString = (JSON.stringify) ? JSON.stringify : function( o )
 {
-	if ( JSON.stringify )
+	/* Not an object or array */
+	var sType = typeof o;
+	if (sType !== "object" || o === null)
 	{
-		return JSON.stringify( obj );
-	}
-	
-	var t = typeof (obj);
-	if (t != "object" || obj === null) {
 		// simple data type
-		if (t == "string") {
+		if (sType === "string")
-			obj = '"'+obj+'"';
+		{
+			o = '"'+o+'"';
 		}
-		return String(obj);
+		return o+"";
 	}
-	else {
+
-		// recurse array or object
+	/* If object or array, need to recurse over it */
-		var n, v, json = [], arr = (obj && obj.constructor == Array);
+	var
-		for (n in obj) {
+		sProp, mValue,
-			v = obj[n]; t = typeof(v);
+		json = [],
-			if (t == "string") {
+		bArr = $.isArray(o);
-				v = '"'+v+'"';
+	
-			}
+	for (sProp in o)
-			else if (t == "object" && v !== null) {
+	{
-				v = _fnJsonString(v);
+		mValue = o[sProp];
-			}
+		sType = typeof mValue;
-			json.push((arr ? "" : '"' + n + '":') + String(v));
+
-		}
+		if (sType === "string")
-		return (arr ? "[" : "{") + String(json) + (arr ? "]" : "}");
+		{
-	}
+			mValue = '"'+mValue+'"';
-}
+		}
+		else if (sType === "object" && mValue !== null)
+		{
+			mValue = _fnJsonString(mValue);
+		}
+
+		json.push((bArr ? "" : '"'+sProp+'":') + mValue);
+	}
+
+	return (bArr ? "[" : "{") + json + (bArr ? "]" : "}");
+};
 

media/src/model/model.defaults.js

@@ -924,94 +924,151 @@ DataTable.defaults = {
 
 
 	/**
-	 * State saving in DataTables is very useful, but it does a blanket save on
+	 * Load the table state. With this function you can define from where, and how, the
-	 * all properties that the user can modify, so the table is restored. This
+	 * state of a table is loaded. By default DataTables will load from its state saving
-	 * callback method can be used to modify the saved properties as you require,
+	 * cookie, but you might wish to use local storage (HTML5) or a server-side database.
-	 * just prior to them being loaded. This method can also be used to override
-	 * the state loading altogether by returning false.
 	 *  @type function
 	 *  @param {object} oSettings DataTables settings object
-	 *  @param {object} oData Object containing information retrieved from the
+	 *  @param {object} oData The state object to be saved
-	 *    state saving cookie which should be restored. For the exact properties
-	 *    please refer to the DataTables code.
-	 *  @returns {boolean} false if the state should not be loaded, true otherwise
 	 * 
 	 *  @example
-	 *    // Remove a previously saved filter
+	 *    $(document).ready(function() {
-	 *    $(document).ready( function () {
 	 *      $('#example').dataTable( {
 	 *        "bStateSave": true,
-	 *        "fnStateLoadCallback": function ( oSettings, oData ) {
+	 *        "fnStateSave": function (oSettings, oData) {
-	 *          oData.sFilter = "";
+	 *          var o;
-	 *          return true;
+	 *          
+	 *          // Send an Ajax request to the server to get the data. Note that
+	 *          // this is a synchronous request.
+	 *          $.ajax( {
+	 *            "url": "/state_load",
+	 *            "async": false,
+	 *            "dataType": "json",
+	 *            "success": function (json) {
+	 *              o = json;
 	 *            }
 	 *          } );
-	 *    } );
 	 *          
-	 *  @example
+	 *          return o;
-	 *    // Override state loading
-	 *    $(document).ready( function () {
-	 *      $('#example').dataTable( {
-	 *        "bStateSave": true,
-	 *        "fnStateLoadCallback": function ( oSettings, oData ) {
-	 *          return false;
 	 *        }
 	 *      } );
 	 *    } );
 	 */
-	"fnStateLoadCallback": null,
+	"fnStateLoad": function ( oSettings ) {
+		var sData = this.oApi._fnReadCookie( oSettings.sCookiePrefix+oSettings.sInstance );
+		var oData;
+
+		try {
+			oData = (typeof $.parseJSON === 'function') ? 
+				$.parseJSON(sData) : eval( '('+sData+')' );
+		} catch (e) {
+			oData = null;
+		}
+
+		return oData;
+	},
 
 
 	/**
-	 * When using state saving it can be useful to store your own custom
+	 * Callback which allows modification of the saved state prior to loading that state.
-	 * parameters in the state saving cookie that DataTables uses, or to modify
+	 * This callback is called when the table is loading state from the stored data, but
-	 * the settings that DataTables uses. Note that this function can be quite
+	 * prior to the settings object being modified by the saved state. Note that for 
-	 * involved to use since it uses JSON notation in a string, given that jQuery
+	 * plug-in authors, you should use the 'stateLoadParams' event to load parameters for 
-	 * does not provide a "stringify" option for JSON objects.
+	 * a plug-in.
 	 *  @type function
 	 *  @param {object} oSettings DataTables settings object
-	 *  @param {string} sValue a JSON string (without the final closing brace)
+	 *  @param {object} oData The state object that is to be loaded
-	 *    which should be stored in the state saving cookie.
-	 *  @returns {string} The full string that should be used to save the state
 	 * 
 	 *  @example
-	 *    // Add a custom parameter
+	 *    // Remove a saved filter, so filtering is never loaded
-	 *    $(document).ready( function () {
+	 *    $(document).ready(function() {
 	 *      $('#example').dataTable( {
 	 *        "bStateSave": true,
-	 *        "fnStateSaveCallback": function ( oSettings, sValue ) {
+	 *        "fnStateLoadParams": function (oSettings, oData) {
-	 *          sValue += ',"myCustomParameter": "myValue"';
+	 *          oData.oFilter.sSearch = "";
-	 *          return sValue;
-	 *        }
 	 *      } );
 	 *    } );
+	 */
+	"fnStateLoadParams": null,
+
+
+	/**
+	 * Callback that is called when the state has been loaded from the state saving method
+	 * and the DataTables settings object has been modified as a result of the loaded state.
+	 *  @type function
+	 *  @param {object} oSettings DataTables settings object
+	 *  @param {object} oData The state object that was loaded
 	 * 
 	 *  @example
-	 *    // Modify saved filter to be blank
+	 *    // Show an alert with the filtering value that was saved
-	 *    $(document).ready( function () {
+	 *    $(document).ready(function() {
 	 *      $('#example').dataTable( {
 	 *        "bStateSave": true,
-	 *        "fnStateSaveCallback": function ( oSettings, sValue ) {
+	 *        "fnStateLoaded": function (oSettings, oData) {
-	 *          sValue = sValue.replace( /"sFilter":".*?"/, '"sFilter":""' );
+	 *          alert( 'Saved filter was: '+oData.oFilter.sSearch );
-	 *          return sValue;
-	 *        }
 	 *      } );
 	 *    } );
+	 */
+	"fnStateLoaded": null,
+
+
+	/**
+	 * Save the table state. This function allows you to define where and how the state
+	 * information for the table is stored - by default it will use a cookie, but you
+	 * might want to use local storage (HTML5) or a server-side database.
+	 *  @type function
+	 *  @param {object} oSettings DataTables settings object
+	 *  @param {object} oData The state object to be saved
 	 * 
 	 *  @example
-	 *    // Modify saved filter to be blank - using JSON2.js
+	 *    $(document).ready(function() {
-	 *    $(document).ready( function () {
 	 *      $('#example').dataTable( {
 	 *        "bStateSave": true,
-	 *        "fnStateSaveCallback": function ( oSettings, sValue ) {
+	 *        "fnStateSave": function (oSettings, oData) {
-	 *          var oData = JSON.parse( sValue+"}" );
+	 *          // Send an Ajax request to the server with the state object
-	 *          oData.sFilter = "";
+	 *          $.ajax( {
-	 *          return JSON.stringify( oData ).slice( 0, -1 );
+	 *            "url": "/state_save",
+	 *            "data": oData,
+	 *            "dataType": "json",
+	 *            "method": "POST"
+	 *            "success": function () {}
+	 *          } );
 	 *        }
 	 *      } );
 	 *    } );
 	 */
-	"fnStateSaveCallback": null,
+	"fnStateSave": function ( oSettings, oData ) {
+		this.oApi._fnCreateCookie( 
+			oSettings.sCookiePrefix+oSettings.sInstance, 
+			this.oApi._fnJsonString(oData), 
+			oSettings.iCookieDuration, 
+			oSettings.sCookiePrefix, 
+			oSettings.fnCookieCallback
+		);
+	},
+
+
+	/**
+	 * Callback which allows modification of the state to be saved. Called when the table 
+	 * has changed state a new state save is required. This method allows modification of
+	 * the state saving object prior to actually doing the save, including addition or 
+	 * other state properties or modification. Note that for plug-in authors, you should 
+	 * use the 'stateSaveParams' event to save parameters for a plug-in.
+	 *  @type function
+	 *  @param {object} oSettings DataTables settings object
+	 *  @param {object} oData The state object to be saved
+	 * 
+	 *  @example
+	 *    // Remove a saved filter, so filtering is never saved
+	 *    $(document).ready(function() {
+	 *      $('#example').dataTable( {
+	 *        "bStateSave": true,
+	 *        "fnStateLoadParams": function (oSettings, oData) {
+	 *          oData.oFilter.sSearch = "";
+	 *      } );
+	 *    } );
+	 */
+	"fnStateSaveParams": null,
 
 
 	/**
@@ -1766,35 +1823,6 @@ DataTable.defaults = {
 	 *      } );
 	 *    } );
 	 */
-	"sServerMethod": "GET",
+	"sServerMethod": "GET"
-
-
-	"fnStateSave": function ( oSettings, oData ) {
-		this.oApi._fnCreateCookie( 
-			oSettings.sCookiePrefix+oSettings.sInstance, 
-			this.oApi._fnJsonString(oData), 
-			oSettings.iCookieDuration, 
-			oSettings.sCookiePrefix, 
-			oSettings.fnCookieCallback
-		);
-	},
-
-	"fnStateLoad": function ( oSettings ) {
-		var sData = this.oApi._fnReadCookie( oSettings.sCookiePrefix+oSettings.sInstance );
-		var oData;
-
-		try {
-			oData = (typeof $.parseJSON === 'function') ? 
-				$.parseJSON(sData) : eval( '('+sData+')' );
-		} catch (e) {
-			oData = null;
-		}
-
-		return oData;
-	},
-
-	"fnStateSaveParams": null,
-	"fnStateLoadParams": null,
-	"fnStateLoaded": null
 };
 

media/src/model/model.settings.js

@@ -411,8 +411,29 @@ DataTable.models.oSettings = {
 	 */
 	"aoInitComplete": [],
 
+	
+	/**
+	 * Callbacks for modifying the settings to be stored for state saving, prior to
+	 * saving state.
+	 *  @type array
+	 *  @default []
+	 */
 	"aoStateSaveParams": [],
+	
+	/**
+	 * Callbacks for modifying the settings that have been stored for state saving
+	 * prior to using the stored values to restore the state.
+	 *  @type array
+	 *  @default []
+	 */
 	"aoStateLoadParams": [],
+	
+	/**
+	 * Callbacks for operating on the settings object once the saved state has been
+	 * loaded
+	 *  @type array
+	 *  @default []
+	 */
 	"aoStateLoaded": [],
 	
 	/**