docs/source/DataWriter.html

   1 <html>
   2 <head>
   3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   4   <title>The source code</title>
   5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   7 </head>
   8 <body  onload="prettyPrint();">
   9     <pre class="prettyprint lang-js">/*!
  10  * Ext JS Library 3.3.1
  11  * Copyright(c) 2006-2010 Sencha Inc.
  12  * licensing@sencha.com
  13  * http://www.sencha.com/license
  14  */
  15 <div id="cls-Ext.data.DataWriter"></div>/**
  16  * @class Ext.data.DataWriter
  17  * <p>Ext.data.DataWriter facilitates create, update, and destroy actions between
  18  * an Ext.data.Store and a server-side framework. A Writer enabled Store will
  19  * automatically manage the Ajax requests to perform CRUD actions on a Store.</p>
  20  * <p>Ext.data.DataWriter is an abstract base class which is intended to be extended
  21  * and should not be created directly. For existing implementations, see
  22  * {@link Ext.data.JsonWriter}.</p>
  23  * <p>Creating a writer is simple:</p>
  24  * <pre><code>
  25 var writer = new Ext.data.JsonWriter({
  26     encode: false   // &lt;--- false causes data to be printed to jsonData config-property of Ext.Ajax#reqeust
  27 });
  28  * </code></pre>
  29  * * <p>Same old JsonReader as Ext-2.x:</p>
  30  * <pre><code>
  31 var reader = new Ext.data.JsonReader({idProperty: 'id'}, [{name: 'first'}, {name: 'last'}, {name: 'email'}]);
  32  * </code></pre>
  33  *
  34  * <p>The proxy for a writer enabled store can be configured with a simple <code>url</code>:</p>
  35  * <pre><code>
  36 // Create a standard HttpProxy instance.
  37 var proxy = new Ext.data.HttpProxy({
  38     url: 'app.php/users'    // &lt;--- Supports "provides"-type urls, such as '/users.json', '/products.xml' (Hello Rails/Merb)
  39 });
  40  * </code></pre>
  41  * <p>For finer grained control, the proxy may also be configured with an <code>API</code>:</p>
  42  * <pre><code>
  43 // Maximum flexibility with the API-configuration
  44 var proxy = new Ext.data.HttpProxy({
  45     api: {
  46         read    : 'app.php/users/read',
  47         create  : 'app.php/users/create',
  48         update  : 'app.php/users/update',
  49         destroy : {  // &lt;--- Supports object-syntax as well
  50             url: 'app.php/users/destroy',
  51             method: "DELETE"
  52         }
  53     }
  54 });
  55  * </code></pre>
  56  * <p>Pulling it all together into a Writer-enabled Store:</p>
  57  * <pre><code>
  58 var store = new Ext.data.Store({
  59     proxy: proxy,
  60     reader: reader,
  61     writer: writer,
  62     autoLoad: true,
  63     autoSave: true  // -- Cell-level updates.
  64 });
  65  * </code></pre>
  66  * <p>Initiating write-actions <b>automatically</b>, using the existing Ext2.0 Store/Record API:</p>
  67  * <pre><code>
  68 var rec = store.getAt(0);
  69 rec.set('email', 'foo@bar.com');  // &lt;--- Immediately initiates an UPDATE action through configured proxy.
  70
  71 store.remove(rec);  // &lt;---- Immediately initiates a DESTROY action through configured proxy.
  72  * </code></pre>
  73  * <p>For <b>record/batch</b> updates, use the Store-configuration {@link Ext.data.Store#autoSave autoSave:false}</p>
  74  * <pre><code>
  75 var store = new Ext.data.Store({
  76     proxy: proxy,
  77     reader: reader,
  78     writer: writer,
  79     autoLoad: true,
  80     autoSave: false  // -- disable cell-updates
  81 });
  82
  83 var urec = store.getAt(0);
  84 urec.set('email', 'foo@bar.com');
  85
  86 var drec = store.getAt(1);
  87 store.remove(drec);
  88
  89 // Push the button!
  90 store.save();
  91  * </code></pre>
  92  * @constructor Create a new DataWriter
  93  * @param {Object} meta Metadata configuration options (implementation-specific)
  94  * @param {Object} recordType Either an Array of field definition objects as specified
  95  * in {@link Ext.data.Record#create}, or an {@link Ext.data.Record} object created
  96  * using {@link Ext.data.Record#create}.
  97  */
  98 Ext.data.DataWriter = function(config){
  99     Ext.apply(this, config);
 100 };
 101 Ext.data.DataWriter.prototype = {
 102
 103     <div id="cfg-Ext.data.DataWriter-writeAllFields"></div>/**
 104      * @cfg {Boolean} writeAllFields
 105      * <tt>false</tt> by default.  Set <tt>true</tt> to have DataWriter return ALL fields of a modified
 106      * record -- not just those that changed.
 107      * <tt>false</tt> to have DataWriter only request modified fields from a record.
 108      */
 109     writeAllFields : false,
 110     <div id="cfg-Ext.data.DataWriter-listful"></div>/**
 111      * @cfg {Boolean} listful
 112      * <tt>false</tt> by default.  Set <tt>true</tt> to have the DataWriter <b>always</b> write HTTP params as a list,
 113      * even when acting upon a single record.
 114      */
 115     listful : false,    // <-- listful is actually not used internally here in DataWriter.  @see Ext.data.Store#execute.
 116
 117     <div id="method-Ext.data.DataWriter-apply"></div>/**
 118      * Compiles a Store recordset into a data-format defined by an extension such as {@link Ext.data.JsonWriter} or {@link Ext.data.XmlWriter} in preparation for a {@link Ext.data.Api#actions server-write action}.  The first two params are similar similar in nature to {@link Ext#apply},
 119      * Where the first parameter is the <i>receiver</i> of paramaters and the second, baseParams, <i>the source</i>.
 120      * @param {Object} params The request-params receiver.
 121      * @param {Object} baseParams as defined by {@link Ext.data.Store#baseParams}.  The baseParms must be encoded by the extending class, eg: {@link Ext.data.JsonWriter}, {@link Ext.data.XmlWriter}.
 122      * @param {String} action [{@link Ext.data.Api#actions create|update|destroy}]
 123      * @param {Record/Record[]} rs The recordset to write, the subject(s) of the write action.
 124      */
 125     apply : function(params, baseParams, action, rs) {
 126         var data    = [],
 127         renderer    = action + 'Record';
 128         // TODO implement @cfg listful here
 129         if (Ext.isArray(rs)) {
 130             Ext.each(rs, function(rec){
 131                 data.push(this[renderer](rec));
 132             }, this);
 133         }
 134         else if (rs instanceof Ext.data.Record) {
 135             data = this[renderer](rs);
 136         }
 137         this.render(params, baseParams, data);
 138     },
 139
 140     <div id="method-Ext.data.DataWriter-render"></div>/**
 141      * abstract method meant to be overridden by all DataWriter extensions.  It's the extension's job to apply the "data" to the "params".
 142      * The data-object provided to render is populated with data according to the meta-info defined in the user's DataReader config,
 143      * @param {String} action [Ext.data.Api.actions.create|read|update|destroy]
 144      * @param {Record[]} rs Store recordset
 145      * @param {Object} params Http params to be sent to server.
 146      * @param {Object} data object populated according to DataReader meta-data.
 147      */
 148     render : Ext.emptyFn,
 149
 150     <div id="cfg-Ext.data.DataWriter-updateRecord"></div>/**
 151      * @cfg {Function} updateRecord Abstract method that should be implemented in all subclasses
 152      * (e.g.: {@link Ext.data.JsonWriter#updateRecord JsonWriter.updateRecord}
 153      */
 154     updateRecord : Ext.emptyFn,
 155
 156     <div id="cfg-Ext.data.DataWriter-createRecord"></div>/**
 157      * @cfg {Function} createRecord Abstract method that should be implemented in all subclasses
 158      * (e.g.: {@link Ext.data.JsonWriter#createRecord JsonWriter.createRecord})
 159      */
 160     createRecord : Ext.emptyFn,
 161
 162     <div id="cfg-Ext.data.DataWriter-destroyRecord"></div>/**
 163      * @cfg {Function} destroyRecord Abstract method that should be implemented in all subclasses
 164      * (e.g.: {@link Ext.data.JsonWriter#destroyRecord JsonWriter.destroyRecord})
 165      */
 166     destroyRecord : Ext.emptyFn,
 167
 168     <div id="method-Ext.data.DataWriter-toHash"></div>/**
 169      * Converts a Record to a hash, taking into account the state of the Ext.data.Record along with configuration properties
 170      * related to its rendering, such as {@link #writeAllFields}, {@link Ext.data.Record#phantom phantom}, {@link Ext.data.Record#getChanges getChanges} and
 171      * {@link Ext.data.DataReader#idProperty idProperty}
 172      * @param {Ext.data.Record} rec The Record from which to create a hash.
 173      * @param {Object} config <b>NOT YET IMPLEMENTED</b>.  Will implement an exlude/only configuration for fine-control over which fields do/don't get rendered.
 174      * @return {Object}
 175      * @protected
 176      * TODO Implement excludes/only configuration with 2nd param?
 177      */
 178     toHash : function(rec, config) {
 179         var map = rec.fields.map,
 180             data = {},
 181             raw = (this.writeAllFields === false && rec.phantom === false) ? rec.getChanges() : rec.data,
 182             m;
 183         Ext.iterate(raw, function(prop, value){
 184             if((m = map[prop])){
 185                 data[m.mapping ? m.mapping : m.name] = value;
 186             }
 187         });
 188         // we don't want to write Ext auto-generated id to hash.  Careful not to remove it on Models not having auto-increment pk though.
 189         // We can tell its not auto-increment if the user defined a DataReader field for it *and* that field's value is non-empty.
 190         // we could also do a RegExp here for the Ext.data.Record AUTO_ID prefix.
 191         if (rec.phantom) {
 192             if (rec.fields.containsKey(this.meta.idProperty) && Ext.isEmpty(rec.data[this.meta.idProperty])) {
 193                 delete data[this.meta.idProperty];
 194             }
 195         } else {
 196             data[this.meta.idProperty] = rec.id;
 197         }
 198         return data;
 199     },
 200
 201     <div id="method-Ext.data.DataWriter-toArray"></div>/**
 202      * Converts a {@link Ext.data.DataWriter#toHash Hashed} {@link Ext.data.Record} to fields-array array suitable
 203      * for encoding to xml via XTemplate, eg:
 204 <code><pre>&lt;tpl for=".">&lt;{name}>{value}&lt;/{name}&lt;/tpl></pre></code>
 205      * eg, <b>non-phantom</b>:
 206 <code><pre>{id: 1, first: 'foo', last: 'bar'} --> [{name: 'id', value: 1}, {name: 'first', value: 'foo'}, {name: 'last', value: 'bar'}]</pre></code>
 207      * {@link Ext.data.Record#phantom Phantom} records will have had their idProperty omitted in {@link #toHash} if determined to be auto-generated.
 208      * Non AUTOINCREMENT pks should have been protected.
 209      * @param {Hash} data Hashed by Ext.data.DataWriter#toHash
 210      * @return {[Object]} Array of attribute-objects.
 211      * @protected
 212      */
 213     toArray : function(data) {
 214         var fields = [];
 215         Ext.iterate(data, function(k, v) {fields.push({name: k, value: v});},this);
 216         return fields;
 217     }
 218 };</pre>
 219 </body>
 220 </html>