store.js

ext-2.3.0

/*
 * Ext JS Library 2.3.0
 * Copyright(c) 2006-2009, Ext JS, LLC.
 * [e-mail]
 * 
 * http://extjs.com/license
 */

/**
 * @class Ext.data.Store
 * @extends Ext.util.Observable
 * The Store class encapsulates a client side cache of {@link Ext.data.Record Record}
 * objects which provide input data for Components such as the {@link Ext.grid.GridPanel GridPanel},
 * the {@link Ext.form.ComboBox ComboBox}, or the {@link Ext.DataView DataView}</p>
 * <p>A Store object uses its {@link #proxy configured} implementation of {@link Ext.data.DataProxy DataProxy}
 * to access a data object unless you call {@link #loadData} directly and pass in your data.</p>
 * <p>A Store object has no knowledge of the format of the data returned by the Proxy.</p>
 * <p>A Store object uses its {@link #reader configured} implementation of {@link Ext.data.DataReader DataReader}
 * to create {@link Ext.data.Record Record} instances from the data object. These Records
 * are cached and made available through accessor functions.</p>
 * @constructor
 * Creates a new Store.
 * @param {Object} config A config object containing the objects needed for the Store to access data,
 * and read the data into Records.
 */
Ext.data.Store = function(config){
    this.data = new Ext.util.MixedCollection(false);
    this.data.getKey = function(o){
        return o.id;
    };
    /**
     * An object containing properties which are used as parameters on any HTTP request.
     * This property can be changed after creating the Store to send different parameters.
     * @property
     */
    this.baseParams = {};
    /**
     * <p>An object containing properties which specify the names of the paging and
     * sorting parameters passed to remote servers when loading blocks of data. By default, this
     * object takes the following form:</p><pre><code>
{
    start : "start",    // The parameter name which specifies the start row
    limit : "limit",    // The parameter name which specifies number of rows to return
    sort : "sort",      // The parameter name which specifies the column to sort on
    dir : "dir"         // The parameter name which specifies the sort direction
}
</code></pre>
     * <p>The server must produce the requested data block upon receipt of these parameter names.
     * If different parameter names are required, this property can be overriden using a configuration
     * property.</p>
     * <p>A {@link Ext.PagingToolbar PagingToolbar} bound to this grid uses this property to determine
     * the parameter names to use in its requests.
     * @property
     */
    this.paramNames = {
        "start" : "start",
        "limit" : "limit",
        "sort" : "sort",
        "dir" : "dir"
    };

    if(config && config.data){
        this.inlineData = config.data;
        delete config.data;
    }

    Ext.apply(this, config);

    if(this.url && !this.proxy){
        this.proxy = new Ext.data.HttpProxy({url: this.url});
    }

    if(this.reader){ // reader passed
        if(!this.recordType){
            this.recordType = this.reader.recordType;
        }
        if(this.reader.onMetaChange){
            this.reader.onMetaChange = this.onMetaChange.createDelegate(this);
        }
    }

    /**
     * The {@link Ext.data.Record Record} constructor as supplied to (or created by) the {@link Ext.data.Reader#Reader Reader}. Read-only.
     * <p>If the Reader was constructed by passing in an Array of field definition objects, instead of a created
     * Record constructor it will have {@link Ext.data.Record#create created a constructor} from that Array.</p>
     * <p>This property may be used to create new Records of the type held in this Store.</p>
     * @property recordType
     * @type Function
     */
    if(this.recordType){
        /**
         * A MixedCollection containing the defined {@link Ext.data.Field Field}s for the Records stored in this Store. Read-only.
         * @property fields
         * @type Ext.util.MixedCollection
         */
        this.fields = this.recordType.prototype.fields;
    }
    this.modified = [];

    this.addEvents(
        /**
         * @event datachanged
         * Fires when the data cache has changed in a bulk manner (e.g., it has been sorted, filtered, etc.) and a 
         * widget that is using this Store as a Record cache should refresh its view.
         * @param {Store} this
         */
        'datachanged',
        /**
         * @event metachange
         * Fires when this store's reader provides new metadata (fields). This is currently only supported for JsonReaders.
         * @param {Store} this
         * @param {Object} meta The JSON metadata
         */
        'metachange',
        /**
         * @event add
         * Fires when Records have been added to the Store
         * @param {Store} this
         * @param {Ext.data.Record[]} records The array of Records added
         * @param {Number} index The index at which the record(s) were added
         */
        'add',
        /**
         * @event remove
         * Fires when a Record has been removed from the Store
         * @param {Store} this
         * @param {Ext.data.Record} record The Record that was removed
         * @param {Number} index The index at which the record was removed
         */
        'remove',
        /**
         * @event update
         * Fires when a Record has been updated
         * @param {Store} this
         * @param {Ext.data.Record} record The Record that was updated
         * @param {String} operation The update operation being performed.  Value may be one of:
         * <pre><code>
 Ext.data.Record.EDIT
 Ext.data.Record.REJECT
 Ext.data.Record.COMMIT
         * </code></pre>
         */
        'update',
        /**
         * @event clear
         * Fires when the data cache has been cleared.
         * @param {Store} this
         */
        'clear',
        /**
         * @event beforeload
         * Fires before a request is made for a new data object.  If the beforeload handler returns false
         * the load action will be canceled.
         * @param {Store} this
         * @param {Object} options The loading options that were specified (see {@link #load} for details)
         */
        'beforeload',
        /**
         * @event load
         * Fires after a new set of Records has been loaded.
         * @param {Store} this
         * @param {Ext.data.Record[]} records The Records that were loaded
         * @param {Object} options The loading options that were specified (see {@link #load} for details)
         */
        'load',
        /**
         * @event loadexception
         * Fires if an exception occurs in the Proxy during loading.
         * Called with the signature of the Proxy's "loadexception" event.
         */
        'loadexception'
    );

    if(this.proxy){
        this.relayEvents(this.proxy,  ["loadexception"]);
    }

    this.sortToggle = {};
    if(this.sortInfo){
        this.setDefaultSort(this.sortInfo.field, this.sortInfo.direction);
    }

    Ext.data.Store.superclass.constructor.call(this);

    if(this.storeId || this.id){
        Ext.StoreMgr.register(this);
    }
    if(this.inlineData){
        this.loadData(this.inlineData);
        delete this.inlineData;
    }else if(this.autoLoad){
        this.load.defer(10, this, [
            typeof this.autoLoad == 'object' ?
                this.autoLoad : undefined]);
    }
};
Ext.extend(Ext.data.Store, Ext.util.Observable, {
    /**
    * @cfg {String} storeId If passed, the id to use to register with the StoreMgr
    */
    /**
    * @cfg {String} url If passed, an HttpProxy is created for the passed URL
    */
    /**
    * @cfg {Boolean/Object} autoLoad If passed, this store's load method is automatically called after creation with the autoLoad object
    */
    /**
    * @cfg {Ext.data.DataProxy} proxy The Proxy object which provides access to a data object.
    */
    /**
    * @cfg {Array} data Inline data to be loaded when the store is initialized.
    */
    /**
    * @cfg {Ext.data.DataReader} reader The DataReader object which processes the data object and returns
    * an Array of Ext.data.Record objects which are cached keyed by their <em>id</em> property.
    */
    /**
    * @cfg {Object} baseParams<p>An object containing properties which are to be sent as parameters.</p>
    * <p>Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode}.</p>
    * on any HTTP request
    */
    /**
    * @cfg {Object} sortInfo A config object in the format: {field: "fieldName", direction: "ASC|DESC"} to 
    * specify the sort order in the request of a remote Store's {@link #load} operation.  Note that for
    * local sorting, the direction property is case-sensitive.
    */
    /**
    * @cfg {boolean} remoteSort True if sorting is to be handled by requesting the
    * Proxy to provide a refreshed version of the data object in sorted order, as
    * opposed to sorting the Record cache in place (defaults to false).
    * <p>If remote sorting is specified, then clicking on a column header causes the
    * current page to be requested from the server with the addition of the following
    * two parameters:
    * <div class="mdetail-params"><ul>
    * <li><b>sort</b> : String<p class="sub-desc">The name (as specified in
    * the Record's Field definition) of the field to sort on.</p></li>
    * <li><b>dir</b> : String<p class="sub-desc">The direction of the sort, "ASC" or "DESC" (case-sensitive).</p></li>
    * </ul></div></p>
    */
    remoteSort : false,

    /**
    * @cfg {boolean} pruneModifiedRecords True to clear all modified record information each time the store is
     * loaded or when a record is removed. (defaults to false).
    */
    pruneModifiedRecords : false,

    /**
     * Contains the last options object used as the parameter to the load method. See {@link #load}
     * for the details of what this may contain. This may be useful for accessing any params which
     * were used to load the current Record cache.
     * @property
     */
   lastOptions : null,

    destroy : function(){
        if(this.storeId || this.id){
            Ext.StoreMgr.unregister(this);
        }
        this.data = null;
        Ext.destroy(this.proxy);
        this.reader = null;
        this.purgeListeners();
    },

    /**
     * Add Records to the Store and fires the {@link #add} event.
     * @param {Ext.data.Record[]} records An Array of Ext.data.Record objects to add to the cache.
     */
    add : function(records){
        records = [].concat(records);
        if(records.length < 1){
            return;
        }
        for(var i = 0, len = records.length; i < len; i++){
            records[i].join(this);
        }
        var index = this.data.length;
        this.data.addAll(records);
        if(this.snapshot){
            this.snapshot.addAll(records);
        }
        this.fireEvent("add", this, records, index);
    },

    /**
     * (Local sort only) Inserts the passed Record into the Store at the index where it
     * should go based on the current sort information.
     * @param {Ext.data.Record} record