/** - * @class Ext.Direct - * @extends Ext.util.Observable - *- - \ No newline at end of file + + + + +Overview
- * - *Ext.Direct aims to streamline communication between the client and server - * by providing a single interface that reduces the amount of common code - * typically required to validate data and handle returned data packets - * (reading data, error conditions, etc).
- * - *The Ext.direct namespace includes several classes for a closer integration - * with the server-side. The Ext.data namespace also includes classes for working - * with Ext.data.Stores which are backed by data from an Ext.Direct method.
- * - *Specification
- * - *For additional information consult the - * Ext.Direct Specification.
- * - *Providers
- * - *Ext.Direct uses a provider architecture, where one or more providers are - * used to transport data to and from the server. There are several providers - * that exist in the core at the moment:
- * - *- * - *
- {@link Ext.direct.JsonProvider JsonProvider} for simple JSON operations
- *- {@link Ext.direct.PollingProvider PollingProvider} for repeated requests
- *- {@link Ext.direct.RemotingProvider RemotingProvider} exposes server side - * on the client.
- *A provider does not need to be invoked directly, providers are added via - * {@link Ext.Direct}.{@link Ext.Direct#add add}.
- * - *Router
- * - *Ext.Direct utilizes a "router" on the server to direct requests from the client - * to the appropriate server-side method. Because the Ext.Direct API is completely - * platform-agnostic, you could completely swap out a Java based server solution - * and replace it with one that uses C# without changing the client side JavaScript - * at all.
- * - *Server side events
- * - *Custom events from the server may be handled by the client by adding - * listeners, for example:
- *- * @singleton - */ -Ext.Direct = Ext.extend(Ext.util.Observable, { - /** - * Each event type implements a getData() method. The default event types are: - *-{"type":"event","name":"message","data":"Successfully polled at: 11:19:30 am"} - -// add a handler for a 'message' event sent by the server -Ext.Direct.on('message', function(e){ - out.append(String.format('<p><i>{0}</i></p>', e.data)); - out.el.scrollTo('t', 100000, true); -}); - *- * @property eventTypes - * @type Object - */ - - /** - * Four types of possible exceptions which can occur: - *- *
- event : Ext.Direct.Event
- *- exception : Ext.Direct.ExceptionEvent
- *- rpc : Ext.Direct.RemotingEvent
- *- * @property exceptions - * @type Object - */ - exceptions: { - TRANSPORT: 'xhr', - PARSE: 'parse', - LOGIN: 'login', - SERVER: 'exception' - }, - - // private - constructor: function(){ - this.addEvents( - /** - * @event event - * Fires after an event. - * @param {event} e The {@link Ext.Direct#eventTypes Ext.Direct.Event type} that occurred. - * @param {Ext.direct.Provider} provider The {@link Ext.direct.Provider Provider}. - */ - 'event', - /** - * @event exception - * Fires after an event exception. - * @param {event} e The {@link Ext.Direct#eventTypes Ext.Direct.Event type} that occurred. - */ - 'exception' - ); - this.transactions = {}; - this.providers = {}; - }, - - /** - * Adds an Ext.Direct Provider and creates the proxy or stub methods to execute server-side methods. - * If the provider is not already connected, it will auto-connect. - *- *
- Ext.Direct.exceptions.TRANSPORT : 'xhr'
- *- Ext.Direct.exceptions.PARSE : 'parse'
- *- Ext.Direct.exceptions.LOGIN : 'login'
- *- Ext.Direct.exceptions.SERVER : 'exception'
- *- * @param {Object/Array} provider Accepts either an Array of Provider descriptions (an instance - * or config object for a Provider) or any number of Provider descriptions as arguments. Each - * Provider description instructs Ext.Direct how to create client-side stub methods. - */ - addProvider : function(provider){ - var a = arguments; - if(a.length > 1){ - for(var i = 0, len = a.length; i < len; i++){ - this.addProvider(a[i]); - } - return; - } - - // if provider has not already been instantiated - if(!provider.events){ - provider = new Ext.Direct.PROVIDERS[provider.type](provider); - } - provider.id = provider.id || Ext.id(); - this.providers[provider.id] = provider; - - provider.on('data', this.onProviderData, this); - provider.on('exception', this.onProviderException, this); - - - if(!provider.isConnected()){ - provider.connect(); - } - - return provider; - }, - - /** - * Retrieve a {@link Ext.direct.Provider provider} by the - * {@link Ext.direct.Provider#id id} specified when the provider is - * {@link #addProvider added}. - * @param {String} id Unique identifier assigned to the provider when calling {@link #addProvider} - */ - getProvider : function(id){ - return this.providers[id]; - }, - - removeProvider : function(id){ - var provider = id.id ? id : this.providers[id.id]; - provider.un('data', this.onProviderData, this); - provider.un('exception', this.onProviderException, this); - delete this.providers[provider.id]; - return provider; - }, - - addTransaction: function(t){ - this.transactions[t.tid] = t; - return t; - }, - - removeTransaction: function(t){ - delete this.transactions[t.tid || t]; - return t; - }, - - getTransaction: function(tid){ - return this.transactions[tid.tid || tid]; - }, - - onProviderData : function(provider, e){ - if(Ext.isArray(e)){ - for(var i = 0, len = e.length; i < len; i++){ - this.onProviderData(provider, e[i]); - } - return; - } - if(e.name && e.name != 'event' && e.name != 'exception'){ - this.fireEvent(e.name, e); - }else if(e.type == 'exception'){ - this.fireEvent('exception', e); - } - this.fireEvent('event', e, provider); - }, - - createEvent : function(response, extraProps){ - return new Ext.Direct.eventTypes[response.type](Ext.apply(response, extraProps)); - } -}); -// overwrite impl. with static instance -Ext.Direct = new Ext.Direct(); - -Ext.Direct.TID = 1; -Ext.Direct.PROVIDERS = {};-var pollProv = new Ext.direct.PollingProvider({ - url: 'php/poll2.php' -}); - -Ext.Direct.addProvider( - { - "type":"remoting", // create a {@link Ext.direct.RemotingProvider} - "url":"php\/router.php", // url to connect to the Ext.Direct server-side router. - "actions":{ // each property within the actions object represents a Class - "TestAction":[ // array of methods within each server side Class - { - "name":"doEcho", // name of method - "len":1 - },{ - "name":"multiply", - "len":1 - },{ - "name":"doForm", - "formHandler":true, // handle form on server with Ext.Direct.Transaction - "len":1 - }] - }, - "namespace":"myApplication",// namespace to create the Remoting Provider in - },{ - type: 'polling', // create a {@link Ext.direct.PollingProvider} - url: 'php/poll.php' - }, - pollProv // reference to previously created instance -); - *
/** + * This class is used to send requests to the server using {@link Ext.direct.Manager Ext.Direct}. When a + * request is made, the transport mechanism is handed off to the appropriate + * {@link Ext.direct.RemotingProvider Provider} to complete the call. + * + * # Specifying the function + * + * This proxy expects a Direct remoting method to be passed in order to be able to complete requests. + * This can be done by specifying the {@link #directFn} configuration. This will use the same direct + * method for all requests. Alternatively, you can provide an {@link #api} configuration. This + * allows you to specify a different remoting method for each CRUD action. + * + * # Parameters + * + * This proxy provides options to help configure which parameters will be sent to the server. + * By specifying the {@link #paramsAsHash} option, it will send an object literal containing each + * of the passed parameters. The {@link #paramOrder} option can be used to specify the order in which + * the remoting method parameters are passed. + * + * # Example Usage + * + * Ext.define('User', { + * extend: 'Ext.data.Model', + * fields: ['firstName', 'lastName'], + * proxy: { + * type: 'direct', + * directFn: MyApp.getUsers, + * paramOrder: 'id' // Tells the proxy to pass the id as the first parameter to the remoting method. + * } + * }); + * User.load(1); + */ +Ext.define('Ext.data.proxy.Direct', { + /* Begin Definitions */ + + extend: 'Ext.data.proxy.Server', + alternateClassName: 'Ext.data.DirectProxy', + + alias: 'proxy.direct', + + requires: ['Ext.direct.Manager'], + + /* End Definitions */ + + /** + * @cfg {String/String[]} paramOrder + * Defaults to undefined. A list of params to be executed server side. Specify the params in the order in + * which they must be executed on the server-side as either (1) an Array of String values, or (2) a String + * of params delimited by either whitespace, comma, or pipe. For example, any of the following would be + * acceptable: + * + * paramOrder: ['param1','param2','param3'] + * paramOrder: 'param1 param2 param3' + * paramOrder: 'param1,param2,param3' + * paramOrder: 'param1|param2|param' + */ + paramOrder: undefined, + + /** + * @cfg {Boolean} paramsAsHash + * Send parameters as a collection of named arguments. + * Providing a {@link #paramOrder} nullifies this configuration. + */ + paramsAsHash: true, + + /** + * @cfg {Function} directFn + * Function to call when executing a request. directFn is a simple alternative to defining the api configuration-parameter + * for Store's which will not implement a full CRUD api. + */ + directFn : undefined, + + /** + * @cfg {Object} api + * The same as {@link Ext.data.proxy.Server#api}, however instead of providing urls, you should provide a direct + * function call. + */ + + /** + * @cfg {Object} extraParams + * Extra parameters that will be included on every read request. Individual requests with params + * of the same name will override these params when they are in conflict. + */ + + // private + paramOrderRe: /[\s,|]/, + + constructor: function(config){ + var me = this; + + Ext.apply(me, config); + if (Ext.isString(me.paramOrder)) { + me.paramOrder = me.paramOrder.split(me.paramOrderRe); + } + me.callParent(arguments); + }, + + doRequest: function(operation, callback, scope) { + var me = this, + writer = me.getWriter(), + request = me.buildRequest(operation, callback, scope), + fn = me.api[request.action] || me.directFn, + args = [], + params = request.params, + paramOrder = me.paramOrder, + method, + i = 0, + len; + + //<debug> + if (!fn) { + Ext.Error.raise('No direct function specified for this proxy'); + } + //</debug> + + if (operation.allowWrite()) { + request = writer.write(request); + } + + if (operation.action == 'read') { + // We need to pass params + method = fn.directCfg.method; + + if (method.ordered) { + if (method.len > 0) { + if (paramOrder) { + for (len = paramOrder.length; i < len; ++i) { + args.push(params[paramOrder[i]]); + } + } else if (me.paramsAsHash) { + args.push(params); + } + } + } else { + args.push(params); + } + } else { + args.push(request.jsonData); + } + + Ext.apply(request, { + args: args, + directFn: fn + }); + args.push(me.createRequestCallback(request, operation, callback, scope), me); + fn.apply(window, args); + }, + + /* + * Inherit docs. We don't apply any encoding here because + * all of the direct requests go out as jsonData + */ + applyEncoding: function(value){ + return value; + }, + + createRequestCallback: function(request, operation, callback, scope){ + var me = this; + + return function(data, event){ + me.processResponse(event.status, operation, request, event, callback, scope); + }; + }, + + // inherit docs + extractResponseData: function(response){ + return Ext.isDefined(response.result) ? response.result : response.data; + }, + + // inherit docs + setException: function(operation, response) { + operation.setException(response.message); + }, + + // inherit docs + buildUrl: function(){ + return ''; + } +}); ++ +