Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / Action2.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="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/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-form-action-Action'>/**
19 </span> * @class Ext.form.action.Action
20  * @extends Ext.Base
21  * &lt;p&gt;The subclasses of this class provide actions to perform upon {@link Ext.form.Basic Form}s.&lt;/p&gt;
22  * &lt;p&gt;Instances of this class are only created by a {@link Ext.form.Basic Form} when
23  * the Form needs to perform an action such as submit or load. The Configuration options
24  * listed for this class are set through the Form's action methods: {@link Ext.form.Basic#submit submit},
25  * {@link Ext.form.Basic#load load} and {@link Ext.form.Basic#doAction doAction}&lt;/p&gt;
26  * &lt;p&gt;The instance of Action which performed the action is passed to the success
27  * and failure callbacks of the Form's action methods ({@link Ext.form.Basic#submit submit},
28  * {@link Ext.form.Basic#load load} and {@link Ext.form.Basic#doAction doAction}),
29  * and to the {@link Ext.form.Basic#actioncomplete actioncomplete} and
30  * {@link Ext.form.Basic#actionfailed actionfailed} event handlers.&lt;/p&gt;
31  */
32 Ext.define('Ext.form.action.Action', {
33     alternateClassName: 'Ext.form.Action',
34
35 <span id='Ext-form-action-Action-cfg-form'>    /**
36 </span>     * @cfg {Ext.form.Basic} form The {@link Ext.form.Basic BasicForm} instance that
37      * is invoking this Action. Required.
38      */
39
40 <span id='Ext-form-action-Action-cfg-url'>    /**
41 </span>     * @cfg {String} url The URL that the Action is to invoke. Will default to the {@link Ext.form.Basic#url url}
42      * configured on the {@link #form}.
43      */
44
45 <span id='Ext-form-action-Action-cfg-reset'>    /**
46 </span>     * @cfg {Boolean} reset When set to &lt;tt&gt;&lt;b&gt;true&lt;/b&gt;&lt;/tt&gt;, causes the Form to be
47      * {@link Ext.form.Basic#reset reset} on Action success. If specified, this happens
48      * before the {@link #success} callback is called and before the Form's
49      * {@link Ext.form.Basic#actioncomplete actioncomplete} event fires.
50      */
51
52 <span id='Ext-form-action-Action-cfg-method'>    /**
53 </span>     * @cfg {String} method The HTTP method to use to access the requested URL. Defaults to the
54      * {@link Ext.form.Basic#method BasicForm's method}, or 'POST' if not specified.
55      */
56
57 <span id='Ext-form-action-Action-cfg-params'>    /**
58 </span>     * @cfg {Object/String} params &lt;p&gt;Extra parameter values to pass. These are added to the Form's
59      * {@link Ext.form.Basic#baseParams} and passed to the specified URL along with the Form's
60      * input fields.&lt;/p&gt;
61      * &lt;p&gt;Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode Ext.Object.toQueryString}.&lt;/p&gt;
62      */
63
64 <span id='Ext-form-action-Action-cfg-headers'>    /**
65 </span>     * @cfg {Object} headers &lt;p&gt;Extra headers to be sent in the AJAX request for submit and load actions. See
66      * {@link Ext.data.proxy.Ajax#headers}.&lt;/p&gt;
67      */
68
69 <span id='Ext-form-action-Action-cfg-timeout'>    /**
70 </span>     * @cfg {Number} timeout The number of seconds to wait for a server response before
71      * failing with the {@link #failureType} as {@link Ext.form.action.Action#CONNECT_FAILURE}. If not specified,
72      * defaults to the configured &lt;tt&gt;{@link Ext.form.Basic#timeout timeout}&lt;/tt&gt; of the
73      * {@link #form}.
74      */
75
76 <span id='Ext-form-action-Action-cfg-success'>    /**
77 </span>     * @cfg {Function} success The function to call when a valid success return packet is received.
78      * The function is passed the following parameters:&lt;ul class=&quot;mdetail-params&quot;&gt;
79      * &lt;li&gt;&lt;b&gt;form&lt;/b&gt; : Ext.form.Basic&lt;div class=&quot;sub-desc&quot;&gt;The form that requested the action&lt;/div&gt;&lt;/li&gt;
80      * &lt;li&gt;&lt;b&gt;action&lt;/b&gt; : Ext.form.action.Action&lt;div class=&quot;sub-desc&quot;&gt;The Action class. The {@link #result}
81      * property of this object may be examined to perform custom postprocessing.&lt;/div&gt;&lt;/li&gt;
82      * &lt;/ul&gt;
83      */
84
85 <span id='Ext-form-action-Action-cfg-failure'>    /**
86 </span>     * @cfg {Function} failure The function to call when a failure packet was received, or when an
87      * error ocurred in the Ajax communication.
88      * The function is passed the following parameters:&lt;ul class=&quot;mdetail-params&quot;&gt;
89      * &lt;li&gt;&lt;b&gt;form&lt;/b&gt; : Ext.form.Basic&lt;div class=&quot;sub-desc&quot;&gt;The form that requested the action&lt;/div&gt;&lt;/li&gt;
90      * &lt;li&gt;&lt;b&gt;action&lt;/b&gt; : Ext.form.action.Action&lt;div class=&quot;sub-desc&quot;&gt;The Action class. If an Ajax
91      * error ocurred, the failure type will be in {@link #failureType}. The {@link #result}
92      * property of this object may be examined to perform custom postprocessing.&lt;/div&gt;&lt;/li&gt;
93      * &lt;/ul&gt;
94      */
95
96 <span id='Ext-form-action-Action-cfg-scope'>    /**
97 </span>     * @cfg {Object} scope The scope in which to call the configured &lt;tt&gt;success&lt;/tt&gt; and &lt;tt&gt;failure&lt;/tt&gt;
98      * callback functions (the &lt;tt&gt;this&lt;/tt&gt; reference for the callback functions).
99      */
100
101 <span id='Ext-form-action-Action-cfg-waitMsg'>    /**
102 </span>     * @cfg {String} waitMsg The message to be displayed by a call to {@link Ext.window.MessageBox#wait}
103      * during the time the action is being processed.
104      */
105
106 <span id='Ext-form-action-Action-cfg-waitTitle'>    /**
107 </span>     * @cfg {String} waitTitle The title to be displayed by a call to {@link Ext.window.MessageBox#wait}
108      * during the time the action is being processed.
109      */
110
111 <span id='Ext-form-action-Action-cfg-submitEmptyText'>    /**
112 </span>     * @cfg {Boolean} submitEmptyText If set to &lt;tt&gt;true&lt;/tt&gt;, the emptyText value will be sent with the form
113      * when it is submitted. Defaults to &lt;tt&gt;true&lt;/tt&gt;.
114      */
115     submitEmptyText : true,
116 <span id='Ext-form-action-Action-property-type'>    /**
117 </span>     * @property type
118      * The type of action this Action instance performs.
119      * Currently only &quot;submit&quot; and &quot;load&quot; are supported.
120      * @type {String}
121      */
122
123 <span id='Ext-form-action-Action-property-failureType'>    /**
124 </span>     * The type of failure detected will be one of these: {@link Ext.form.action.Action#CLIENT_INVALID},
125      * {@link Ext.form.action.Action#SERVER_INVALID}, {@link Ext.form.action.Action#CONNECT_FAILURE}, or
126      * {@link Ext.form.action.Action#LOAD_FAILURE}.  Usage:
127      * &lt;pre&gt;&lt;code&gt;
128 var fp = new Ext.form.Panel({
129 ...
130 buttons: [{
131     text: 'Save',
132     formBind: true,
133     handler: function(){
134         if(fp.getForm().isValid()){
135             fp.getForm().submit({
136                 url: 'form-submit.php',
137                 waitMsg: 'Submitting your data...',
138                 success: function(form, action){
139                     // server responded with success = true
140                     var result = action.{@link #result};
141                 },
142                 failure: function(form, action){
143                     if (action.{@link #failureType} === {@link Ext.form.action.Action#CONNECT_FAILURE}) {
144                         Ext.Msg.alert('Error',
145                             'Status:'+action.{@link #response}.status+': '+
146                             action.{@link #response}.statusText);
147                     }
148                     if (action.failureType === {@link Ext.form.action.Action#SERVER_INVALID}){
149                         // server responded with success = false
150                         Ext.Msg.alert('Invalid', action.{@link #result}.errormsg);
151                     }
152                 }
153             });
154         }
155     }
156 },{
157     text: 'Reset',
158     handler: function(){
159         fp.getForm().reset();
160     }
161 }]
162      * &lt;/code&gt;&lt;/pre&gt;
163      * @property failureType
164      * @type {String}
165      */
166
167 <span id='Ext-form-action-Action-property-response'>    /**
168 </span>     * The raw XMLHttpRequest object used to perform the action.
169      * @property response
170      * @type {Object}
171      */
172
173 <span id='Ext-form-action-Action-property-result'>    /**
174 </span>     * The decoded response object containing a boolean &lt;tt&gt;success&lt;/tt&gt; property and
175      * other, action-specific properties.
176      * @property result
177      * @type {Object}
178      */
179
180 <span id='Ext-form-action-Action-method-constructor'>    /**
181 </span>     * Creates new Action.
182      * @param {Object} config (optional) Config object.
183      */
184     constructor: function(config) {
185         if (config) {
186             Ext.apply(this, config);
187         }
188
189         // Normalize the params option to an Object
190         var params = config.params;
191         if (Ext.isString(params)) {
192             this.params = Ext.Object.fromQueryString(params);
193         }
194     },
195
196 <span id='Ext-form-action-Action-property-run'>    /**
197 </span>     * Invokes this action using the current configuration.
198      */
199     run: Ext.emptyFn,
200
201 <span id='Ext-form-action-Action-method-onSuccess'>    /**
202 </span>     * @private
203      * @method onSuccess
204      * Callback method that gets invoked when the action completes successfully. Must be implemented by subclasses.
205      * @param {Object} response
206      */
207
208 <span id='Ext-form-action-Action-method-handleResponse'>    /**
209 </span>     * @private
210      * @method handleResponse
211      * Handles the raw response and builds a result object from it. Must be implemented by subclasses.
212      * @param {Object} response
213      */
214
215 <span id='Ext-form-action-Action-method-onFailure'>    /**
216 </span>     * @private
217      * Handles a failure response.
218      * @param {Object} response
219      */
220     onFailure : function(response){
221         this.response = response;
222         this.failureType = Ext.form.action.Action.CONNECT_FAILURE;
223         this.form.afterAction(this, false);
224     },
225
226 <span id='Ext-form-action-Action-method-processResponse'>    /**
227 </span>     * @private
228      * Validates that a response contains either responseText or responseXML and invokes
229      * {@link #handleResponse} to build the result object.
230      * @param {Object} response The raw response object.
231      * @return {Object/Boolean} result The result object as built by handleResponse, or &lt;tt&gt;true&lt;/tt&gt; if
232      *                         the response had empty responseText and responseXML.
233      */
234     processResponse : function(response){
235         this.response = response;
236         if (!response.responseText &amp;&amp; !response.responseXML) {
237             return true;
238         }
239         return (this.result = this.handleResponse(response));
240     },
241
242 <span id='Ext-form-action-Action-method-getUrl'>    /**
243 </span>     * @private
244      * Build the URL for the AJAX request. Used by the standard AJAX submit and load actions.
245      * @return {String} The URL.
246      */
247     getUrl: function() {
248         return this.url || this.form.url;
249     },
250
251 <span id='Ext-form-action-Action-method-getMethod'>    /**
252 </span>     * @private
253      * Determine the HTTP method to be used for the request.
254      * @return {String} The HTTP method
255      */
256     getMethod: function() {
257         return (this.method || this.form.method || 'POST').toUpperCase();
258     },
259
260 <span id='Ext-form-action-Action-method-getParams'>    /**
261 </span>     * @private
262      * Get the set of parameters specified in the BasicForm's baseParams and/or the params option.
263      * Items in params override items of the same name in baseParams.
264      * @return {Object} the full set of parameters
265      */
266     getParams: function() {
267         return Ext.apply({}, this.params, this.form.baseParams);
268     },
269
270 <span id='Ext-form-action-Action-method-createCallback'>    /**
271 </span>     * @private
272      * Creates a callback object.
273      */
274     createCallback: function() {
275         var me = this,
276             undef,
277             form = me.form;
278         return {
279             success: me.onSuccess,
280             failure: me.onFailure,
281             scope: me,
282             timeout: (this.timeout * 1000) || (form.timeout * 1000),
283             upload: form.fileUpload ? me.onSuccess : undef
284         };
285     },
286
287     statics: {
288 <span id='Ext-form-action-Action-static-property-CLIENT_INVALID'>        /**
289 </span>         * @property CLIENT_INVALID
290          * Failure type returned when client side validation of the Form fails
291          * thus aborting a submit action. Client side validation is performed unless
292          * {@link Ext.form.action.Submit#clientValidation} is explicitly set to &lt;tt&gt;false&lt;/tt&gt;.
293          * @type {String}
294          * @static
295          */
296         CLIENT_INVALID: 'client',
297
298 <span id='Ext-form-action-Action-static-property-SERVER_INVALID'>        /**
299 </span>         * @property SERVER_INVALID
300          * &lt;p&gt;Failure type returned when server side processing fails and the {@link #result}'s
301          * &lt;tt&gt;success&lt;/tt&gt; property is set to &lt;tt&gt;false&lt;/tt&gt;.&lt;/p&gt;
302          * &lt;p&gt;In the case of a form submission, field-specific error messages may be returned in the
303          * {@link #result}'s &lt;tt&gt;errors&lt;/tt&gt; property.&lt;/p&gt;
304          * @type {String}
305          * @static
306          */
307         SERVER_INVALID: 'server',
308
309 <span id='Ext-form-action-Action-static-property-CONNECT_FAILURE'>        /**
310 </span>         * @property CONNECT_FAILURE
311          * Failure type returned when a communication error happens when attempting
312          * to send a request to the remote server. The {@link #response} may be examined to
313          * provide further information.
314          * @type {String}
315          * @static
316          */
317         CONNECT_FAILURE: 'connect',
318
319 <span id='Ext-form-action-Action-static-property-LOAD_FAILURE'>        /**
320 </span>         * @property LOAD_FAILURE
321          * Failure type returned when the response's &lt;tt&gt;success&lt;/tt&gt;
322          * property is set to &lt;tt&gt;false&lt;/tt&gt;, or no field values are returned in the response's
323          * &lt;tt&gt;data&lt;/tt&gt; property.
324          * @type {String}
325          * @static
326          */
327         LOAD_FAILURE: 'load'
328
329
330     }
331 });
332 </pre>
333 </body>
334 </html>