src/data/proxy/Direct.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  * @class Ext.data.proxy.Direct
  17  * @extends Ext.data.proxy.Server
  18  *
  19  * This class is used to send requests to the server using {@link Ext.direct}. When a request is made,
  20  * the transport mechanism is handed off to the appropriate {@link Ext.direct.RemotingProvider Provider}
  21  * to complete the call.
  22  *
  23  * ## Specifying the function
  24  * This proxy expects a Direct remoting method to be passed in order to be able to complete requests.
  25  * This can be done by specifying the {@link #directFn} configuration. This will use the same direct
  26  * method for all requests. Alternatively, you can provide an {@link #api} configuration. This
  27  * allows you to specify a different remoting method for each CRUD action.
  28  *
  29  * ## Parameters
  30  * This proxy provides options to help configure which parameters will be sent to the server.
  31  * By specifying the {@link #paramsAsHash} option, it will send an object literal containing each
  32  * of the passed parameters. The {@link #paramOrder} option can be used to specify the order in which
  33  * the remoting method parameters are passed.
  34  *
  35  * ## Example Usage
  36  *
  37  *     Ext.define('User', {
  38  *         extend: 'Ext.data.Model',
  39  *         fields: ['firstName', 'lastName'],
  40  *         proxy: {
  41  *             type: 'direct',
  42  *             directFn: MyApp.getUsers,
  43  *             paramOrder: 'id' // Tells the proxy to pass the id as the first parameter to the remoting method.
  44  *         }
  45  *     });
  46  *     User.load(1);
  47  */
  48 Ext.define('Ext.data.proxy.Direct', {
  49     /* Begin Definitions */
  50
  51     extend: 'Ext.data.proxy.Server',
  52     alternateClassName: 'Ext.data.DirectProxy',
  53
  54     alias: 'proxy.direct',
  55
  56     requires: ['Ext.direct.Manager'],
  57
  58     /* End Definitions */
  59
  60    /**
  61      * @cfg {Array/String} paramOrder Defaults to <tt>undefined</tt>. A list of params to be executed
  62      * server side.  Specify the params in the order in which they must be executed on the server-side
  63      * as either (1) an Array of String values, or (2) a String of params delimited by either whitespace,
  64      * comma, or pipe. For example,
  65      * any of the following would be acceptable:<pre><code>
  66 paramOrder: ['param1','param2','param3']
  67 paramOrder: 'param1 param2 param3'
  68 paramOrder: 'param1,param2,param3'
  69 paramOrder: 'param1|param2|param'
  70      </code></pre>
  71      */
  72     paramOrder: undefined,
  73
  74     /**
  75      * @cfg {Boolean} paramsAsHash
  76      * Send parameters as a collection of named arguments (defaults to <tt>true</tt>). Providing a
  77      * <tt>{@link #paramOrder}</tt> nullifies this configuration.
  78      */
  79     paramsAsHash: true,
  80
  81     /**
  82      * @cfg {Function} directFn
  83      * Function to call when executing a request.  directFn is a simple alternative to defining the api configuration-parameter
  84      * for Store's which will not implement a full CRUD api.
  85      */
  86     directFn : undefined,
  87
  88     /**
  89      * @cfg {Object} api The same as {@link Ext.data.proxy.Server#api}, however instead of providing urls, you should provide a direct
  90      * function call.
  91      */
  92
  93     /**
  94      * @cfg {Object} extraParams Extra parameters that will be included on every read request. Individual requests with params
  95      * of the same name will override these params when they are in conflict.
  96      */
  97
  98     // private
  99     paramOrderRe: /[\s,|]/,
 100
 101     constructor: function(config){
 102         var me = this;
 103
 104         Ext.apply(me, config);
 105         if (Ext.isString(me.paramOrder)) {
 106             me.paramOrder = me.paramOrder.split(me.paramOrderRe);
 107         }
 108         me.callParent(arguments);
 109     },
 110
 111     doRequest: function(operation, callback, scope) {
 112         var me = this,
 113             writer = me.getWriter(),
 114             request = me.buildRequest(operation, callback, scope),
 115             fn = me.api[request.action]  || me.directFn,
 116             args = [],
 117             params = request.params,
 118             paramOrder = me.paramOrder,
 119             method,
 120             i = 0,
 121             len;
 122
 123         //<debug>
 124         if (!fn) {
 125             Ext.Error.raise('No direct function specified for this proxy');
 126         }
 127         //</debug>
 128
 129         if (operation.allowWrite()) {
 130             request = writer.write(request);
 131         }
 132
 133         if (operation.action == 'read') {
 134             // We need to pass params
 135             method = fn.directCfg.method;
 136
 137             if (method.ordered) {
 138                 if (method.len > 0) {
 139                     if (paramOrder) {
 140                         for (len = paramOrder.length; i < len; ++i) {
 141                             args.push(params[paramOrder[i]]);
 142                         }
 143                     } else if (me.paramsAsHash) {
 144                         args.push(params);
 145                     }
 146                 }
 147             } else {
 148                 args.push(params);
 149             }
 150         } else {
 151             args.push(request.jsonData);
 152         }
 153
 154         Ext.apply(request, {
 155             args: args,
 156             directFn: fn
 157         });
 158         args.push(me.createRequestCallback(request, operation, callback, scope), me);
 159         fn.apply(window, args);
 160     },
 161
 162     /*
 163      * Inherit docs. We don't apply any encoding here because
 164      * all of the direct requests go out as jsonData
 165      */
 166     applyEncoding: function(value){
 167         return value;
 168     },
 169
 170     createRequestCallback: function(request, operation, callback, scope){
 171         var me = this;
 172
 173         return function(data, event){
 174             me.processResponse(event.status, operation, request, event, callback, scope);
 175         };
 176     },
 177
 178     // inherit docs
 179     extractResponseData: function(response){
 180         return Ext.isDefined(response.result) ? response.result : response.data;
 181     },
 182
 183     // inherit docs
 184     setException: function(operation, response) {
 185         operation.setException(response.message);
 186     },
 187
 188     // inherit docs
 189     buildUrl: function(){
 190         return '';
 191     }
 192 });
 193