Upgrade to ExtJS 4.0.2 - Released 06/09/2011
[extjs.git] / docs / source / Proxy2.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-data-proxy-Proxy'>/**
19 </span> * @author Ed Spencer
20  * @class Ext.data.proxy.Proxy
21  * 
22  * &lt;p&gt;Proxies are used by {@link Ext.data.Store Stores} to handle the loading and saving of {@link Ext.data.Model Model} data.
23  * Usually developers will not need to create or interact with proxies directly.&lt;/p&gt;
24  * &lt;p&gt;&lt;u&gt;Types of Proxy&lt;/u&gt;&lt;/p&gt;
25  * 
26  * &lt;p&gt;There are two main types of Proxy - {@link Ext.data.proxy.Client Client} and {@link Ext.data.proxy.Server Server}. The Client proxies
27  * save their data locally and include the following subclasses:&lt;/p&gt;
28  * 
29  * &lt;ul style=&quot;list-style-type: disc; padding-left: 25px&quot;&gt;
30  * &lt;li&gt;{@link Ext.data.proxy.LocalStorage LocalStorageProxy} - saves its data to localStorage if the browser supports it&lt;/li&gt;
31  * &lt;li&gt;{@link Ext.data.proxy.SessionStorage SessionStorageProxy} - saves its data to sessionStorage if the browsers supports it&lt;/li&gt;
32  * &lt;li&gt;{@link Ext.data.proxy.Memory MemoryProxy} - holds data in memory only, any data is lost when the page is refreshed&lt;/li&gt;
33  * &lt;/ul&gt;
34  * 
35  * &lt;p&gt;The Server proxies save their data by sending requests to some remote server. These proxies include:&lt;/p&gt;
36  * 
37  * &lt;ul style=&quot;list-style-type: disc; padding-left: 25px&quot;&gt;
38  * &lt;li&gt;{@link Ext.data.proxy.Ajax Ajax} - sends requests to a server on the same domain&lt;/li&gt;
39  * &lt;li&gt;{@link Ext.data.proxy.JsonP JsonP} - uses JSON-P to send requests to a server on a different domain&lt;/li&gt;
40  * &lt;li&gt;{@link Ext.data.proxy.Direct Direct} - uses {@link Ext.direct} to send requests&lt;/li&gt;
41  * &lt;/ul&gt;
42  * 
43  * &lt;p&gt;Proxies operate on the principle that all operations performed are either Create, Read, Update or Delete. These four operations 
44  * are mapped to the methods {@link #create}, {@link #read}, {@link #update} and {@link #destroy} respectively. Each Proxy subclass 
45  * implements these functions.&lt;/p&gt;
46  * 
47  * &lt;p&gt;The CRUD methods each expect an {@link Ext.data.Operation Operation} object as the sole argument. The Operation encapsulates 
48  * information about the action the Store wishes to perform, the {@link Ext.data.Model model} instances that are to be modified, etc.
49  * See the {@link Ext.data.Operation Operation} documentation for more details. Each CRUD method also accepts a callback function to be 
50  * called asynchronously on completion.&lt;/p&gt;
51  * 
52  * &lt;p&gt;Proxies also support batching of Operations via a {@link Ext.data.Batch batch} object, invoked by the {@link #batch} method.&lt;/p&gt;
53  * 
54  */
55 Ext.define('Ext.data.proxy.Proxy', {
56     alias: 'proxy.proxy',
57     alternateClassName: ['Ext.data.DataProxy', 'Ext.data.Proxy'],
58     requires: [
59         'Ext.data.reader.Json',
60         'Ext.data.writer.Json'
61     ],
62     uses: [
63         'Ext.data.Batch', 
64         'Ext.data.Operation', 
65         'Ext.data.Model'
66     ],
67     mixins: {
68         observable: 'Ext.util.Observable'
69     },
70     
71 <span id='Ext-data-proxy-Proxy-cfg-batchOrder'>    /**
72 </span>     * @cfg {String} batchOrder
73      * Comma-separated ordering 'create', 'update' and 'destroy' actions when batching. Override this
74      * to set a different order for the batched CRUD actions to be executed in. Defaults to 'create,update,destroy'
75      */
76     batchOrder: 'create,update,destroy',
77     
78 <span id='Ext-data-proxy-Proxy-cfg-batchActions'>    /**
79 </span>     * @cfg {Boolean} batchActions True to batch actions of a particular type when synchronizing the store.
80      * Defaults to &lt;tt&gt;true&lt;/tt&gt;.
81      */
82     batchActions: true,
83     
84 <span id='Ext-data-proxy-Proxy-cfg-defaultReaderType'>    /**
85 </span>     * @cfg {String} defaultReaderType The default registered reader type. Defaults to 'json'
86      * @private
87      */
88     defaultReaderType: 'json',
89     
90 <span id='Ext-data-proxy-Proxy-cfg-defaultWriterType'>    /**
91 </span>     * @cfg {String} defaultWriterType The default registered writer type. Defaults to 'json'
92      * @private
93      */
94     defaultWriterType: 'json',
95     
96 <span id='Ext-data-proxy-Proxy-cfg-model'>    /**
97 </span>     * @cfg {String/Ext.data.Model} model The name of the Model to tie to this Proxy. Can be either the string name of
98      * the Model, or a reference to the Model constructor. Required.
99      */
100     
101     isProxy: true,
102     
103 <span id='Ext-data-proxy-Proxy-method-constructor'>    /**
104 </span>     * Creates the Proxy
105      * @param {Object} config (optional) Config object.
106      */
107     constructor: function(config) {
108         config = config || {};
109         
110         if (config.model === undefined) {
111             delete config.model;
112         }
113
114         this.mixins.observable.constructor.call(this, config);
115         
116         if (this.model !== undefined &amp;&amp; !(this.model instanceof Ext.data.Model)) {
117             this.setModel(this.model);
118         }
119     },
120     
121 <span id='Ext-data-proxy-Proxy-method-setModel'>    /**
122 </span>     * Sets the model associated with this proxy. This will only usually be called by a Store
123      * @param {String|Ext.data.Model} model The new model. Can be either the model name string,
124      * or a reference to the model's constructor
125      * @param {Boolean} setOnStore Sets the new model on the associated Store, if one is present
126      */
127     setModel: function(model, setOnStore) {
128         this.model = Ext.ModelManager.getModel(model);
129         
130         var reader = this.reader,
131             writer = this.writer;
132         
133         this.setReader(reader);
134         this.setWriter(writer);
135         
136         if (setOnStore &amp;&amp; this.store) {
137             this.store.setModel(this.model);
138         }
139     },
140     
141 <span id='Ext-data-proxy-Proxy-method-getModel'>    /**
142 </span>     * Returns the model attached to this Proxy
143      * @return {Ext.data.Model} The model
144      */
145     getModel: function() {
146         return this.model;
147     },
148     
149 <span id='Ext-data-proxy-Proxy-method-setReader'>    /**
150 </span>     * Sets the Proxy's Reader by string, config object or Reader instance
151      * @param {String|Object|Ext.data.reader.Reader} reader The new Reader, which can be either a type string, a configuration object
152      * or an Ext.data.reader.Reader instance
153      * @return {Ext.data.reader.Reader} The attached Reader object
154      */
155     setReader: function(reader) {
156         var me = this;
157         
158         if (reader === undefined || typeof reader == 'string') {
159             reader = {
160                 type: reader
161             };
162         }
163
164         if (reader.isReader) {
165             reader.setModel(me.model);
166         } else {
167             Ext.applyIf(reader, {
168                 proxy: me,
169                 model: me.model,
170                 type : me.defaultReaderType
171             });
172
173             reader = Ext.createByAlias('reader.' + reader.type, reader);
174         }
175         
176         me.reader = reader;
177         return me.reader;
178     },
179     
180 <span id='Ext-data-proxy-Proxy-method-getReader'>    /**
181 </span>     * Returns the reader currently attached to this proxy instance
182      * @return {Ext.data.reader.Reader} The Reader instance
183      */
184     getReader: function() {
185         return this.reader;
186     },
187     
188 <span id='Ext-data-proxy-Proxy-method-setWriter'>    /**
189 </span>     * Sets the Proxy's Writer by string, config object or Writer instance
190      * @param {String|Object|Ext.data.writer.Writer} writer The new Writer, which can be either a type string, a configuration object
191      * or an Ext.data.writer.Writer instance
192      * @return {Ext.data.writer.Writer} The attached Writer object
193      */
194     setWriter: function(writer) {
195         if (writer === undefined || typeof writer == 'string') {
196             writer = {
197                 type: writer
198             };
199         }
200
201         if (!(writer instanceof Ext.data.writer.Writer)) {
202             Ext.applyIf(writer, {
203                 model: this.model,
204                 type : this.defaultWriterType
205             });
206
207             writer = Ext.createByAlias('writer.' + writer.type, writer);
208         }
209         
210         this.writer = writer;
211         
212         return this.writer;
213     },
214     
215 <span id='Ext-data-proxy-Proxy-method-getWriter'>    /**
216 </span>     * Returns the writer currently attached to this proxy instance
217      * @return {Ext.data.writer.Writer} The Writer instance
218      */
219     getWriter: function() {
220         return this.writer;
221     },
222     
223 <span id='Ext-data-proxy-Proxy-method-create'>    /**
224 </span>     * Performs the given create operation.
225      * @param {Ext.data.Operation} operation The Operation to perform
226      * @param {Function} callback Callback function to be called when the Operation has completed (whether successful or not)
227      * @param {Object} scope Scope to execute the callback function in
228      * @method
229      */
230     create: Ext.emptyFn,
231     
232 <span id='Ext-data-proxy-Proxy-method-read'>    /**
233 </span>     * Performs the given read operation.
234      * @param {Ext.data.Operation} operation The Operation to perform
235      * @param {Function} callback Callback function to be called when the Operation has completed (whether successful or not)
236      * @param {Object} scope Scope to execute the callback function in
237      * @method
238      */
239     read: Ext.emptyFn,
240     
241 <span id='Ext-data-proxy-Proxy-method-update'>    /**
242 </span>     * Performs the given update operation.
243      * @param {Ext.data.Operation} operation The Operation to perform
244      * @param {Function} callback Callback function to be called when the Operation has completed (whether successful or not)
245      * @param {Object} scope Scope to execute the callback function in
246      * @method
247      */
248     update: Ext.emptyFn,
249     
250 <span id='Ext-data-proxy-Proxy-method-destroy'>    /**
251 </span>     * Performs the given destroy operation.
252      * @param {Ext.data.Operation} operation The Operation to perform
253      * @param {Function} callback Callback function to be called when the Operation has completed (whether successful or not)
254      * @param {Object} scope Scope to execute the callback function in
255      * @method
256      */
257     destroy: Ext.emptyFn,
258     
259 <span id='Ext-data-proxy-Proxy-method-batch'>    /**
260 </span>     * Performs a batch of {@link Ext.data.Operation Operations}, in the order specified by {@link #batchOrder}. Used internally by
261      * {@link Ext.data.Store}'s {@link Ext.data.Store#sync sync} method. Example usage:
262      * &lt;pre&gt;&lt;code&gt;
263      * myProxy.batch({
264      *     create : [myModel1, myModel2],
265      *     update : [myModel3],
266      *     destroy: [myModel4, myModel5]
267      * });
268      * &lt;/code&gt;&lt;/pre&gt;
269      * Where the myModel* above are {@link Ext.data.Model Model} instances - in this case 1 and 2 are new instances and have not been 
270      * saved before, 3 has been saved previously but needs to be updated, and 4 and 5 have already been saved but should now be destroyed.
271      * @param {Object} operations Object containing the Model instances to act upon, keyed by action name
272      * @param {Object} listeners Optional listeners object passed straight through to the Batch - see {@link Ext.data.Batch}
273      * @return {Ext.data.Batch} The newly created Ext.data.Batch object
274      */
275     batch: function(operations, listeners) {
276         var me = this,
277             batch = Ext.create('Ext.data.Batch', {
278                 proxy: me,
279                 listeners: listeners || {}
280             }),
281             useBatch = me.batchActions, 
282             records;
283         
284         Ext.each(me.batchOrder.split(','), function(action) {
285             records = operations[action];
286             if (records) {
287                 if (useBatch) {
288                     batch.add(Ext.create('Ext.data.Operation', {
289                         action: action,
290                         records: records
291                     }));
292                 } else {
293                     Ext.each(records, function(record){
294                         batch.add(Ext.create('Ext.data.Operation', {
295                             action : action, 
296                             records: [record]
297                         }));
298                     });
299                 }
300             }
301         }, me);
302         
303         batch.start();
304         return batch;
305     }
306 }, function() {
307     // Ext.data.proxy.ProxyMgr.registerType('proxy', this);
308     
309     //backwards compatibility
310     Ext.data.DataProxy = this;
311     // Ext.deprecate('platform', '2.0', function() {
312     //     Ext.data.DataProxy = this;
313     // }, this);
314 });
315 </pre>
316 </body>
317 </html>