src/data/writer/Writer.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   9 GNU General Public License Usage
  10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file.  Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @author Ed Spencer
  17  *
  18  * Base Writer class used by most subclasses of {@link Ext.data.proxy.Server}. This class is responsible for taking a
  19  * set of {@link Ext.data.Operation} objects and a {@link Ext.data.Request} object and modifying that request based on
  20  * the Operations.
  21  *
  22  * For example a Ext.data.writer.Json would format the Operations and their {@link Ext.data.Model} instances based on
  23  * the config options passed to the JsonWriter's constructor.
  24  *
  25  * Writers are not needed for any kind of local storage - whether via a {@link Ext.data.proxy.WebStorage Web Storage
  26  * proxy} (see {@link Ext.data.proxy.LocalStorage localStorage} and {@link Ext.data.proxy.SessionStorage
  27  * sessionStorage}) or just in memory via a {@link Ext.data.proxy.Memory MemoryProxy}.
  28  */
  29 Ext.define('Ext.data.writer.Writer', {
  30     alias: 'writer.base',
  31     alternateClassName: ['Ext.data.DataWriter', 'Ext.data.Writer'],
  32
  33     /**
  34      * @cfg {Boolean} writeAllFields
  35      * True to write all fields from the record to the server. If set to false it will only send the fields that were
  36      * modified. Note that any fields that have {@link Ext.data.Field#persist} set to false will still be ignored.
  37      */
  38     writeAllFields: true,
  39
  40     /**
  41      * @cfg {String} nameProperty
  42      * This property is used to read the key for each value that will be sent to the server. For example:
  43      *
  44      *     Ext.define('Person', {
  45      *         extend: 'Ext.data.Model',
  46      *         fields: [{
  47      *             name: 'first',
  48      *             mapping: 'firstName'
  49      *         }, {
  50      *             name: 'last',
  51      *             mapping: 'lastName'
  52      *         }, {
  53      *             name: 'age'
  54      *         }]
  55      *     });
  56      *     new Ext.data.writer.Writer({
  57      *         writeAllFields: true,
  58      *         nameProperty: 'mapping'
  59      *     });
  60      *
  61      *     // This will be sent to the server
  62      *     {
  63      *         firstName: 'first name value',
  64      *         lastName: 'last name value',
  65      *         age: 1
  66      *     }
  67      *
  68      * If the value is not present, the field name will always be used.
  69      */
  70     nameProperty: 'name',
  71
  72     /**
  73      * Creates new Writer.
  74      * @param {Object} [config] Config object.
  75      */
  76     constructor: function(config) {
  77         Ext.apply(this, config);
  78     },
  79
  80     /**
  81      * Prepares a Proxy's Ext.data.Request object
  82      * @param {Ext.data.Request} request The request object
  83      * @return {Ext.data.Request} The modified request object
  84      */
  85     write: function(request) {
  86         var operation = request.operation,
  87             records   = operation.records || [],
  88             len       = records.length,
  89             i         = 0,
  90             data      = [];
  91
  92         for (; i < len; i++) {
  93             data.push(this.getRecordData(records[i]));
  94         }
  95         return this.writeRecords(request, data);
  96     },
  97
  98     /**
  99      * Formats the data for each record before sending it to the server. This method should be overridden to format the
 100      * data in a way that differs from the default.
 101      * @param {Object} record The record that we are writing to the server.
 102      * @return {Object} An object literal of name/value keys to be written to the server. By default this method returns
 103      * the data property on the record.
 104      */
 105     getRecordData: function(record) {
 106         var isPhantom = record.phantom === true,
 107             writeAll = this.writeAllFields || isPhantom,
 108             nameProperty = this.nameProperty,
 109             fields = record.fields,
 110             data = {},
 111             changes,
 112             name,
 113             field,
 114             key;
 115
 116         if (writeAll) {
 117             fields.each(function(field){
 118                 if (field.persist) {
 119                     name = field[nameProperty] || field.name;
 120                     data[name] = record.get(field.name);
 121                 }
 122             });
 123         } else {
 124             // Only write the changes
 125             changes = record.getChanges();
 126             for (key in changes) {
 127                 if (changes.hasOwnProperty(key)) {
 128                     field = fields.get(key);
 129                     name = field[nameProperty] || field.name;
 130                     data[name] = changes[key];
 131                 }
 132             }
 133             if (!isPhantom) {
 134                 // always include the id for non phantoms
 135                 data[record.idProperty] = record.getId();
 136             }
 137         }
 138         return data;
 139     }
 140 });
 141