src/data/DataWriter.js

   1 /*!
   2  * Ext JS Library 3.0.0
   3  * Copyright(c) 2006-2009 Ext JS, LLC
   4  * licensing@extjs.com
   5  * http://www.extjs.com/license
   6  */
   7 /**
   8  * @class Ext.data.DataWriter
   9  * <p>Ext.data.DataWriter facilitates create, update, and destroy actions between
  10  * an Ext.data.Store and a server-side framework. A Writer enabled Store will
  11  * automatically manage the Ajax requests to perform CRUD actions on a Store.</p>
  12  * <p>Ext.data.DataWriter is an abstract base class which is intended to be extended
  13  * and should not be created directly. For existing implementations, see
  14  * {@link Ext.data.JsonWriter}.</p>
  15  * <p>Creating a writer is simple:</p>
  16  * <pre><code>
  17 var writer = new Ext.data.JsonWriter();
  18  * </code></pre>
  19  * <p>The proxy for a writer enabled store can be configured with a simple <code>url</code>:</p>
  20  * <pre><code>
  21 // Create a standard HttpProxy instance.
  22 var proxy = new Ext.data.HttpProxy({
  23     url: 'app.php/users'
  24 });
  25  * </code></pre>
  26  * <p>For finer grained control, the proxy may also be configured with an <code>api</code>:</p>
  27  * <pre><code>
  28 // Use the api specification
  29 var proxy = new Ext.data.HttpProxy({
  30     api: {
  31         read    : 'app.php/users/read',
  32         create  : 'app.php/users/create',
  33         update  : 'app.php/users/update',
  34         destroy : 'app.php/users/destroy'
  35     }
  36 });
  37  * </code></pre>
  38  * <p>Creating a Writer enabled store:</p>
  39  * <pre><code>
  40 var store = new Ext.data.Store({
  41     proxy: proxy,
  42     reader: reader,
  43     writer: writer
  44 });
  45  * </code></pre>
  46  * @constructor Create a new DataWriter
  47  * @param {Object} meta Metadata configuration options (implementation-specific)
  48  * @param {Object} recordType Either an Array of field definition objects as specified
  49  * in {@link Ext.data.Record#create}, or an {@link Ext.data.Record} object created
  50  * using {@link Ext.data.Record#create}.
  51  */
  52 Ext.data.DataWriter = function(config){
  53     /**
  54      * This DataWriter's configured metadata as passed to the constructor.
  55      * @type Mixed
  56      * @property meta
  57      */
  58     Ext.apply(this, config);
  59 };
  60
  61 Ext.data.DataWriter.prototype = {
  62
  63     /**
  64      * @cfg {Boolean} writeAllFields
  65      * <tt>false</tt> by default.  Set <tt>true</tt> to have DataWriter return ALL fields of a modified
  66      * record -- not just those that changed.
  67      * <tt>false</tt> to have DataWriter only request modified fields from a record.
  68      */
  69     writeAllFields : false,
  70     /**
  71      * @cfg {Boolean} listful
  72      * <tt>false</tt> by default.  Set <tt>true</tt> to have the DataWriter <b>always</b> write HTTP params as a list,
  73      * even when acting upon a single record.
  74      */
  75     listful : false,    // <-- listful is actually not used internally here in DataWriter.  @see Ext.data.Store#execute.
  76
  77     /**
  78      * Writes data in preparation for server-write action.  Simply proxies to DataWriter#update, DataWriter#create
  79      * DataWriter#destroy.
  80      * @param {String} action [CREATE|UPDATE|DESTROY]
  81      * @param {Object} params The params-hash to write-to
  82      * @param {Record/Record[]} rs The recordset write.
  83      */
  84     write : function(action, params, rs) {
  85         this.render(action, rs, params, this[action](rs));
  86     },
  87
  88     /**
  89      * abstract method meant to be overridden by all DataWriter extensions.  It's the extension's job to apply the "data" to the "params".
  90      * The data-object provided to render is populated with data according to the meta-info defined in the user's DataReader config,
  91      * @param {String} action [Ext.data.Api.actions.create|read|update|destroy]
  92      * @param {Record[]} rs Store recordset
  93      * @param {Object} params Http params to be sent to server.
  94      * @param {Object} data object populated according to DataReader meta-data.
  95      */
  96     render : Ext.emptyFn,
  97
  98     /**
  99      * update
 100      * @param {Object} p Params-hash to apply result to.
 101      * @param {Record/Record[]} rs Record(s) to write
 102      * @private
 103      */
 104     update : function(rs) {
 105         var params = {};
 106         if (Ext.isArray(rs)) {
 107             var data = [],
 108                 ids = [];
 109             Ext.each(rs, function(val){
 110                 ids.push(val.id);
 111                 data.push(this.updateRecord(val));
 112             }, this);
 113             params[this.meta.idProperty] = ids;
 114             params[this.meta.root] = data;
 115         }
 116         else if (rs instanceof Ext.data.Record) {
 117             params[this.meta.idProperty] = rs.id;
 118             params[this.meta.root] = this.updateRecord(rs);
 119         }
 120         return params;
 121     },
 122
 123     /**
 124      * @cfg {Function} saveRecord Abstract method that should be implemented in all subclasses
 125      * (e.g.: {@link Ext.data.JsonWriter#saveRecord JsonWriter.saveRecord}
 126      */
 127     updateRecord : Ext.emptyFn,
 128
 129     /**
 130      * create
 131      * @param {Object} p Params-hash to apply result to.
 132      * @param {Record/Record[]} rs Record(s) to write
 133      * @private
 134      */
 135     create : function(rs) {
 136         var params = {};
 137         if (Ext.isArray(rs)) {
 138             var data = [];
 139             Ext.each(rs, function(val){
 140                 data.push(this.createRecord(val));
 141             }, this);
 142             params[this.meta.root] = data;
 143         }
 144         else if (rs instanceof Ext.data.Record) {
 145             params[this.meta.root] = this.createRecord(rs);
 146         }
 147         return params;
 148     },
 149
 150     /**
 151      * @cfg {Function} createRecord Abstract method that should be implemented in all subclasses
 152      * (e.g.: {@link Ext.data.JsonWriter#createRecord JsonWriter.createRecord})
 153      */
 154     createRecord : Ext.emptyFn,
 155
 156     /**
 157      * destroy
 158      * @param {Object} p Params-hash to apply result to.
 159      * @param {Record/Record[]} rs Record(s) to write
 160      * @private
 161      */
 162     destroy : function(rs) {
 163         var params = {};
 164         if (Ext.isArray(rs)) {
 165             var data = [],
 166                 ids = [];
 167             Ext.each(rs, function(val){
 168                 data.push(this.destroyRecord(val));
 169             }, this);
 170             params[this.meta.root] = data;
 171         } else if (rs instanceof Ext.data.Record) {
 172             params[this.meta.root] = this.destroyRecord(rs);
 173         }
 174         return params;
 175     },
 176
 177     /**
 178      * @cfg {Function} destroyRecord Abstract method that should be implemented in all subclasses
 179      * (e.g.: {@link Ext.data.JsonWriter#destroyRecord JsonWriter.destroyRecord})
 180      */
 181     destroyRecord : Ext.emptyFn,
 182
 183     /**
 184      * Converts a Record to a hash
 185      * @param {Record}
 186      * @private
 187      */
 188     toHash : function(rec) {
 189         var map = rec.fields.map,
 190             data = {},
 191             raw = (this.writeAllFields === false && rec.phantom === false) ? rec.getChanges() : rec.data,
 192             m;
 193         Ext.iterate(raw, function(prop, value){
 194             if((m = map[prop])){
 195                 data[m.mapping ? m.mapping : m.name] = value;
 196             }
 197         });
 198         data[this.meta.idProperty] = rec.id;
 199         return data;
 200     }
 201 };