docs/source/Store.html

   1 <html>
   2 <head>
   3   <title>The source code</title>
   4     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   5     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   6 </head>
   7 <body  onload="prettyPrint();">
   8     <pre class="prettyprint lang-js">/*!
   9  * Ext JS Library 3.0.3
  10  * Copyright(c) 2006-2009 Ext JS, LLC
  11  * licensing@extjs.com
  12  * http://www.extjs.com/license
  13  */
  14 <div id="cls-Ext.data.Store"></div>/**
  15  * @class Ext.data.Store
  16  * @extends Ext.util.Observable
  17  * <p>The Store class encapsulates a client side cache of {@link Ext.data.Record Record}
  18  * objects which provide input data for Components such as the {@link Ext.grid.GridPanel GridPanel},
  19  * the {@link Ext.form.ComboBox ComboBox}, or the {@link Ext.DataView DataView}.</p>
  20  * <p><u>Retrieving Data</u></p>
  21  * <p>A Store object may access a data object using:<div class="mdetail-params"><ul>
  22  * <li>{@link #proxy configured implementation} of {@link Ext.data.DataProxy DataProxy}</li>
  23  * <li>{@link #data} to automatically pass in data</li>
  24  * <li>{@link #loadData} to manually pass in data</li>
  25  * </ul></div></p>
  26  * <p><u>Reading Data</u></p>
  27  * <p>A Store object has no inherent knowledge of the format of the data object (it could be
  28  * an Array, XML, or JSON). A Store object uses an appropriate {@link #reader configured implementation}
  29  * of a {@link Ext.data.DataReader DataReader} to create {@link Ext.data.Record Record} instances from the data
  30  * object.</p>
  31  * <p><u>Store Types</u></p>
  32  * <p>There are several implementations of Store available which are customized for use with
  33  * a specific DataReader implementation.  Here is an example using an ArrayStore which implicitly
  34  * creates a reader commensurate to an Array data object.</p>
  35  * <pre><code>
  36 var myStore = new Ext.data.ArrayStore({
  37     fields: ['fullname', 'first'],
  38     idIndex: 0 // id for each record will be the first element
  39 });
  40  * </code></pre>
  41  * <p>For custom implementations create a basic {@link Ext.data.Store} configured as needed:</p>
  42  * <pre><code>
  43 // create a {@link Ext.data.Record Record} constructor:
  44 var rt = Ext.data.Record.create([
  45     {name: 'fullname'},
  46     {name: 'first'}
  47 ]);
  48 var myStore = new Ext.data.Store({
  49     // explicitly create reader
  50     reader: new Ext.data.ArrayReader(
  51         {
  52             idIndex: 0  // id for each record will be the first element
  53         },
  54         rt // recordType
  55     )
  56 });
  57  * </code></pre>
  58  * <p>Load some data into store (note the data object is an array which corresponds to the reader):</p>
  59  * <pre><code>
  60 var myData = [
  61     [1, 'Fred Flintstone', 'Fred'],  // note that id for the record is the first element
  62     [2, 'Barney Rubble', 'Barney']
  63 ];
  64 myStore.loadData(myData);
  65  * </code></pre>
  66  * <p>Records are cached and made available through accessor functions.  An example of adding
  67  * a record to the store:</p>
  68  * <pre><code>
  69 var defaultData = {
  70     fullname: 'Full Name',
  71     first: 'First Name'
  72 };
  73 var recId = 100; // provide unique id for the record
  74 var r = new myStore.recordType(defaultData, ++recId); // create new record
  75 myStore.{@link #insert}(0, r); // insert a new record into the store (also see {@link #add})
  76  * </code></pre>
  77  * <p><u>Writing Data</u></p>
  78  * <p>And <b>new in Ext version 3</b>, use the new {@link Ext.data.DataWriter DataWriter} to create an automated, <a href="http://extjs.com/deploy/dev/examples/writer/writer.html">Writable Store</a>
  79  * along with <a href="http://extjs.com/deploy/dev/examples/restful/restful.html">RESTful features.</a>
  80  * @constructor
  81  * Creates a new Store.
  82  * @param {Object} config A config object containing the objects needed for the Store to access data,
  83  * and read the data into Records.
  84  * @xtype store
  85  */
  86 Ext.data.Store = function(config){
  87     this.data = new Ext.util.MixedCollection(false);
  88     this.data.getKey = function(o){
  89         return o.id;
  90     };
  91     <div id="prop-Ext.data.Store-baseParams"></div>/**
  92      * See the <code>{@link #baseParams corresponding configuration option}</code>
  93      * for a description of this property.
  94      * To modify this property see <code>{@link #setBaseParam}</code>.
  95      * @property
  96      */
  97     this.baseParams = {};
  98
  99     // temporary removed-records cache
 100     this.removed = [];
 101
 102     if(config && config.data){
 103         this.inlineData = config.data;
 104         delete config.data;
 105     }
 106
 107     Ext.apply(this, config);
 108
 109     this.paramNames = Ext.applyIf(this.paramNames || {}, this.defaultParamNames);
 110
 111     if(this.url && !this.proxy){
 112         this.proxy = new Ext.data.HttpProxy({url: this.url});
 113     }
 114     // If Store is RESTful, so too is the DataProxy
 115     if (this.restful === true && this.proxy) {
 116         // When operating RESTfully, a unique transaction is generated for each record.
 117         this.batch = false;
 118         Ext.data.Api.restify(this.proxy);
 119     }
 120
 121     if(this.reader){ // reader passed
 122         if(!this.recordType){
 123             this.recordType = this.reader.recordType;
 124         }
 125         if(this.reader.onMetaChange){
 126             //this.reader.onMetaChange = this.onMetaChange.createDelegate(this);
 127             this.reader.onMetaChange = this.reader.onMetaChange.createSequence(this.onMetaChange, this);
 128         }
 129         if (this.writer) { // writer passed
 130             this.writer.meta = this.reader.meta;
 131             this.pruneModifiedRecords = true;
 132         }
 133     }
 134
 135     <div id="prop-Ext.data.Store-recordType"></div>/**
 136      * The {@link Ext.data.Record Record} constructor as supplied to (or created by) the
 137      * {@link Ext.data.DataReader Reader}. Read-only.
 138      * <p>If the Reader was constructed by passing in an Array of {@link Ext.data.Field} definition objects,
 139      * instead of a Record constructor, it will implicitly create a Record constructor from that Array (see
 140      * {@link Ext.data.Record}.{@link Ext.data.Record#create create} for additional details).</p>
 141      * <p>This property may be used to create new Records of the type held in this Store, for example:</p><pre><code>
 142 // create the data store
 143 var store = new Ext.data.ArrayStore({
 144     autoDestroy: true,
 145     fields: [
 146        {name: 'company'},
 147        {name: 'price', type: 'float'},
 148        {name: 'change', type: 'float'},
 149        {name: 'pctChange', type: 'float'},
 150        {name: 'lastChange', type: 'date', dateFormat: 'n/j h:ia'}
 151     ]
 152 });
 153 store.loadData(myData);
 154
 155 // create the Grid
 156 var grid = new Ext.grid.EditorGridPanel({
 157     store: store,
 158     colModel: new Ext.grid.ColumnModel({
 159         columns: [
 160             {id:'company', header: 'Company', width: 160, dataIndex: 'company'},
 161             {header: 'Price', renderer: 'usMoney', dataIndex: 'price'},
 162             {header: 'Change', renderer: change, dataIndex: 'change'},
 163             {header: '% Change', renderer: pctChange, dataIndex: 'pctChange'},
 164             {header: 'Last Updated', width: 85,
 165                 renderer: Ext.util.Format.dateRenderer('m/d/Y'),
 166                 dataIndex: 'lastChange'}
 167         ],
 168         defaults: {
 169             sortable: true,
 170             width: 75
 171         }
 172     }),
 173     autoExpandColumn: 'company', // match the id specified in the column model
 174     height:350,
 175     width:600,
 176     title:'Array Grid',
 177     tbar: [{
 178         text: 'Add Record',
 179         handler : function(){
 180             var defaultData = {
 181                 change: 0,
 182                 company: 'New Company',
 183                 lastChange: (new Date()).clearTime(),
 184                 pctChange: 0,
 185                 price: 10
 186             };
 187             var recId = 3; // provide unique id
 188             var p = new store.recordType(defaultData, recId); // create new record
 189             grid.stopEditing();
 190             store.{@link #insert}(0, p); // insert a new record into the store (also see {@link #add})
 191             grid.startEditing(0, 0);
 192         }
 193     }]
 194 });
 195      * </code></pre>
 196      * @property recordType
 197      * @type Function
 198      */
 199
 200     if(this.recordType){
 201         <div id="prop-Ext.data.Store-fields"></div>/**
 202          * A {@link Ext.util.MixedCollection MixedCollection} containing the defined {@link Ext.data.Field Field}s
 203          * for the {@link Ext.data.Record Records} stored in this Store. Read-only.
 204          * @property fields
 205          * @type Ext.util.MixedCollection
 206          */
 207         this.fields = this.recordType.prototype.fields;
 208     }
 209     this.modified = [];
 210
 211     this.addEvents(
 212         <div id="event-Ext.data.Store-datachanged"></div>/**
 213          * @event datachanged
 214          * Fires when the data cache has changed in a bulk manner (e.g., it has been sorted, filtered, etc.) and a
 215          * widget that is using this Store as a Record cache should refresh its view.
 216          * @param {Store} this
 217          */
 218         'datachanged',
 219         <div id="event-Ext.data.Store-metachange"></div>/**
 220          * @event metachange
 221          * Fires when this store's reader provides new metadata (fields). This is currently only supported for JsonReaders.
 222          * @param {Store} this
 223          * @param {Object} meta The JSON metadata
 224          */
 225         'metachange',
 226         <div id="event-Ext.data.Store-add"></div>/**
 227          * @event add
 228          * Fires when Records have been {@link #add}ed to the Store
 229          * @param {Store} this
 230          * @param {Ext.data.Record[]} records The array of Records added
 231          * @param {Number} index The index at which the record(s) were added
 232          */
 233         'add',
 234         <div id="event-Ext.data.Store-remove"></div>/**
 235          * @event remove
 236          * Fires when a Record has been {@link #remove}d from the Store
 237          * @param {Store} this
 238          * @param {Ext.data.Record} record The Record that was removed
 239          * @param {Number} index The index at which the record was removed
 240          */
 241         'remove',
 242         <div id="event-Ext.data.Store-update"></div>/**
 243          * @event update
 244          * Fires when a Record has been updated
 245          * @param {Store} this
 246          * @param {Ext.data.Record} record The Record that was updated
 247          * @param {String} operation The update operation being performed.  Value may be one of:
 248          * <pre><code>
 249  Ext.data.Record.EDIT
 250  Ext.data.Record.REJECT
 251  Ext.data.Record.COMMIT
 252          * </code></pre>
 253          */
 254         'update',
 255         <div id="event-Ext.data.Store-clear"></div>/**
 256          * @event clear
 257          * Fires when the data cache has been cleared.
 258          * @param {Store} this
 259          * @param {Record[]} The records that were cleared.
 260          */
 261         'clear',
 262         <div id="event-Ext.data.Store-exception"></div>/**
 263          * @event exception
 264          * <p>Fires if an exception occurs in the Proxy during a remote request.
 265          * This event is relayed through the corresponding {@link Ext.data.DataProxy}.
 266          * See {@link Ext.data.DataProxy}.{@link Ext.data.DataProxy#exception exception}
 267          * for additional details.
 268          * @param {misc} misc See {@link Ext.data.DataProxy}.{@link Ext.data.DataProxy#exception exception}
 269          * for description.
 270          */
 271         'exception',
 272         <div id="event-Ext.data.Store-beforeload"></div>/**
 273          * @event beforeload
 274          * Fires before a request is made for a new data object.  If the beforeload handler returns
 275          * <tt>false</tt> the {@link #load} action will be canceled.
 276          * @param {Store} this
 277          * @param {Object} options The loading options that were specified (see {@link #load} for details)
 278          */
 279         'beforeload',
 280         <div id="event-Ext.data.Store-load"></div>/**
 281          * @event load
 282          * Fires after a new set of Records has been loaded.
 283          * @param {Store} this
 284          * @param {Ext.data.Record[]} records The Records that were loaded
 285          * @param {Object} options The loading options that were specified (see {@link #load} for details)
 286          */
 287         'load',
 288         <div id="event-Ext.data.Store-loadexception"></div>/**
 289          * @event loadexception
 290          * <p>This event is <b>deprecated</b> in favor of the catch-all <b><code>{@link #exception}</code></b>
 291          * event instead.</p>
 292          * <p>This event is relayed through the corresponding {@link Ext.data.DataProxy}.
 293          * See {@link Ext.data.DataProxy}.{@link Ext.data.DataProxy#loadexception loadexception}
 294          * for additional details.
 295          * @param {misc} misc See {@link Ext.data.DataProxy}.{@link Ext.data.DataProxy#loadexception loadexception}
 296          * for description.
 297          */
 298         'loadexception',
 299         <div id="event-Ext.data.Store-beforewrite"></div>/**
 300          * @event beforewrite
 301          * @param {Ext.data.Store} store
 302          * @param {String} action [Ext.data.Api.actions.create|update|destroy]
 303          * @param {Record/Array[Record]} rs
 304          * @param {Object} options The loading options that were specified. Edit <code>options.params</code> to add Http parameters to the request.  (see {@link #save} for details)
 305          * @param {Object} arg The callback's arg object passed to the {@link #request} function
 306          */
 307         'beforewrite',
 308         <div id="event-Ext.data.Store-write"></div>/**
 309          * @event write
 310          * Fires if the server returns 200 after an Ext.data.Api.actions CRUD action.
 311          * Success of the action is determined in the <code>result['successProperty']</code>property (<b>NOTE</b> for RESTful stores,
 312          * a simple 20x response is sufficient for the actions "destroy" and "update".  The "create" action should should return 200 along with a database pk).
 313          * @param {Ext.data.Store} store
 314          * @param {String} action [Ext.data.Api.actions.create|update|destroy]
 315          * @param {Object} result The 'data' picked-out out of the response for convenience.
 316          * @param {Ext.Direct.Transaction} res
 317          * @param {Record/Record[]} rs Store's records, the subject(s) of the write-action
 318          */
 319         'write'
 320     );
 321
 322     if(this.proxy){
 323         this.relayEvents(this.proxy,  ['loadexception', 'exception']);
 324     }
 325     // With a writer set for the Store, we want to listen to add/remove events to remotely create/destroy records.
 326     if (this.writer) {
 327         this.on({
 328             scope: this,
 329             add: this.createRecords,
 330             remove: this.destroyRecord,
 331             update: this.updateRecord,
 332             clear: this.onClear
 333         });
 334     }
 335
 336     this.sortToggle = {};
 337     if(this.sortField){
 338         this.setDefaultSort(this.sortField, this.sortDir);
 339     }else if(this.sortInfo){
 340         this.setDefaultSort(this.sortInfo.field, this.sortInfo.direction);
 341     }
 342
 343     Ext.data.Store.superclass.constructor.call(this);
 344
 345     if(this.id){
 346         this.storeId = this.id;
 347         delete this.id;
 348     }
 349     if(this.storeId){
 350         Ext.StoreMgr.register(this);
 351     }
 352     if(this.inlineData){
 353         this.loadData(this.inlineData);
 354         delete this.inlineData;
 355     }else if(this.autoLoad){
 356         this.load.defer(10, this, [
 357             typeof this.autoLoad == 'object' ?
 358                 this.autoLoad : undefined]);
 359     }
 360 };
 361 Ext.extend(Ext.data.Store, Ext.util.Observable, {
 362     <div id="cfg-Ext.data.Store-storeId"></div>/**
 363      * @cfg {String} storeId If passed, the id to use to register with the <b>{@link Ext.StoreMgr StoreMgr}</b>.
 364      * <p><b>Note</b>: if a (deprecated) <tt>{@link #id}</tt> is specified it will supersede the <tt>storeId</tt>
 365      * assignment.</p>
 366      */
 367     <div id="cfg-Ext.data.Store-url"></div>/**
 368      * @cfg {String} url If a <tt>{@link #proxy}</tt> is not specified the <tt>url</tt> will be used to
 369      * implicitly configure a {@link Ext.data.HttpProxy HttpProxy} if an <tt>url</tt> is specified.
 370      * Typically this option, or the <code>{@link #data}</code> option will be specified.
 371      */
 372     <div id="cfg-Ext.data.Store-autoLoad"></div>/**
 373      * @cfg {Boolean/Object} autoLoad If <tt>{@link #data}</tt> is not specified, and if <tt>autoLoad</tt>
 374      * is <tt>true</tt> or an <tt>Object</tt>, this store's {@link #load} method is automatically called
 375      * after creation. If the value of <tt>autoLoad</tt> is an <tt>Object</tt>, this <tt>Object</tt> will
 376      * be passed to the store's {@link #load} method.
 377      */
 378     <div id="cfg-Ext.data.Store-proxy"></div>/**
 379      * @cfg {Ext.data.DataProxy} proxy The {@link Ext.data.DataProxy DataProxy} object which provides
 380      * access to a data object.  See <code>{@link #url}</code>.
 381      */
 382     <div id="cfg-Ext.data.Store-data"></div>/**
 383      * @cfg {Array} data An inline data object readable by the <code>{@link #reader}</code>.
 384      * Typically this option, or the <code>{@link #url}</code> option will be specified.
 385      */
 386     <div id="cfg-Ext.data.Store-reader"></div>/**
 387      * @cfg {Ext.data.DataReader} reader The {@link Ext.data.DataReader Reader} object which processes the
 388      * data object and returns an Array of {@link Ext.data.Record} objects which are cached keyed by their
 389      * <b><tt>{@link Ext.data.Record#id id}</tt></b> property.
 390      */
 391     <div id="cfg-Ext.data.Store-writer"></div>/**
 392      * @cfg {Ext.data.DataWriter} writer
 393      * <p>The {@link Ext.data.DataWriter Writer} object which processes a record object for being written
 394      * to the server-side database.</p>
 395      * <br><p>When a writer is installed into a Store the {@link #add}, {@link #remove}, and {@link #update}
 396      * events on the store are monitored in order to remotely {@link #createRecords create records},
 397      * {@link #destroyRecord destroy records}, or {@link #updateRecord update records}.</p>
 398      * <br><p>The proxy for this store will relay any {@link #writexception} events to this store.</p>
 399      * <br><p>Sample implementation:
 400      * <pre><code>
 401 var writer = new {@link Ext.data.JsonWriter}({
 402     encode: true,
 403     writeAllFields: true // write all fields, not just those that changed
 404 });
 405
 406 // Typical Store collecting the Proxy, Reader and Writer together.
 407 var store = new Ext.data.Store({
 408     storeId: 'user',
 409     root: 'records',
 410     proxy: proxy,
 411     reader: reader,
 412     writer: writer,     // <-- plug a DataWriter into the store just as you would a Reader
 413     paramsAsHash: true,
 414     autoSave: false    // <-- false to delay executing create, update, destroy requests
 415                         //     until specifically told to do so.
 416 });
 417      * </code></pre></p>
 418      */
 419     writer : undefined,
 420     <div id="cfg-Ext.data.Store-baseParams"></div>/**
 421      * @cfg {Object} baseParams
 422      * <p>An object containing properties which are to be sent as parameters
 423      * for <i>every</i> HTTP request.</p>
 424      * <p>Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode}.</p>
 425      * <p><b>Note</b>: <code>baseParams</code> may be superseded by any <code>params</code>
 426      * specified in a <code>{@link #load}</code> request, see <code>{@link #load}</code>
 427      * for more details.</p>
 428      * This property may be modified after creation using the <code>{@link #setBaseParam}</code>
 429      * method.
 430      * @property
 431      */
 432     <div id="cfg-Ext.data.Store-sortInfo"></div>/**
 433      * @cfg {Object} sortInfo A config object to specify the sort order in the request of a Store's
 434      * {@link #load} operation.  Note that for local sorting, the <tt>direction</tt> property is
 435      * case-sensitive. See also {@link #remoteSort} and {@link #paramNames}.
 436      * For example:<pre><code>
 437 sortInfo: {
 438     field: 'fieldName',
 439     direction: 'ASC' // or 'DESC' (case sensitive for local sorting)
 440 }
 441 </code></pre>
 442      */
 443     <div id="cfg-Ext.data.Store-remoteSort"></div>/**
 444      * @cfg {boolean} remoteSort <tt>true</tt> if sorting is to be handled by requesting the <tt>{@link #proxy Proxy}</tt>
 445      * to provide a refreshed version of the data object in sorted order, as opposed to sorting the Record cache
 446      * in place (defaults to <tt>false</tt>).
 447      * <p>If <tt>remoteSort</tt> is <tt>true</tt>, then clicking on a {@link Ext.grid.Column Grid Column}'s
 448      * {@link Ext.grid.Column#header header} causes the current page to be requested from the server appending
 449      * the following two parameters to the <b><tt>{@link #load params}</tt></b>:<div class="mdetail-params"><ul>
 450      * <li><b><tt>sort</tt></b> : String<p class="sub-desc">The <tt>name</tt> (as specified in the Record's
 451      * {@link Ext.data.Field Field definition}) of the field to sort on.</p></li>
 452      * <li><b><tt>dir</tt></b> : String<p class="sub-desc">The direction of the sort, 'ASC' or 'DESC' (case-sensitive).</p></li>
 453      * </ul></div></p>
 454      */
 455     remoteSort : false,
 456
 457     <div id="cfg-Ext.data.Store-autoDestroy"></div>/**
 458      * @cfg {Boolean} autoDestroy <tt>true</tt> to destroy the store when the component the store is bound
 459      * to is destroyed (defaults to <tt>false</tt>).
 460      * <p><b>Note</b>: this should be set to true when using stores that are bound to only 1 component.</p>
 461      */
 462     autoDestroy : false,
 463
 464     <div id="cfg-Ext.data.Store-pruneModifiedRecords"></div>/**
 465      * @cfg {Boolean} pruneModifiedRecords <tt>true</tt> to clear all modified record information each time
 466      * the store is loaded or when a record is removed (defaults to <tt>false</tt>). See {@link #getModifiedRecords}
 467      * for the accessor method to retrieve the modified records.
 468      */
 469     pruneModifiedRecords : false,
 470
 471     <div id="prop-Ext.data.Store-lastOptions"></div>/**
 472      * Contains the last options object used as the parameter to the {@link #load} method. See {@link #load}
 473      * for the details of what this may contain. This may be useful for accessing any params which were used
 474      * to load the current Record cache.
 475      * @property
 476      */
 477     lastOptions : null,
 478
 479     <div id="cfg-Ext.data.Store-autoSave"></div>/**
 480      * @cfg {Boolean} autoSave
 481      * <p>Defaults to <tt>true</tt> causing the store to automatically {@link #save} records to
 482      * the server when a record is modified (ie: becomes 'dirty'). Specify <tt>false</tt> to manually call {@link #save}
 483      * to send all modifiedRecords to the server.</p>
 484      * <br><p><b>Note</b>: each CRUD action will be sent as a separate request.</p>
 485      */
 486     autoSave : true,
 487
 488     <div id="cfg-Ext.data.Store-batch"></div>/**
 489      * @cfg {Boolean} batch
 490      * <p>Defaults to <tt>true</tt> (unless <code>{@link #restful}:true</code>). Multiple
 491      * requests for each CRUD action (CREATE, READ, UPDATE and DESTROY) will be combined
 492      * and sent as one transaction. Only applies when <code>{@link #autoSave}</code> is set
 493      * to <tt>false</tt>.</p>
 494      * <br><p>If Store is RESTful, the DataProxy is also RESTful, and a unique transaction is
 495      * generated for each record.</p>
 496      */
 497     batch : true,
 498
 499     <div id="cfg-Ext.data.Store-restful"></div>/**
 500      * @cfg {Boolean} restful
 501      * Defaults to <tt>false</tt>.  Set to <tt>true</tt> to have the Store and the set
 502      * Proxy operate in a RESTful manner. The store will automatically generate GET, POST,
 503      * PUT and DELETE requests to the server. The HTTP method used for any given CRUD
 504      * action is described in {@link Ext.data.Api#restActions}.  For additional information
 505      * see {@link Ext.data.DataProxy#restful}.
 506      * <p><b>Note</b>: if <code>{@link #restful}:true</code> <code>batch</code> will
 507      * internally be set to <tt>false</tt>.</p>
 508      */
 509     restful: false,
 510
 511     <div id="cfg-Ext.data.Store-paramNames"></div>/**
 512      * @cfg {Object} paramNames
 513      * <p>An object containing properties which specify the names of the paging and
 514      * sorting parameters passed to remote servers when loading blocks of data. By default, this
 515      * object takes the following form:</p><pre><code>
 516 {
 517     start : 'start',  // The parameter name which specifies the start row
 518     limit : 'limit',  // The parameter name which specifies number of rows to return
 519     sort : 'sort',    // The parameter name which specifies the column to sort on
 520     dir : 'dir'       // The parameter name which specifies the sort direction
 521 }
 522 </code></pre>
 523      * <p>The server must produce the requested data block upon receipt of these parameter names.
 524      * If different parameter names are required, this property can be overriden using a configuration
 525      * property.</p>
 526      * <p>A {@link Ext.PagingToolbar PagingToolbar} bound to this Store uses this property to determine
 527      * the parameter names to use in its {@link #load requests}.
 528      */
 529     paramNames : undefined,
 530
 531     <div id="cfg-Ext.data.Store-defaultParamNames"></div>/**
 532      * @cfg {Object} defaultParamNames
 533      * Provides the default values for the {@link #paramNames} property. To globally modify the parameters
 534      * for all stores, this object should be changed on the store prototype.
 535      */
 536     defaultParamNames : {
 537         start : 'start',
 538         limit : 'limit',
 539         sort : 'sort',
 540         dir : 'dir'
 541     },
 542
 543     <div id="method-Ext.data.Store-destroy"></div>/**
 544      * Destroys the store.
 545      */
 546     destroy : function(){
 547         if(!this.isDestroyed){
 548             if(this.storeId){
 549                 Ext.StoreMgr.unregister(this);
 550             }
 551             this.clearData();
 552             this.data = null;
 553             Ext.destroy(this.proxy);
 554             this.reader = this.writer = null;
 555             this.purgeListeners();
 556             this.isDestroyed = true;
 557         }
 558     },
 559
 560     <div id="method-Ext.data.Store-add"></div>/**
 561      * Add Records to the Store and fires the {@link #add} event.  To add Records
 562      * to the store from a remote source use <code>{@link #load}({add:true})</code>.
 563      * See also <code>{@link #recordType}</code> and <code>{@link #insert}</code>.
 564      * @param {Ext.data.Record[]} records An Array of Ext.data.Record objects
 565      * to add to the cache. See {@link #recordType}.
 566      */
 567     add : function(records){
 568         records = [].concat(records);
 569         if(records.length < 1){
 570             return;
 571         }
 572         for(var i = 0, len = records.length; i < len; i++){
 573             records[i].join(this);
 574         }
 575         var index = this.data.length;
 576         this.data.addAll(records);
 577         if(this.snapshot){
 578             this.snapshot.addAll(records);
 579         }
 580         this.fireEvent('add', this, records, index);
 581     },
 582
 583     <div id="method-Ext.data.Store-addSorted"></div>/**
 584      * (Local sort only) Inserts the passed Record into the Store at the index where it
 585      * should go based on the current sort information.
 586      * @param {Ext.data.Record} record
 587      */
 588     addSorted : function(record){
 589         var index = this.findInsertIndex(record);
 590         this.insert(index, record);
 591     },
 592
 593     <div id="method-Ext.data.Store-remove"></div>/**
 594      * Remove a Record from the Store and fires the {@link #remove} event.
 595      * @param {Ext.data.Record} record The Ext.data.Record object to remove from the cache.
 596      */
 597     remove : function(record){
 598         var index = this.data.indexOf(record);
 599         if(index > -1){
 600             record.join(null);
 601             this.data.removeAt(index);
 602             if(this.pruneModifiedRecords){
 603                 this.modified.remove(record);
 604             }
 605             if(this.snapshot){
 606                 this.snapshot.remove(record);
 607             }
 608             this.fireEvent('remove', this, record, index);
 609         }
 610     },
 611
 612     <div id="method-Ext.data.Store-removeAt"></div>/**
 613      * Remove a Record from the Store at the specified index. Fires the {@link #remove} event.
 614      * @param {Number} index The index of the record to remove.
 615      */
 616     removeAt : function(index){
 617         this.remove(this.getAt(index));
 618     },
 619
 620     <div id="method-Ext.data.Store-removeAll"></div>/**
 621      * Remove all Records from the Store and fires the {@link #clear} event.
 622      */
 623     removeAll : function(){
 624         var items = [];
 625         this.each(function(rec){
 626             items.push(rec);
 627         });
 628         this.clearData();
 629         if(this.snapshot){
 630             this.snapshot.clear();
 631         }
 632         if(this.pruneModifiedRecords){
 633             this.modified = [];
 634         }
 635         this.fireEvent('clear', this, items);
 636     },
 637
 638     // private
 639     onClear: function(store, records){
 640         Ext.each(records, function(rec, index){
 641             this.destroyRecord(this, rec, index);
 642         }, this);
 643     },
 644
 645     <div id="method-Ext.data.Store-insert"></div>/**
 646      * Inserts Records into the Store at the given index and fires the {@link #add} event.
 647      * See also <code>{@link #add}</code> and <code>{@link #addSorted}</code>.
 648      * @param {Number} index The start index at which to insert the passed Records.
 649      * @param {Ext.data.Record[]} records An Array of Ext.data.Record objects to add to the cache.
 650      */
 651     insert : function(index, records){
 652         records = [].concat(records);
 653         for(var i = 0, len = records.length; i < len; i++){
 654             this.data.insert(index, records[i]);
 655             records[i].join(this);
 656         }
 657         this.fireEvent('add', this, records, index);
 658     },
 659
 660     <div id="method-Ext.data.Store-indexOf"></div>/**
 661      * Get the index within the cache of the passed Record.
 662      * @param {Ext.data.Record} record The Ext.data.Record object to find.
 663      * @return {Number} The index of the passed Record. Returns -1 if not found.
 664      */
 665     indexOf : function(record){
 666         return this.data.indexOf(record);
 667     },
 668
 669     <div id="method-Ext.data.Store-indexOfId"></div>/**
 670      * Get the index within the cache of the Record with the passed id.
 671      * @param {String} id The id of the Record to find.
 672      * @return {Number} The index of the Record. Returns -1 if not found.
 673      */
 674     indexOfId : function(id){
 675         return this.data.indexOfKey(id);
 676     },
 677
 678     <div id="method-Ext.data.Store-getById"></div>/**
 679      * Get the Record with the specified id.
 680      * @param {String} id The id of the Record to find.
 681      * @return {Ext.data.Record} The Record with the passed id. Returns undefined if not found.
 682      */
 683     getById : function(id){
 684         return this.data.key(id);
 685     },
 686
 687     <div id="method-Ext.data.Store-getAt"></div>/**
 688      * Get the Record at the specified index.
 689      * @param {Number} index The index of the Record to find.
 690      * @return {Ext.data.Record} The Record at the passed index. Returns undefined if not found.
 691      */
 692     getAt : function(index){
 693         return this.data.itemAt(index);
 694     },
 695
 696     <div id="method-Ext.data.Store-getRange"></div>/**
 697      * Returns a range of Records between specified indices.
 698      * @param {Number} startIndex (optional) The starting index (defaults to 0)
 699      * @param {Number} endIndex (optional) The ending index (defaults to the last Record in the Store)
 700      * @return {Ext.data.Record[]} An array of Records
 701      */
 702     getRange : function(start, end){
 703         return this.data.getRange(start, end);
 704     },
 705
 706     // private
 707     storeOptions : function(o){
 708         o = Ext.apply({}, o);
 709         delete o.callback;
 710         delete o.scope;
 711         this.lastOptions = o;
 712     },
 713
 714     // private
 715     clearData: function(){
 716         this.data.each(function(rec) {
 717             rec.join(null);
 718         });
 719         this.data.clear();
 720     },
 721
 722     <div id="method-Ext.data.Store-load"></div>/**
 723      * <p>Loads the Record cache from the configured <tt>{@link #proxy}</tt> using the configured <tt>{@link #reader}</tt>.</p>
 724      * <br><p>Notes:</p><div class="mdetail-params"><ul>
 725      * <li><b><u>Important</u></b>: loading is asynchronous! This call will return before the new data has been
 726      * loaded. To perform any post-processing where information from the load call is required, specify
 727      * the <tt>callback</tt> function to be called, or use a {@link Ext.util.Observable#listeners a 'load' event handler}.</li>
 728      * <li>If using {@link Ext.PagingToolbar remote paging}, the first load call must specify the <tt>start</tt> and <tt>limit</tt>
 729      * properties in the <code>options.params</code> property to establish the initial position within the
 730      * dataset, and the number of Records to cache on each read from the Proxy.</li>
 731      * <li>If using {@link #remoteSort remote sorting}, the configured <code>{@link #sortInfo}</code>
 732      * will be automatically included with the posted parameters according to the specified
 733      * <code>{@link #paramNames}</code>.</li>
 734      * </ul></div>
 735      * @param {Object} options An object containing properties which control loading options:<ul>
 736      * <li><b><tt>params</tt></b> :Object<div class="sub-desc"><p>An object containing properties to pass as HTTP
 737      * parameters to a remote data source. <b>Note</b>: <code>params</code> will override any
 738      * <code>{@link #baseParams}</code> of the same name.</p>
 739      * <p>Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode}.</p></div></li>
 740      * <li><b><tt>callback</tt></b> : Function<div class="sub-desc"><p>A function to be called after the Records
 741      * have been loaded. The <tt>callback</tt> is called after the load event and is passed the following arguments:<ul>
 742      * <li><tt>r</tt> : Ext.data.Record[]</li>
 743      * <li><tt>options</tt>: Options object from the load call</li>
 744      * <li><tt>success</tt>: Boolean success indicator</li></ul></p></div></li>
 745      * <li><b><tt>scope</tt></b> : Object<div class="sub-desc"><p>Scope with which to call the callback (defaults
 746      * to the Store object)</p></div></li>
 747      * <li><b><tt>add</tt></b> : Boolean<div class="sub-desc"><p>Indicator to append loaded records rather than
 748      * replace the current cache.  <b>Note</b>: see note for <tt>{@link #loadData}</tt></p></div></li>
 749      * </ul>
 750      * @return {Boolean} If the <i>developer</i> provided <tt>{@link #beforeload}</tt> event handler returns
 751      * <tt>false</tt>, the load call will abort and will return <tt>false</tt>; otherwise will return <tt>true</tt>.
 752      */
 753     load : function(options) {
 754         options = options || {};
 755         this.storeOptions(options);
 756         if(this.sortInfo && this.remoteSort){
 757             var pn = this.paramNames;
 758             options.params = options.params || {};
 759             options.params[pn.sort] = this.sortInfo.field;
 760             options.params[pn.dir] = this.sortInfo.direction;
 761         }
 762         try {
 763             return this.execute('read', null, options); // <-- null represents rs.  No rs for load actions.
 764         } catch(e) {
 765             this.handleException(e);
 766             return false;
 767         }
 768     },
 769
 770     /**
 771      * updateRecord  Should not be used directly.  This method will be called automatically if a Writer is set.
 772      * Listens to 'update' event.
 773      * @param {Object} store
 774      * @param {Object} record
 775      * @param {Object} action
 776      * @private
 777      */
 778     updateRecord : function(store, record, action) {
 779         if (action == Ext.data.Record.EDIT && this.autoSave === true && (!record.phantom || (record.phantom && record.isValid))) {
 780             this.save();
 781         }
 782     },
 783
 784     /**
 785      * Should not be used directly.  Store#add will call this automatically if a Writer is set
 786      * @param {Object} store
 787      * @param {Object} rs
 788      * @param {Object} index
 789      * @private
 790      */
 791     createRecords : function(store, rs, index) {
 792         for (var i = 0, len = rs.length; i < len; i++) {
 793             if (rs[i].phantom && rs[i].isValid()) {
 794                 rs[i].markDirty();  // <-- Mark new records dirty
 795                 this.modified.push(rs[i]);  // <-- add to modified
 796             }
 797         }
 798         if (this.autoSave === true) {
 799             this.save();
 800         }
 801     },
 802
 803     /**
 804      * Destroys a record or records.  Should not be used directly.  It's called by Store#remove if a Writer is set.
 805      * @param {Store} this
 806      * @param {Ext.data.Record/Ext.data.Record[]}
 807      * @param {Number} index
 808      * @private
 809      */
 810     destroyRecord : function(store, record, index) {
 811         if (this.modified.indexOf(record) != -1) {  // <-- handled already if @cfg pruneModifiedRecords == true
 812             this.modified.remove(record);
 813         }
 814         if (!record.phantom) {
 815             this.removed.push(record);
 816
 817             // since the record has already been removed from the store but the server request has not yet been executed,
 818             // must keep track of the last known index this record existed.  If a server error occurs, the record can be
 819             // put back into the store.  @see Store#createCallback where the record is returned when response status === false
 820             record.lastIndex = index;
 821
 822             if (this.autoSave === true) {
 823                 this.save();
 824             }
 825         }
 826     },
 827
 828     /**
 829      * This method should generally not be used directly.  This method is called internally
 830      * by {@link #load}, or if a Writer is set will be called automatically when {@link #add},
 831      * {@link #remove}, or {@link #update} events fire.
 832      * @param {String} action Action name ('read', 'create', 'update', or 'destroy')
 833      * @param {Record/Record[]} rs
 834      * @param {Object} options
 835      * @throws Error
 836      * @private
 837      */
 838     execute : function(action, rs, options) {
 839         // blow up if action not Ext.data.CREATE, READ, UPDATE, DESTROY
 840         if (!Ext.data.Api.isAction(action)) {
 841             throw new Ext.data.Api.Error('execute', action);
 842         }
 843         // make sure options has a params key
 844         options = Ext.applyIf(options||{}, {
 845             params: {}
 846         });
 847
 848         // have to separate before-events since load has a different signature than create,destroy and save events since load does not
 849         // include the rs (record resultset) parameter.  Capture return values from the beforeaction into doRequest flag.
 850         var doRequest = true;
 851
 852         if (action === 'read') {
 853             Ext.applyIf(options.params, this.baseParams);
 854             doRequest = this.fireEvent('beforeload', this, options);
 855         }
 856         else {
 857             // if Writer is configured as listful, force single-record rs to be [{}] instead of {}
 858             // TODO Move listful rendering into DataWriter where the @cfg is defined.  Should be easy now.
 859             if (this.writer.listful === true && this.restful !== true) {
 860                 rs = (Ext.isArray(rs)) ? rs : [rs];
 861             }
 862             // if rs has just a single record, shift it off so that Writer writes data as '{}' rather than '[{}]'
 863             else if (Ext.isArray(rs) && rs.length == 1) {
 864                 rs = rs.shift();
 865             }
 866             // Write the action to options.params
 867             if ((doRequest = this.fireEvent('beforewrite', this, action, rs, options)) !== false) {
 868                 this.writer.write(action, options.params, rs);
 869             }
 870         }
 871         if (doRequest !== false) {
 872             // Send request to proxy.
 873             var params = Ext.apply({}, options.params, this.baseParams);
 874             if (this.writer && this.proxy.url && !this.proxy.restful && !Ext.data.Api.hasUniqueUrl(this.proxy, action)) {
 875                 params.xaction = action;    // <-- really old, probaby unecessary.
 876             }
 877             // Note:  Up until this point we've been dealing with 'action' as a key from Ext.data.Api.actions.
 878             // We'll flip it now and send the value into DataProxy#request, since it's the value which maps to
 879             // the user's configured DataProxy#api
 880             this.proxy.request(Ext.data.Api.actions[action], rs, params, this.reader, this.createCallback(action, rs), this, options);
 881         }
 882         return doRequest;
 883     },
 884
 885     <div id="method-Ext.data.Store-save"></div>/**
 886      * Saves all pending changes to the store.  If the commensurate Ext.data.Api.actions action is not configured, then
 887      * the configured <code>{@link #url}</code> will be used.
 888      * <pre>
 889      * change            url
 890      * ---------------   --------------------
 891      * removed records   Ext.data.Api.actions.destroy
 892      * phantom records   Ext.data.Api.actions.create
 893      * {@link #getModifiedRecords modified records}  Ext.data.Api.actions.update
 894      * </pre>
 895      * @TODO:  Create extensions of Error class and send associated Record with thrown exceptions.
 896      * e.g.:  Ext.data.DataReader.Error or Ext.data.Error or Ext.data.DataProxy.Error, etc.
 897      */
 898     save : function() {
 899         if (!this.writer) {
 900             throw new Ext.data.Store.Error('writer-undefined');
 901         }
 902
 903         // DESTROY:  First check for removed records.  Records in this.removed are guaranteed non-phantoms.  @see Store#remove
 904         if (this.removed.length) {
 905             this.doTransaction('destroy', this.removed);
 906         }
 907
 908         // Check for modified records. Use a copy so Store#rejectChanges will work if server returns error.
 909         var rs = [].concat(this.getModifiedRecords());
 910         if (!rs.length) { // Bail-out if empty...
 911             return true;
 912         }
 913
 914         // CREATE:  Next check for phantoms within rs.  splice-off and execute create.
 915         var phantoms = [];
 916         for (var i = rs.length-1; i >= 0; i--) {
 917             if (rs[i].phantom === true) {
 918                 var rec = rs.splice(i, 1).shift();
 919                 if (rec.isValid()) {
 920                     phantoms.push(rec);
 921                 }
 922             } else if (!rs[i].isValid()) { // <-- while we're here, splice-off any !isValid real records
 923                 rs.splice(i,1);
 924             }
 925         }
 926         // If we have valid phantoms, create them...
 927         if (phantoms.length) {
 928             this.doTransaction('create', phantoms);
 929         }
 930
 931         // UPDATE:  And finally, if we're still here after splicing-off phantoms and !isValid real records, update the rest...
 932         if (rs.length) {
 933             this.doTransaction('update', rs);
 934         }
 935         return true;
 936     },
 937
 938     // private.  Simply wraps call to Store#execute in try/catch.  Defers to Store#handleException on error.  Loops if batch: false
 939     doTransaction : function(action, rs) {
 940         function transaction(records) {
 941             try {
 942                 this.execute(action, records);
 943             } catch (e) {
 944                 this.handleException(e);
 945             }
 946         }
 947         if (this.batch === false) {
 948             for (var i = 0, len = rs.length; i < len; i++) {
 949                 transaction.call(this, rs[i]);
 950             }
 951         } else {
 952             transaction.call(this, rs);
 953         }
 954     },
 955
 956     // @private callback-handler for remote CRUD actions
 957     // Do not override -- override loadRecords, onCreateRecords, onDestroyRecords and onUpdateRecords instead.
 958     createCallback : function(action, rs) {
 959         var actions = Ext.data.Api.actions;
 960         return (action == 'read') ? this.loadRecords : function(data, response, success) {
 961             // calls: onCreateRecords | onUpdateRecords | onDestroyRecords
 962             this['on' + Ext.util.Format.capitalize(action) + 'Records'](success, rs, [].concat(data));
 963             // If success === false here, exception will have been called in DataProxy
 964             if (success === true) {
 965                 this.fireEvent('write', this, action, data, response, rs);
 966             }
 967         };
 968     },
 969
 970     // Clears records from modified array after an exception event.
 971     // NOTE:  records are left marked dirty.  Do we want to commit them even though they were not updated/realized?
 972     // TODO remove this method?
 973     clearModified : function(rs) {
 974         if (Ext.isArray(rs)) {
 975             for (var n=rs.length-1;n>=0;n--) {
 976                 this.modified.splice(this.modified.indexOf(rs[n]), 1);
 977             }
 978         } else {
 979             this.modified.splice(this.modified.indexOf(rs), 1);
 980         }
 981     },
 982
 983     // remap record ids in MixedCollection after records have been realized.  @see Store#onCreateRecords, @see DataReader#realize
 984     reMap : function(record) {
 985         if (Ext.isArray(record)) {
 986             for (var i = 0, len = record.length; i < len; i++) {
 987                 this.reMap(record[i]);
 988             }
 989         } else {
 990             delete this.data.map[record._phid];
 991             this.data.map[record.id] = record;
 992             var index = this.data.keys.indexOf(record._phid);
 993             this.data.keys.splice(index, 1, record.id);
 994             delete record._phid;
 995         }
 996     },
 997
 998     // @protected onCreateRecord proxy callback for create action
 999     onCreateRecords : function(success, rs, data) {
1000         if (success === true) {
1001             try {
1002                 this.reader.realize(rs, data);
1003                 this.reMap(rs);
1004             }
1005             catch (e) {
1006                 this.handleException(e);
1007                 if (Ext.isArray(rs)) {
1008                     // Recurse to run back into the try {}.  DataReader#realize splices-off the rs until empty.
1009                     this.onCreateRecords(success, rs, data);
1010                 }
1011             }
1012         }
1013     },
1014
1015     // @protected, onUpdateRecords proxy callback for update action
1016     onUpdateRecords : function(success, rs, data) {
1017         if (success === true) {
1018             try {
1019                 this.reader.update(rs, data);
1020             } catch (e) {
1021                 this.handleException(e);
1022                 if (Ext.isArray(rs)) {
1023                     // Recurse to run back into the try {}.  DataReader#update splices-off the rs until empty.
1024                     this.onUpdateRecords(success, rs, data);
1025                 }
1026             }
1027         }
1028     },
1029
1030     // @protected onDestroyRecords proxy callback for destroy action
1031     onDestroyRecords : function(success, rs, data) {
1032         // splice each rec out of this.removed
1033         rs = (rs instanceof Ext.data.Record) ? [rs] : [].concat(rs);
1034         for (var i=0,len=rs.length;i<len;i++) {
1035             this.removed.splice(this.removed.indexOf(rs[i]), 1);
1036         }
1037         if (success === false) {
1038             // put records back into store if remote destroy fails.
1039             // @TODO: Might want to let developer decide.
1040             for (i=rs.length-1;i>=0;i--) {
1041                 this.insert(rs[i].lastIndex, rs[i]);    // <-- lastIndex set in Store#destroyRecord
1042             }
1043         }
1044     },
1045
1046     // protected handleException.  Possibly temporary until Ext framework has an exception-handler.
1047     handleException : function(e) {
1048         // @see core/Error.js
1049         Ext.handleError(e);
1050     },
1051
1052     <div id="method-Ext.data.Store-reload"></div>/**
1053      * <p>Reloads the Record cache from the configured Proxy using the configured {@link Ext.data.Reader Reader} and
1054      * the options from the last load operation performed.</p>
1055      * <p><b>Note</b>: see the Important note in {@link #load}.</p>
1056      * @param {Object} options (optional) An <tt>Object</tt> containing {@link #load loading options} which may
1057      * override the options used in the last {@link #load} operation. See {@link #load} for details (defaults to
1058      * <tt>null</tt>, in which case the {@link #lastOptions} are used).
1059      */
1060     reload : function(options){
1061         this.load(Ext.applyIf(options||{}, this.lastOptions));
1062     },
1063
1064     // private
1065     // Called as a callback by the Reader during a load operation.
1066     loadRecords : function(o, options, success){
1067         if(!o || success === false){
1068             if(success !== false){
1069                 this.fireEvent('load', this, [], options);
1070             }
1071             if(options.callback){
1072                 options.callback.call(options.scope || this, [], options, false, o);
1073             }
1074             return;
1075         }
1076         var r = o.records, t = o.totalRecords || r.length;
1077         if(!options || options.add !== true){
1078             if(this.pruneModifiedRecords){
1079                 this.modified = [];
1080             }
1081             for(var i = 0, len = r.length; i < len; i++){
1082                 r[i].join(this);
1083             }
1084             if(this.snapshot){
1085                 this.data = this.snapshot;
1086                 delete this.snapshot;
1087             }
1088             this.clearData();
1089             this.data.addAll(r);
1090             this.totalLength = t;
1091             this.applySort();
1092             this.fireEvent('datachanged', this);
1093         }else{
1094             this.totalLength = Math.max(t, this.data.length+r.length);
1095             this.add(r);
1096         }
1097         this.fireEvent('load', this, r, options);
1098         if(options.callback){
1099             options.callback.call(options.scope || this, r, options, true);
1100         }
1101     },
1102
1103     <div id="method-Ext.data.Store-loadData"></div>/**
1104      * Loads data from a passed data block and fires the {@link #load} event. A {@link Ext.data.Reader Reader}
1105      * which understands the format of the data must have been configured in the constructor.
1106      * @param {Object} data The data block from which to read the Records.  The format of the data expected
1107      * is dependent on the type of {@link Ext.data.Reader Reader} that is configured and should correspond to
1108      * that {@link Ext.data.Reader Reader}'s <tt>{@link Ext.data.Reader#readRecords}</tt> parameter.
1109      * @param {Boolean} append (Optional) <tt>true</tt> to append the new Records rather the default to replace
1110      * the existing cache.
1111      * <b>Note</b>: that Records in a Store are keyed by their {@link Ext.data.Record#id id}, so added Records
1112      * with ids which are already present in the Store will <i>replace</i> existing Records. Only Records with
1113      * new, unique ids will be added.
1114      */
1115     loadData : function(o, append){
1116         var r = this.reader.readRecords(o);
1117         this.loadRecords(r, {add: append}, true);
1118     },
1119
1120     <div id="method-Ext.data.Store-getCount"></div>/**
1121      * Gets the number of cached records.
1122      * <p>If using paging, this may not be the total size of the dataset. If the data object
1123      * used by the Reader contains the dataset size, then the {@link #getTotalCount} function returns
1124      * the dataset size.  <b>Note</b>: see the Important note in {@link #load}.</p>
1125      * @return {Number} The number of Records in the Store's cache.
1126      */
1127     getCount : function(){
1128         return this.data.length || 0;
1129     },
1130
1131     <div id="method-Ext.data.Store-getTotalCount"></div>/**
1132      * Gets the total number of records in the dataset as returned by the server.
1133      * <p>If using paging, for this to be accurate, the data object used by the {@link #reader Reader}
1134      * must contain the dataset size. For remote data sources, the value for this property
1135      * (<tt>totalProperty</tt> for {@link Ext.data.JsonReader JsonReader},
1136      * <tt>totalRecords</tt> for {@link Ext.data.XmlReader XmlReader}) shall be returned by a query on the server.
1137      * <b>Note</b>: see the Important note in {@link #load}.</p>
1138      * @return {Number} The number of Records as specified in the data object passed to the Reader
1139      * by the Proxy.
1140      * <p><b>Note</b>: this value is not updated when changing the contents of the Store locally.</p>
1141      */
1142     getTotalCount : function(){
1143         return this.totalLength || 0;
1144     },
1145
1146     <div id="method-Ext.data.Store-getSortState"></div>/**
1147      * Returns an object describing the current sort state of this Store.
1148      * @return {Object} The sort state of the Store. An object with two properties:<ul>
1149      * <li><b>field : String<p class="sub-desc">The name of the field by which the Records are sorted.</p></li>
1150      * <li><b>direction : String<p class="sub-desc">The sort order, 'ASC' or 'DESC' (case-sensitive).</p></li>
1151      * </ul>
1152      * See <tt>{@link #sortInfo}</tt> for additional details.
1153      */
1154     getSortState : function(){
1155         return this.sortInfo;
1156     },
1157
1158     // private
1159     applySort : function(){
1160         if(this.sortInfo && !this.remoteSort){
1161             var s = this.sortInfo, f = s.field;
1162             this.sortData(f, s.direction);
1163         }
1164     },
1165
1166     // private
1167     sortData : function(f, direction){
1168         direction = direction || 'ASC';
1169         var st = this.fields.get(f).sortType;
1170         var fn = function(r1, r2){
1171             var v1 = st(r1.data[f]), v2 = st(r2.data[f]);
1172             return v1 > v2 ? 1 : (v1 < v2 ? -1 : 0);
1173         };
1174         this.data.sort(direction, fn);
1175         if(this.snapshot && this.snapshot != this.data){
1176             this.snapshot.sort(direction, fn);
1177         }
1178     },
1179
1180     <div id="method-Ext.data.Store-setDefaultSort"></div>/**
1181      * Sets the default sort column and order to be used by the next {@link #load} operation.
1182      * @param {String} fieldName The name of the field to sort by.
1183      * @param {String} dir (optional) The sort order, 'ASC' or 'DESC' (case-sensitive, defaults to <tt>'ASC'</tt>)
1184      */
1185     setDefaultSort : function(field, dir){
1186         dir = dir ? dir.toUpperCase() : 'ASC';
1187         this.sortInfo = {field: field, direction: dir};
1188         this.sortToggle[field] = dir;
1189     },
1190
1191     <div id="method-Ext.data.Store-sort"></div>/**
1192      * Sort the Records.
1193      * If remote sorting is used, the sort is performed on the server, and the cache is reloaded. If local
1194      * sorting is used, the cache is sorted internally. See also {@link #remoteSort} and {@link #paramNames}.
1195      * @param {String} fieldName The name of the field to sort by.
1196      * @param {String} dir (optional) The sort order, 'ASC' or 'DESC' (case-sensitive, defaults to <tt>'ASC'</tt>)
1197      */
1198     sort : function(fieldName, dir){
1199         var f = this.fields.get(fieldName);
1200         if(!f){
1201             return false;
1202         }
1203         if(!dir){
1204             if(this.sortInfo && this.sortInfo.field == f.name){ // toggle sort dir
1205                 dir = (this.sortToggle[f.name] || 'ASC').toggle('ASC', 'DESC');
1206             }else{
1207                 dir = f.sortDir;
1208             }
1209         }
1210         var st = (this.sortToggle) ? this.sortToggle[f.name] : null;
1211         var si = (this.sortInfo) ? this.sortInfo : null;
1212
1213         this.sortToggle[f.name] = dir;
1214         this.sortInfo = {field: f.name, direction: dir};
1215         if(!this.remoteSort){
1216             this.applySort();
1217             this.fireEvent('datachanged', this);
1218         }else{
1219             if (!this.load(this.lastOptions)) {
1220                 if (st) {
1221                     this.sortToggle[f.name] = st;
1222                 }
1223                 if (si) {
1224                     this.sortInfo = si;
1225                 }
1226             }
1227         }
1228     },
1229
1230     <div id="method-Ext.data.Store-each"></div>/**
1231      * Calls the specified function for each of the {@link Ext.data.Record Records} in the cache.
1232      * @param {Function} fn The function to call. The {@link Ext.data.Record Record} is passed as the first parameter.
1233      * Returning <tt>false</tt> aborts and exits the iteration.
1234      * @param {Object} scope (optional) The scope in which to call the function (defaults to the {@link Ext.data.Record Record}).
1235      */
1236     each : function(fn, scope){
1237         this.data.each(fn, scope);
1238     },
1239
1240     <div id="method-Ext.data.Store-getModifiedRecords"></div>/**
1241      * Gets all {@link Ext.data.Record records} modified since the last commit.  Modified records are
1242      * persisted across load operations (e.g., during paging). <b>Note</b>: deleted records are not
1243      * included.  See also <tt>{@link #pruneModifiedRecords}</tt> and
1244      * {@link Ext.data.Record}<tt>{@link Ext.data.Record#markDirty markDirty}.</tt>.
1245      * @return {Ext.data.Record[]} An array of {@link Ext.data.Record Records} containing outstanding
1246      * modifications.  To obtain modified fields within a modified record see
1247      *{@link Ext.data.Record}<tt>{@link Ext.data.Record#modified modified}.</tt>.
1248      */
1249     getModifiedRecords : function(){
1250         return this.modified;
1251     },
1252
1253     // private
1254     createFilterFn : function(property, value, anyMatch, caseSensitive){
1255         if(Ext.isEmpty(value, false)){
1256             return false;
1257         }
1258         value = this.data.createValueMatcher(value, anyMatch, caseSensitive);
1259         return function(r){
1260             return value.test(r.data[property]);
1261         };
1262     },
1263
1264     <div id="method-Ext.data.Store-sum"></div>/**
1265      * Sums the value of <tt>property</tt> for each {@link Ext.data.Record record} between <tt>start</tt>
1266      * and <tt>end</tt> and returns the result.
1267      * @param {String} property A field in each record
1268      * @param {Number} start (optional) The record index to start at (defaults to <tt>0</tt>)
1269      * @param {Number} end (optional) The last record index to include (defaults to length - 1)
1270      * @return {Number} The sum
1271      */
1272     sum : function(property, start, end){
1273         var rs = this.data.items, v = 0;
1274         start = start || 0;
1275         end = (end || end === 0) ? end : rs.length-1;
1276
1277         for(var i = start; i <= end; i++){
1278             v += (rs[i].data[property] || 0);
1279         }
1280         return v;
1281     },
1282
1283     <div id="method-Ext.data.Store-filter"></div>/**
1284      * Filter the {@link Ext.data.Record records} by a specified property.
1285      * @param {String} field A field on your records
1286      * @param {String/RegExp} value Either a string that the field should begin with, or a RegExp to test
1287      * against the field.
1288      * @param {Boolean} anyMatch (optional) <tt>true</tt> to match any part not just the beginning
1289      * @param {Boolean} caseSensitive (optional) <tt>true</tt> for case sensitive comparison
1290      */
1291     filter : function(property, value, anyMatch, caseSensitive){
1292         var fn = this.createFilterFn(property, value, anyMatch, caseSensitive);
1293         return fn ? this.filterBy(fn) : this.clearFilter();
1294     },
1295
1296     <div id="method-Ext.data.Store-filterBy"></div>/**
1297      * Filter by a function. The specified function will be called for each
1298      * Record in this Store. If the function returns <tt>true</tt> the Record is included,
1299      * otherwise it is filtered out.
1300      * @param {Function} fn The function to be called. It will be passed the following parameters:<ul>
1301      * <li><b>record</b> : Ext.data.Record<p class="sub-desc">The {@link Ext.data.Record record}
1302      * to test for filtering. Access field values using {@link Ext.data.Record#get}.</p></li>
1303      * <li><b>id</b> : Object<p class="sub-desc">The ID of the Record passed.</p></li>
1304      * </ul>
1305      * @param {Object} scope (optional) The scope of the function (defaults to this)
1306      */
1307     filterBy : function(fn, scope){
1308         this.snapshot = this.snapshot || this.data;
1309         this.data = this.queryBy(fn, scope||this);
1310         this.fireEvent('datachanged', this);
1311     },
1312
1313     <div id="method-Ext.data.Store-query"></div>/**
1314      * Query the records by a specified property.
1315      * @param {String} field A field on your records
1316      * @param {String/RegExp} value Either a string that the field
1317      * should begin with, or a RegExp to test against the field.
1318      * @param {Boolean} anyMatch (optional) True to match any part not just the beginning
1319      * @param {Boolean} caseSensitive (optional) True for case sensitive comparison
1320      * @return {MixedCollection} Returns an Ext.util.MixedCollection of the matched records
1321      */
1322     query : function(property, value, anyMatch, caseSensitive){
1323         var fn = this.createFilterFn(property, value, anyMatch, caseSensitive);
1324         return fn ? this.queryBy(fn) : this.data.clone();
1325     },
1326
1327     <div id="method-Ext.data.Store-queryBy"></div>/**
1328      * Query the cached records in this Store using a filtering function. The specified function
1329      * will be called with each record in this Store. If the function returns <tt>true</tt> the record is
1330      * included in the results.
1331      * @param {Function} fn The function to be called. It will be passed the following parameters:<ul>
1332      * <li><b>record</b> : Ext.data.Record<p class="sub-desc">The {@link Ext.data.Record record}
1333      * to test for filtering. Access field values using {@link Ext.data.Record#get}.</p></li>
1334      * <li><b>id</b> : Object<p class="sub-desc">The ID of the Record passed.</p></li>
1335      * </ul>
1336      * @param {Object} scope (optional) The scope of the function (defaults to this)
1337      * @return {MixedCollection} Returns an Ext.util.MixedCollection of the matched records
1338      **/
1339     queryBy : function(fn, scope){
1340         var data = this.snapshot || this.data;
1341         return data.filterBy(fn, scope||this);
1342     },
1343
1344     <div id="method-Ext.data.Store-find"></div>/**
1345      * Finds the index of the first matching record in this store by a specific property/value.
1346      * @param {String} property A property on your objects
1347      * @param {String/RegExp} value Either a string that the property value
1348      * should begin with, or a RegExp to test against the property.
1349      * @param {Number} startIndex (optional) The index to start searching at
1350      * @param {Boolean} anyMatch (optional) True to match any part of the string, not just the beginning
1351      * @param {Boolean} caseSensitive (optional) True for case sensitive comparison
1352      * @return {Number} The matched index or -1
1353      */
1354     find : function(property, value, start, anyMatch, caseSensitive){
1355         var fn = this.createFilterFn(property, value, anyMatch, caseSensitive);
1356         return fn ? this.data.findIndexBy(fn, null, start) : -1;
1357     },
1358
1359     <div id="method-Ext.data.Store-findExact"></div>/**
1360      * Finds the index of the first matching record in this store by a specific property/value.
1361      * @param {String} property A property on your objects
1362      * @param {String/RegExp} value The value to match against
1363      * @param {Number} startIndex (optional) The index to start searching at
1364      * @return {Number} The matched index or -1
1365      */
1366     findExact: function(property, value, start){
1367         return this.data.findIndexBy(function(rec){
1368             return rec.get(property) === value;
1369         }, this, start);
1370     },
1371
1372     <div id="method-Ext.data.Store-findBy"></div>/**
1373      * Find the index of the first matching Record in this Store by a function.
1374      * If the function returns <tt>true</tt> it is considered a match.
1375      * @param {Function} fn The function to be called. It will be passed the following parameters:<ul>
1376      * <li><b>record</b> : Ext.data.Record<p class="sub-desc">The {@link Ext.data.Record record}
1377      * to test for filtering. Access field values using {@link Ext.data.Record#get}.</p></li>
1378      * <li><b>id</b> : Object<p class="sub-desc">The ID of the Record passed.</p></li>
1379      * </ul>
1380      * @param {Object} scope (optional) The scope of the function (defaults to this)
1381      * @param {Number} startIndex (optional) The index to start searching at
1382      * @return {Number} The matched index or -1
1383      */
1384     findBy : function(fn, scope, start){
1385         return this.data.findIndexBy(fn, scope, start);
1386     },
1387
1388     <div id="method-Ext.data.Store-collect"></div>/**
1389      * Collects unique values for a particular dataIndex from this store.
1390      * @param {String} dataIndex The property to collect
1391      * @param {Boolean} allowNull (optional) Pass true to allow null, undefined or empty string values
1392      * @param {Boolean} bypassFilter (optional) Pass true to collect from all records, even ones which are filtered
1393      * @return {Array} An array of the unique values
1394      **/
1395     collect : function(dataIndex, allowNull, bypassFilter){
1396         var d = (bypassFilter === true && this.snapshot) ?
1397                 this.snapshot.items : this.data.items;
1398         var v, sv, r = [], l = {};
1399         for(var i = 0, len = d.length; i < len; i++){
1400             v = d[i].data[dataIndex];
1401             sv = String(v);
1402             if((allowNull || !Ext.isEmpty(v)) && !l[sv]){
1403                 l[sv] = true;
1404                 r[r.length] = v;
1405             }
1406         }
1407         return r;
1408     },
1409
1410     <div id="method-Ext.data.Store-clearFilter"></div>/**
1411      * Revert to a view of the Record cache with no filtering applied.
1412      * @param {Boolean} suppressEvent If <tt>true</tt> the filter is cleared silently without firing the
1413      * {@link #datachanged} event.
1414      */
1415     clearFilter : function(suppressEvent){
1416         if(this.isFiltered()){
1417             this.data = this.snapshot;
1418             delete this.snapshot;
1419             if(suppressEvent !== true){
1420                 this.fireEvent('datachanged', this);
1421             }
1422         }
1423     },
1424
1425     <div id="method-Ext.data.Store-isFiltered"></div>/**
1426      * Returns true if this store is currently filtered
1427      * @return {Boolean}
1428      */
1429     isFiltered : function(){
1430         return this.snapshot && this.snapshot != this.data;
1431     },
1432
1433     // private
1434     afterEdit : function(record){
1435         if(this.modified.indexOf(record) == -1){
1436             this.modified.push(record);
1437         }
1438         this.fireEvent('update', this, record, Ext.data.Record.EDIT);
1439     },
1440
1441     // private
1442     afterReject : function(record){
1443         this.modified.remove(record);
1444         this.fireEvent('update', this, record, Ext.data.Record.REJECT);
1445     },
1446
1447     // private
1448     afterCommit : function(record){
1449         this.modified.remove(record);
1450         this.fireEvent('update', this, record, Ext.data.Record.COMMIT);
1451     },
1452
1453     <div id="method-Ext.data.Store-commitChanges"></div>/**
1454      * Commit all Records with {@link #getModifiedRecords outstanding changes}. To handle updates for changes,
1455      * subscribe to the Store's {@link #update update event}, and perform updating when the third parameter is
1456      * Ext.data.Record.COMMIT.
1457      */
1458     commitChanges : function(){
1459         var m = this.modified.slice(0);
1460         this.modified = [];
1461         for(var i = 0, len = m.length; i < len; i++){
1462             m[i].commit();
1463         }
1464     },
1465
1466     <div id="method-Ext.data.Store-rejectChanges"></div>/**
1467      * {@link Ext.data.Record#reject Reject} outstanding changes on all {@link #getModifiedRecords modified records}.
1468      */
1469     rejectChanges : function(){
1470         var m = this.modified.slice(0);
1471         this.modified = [];
1472         for(var i = 0, len = m.length; i < len; i++){
1473             m[i].reject();
1474         }
1475         var m = this.removed.slice(0).reverse();
1476         this.removed = [];
1477         for(var i = 0, len = m.length; i < len; i++){
1478             this.insert(m[i].lastIndex||0, m[i]);
1479             m[i].reject();
1480         }
1481     },
1482
1483     // private
1484     onMetaChange : function(meta){
1485         this.recordType = this.reader.recordType;
1486         this.fields = this.recordType.prototype.fields;
1487         delete this.snapshot;
1488         if(this.reader.meta.sortInfo){
1489             this.sortInfo = this.reader.meta.sortInfo;
1490         }else if(this.sortInfo  && !this.fields.get(this.sortInfo.field)){
1491             delete this.sortInfo;
1492         }
1493         if(this.writer){
1494             this.writer.meta = this.reader.meta;
1495         }
1496         this.modified = [];
1497         this.fireEvent('metachange', this, this.reader.meta);
1498     },
1499
1500     // private
1501     findInsertIndex : function(record){
1502         this.suspendEvents();
1503         var data = this.data.clone();
1504         this.data.add(record);
1505         this.applySort();
1506         var index = this.data.indexOf(record);
1507         this.data = data;
1508         this.resumeEvents();
1509         return index;
1510     },
1511
1512     <div id="method-Ext.data.Store-setBaseParam"></div>/**
1513      * Set the value for a property name in this store's {@link #baseParams}.  Usage:</p><pre><code>
1514 myStore.setBaseParam('foo', {bar:3});
1515 </code></pre>
1516      * @param {String} name Name of the property to assign
1517      * @param {Mixed} value Value to assign the <tt>name</tt>d property
1518      **/
1519     setBaseParam : function (name, value){
1520         this.baseParams = this.baseParams || {};
1521         this.baseParams[name] = value;
1522     }
1523 });
1524
1525 Ext.reg('store', Ext.data.Store);
1526
1527 <div id="cls-Ext.data.Store.Error"></div>/**
1528  * @class Ext.data.Store.Error
1529  * @extends Ext.Error
1530  * Store Error extension.
1531  * @param {String} name
1532  */
1533 Ext.data.Store.Error = Ext.extend(Ext.Error, {
1534     name: 'Ext.data.Store'
1535 });
1536 Ext.apply(Ext.data.Store.Error.prototype, {
1537     lang: {
1538         'writer-undefined' : 'Attempted to execute a write-action without a DataWriter installed.'
1539     }
1540 });
1541
1542 </pre>
1543 </body>
1544 </html>