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  * @class Ext.data.writer.Writer
  18  * @extends Object
  19  *
  20  * <p>Base Writer class used by most subclasses of {@link Ext.data.proxy.Server}. This class is
  21  * responsible for taking a set of {@link Ext.data.Operation} objects and a {@link Ext.data.Request}
  22  * object and modifying that request based on the Operations.</p>
  23  *
  24  * <p>For example a Ext.data.writer.Json would format the Operations and their {@link Ext.data.Model}
  25  * instances based on the config options passed to the JsonWriter's constructor.</p>
  26  *
  27  * <p>Writers are not needed for any kind of local storage - whether via a
  28  * {@link Ext.data.proxy.WebStorage Web Storage proxy} (see {@link Ext.data.proxy.LocalStorage localStorage}
  29  * and {@link Ext.data.proxy.SessionStorage sessionStorage}) or just in memory via a
  30  * {@link Ext.data.proxy.Memory MemoryProxy}.</p>
  31  */
  32 Ext.define('Ext.data.writer.Writer', {
  33     alias: 'writer.base',
  34     alternateClassName: ['Ext.data.DataWriter', 'Ext.data.Writer'],
  35
  36     /**
  37      * @cfg {Boolean} writeAllFields True to write all fields from the record to the server. If set to false it
  38      * will only send the fields that were modified. Defaults to <tt>true</tt>. Note that any fields that have
  39      * {@link Ext.data.Field#persist} set to false will still be ignored.
  40      */
  41     writeAllFields: true,
  42
  43     /**
  44      * @cfg {String} nameProperty This property is used to read the key for each value that will be sent to the server.
  45      * For example:
  46      * <pre><code>
  47 Ext.define('Person', {
  48     extend: 'Ext.data.Model',
  49     fields: [{
  50         name: 'first',
  51         mapping: 'firstName'
  52     }, {
  53         name: 'last',
  54         mapping: 'lastName'
  55     }, {
  56         name: 'age'
  57     }]
  58 });
  59 new Ext.data.writer.Writer({
  60     writeAllFields: true,
  61     nameProperty: 'mapping'
  62 });
  63
  64 // This will be sent to the server
  65 {
  66     firstName: 'first name value',
  67     lastName: 'last name value',
  68     age: 1
  69 }
  70
  71      * </code></pre>
  72      * Defaults to <tt>name</tt>. If the value is not present, the field name will always be used.
  73      */
  74     nameProperty: 'name',
  75
  76     /**
  77      * Creates new Writer.
  78      * @param {Object} config (optional) Config object.
  79      */
  80     constructor: function(config) {
  81         Ext.apply(this, config);
  82     },
  83
  84     /**
  85      * Prepares a Proxy's Ext.data.Request object
  86      * @param {Ext.data.Request} request The request object
  87      * @return {Ext.data.Request} The modified request object
  88      */
  89     write: function(request) {
  90         var operation = request.operation,
  91             records   = operation.records || [],
  92             len       = records.length,
  93             i         = 0,
  94             data      = [];
  95
  96         for (; i < len; i++) {
  97             data.push(this.getRecordData(records[i]));
  98         }
  99         return this.writeRecords(request, data);
 100     },
 101
 102     /**
 103      * Formats the data for each record before sending it to the server. This
 104      * method should be overridden to format the data in a way that differs from the default.
 105      * @param {Object} record The record that we are writing to the server.
 106      * @return {Object} An object literal of name/value keys to be written to the server.
 107      * By default this method returns the data property on the record.
 108      */
 109     getRecordData: function(record) {
 110         var isPhantom = record.phantom === true,
 111             writeAll = this.writeAllFields || isPhantom,
 112             nameProperty = this.nameProperty,
 113             fields = record.fields,
 114             data = {},
 115             changes,
 116             name,
 117             field,
 118             key;
 119
 120         if (writeAll) {
 121             fields.each(function(field){
 122                 if (field.persist) {
 123                     name = field[nameProperty] || field.name;
 124                     data[name] = record.get(field.name);
 125                 }
 126             });
 127         } else {
 128             // Only write the changes
 129             changes = record.getChanges();
 130             for (key in changes) {
 131                 if (changes.hasOwnProperty(key)) {
 132                     field = fields.get(key);
 133                     name = field[nameProperty] || field.name;
 134                     data[name] = changes[key];
 135                 }
 136             }
 137             if (!isPhantom) {
 138                 // always include the id for non phantoms
 139                 data[record.idProperty] = record.getId();
 140             }
 141         }
 142         return data;
 143     }
 144 });
 145