Upgrade to ExtJS 3.2.1 - Released 04/27/2010
[extjs.git] / docs / source / HttpProxy.html
index 8b0624c..fd59abd 100644 (file)
-<html>\r
-<head>\r
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
-  <title>The source code</title>\r
-    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
-    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
-</head>\r
-<body  onload="prettyPrint();">\r
-    <pre class="prettyprint lang-js"><div id="cls-Ext.data.HttpProxy"></div>/**\r
- * @class Ext.data.HttpProxy\r
- * @extends Ext.data.DataProxy\r
- * <p>An implementation of {@link Ext.data.DataProxy} that processes data requests within the same\r
- * domain of the originating page.</p>\r
- * <p><b>Note</b>: this class cannot be used to retrieve data from a domain other\r
- * than the domain from which the running page was served. For cross-domain requests, use a\r
- * {@link Ext.data.ScriptTagProxy ScriptTagProxy}.</p>\r
- * <p>Be aware that to enable the browser to parse an XML document, the server must set\r
- * the Content-Type header in the HTTP response to "<tt>text/xml</tt>".</p>\r
- * @constructor\r
- * @param {Object} conn\r
- * An {@link Ext.data.Connection} object, or options parameter to {@link Ext.Ajax#request}.\r
- * <p>Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the\r
- * Store's call to {@link #load} will override any specified <tt>callback</tt> and <tt>params</tt>\r
- * options. In this case, use the Store's {@link Ext.data.Store#events events} to modify parameters,\r
- * or react to loading events. The Store's {@link Ext.data.Store#baseParams baseParams} may also be\r
- * used to pass parameters known at instantiation time.</p>\r
- * <p>If an options parameter is passed, the singleton {@link Ext.Ajax} object will be used to make\r
- * the request.</p>\r
- */\r
-Ext.data.HttpProxy = function(conn){\r
-    Ext.data.HttpProxy.superclass.constructor.call(this, conn);\r
-\r
-    <div id="prop-Ext.data.HttpProxy-conn"></div>/**\r
-     * The Connection object (Or options parameter to {@link Ext.Ajax#request}) which this HttpProxy\r
-     * uses to make requests to the server. Properties of this object may be changed dynamically to\r
-     * change the way data is requested.\r
-     * @property\r
-     */\r
-    this.conn = conn;\r
-\r
-    // nullify the connection url.  The url param has been copied to 'this' above.  The connection\r
-    // url will be set during each execution of doRequest when buildUrl is called.  This makes it easier for users to override the\r
-    // connection url during beforeaction events (ie: beforeload, beforewrite, etc).\r
-    // Url is always re-defined during doRequest.\r
-    this.conn.url = null;\r
-\r
-    this.useAjax = !conn || !conn.events;\r
-\r
-    // A hash containing active requests, keyed on action [Ext.data.Api.actions.create|read|update|destroy]\r
-    var actions = Ext.data.Api.actions;\r
-    this.activeRequest = {};\r
-    for (var verb in actions) {\r
-        this.activeRequest[actions[verb]] = undefined;\r
-    }\r
-};\r
-\r
-Ext.extend(Ext.data.HttpProxy, Ext.data.DataProxy, {\r
-    <div id="method-Ext.data.HttpProxy-getConnection"></div>/**\r
-     * Return the {@link Ext.data.Connection} object being used by this Proxy.\r
-     * @return {Connection} The Connection object. This object may be used to subscribe to events on\r
-     * a finer-grained basis than the DataProxy events.\r
-     */\r
-    getConnection : function() {\r
-        return this.useAjax ? Ext.Ajax : this.conn;\r
-    },\r
-\r
-    <div id="method-Ext.data.HttpProxy-setUrl"></div>/**\r
-     * Used for overriding the url used for a single request.  Designed to be called during a beforeaction event.  Calling setUrl\r
-     * will override any urls set via the api configuration parameter.  Set the optional parameter makePermanent to set the url for\r
-     * all subsequent requests.  If not set to makePermanent, the next request will use the same url or api configuration defined\r
-     * in the initial proxy configuration.\r
-     * @param {String} url\r
-     * @param {Boolean} makePermanent (Optional) [false]\r
-     *\r
-     * (e.g.: beforeload, beforesave, etc).\r
-     */\r
-    setUrl : function(url, makePermanent) {\r
-        this.conn.url = url;\r
-        if (makePermanent === true) {\r
-            this.url = url;\r
-            this.api = null;\r
-            Ext.data.Api.prepare(this);\r
-        }\r
-    },\r
-\r
-    <div id="method-Ext.data.HttpProxy-doRequest"></div>/**\r
-     * HttpProxy implementation of DataProxy#doRequest\r
-     * @param {String} action The crud action type (create, read, update, destroy)\r
-     * @param {Ext.data.Record/Ext.data.Record[]} rs If action is load, rs will be null\r
-     * @param {Object} params An object containing properties which are to be used as HTTP parameters\r
-     * for the request to the remote server.\r
-     * @param {Ext.data.DataReader} reader The Reader object which converts the data\r
-     * object into a block of Ext.data.Records.\r
-     * @param {Function} callback\r
-     * <div class="sub-desc"><p>A function to be called after the request.\r
-     * The <tt>callback</tt> is passed the following arguments:<ul>\r
-     * <li><tt>r</tt> : Ext.data.Record[] The block of Ext.data.Records.</li>\r
-     * <li><tt>options</tt>: Options object from the action request</li>\r
-     * <li><tt>success</tt>: Boolean success indicator</li></ul></p></div>\r
-     * @param {Object} scope The scope (<code>this</code> reference) in which the callback function is executed. Defaults to the browser window.\r
-     * @param {Object} arg An optional argument which is passed to the callback as its second parameter.\r
-     * @protected\r
-     */\r
-    doRequest : function(action, rs, params, reader, cb, scope, arg) {\r
-        var  o = {\r
-            method: (this.api[action]) ? this.api[action]['method'] : undefined,\r
-            request: {\r
-                callback : cb,\r
-                scope : scope,\r
-                arg : arg\r
-            },\r
-            reader: reader,\r
-            callback : this.createCallback(action, rs),\r
-            scope: this\r
-        };\r
-\r
-        // If possible, transmit data using jsonData || xmlData on Ext.Ajax.request (An installed DataWriter would have written it there.).\r
-        // Use std HTTP params otherwise.\r
-        if (params.jsonData) {\r
-            o.jsonData = params.jsonData;\r
-        } else if (params.xmlData) {\r
-            o.xmlData = params.xmlData;\r
-        } else {\r
-            o.params = params || {};\r
-        }\r
-        // Set the connection url.  If this.conn.url is not null here,\r
-        // the user must have overridden the url during a beforewrite/beforeload event-handler.\r
-        // this.conn.url is nullified after each request.\r
-        this.conn.url = this.buildUrl(action, rs);\r
-\r
-        if(this.useAjax){\r
-\r
-            Ext.applyIf(o, this.conn);\r
-\r
-            // If a currently running request is found for this action, abort it.\r
-            if (this.activeRequest[action]) {\r
-                ////\r
-                // Disabled aborting activeRequest while implementing REST.  activeRequest[action] will have to become an array\r
-                // TODO ideas anyone?\r
-                //\r
-                //Ext.Ajax.abort(this.activeRequest[action]);\r
-            }\r
-            this.activeRequest[action] = Ext.Ajax.request(o);\r
-        }else{\r
-            this.conn.request(o);\r
-        }\r
-        // request is sent, nullify the connection url in preparation for the next request\r
-        this.conn.url = null;\r
-    },\r
-\r
-    /**\r
-     * Returns a callback function for a request.  Note a special case is made for the\r
-     * read action vs all the others.\r
-     * @param {String} action [create|update|delete|load]\r
-     * @param {Ext.data.Record[]} rs The Store-recordset being acted upon\r
-     * @private\r
-     */\r
-    createCallback : function(action, rs) {\r
-        return function(o, success, response) {\r
-            this.activeRequest[action] = undefined;\r
-            if (!success) {\r
-                if (action === Ext.data.Api.actions.read) {\r
-                    // @deprecated: fire loadexception for backwards compat.\r
-                    // TODO remove in 3.1\r
-                    this.fireEvent('loadexception', this, o, response);\r
-                }\r
-                this.fireEvent('exception', this, 'response', action, o, response);\r
-                o.request.callback.call(o.request.scope, null, o.request.arg, false);\r
-                return;\r
-            }\r
-            if (action === Ext.data.Api.actions.read) {\r
-                this.onRead(action, o, response);\r
-            } else {\r
-                this.onWrite(action, o, response, rs);\r
-            }\r
-        };\r
-    },\r
-\r
-    <div id="method-Ext.data.HttpProxy-onRead"></div>/**\r
-     * Callback for read action\r
-     * @param {String} action Action name as per {@link Ext.data.Api.actions#read}.\r
-     * @param {Object} o The request transaction object\r
-     * @param {Object} res The server response\r
-     * @fires loadexception (deprecated)\r
-     * @fires exception\r
-     * @fires load\r
-     * @protected\r
-     */\r
-    onRead : function(action, o, response) {\r
-        var result;\r
-        try {\r
-            result = o.reader.read(response);\r
-        }catch(e){\r
-            // @deprecated: fire old loadexception for backwards-compat.\r
-            // TODO remove in 3.1\r
-            this.fireEvent('loadexception', this, o, response, e);\r
-\r
-            this.fireEvent('exception', this, 'response', action, o, response, e);\r
-            o.request.callback.call(o.request.scope, null, o.request.arg, false);\r
-            return;\r
-        }\r
-        if (result.success === false) {\r
-            // @deprecated: fire old loadexception for backwards-compat.\r
-            // TODO remove in 3.1\r
-            this.fireEvent('loadexception', this, o, response);\r
-\r
-            // Get DataReader read-back a response-object to pass along to exception event\r
-            var res = o.reader.readResponse(action, response);\r
-            this.fireEvent('exception', this, 'remote', action, o, res, null);\r
-        }\r
-        else {\r
-            this.fireEvent('load', this, o, o.request.arg);\r
-        }\r
-        // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance\r
-        // the calls to request.callback(...) in each will have to be made identical.\r
-        // NOTE reader.readResponse does not currently return Ext.data.Response\r
-        o.request.callback.call(o.request.scope, result, o.request.arg, result.success);\r
-    },\r
-    <div id="method-Ext.data.HttpProxy-onWrite"></div>/**\r
-     * Callback for write actions\r
-     * @param {String} action [Ext.data.Api.actions.create|read|update|destroy]\r
-     * @param {Object} trans The request transaction object\r
-     * @param {Object} res The server response\r
-     * @fires exception\r
-     * @fires write\r
-     * @protected\r
-     */\r
-    onWrite : function(action, o, response, rs) {\r
-        var reader = o.reader;\r
-        var res;\r
-        try {\r
-            res = reader.readResponse(action, response);\r
-        } catch (e) {\r
-            this.fireEvent('exception', this, 'response', action, o, response, e);\r
-            o.request.callback.call(o.request.scope, null, o.request.arg, false);\r
-            return;\r
-        }\r
-        if (res.success === true) {\r
-            this.fireEvent('write', this, action, res.data, res, rs, o.request.arg);\r
-        } else {\r
-            this.fireEvent('exception', this, 'remote', action, o, res, rs);\r
-        }\r
-        // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance\r
-        // the calls to request.callback(...) in each will have to be made similar.\r
-        // NOTE reader.readResponse does not currently return Ext.data.Response\r
-        o.request.callback.call(o.request.scope, res.data, res, res.success);\r
-    },\r
-\r
-    // inherit docs\r
-    destroy: function(){\r
-        if(!this.useAjax){\r
-            this.conn.abort();\r
-        }else if(this.activeRequest){\r
-            var actions = Ext.data.Api.actions;\r
-            for (var verb in actions) {\r
-                if(this.activeRequest[actions[verb]]){\r
-                    Ext.Ajax.abort(this.activeRequest[actions[verb]]);\r
-                }\r
-            }\r
-        }\r
-        Ext.data.HttpProxy.superclass.destroy.call(this);\r
-    }\r
-});</pre>    \r
-</body>\r
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    
+  <title>The source code</title>
+    <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+    <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+</head>
+<body  onload="prettyPrint();">
+    <pre class="prettyprint lang-js">/*!
+ * Ext JS Library 3.2.1
+ * Copyright(c) 2006-2010 Ext JS, Inc.
+ * licensing@extjs.com
+ * http://www.extjs.com/license
+ */
+<div id="cls-Ext.data.HttpProxy"></div>/**
+ * @class Ext.data.HttpProxy
+ * @extends Ext.data.DataProxy
+ * <p>An implementation of {@link Ext.data.DataProxy} that processes data requests within the same
+ * domain of the originating page.</p>
+ * <p><b>Note</b>: this class cannot be used to retrieve data from a domain other
+ * than the domain from which the running page was served. For cross-domain requests, use a
+ * {@link Ext.data.ScriptTagProxy ScriptTagProxy}.</p>
+ * <p>Be aware that to enable the browser to parse an XML document, the server must set
+ * the Content-Type header in the HTTP response to "<tt>text/xml</tt>".</p>
+ * @constructor
+ * @param {Object} conn
+ * An {@link Ext.data.Connection} object, or options parameter to {@link Ext.Ajax#request}.
+ * <p>Note that if this HttpProxy is being used by a {@link Ext.data.Store Store}, then the
+ * Store's call to {@link #load} will override any specified <tt>callback</tt> and <tt>params</tt>
+ * options. In this case, use the Store's {@link Ext.data.Store#events events} to modify parameters,
+ * or react to loading events. The Store's {@link Ext.data.Store#baseParams baseParams} may also be
+ * used to pass parameters known at instantiation time.</p>
+ * <p>If an options parameter is passed, the singleton {@link Ext.Ajax} object will be used to make
+ * the request.</p>
+ */
+Ext.data.HttpProxy = function(conn){
+    Ext.data.HttpProxy.superclass.constructor.call(this, conn);
+
+    <div id="prop-Ext.data.HttpProxy-conn"></div>/**
+     * The Connection object (Or options parameter to {@link Ext.Ajax#request}) which this HttpProxy
+     * uses to make requests to the server. Properties of this object may be changed dynamically to
+     * change the way data is requested.
+     * @property
+     */
+    this.conn = conn;
+
+    // nullify the connection url.  The url param has been copied to 'this' above.  The connection
+    // url will be set during each execution of doRequest when buildUrl is called.  This makes it easier for users to override the
+    // connection url during beforeaction events (ie: beforeload, beforewrite, etc).
+    // Url is always re-defined during doRequest.
+    this.conn.url = null;
+
+    this.useAjax = !conn || !conn.events;
+
+    // A hash containing active requests, keyed on action [Ext.data.Api.actions.create|read|update|destroy]
+    var actions = Ext.data.Api.actions;
+    this.activeRequest = {};
+    for (var verb in actions) {
+        this.activeRequest[actions[verb]] = undefined;
+    }
+};
+
+Ext.extend(Ext.data.HttpProxy, Ext.data.DataProxy, {
+    <div id="method-Ext.data.HttpProxy-getConnection"></div>/**
+     * Return the {@link Ext.data.Connection} object being used by this Proxy.
+     * @return {Connection} The Connection object. This object may be used to subscribe to events on
+     * a finer-grained basis than the DataProxy events.
+     */
+    getConnection : function() {
+        return this.useAjax ? Ext.Ajax : this.conn;
+    },
+
+    <div id="method-Ext.data.HttpProxy-setUrl"></div>/**
+     * Used for overriding the url used for a single request.  Designed to be called during a beforeaction event.  Calling setUrl
+     * will override any urls set via the api configuration parameter.  Set the optional parameter makePermanent to set the url for
+     * all subsequent requests.  If not set to makePermanent, the next request will use the same url or api configuration defined
+     * in the initial proxy configuration.
+     * @param {String} url
+     * @param {Boolean} makePermanent (Optional) [false]
+     *
+     * (e.g.: beforeload, beforesave, etc).
+     */
+    setUrl : function(url, makePermanent) {
+        this.conn.url = url;
+        if (makePermanent === true) {
+            this.url = url;
+            this.api = null;
+            Ext.data.Api.prepare(this);
+        }
+    },
+
+    <div id="method-Ext.data.HttpProxy-doRequest"></div>/**
+     * HttpProxy implementation of DataProxy#doRequest
+     * @param {String} action The crud action type (create, read, update, destroy)
+     * @param {Ext.data.Record/Ext.data.Record[]} rs If action is load, rs will be null
+     * @param {Object} params An object containing properties which are to be used as HTTP parameters
+     * for the request to the remote server.
+     * @param {Ext.data.DataReader} reader The Reader object which converts the data
+     * object into a block of Ext.data.Records.
+     * @param {Function} callback
+     * <div class="sub-desc"><p>A function to be called after the request.
+     * The <tt>callback</tt> is passed the following arguments:<ul>
+     * <li><tt>r</tt> : Ext.data.Record[] The block of Ext.data.Records.</li>
+     * <li><tt>options</tt>: Options object from the action request</li>
+     * <li><tt>success</tt>: Boolean success indicator</li></ul></p></div>
+     * @param {Object} scope The scope (<code>this</code> reference) in which the callback function is executed. Defaults to the browser window.
+     * @param {Object} arg An optional argument which is passed to the callback as its second parameter.
+     * @protected
+     */
+    doRequest : function(action, rs, params, reader, cb, scope, arg) {
+        var  o = {
+            method: (this.api[action]) ? this.api[action]['method'] : undefined,
+            request: {
+                callback : cb,
+                scope : scope,
+                arg : arg
+            },
+            reader: reader,
+            callback : this.createCallback(action, rs),
+            scope: this
+        };
+
+        // If possible, transmit data using jsonData || xmlData on Ext.Ajax.request (An installed DataWriter would have written it there.).
+        // Use std HTTP params otherwise.
+        if (params.jsonData) {
+            o.jsonData = params.jsonData;
+        } else if (params.xmlData) {
+            o.xmlData = params.xmlData;
+        } else {
+            o.params = params || {};
+        }
+        // Set the connection url.  If this.conn.url is not null here,
+        // the user must have overridden the url during a beforewrite/beforeload event-handler.
+        // this.conn.url is nullified after each request.
+        this.conn.url = this.buildUrl(action, rs);
+
+        if(this.useAjax){
+
+            Ext.applyIf(o, this.conn);
+
+            // If a currently running request is found for this action, abort it.
+            if (this.activeRequest[action]) {
+                ////
+                // Disabled aborting activeRequest while implementing REST.  activeRequest[action] will have to become an array
+                // TODO ideas anyone?
+                //
+                //Ext.Ajax.abort(this.activeRequest[action]);
+            }
+            this.activeRequest[action] = Ext.Ajax.request(o);
+        }else{
+            this.conn.request(o);
+        }
+        // request is sent, nullify the connection url in preparation for the next request
+        this.conn.url = null;
+    },
+
+    /**
+     * Returns a callback function for a request.  Note a special case is made for the
+     * read action vs all the others.
+     * @param {String} action [create|update|delete|load]
+     * @param {Ext.data.Record[]} rs The Store-recordset being acted upon
+     * @private
+     */
+    createCallback : function(action, rs) {
+        return function(o, success, response) {
+            this.activeRequest[action] = undefined;
+            if (!success) {
+                if (action === Ext.data.Api.actions.read) {
+                    // @deprecated: fire loadexception for backwards compat.
+                    // TODO remove
+                    this.fireEvent('loadexception', this, o, response);
+                }
+                this.fireEvent('exception', this, 'response', action, o, response);
+                o.request.callback.call(o.request.scope, null, o.request.arg, false);
+                return;
+            }
+            if (action === Ext.data.Api.actions.read) {
+                this.onRead(action, o, response);
+            } else {
+                this.onWrite(action, o, response, rs);
+            }
+        };
+    },
+
+    <div id="method-Ext.data.HttpProxy-onRead"></div>/**
+     * Callback for read action
+     * @param {String} action Action name as per {@link Ext.data.Api.actions#read}.
+     * @param {Object} o The request transaction object
+     * @param {Object} res The server response
+     * @fires loadexception (deprecated)
+     * @fires exception
+     * @fires load
+     * @protected
+     */
+    onRead : function(action, o, response) {
+        var result;
+        try {
+            result = o.reader.read(response);
+        }catch(e){
+            // @deprecated: fire old loadexception for backwards-compat.
+            // TODO remove
+            this.fireEvent('loadexception', this, o, response, e);
+
+            this.fireEvent('exception', this, 'response', action, o, response, e);
+            o.request.callback.call(o.request.scope, null, o.request.arg, false);
+            return;
+        }
+        if (result.success === false) {
+            // @deprecated: fire old loadexception for backwards-compat.
+            // TODO remove
+            this.fireEvent('loadexception', this, o, response);
+
+            // Get DataReader read-back a response-object to pass along to exception event
+            var res = o.reader.readResponse(action, response);
+            this.fireEvent('exception', this, 'remote', action, o, res, null);
+        }
+        else {
+            this.fireEvent('load', this, o, o.request.arg);
+        }
+        // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance
+        // the calls to request.callback(...) in each will have to be made identical.
+        // NOTE reader.readResponse does not currently return Ext.data.Response
+        o.request.callback.call(o.request.scope, result, o.request.arg, result.success);
+    },
+    <div id="method-Ext.data.HttpProxy-onWrite"></div>/**
+     * Callback for write actions
+     * @param {String} action [Ext.data.Api.actions.create|read|update|destroy]
+     * @param {Object} trans The request transaction object
+     * @param {Object} res The server response
+     * @fires exception
+     * @fires write
+     * @protected
+     */
+    onWrite : function(action, o, response, rs) {
+        var reader = o.reader;
+        var res;
+        try {
+            res = reader.readResponse(action, response);
+        } catch (e) {
+            this.fireEvent('exception', this, 'response', action, o, response, e);
+            o.request.callback.call(o.request.scope, null, o.request.arg, false);
+            return;
+        }
+        if (res.success === true) {
+            this.fireEvent('write', this, action, res.data, res, rs, o.request.arg);
+        } else {
+            this.fireEvent('exception', this, 'remote', action, o, res, rs);
+        }
+        // TODO refactor onRead, onWrite to be more generalized now that we're dealing with Ext.data.Response instance
+        // the calls to request.callback(...) in each will have to be made similar.
+        // NOTE reader.readResponse does not currently return Ext.data.Response
+        o.request.callback.call(o.request.scope, res.data, res, res.success);
+    },
+
+    // inherit docs
+    destroy: function(){
+        if(!this.useAjax){
+            this.conn.abort();
+        }else if(this.activeRequest){
+            var actions = Ext.data.Api.actions;
+            for (var verb in actions) {
+                if(this.activeRequest[actions[verb]]){
+                    Ext.Ajax.abort(this.activeRequest[actions[verb]]);
+                }
+            }
+        }
+        Ext.data.HttpProxy.superclass.destroy.call(this);
+    }
+});</pre>    
+</body>
 </html>
\ No newline at end of file