X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6a7e4474cba9d8be4b2ec445e10f1691f7277c50..7a654f8d43fdb43d78b63d90528bed6e86b608cc:/docs/source/Direct.html diff --git a/docs/source/Direct.html b/docs/source/Direct.html index edbb587d..d51f71eb 100644 --- a/docs/source/Direct.html +++ b/docs/source/Direct.html @@ -1,245 +1,179 @@ - - - - The source code - - - - -
/*!
- * Ext JS Library 3.2.0
- * Copyright(c) 2006-2010 Ext JS, Inc.
- * licensing@extjs.com
- * http://www.extjs.com/license
+Sencha Documentation Project
/**
+ * @class Ext.data.proxy.Direct
+ * @extends Ext.data.proxy.Server
+ * 
+ * This class is used to send requests to the server using {@link 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.
+ * 
+ * ## Paramaters
+ * 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);
  */
-
/** - * @class Ext.Direct - * @extends Ext.util.Observable - *

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:

- *

-{"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);
-});
- * 
- * @singleton - */ -Ext.Direct = Ext.extend(Ext.util.Observable, { -
/** - * Each event type implements a getData() method. The default event types are: - *
    - *
  • event : Ext.Direct.Event
  • - *
  • exception : Ext.Direct.ExceptionEvent
  • - *
  • rpc : Ext.Direct.RemotingEvent
  • - *
- * @property eventTypes - * @type Object +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 {Array/String} paramOrder Defaults to <tt>undefined</tt>. 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:<pre><code> +paramOrder: ['param1','param2','param3'] +paramOrder: 'param1 param2 param3' +paramOrder: 'param1,param2,param3' +paramOrder: 'param1|param2|param' + </code></pre> */ + paramOrder: undefined, -
/** - * Four types of possible exceptions which can occur: - *
    - *
  • Ext.Direct.exceptions.TRANSPORT : 'xhr'
  • - *
  • Ext.Direct.exceptions.PARSE : 'parse'
  • - *
  • Ext.Direct.exceptions.LOGIN : 'login'
  • - *
  • Ext.Direct.exceptions.SERVER : 'exception'
  • - *
- * @property exceptions - * @type Object + /** + * @cfg {Boolean} paramsAsHash + * Send parameters as a collection of named arguments (defaults to <tt>true</tt>). Providing a + * <tt>{@link #paramOrder}</tt> nullifies this configuration. */ - exceptions: { - TRANSPORT: 'xhr', - PARSE: 'parse', - LOGIN: 'login', - SERVER: 'exception' - }, + 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 - 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. - *

-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'
+    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);
     },
-    pollProv // reference to previously created instance
-);
-     * 
- * @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; + + 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'); } - - // if provider has not already been instantiated - if(!provider.events){ - provider = new Ext.Direct.PROVIDERS[provider.type](provider); + //</debug> + + if (operation.allowWrite()) { + request = writer.write(request); } - 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(); + + 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); } - - return provider; + + Ext.apply(request, { + args: args, + directFn: fn + }); + args.push(me.createRequestCallback(request, operation, callback, scope), me); + fn.apply(window, args); }, - -
/** - * 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} + + /* + * Inherit docs. We don't apply any encoding here because + * all of the direct requests go out as jsonData */ - getProvider : function(id){ - return this.providers[id]; - }, - - removeProvider : function(id){ - var provider = id.id ? id : this.providers[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; + applyEncoding: function(value){ + return value; }, - - removeTransaction: function(t){ - delete this.transactions[t.tid || t]; - return t; + + createRequestCallback: function(request, operation, callback, scope){ + var me = this; + + return function(data, event){ + me.processResponse(event.status, operation, request, event, callback, scope); + }; }, - - getTransaction: function(tid){ - return this.transactions[tid.tid || tid]; + + // inherit docs + extractResponseData: function(response){ + return Ext.isDefined(response.result) ? response.result : response.data; }, - - 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); + + // inherit docs + setException: function(operation, response) { + operation.setException(response.message); }, - - createEvent : function(response, extraProps){ - return new Ext.Direct.eventTypes[response.type](Ext.apply(response, extraProps)); + + // inherit docs + buildUrl: function(){ + return ''; } }); -// overwrite impl. with static instance -Ext.Direct = new Ext.Direct(); - -Ext.Direct.TID = 1; -Ext.Direct.PROVIDERS = {};
- - \ No newline at end of file +
\ No newline at end of file