Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / WebStorage.html
index 65fc36b..1fb9d40 100644 (file)
@@ -3,8 +3,8 @@
 <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   <title>The source code</title>
-  <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
-  <script type="text/javascript" src="../prettify/prettify.js"></script>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   <style type="text/css">
     .highlight { display: block; background-color: #ddd; }
   </style>
   </script>
 </head>
 <body onload="prettyPrint(); highlight();">
-  <pre class="prettyprint lang-js"><span id='Ext-data-proxy-WebStorage-method-constructor'><span id='Ext-data-proxy-WebStorage'>/**
-</span></span> * @author Ed Spencer
- * @class Ext.data.proxy.WebStorage
- * @extends Ext.data.proxy.Client
- * 
- * &lt;p&gt;WebStorageProxy is simply a superclass for the {@link Ext.data.proxy.LocalStorage localStorage} and 
- * {@link Ext.data.proxy.SessionStorage sessionStorage} proxies. It uses the new HTML5 key/value client-side storage 
- * objects to save {@link Ext.data.Model model instances} for offline use.&lt;/p&gt;
- * 
- * @constructor
- * Creates the proxy, throws an error if local storage is not supported in the current browser
- * @param {Object} config Optional config object
+  <pre class="prettyprint lang-js"><span id='Ext-data-proxy-WebStorage'>/**
+</span> * @author Ed Spencer
+ *
+ * WebStorageProxy is simply a superclass for the {@link Ext.data.proxy.LocalStorage LocalStorage} and {@link
+ * Ext.data.proxy.SessionStorage SessionStorage} proxies. It uses the new HTML5 key/value client-side storage objects to
+ * save {@link Ext.data.Model model instances} for offline use.
+ * @private
  */
 Ext.define('Ext.data.proxy.WebStorage', {
     extend: 'Ext.data.proxy.Client',
     alternateClassName: 'Ext.data.WebStorageProxy',
-    
+
 <span id='Ext-data-proxy-WebStorage-cfg-id'>    /**
-</span>     * @cfg {String} id The unique ID used as the key in which all record data are stored in the local storage object
+</span>     * @cfg {String} id
+     * The unique ID used as the key in which all record data are stored in the local storage object.
      */
     id: undefined,
 
 <span id='Ext-data-proxy-WebStorage-method-constructor'>    /**
-</span>     * @ignore
+</span>     * Creates the proxy, throws an error if local storage is not supported in the current browser.
+     * @param {Object} config (optional) Config object.
      */
     constructor: function(config) {
         this.callParent(arguments);
-        
+
 <span id='Ext-data-proxy-WebStorage-property-cache'>        /**
-</span>         * Cached map of records already retrieved by this Proxy - ensures that the same instance is always retrieved
-         * @property cache
-         * @type Object
+</span>         * @property {Object} cache
+         * Cached map of records already retrieved by this Proxy. Ensures that the same instance is always retrieved.
          */
         this.cache = {};
 
@@ -74,7 +70,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
             length  = records.length,
             ids     = this.getIds(),
             id, record, i;
-        
+
         operation.setStarted();
 
         for (i = 0; i &lt; length; i++) {
@@ -109,11 +105,11 @@ Ext.define('Ext.data.proxy.WebStorage', {
             ids     = this.getIds(),
             length  = ids.length,
             i, recordData, record;
-        
+
         //read a single record
         if (operation.id) {
             record = this.getRecord(operation.id);
-            
+
             if (record) {
                 records.push(record);
                 operation.setSuccessful();
@@ -124,7 +120,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
             }
             operation.setSuccessful();
         }
-        
+
         operation.setCompleted();
 
         operation.resultSet = Ext.create('Ext.data.ResultSet', {
@@ -150,7 +146,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
         for (i = 0; i &lt; length; i++) {
             record = records[i];
             this.setRecord(record);
-            
+
             //we need to update the set of ids here because it's possible that a non-phantom record was added
             //to this proxy - in which case the record's id would never have been added via the normal 'create' call
             id = record.getId();
@@ -184,7 +180,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
         }
 
         this.setIds(newIds);
-        
+
         operation.setCompleted();
         operation.setSuccessful();
 
@@ -195,7 +191,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
 
 <span id='Ext-data-proxy-WebStorage-method-getRecord'>    /**
 </span>     * @private
-     * Fetches a model instance from the Proxy by ID. Runs each field's decode function (if present) to decode the data
+     * Fetches a model instance from the Proxy by ID. Runs each field's decode function (if present) to decode the data.
      * @param {String} id The record's unique ID
      * @return {Ext.data.Model} The model instance
      */
@@ -224,14 +220,14 @@ Ext.define('Ext.data.proxy.WebStorage', {
 
             this.cache[id] = record;
         }
-        
+
         return this.cache[id];
     },
 
 <span id='Ext-data-proxy-WebStorage-method-setRecord'>    /**
-</span>     * Saves the given record in the Proxy. Runs each field's encode function (if present) to encode the data
+</span>     * Saves the given record in the Proxy. Runs each field's encode function (if present) to encode the data.
      * @param {Ext.data.Model} record The model instance
-     * @param {String} id The id to save the record under (defaults to the value of the record's getId() function)
+     * @param {String} [id] The id to save the record under (defaults to the value of the record's getId() function)
      */
     setRecord: function(record, id) {
         if (id) {
@@ -262,10 +258,10 @@ Ext.define('Ext.data.proxy.WebStorage', {
 
         obj = me.getStorageObject();
         key = me.getRecordKey(id);
-        
+
         //keep the cache up to date
         me.cache[id] = record;
-        
+
         //iPad bug requires that we remove the item before setting it
         obj.removeItem(key);
         obj.setItem(key, Ext.encode(data));
@@ -275,12 +271,12 @@ Ext.define('Ext.data.proxy.WebStorage', {
 </span>     * @private
      * Physically removes a given record from the local storage. Used internally by {@link #destroy}, which you should
      * use instead because it updates the list of currently-stored record ids
-     * @param {String|Number|Ext.data.Model} id The id of the record to remove, or an Ext.data.Model instance
+     * @param {String/Number/Ext.data.Model} id The id of the record to remove, or an Ext.data.Model instance
      */
     removeRecord: function(id, updateIds) {
         var me = this,
             ids;
-            
+
         if (id.isModel) {
             id = id.getId();
         }
@@ -298,7 +294,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
 </span>     * @private
      * Given the id of a record, returns a unique string based on that id and the id of this proxy. This is used when
      * storing data in the local storage object and should prevent naming collisions.
-     * @param {String|Number|Ext.data.Model} id The record id, or a Model instance
+     * @param {String/Number/Ext.data.Model} id The record id, or a Model instance
      * @return {String} The unique key for this record
      */
     getRecordKey: function(id) {
@@ -322,7 +318,7 @@ Ext.define('Ext.data.proxy.WebStorage', {
 <span id='Ext-data-proxy-WebStorage-method-getIds'>    /**
 </span>     * @private
      * Returns the array of record IDs stored in this Proxy
-     * @return {Array} The record IDs. Each is cast as a Number
+     * @return {Number[]} The record IDs. Each is cast as a Number
      */
     getIds: function() {
         var ids    = (this.getStorageObject().getItem(this.id) || &quot;&quot;).split(&quot;,&quot;),
@@ -343,14 +339,14 @@ Ext.define('Ext.data.proxy.WebStorage', {
 <span id='Ext-data-proxy-WebStorage-method-setIds'>    /**
 </span>     * @private
      * Saves the array of ids representing the set of all records in the Proxy
-     * @param {Array} ids The ids to set
+     * @param {Number[]} ids The ids to set
      */
     setIds: function(ids) {
         var obj = this.getStorageObject(),
             str = ids.join(&quot;,&quot;);
-        
+
         obj.removeItem(this.id);
-        
+
         if (!Ext.isEmpty(str)) {
             obj.setItem(this.id, str);
         }
@@ -358,8 +354,8 @@ Ext.define('Ext.data.proxy.WebStorage', {
 
 <span id='Ext-data-proxy-WebStorage-method-getNextId'>    /**
 </span>     * @private
-     * Returns the next numerical ID that can be used when realizing a model instance (see getRecordCounterKey). Increments
-     * the counter.
+     * Returns the next numerical ID that can be used when realizing a model instance (see getRecordCounterKey).
+     * Increments the counter.
      * @return {Number} The id
      */
     getNextId: function() {
@@ -367,15 +363,15 @@ Ext.define('Ext.data.proxy.WebStorage', {
             key  = this.getRecordCounterKey(),
             last = obj.getItem(key),
             ids, id;
-        
+
         if (last === null) {
             ids = this.getIds();
             last = ids[ids.length - 1] || 0;
         }
-        
+
         id = parseInt(last, 10) + 1;
         obj.setItem(key, id);
-        
+
         return id;
     },
 
@@ -390,7 +386,8 @@ Ext.define('Ext.data.proxy.WebStorage', {
     },
 
 <span id='Ext-data-proxy-WebStorage-method-clear'>    /**
-</span>     * Destroys all records stored in the proxy and removes all keys and values used to support the proxy from the storage object
+</span>     * Destroys all records stored in the proxy and removes all keys and values used to support the proxy from the
+     * storage object.
      */
     clear: function() {
         var obj = this.getStorageObject(),