3 This file is part of Ext JS 4
5 Copyright (c) 2011 Sencha Inc
7 Contact: http://www.sencha.com/contact
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.
12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
16 * @class Ext.form.action.Action
18 * <p>The subclasses of this class provide actions to perform upon {@link Ext.form.Basic Form}s.</p>
19 * <p>Instances of this class are only created by a {@link Ext.form.Basic Form} when
20 * the Form needs to perform an action such as submit or load. The Configuration options
21 * listed for this class are set through the Form's action methods: {@link Ext.form.Basic#submit submit},
22 * {@link Ext.form.Basic#load load} and {@link Ext.form.Basic#doAction doAction}</p>
23 * <p>The instance of Action which performed the action is passed to the success
24 * and failure callbacks of 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}),
26 * and to the {@link Ext.form.Basic#actioncomplete actioncomplete} and
27 * {@link Ext.form.Basic#actionfailed actionfailed} event handlers.</p>
29 Ext.define('Ext.form.action.Action', {
30 alternateClassName: 'Ext.form.Action',
33 * @cfg {Ext.form.Basic} form The {@link Ext.form.Basic BasicForm} instance that
34 * is invoking this Action. Required.
38 * @cfg {String} url The URL that the Action is to invoke. Will default to the {@link Ext.form.Basic#url url}
39 * configured on the {@link #form}.
43 * @cfg {Boolean} reset When set to <tt><b>true</b></tt>, causes the Form to be
44 * {@link Ext.form.Basic#reset reset} on Action success. If specified, this happens
45 * before the {@link #success} callback is called and before the Form's
46 * {@link Ext.form.Basic#actioncomplete actioncomplete} event fires.
50 * @cfg {String} method The HTTP method to use to access the requested URL. Defaults to the
51 * {@link Ext.form.Basic#method BasicForm's method}, or 'POST' if not specified.
55 * @cfg {Object/String} params <p>Extra parameter values to pass. These are added to the Form's
56 * {@link Ext.form.Basic#baseParams} and passed to the specified URL along with the Form's
58 * <p>Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode Ext.Object.toQueryString}.</p>
62 * @cfg {Object} headers <p>Extra headers to be sent in the AJAX request for submit and load actions. See
63 * {@link Ext.data.proxy.Ajax#headers}.</p>
67 * @cfg {Number} timeout The number of seconds to wait for a server response before
68 * failing with the {@link #failureType} as {@link Ext.form.action.Action#CONNECT_FAILURE}. If not specified,
69 * defaults to the configured <tt>{@link Ext.form.Basic#timeout timeout}</tt> of the
74 * @cfg {Function} success The function to call when a valid success return packet is received.
75 * The function is passed the following parameters:<ul class="mdetail-params">
76 * <li><b>form</b> : Ext.form.Basic<div class="sub-desc">The form that requested the action</div></li>
77 * <li><b>action</b> : Ext.form.action.Action<div class="sub-desc">The Action class. The {@link #result}
78 * property of this object may be examined to perform custom postprocessing.</div></li>
83 * @cfg {Function} failure The function to call when a failure packet was received, or when an
84 * error ocurred in the Ajax communication.
85 * The function is passed the following parameters:<ul class="mdetail-params">
86 * <li><b>form</b> : Ext.form.Basic<div class="sub-desc">The form that requested the action</div></li>
87 * <li><b>action</b> : Ext.form.action.Action<div class="sub-desc">The Action class. If an Ajax
88 * error ocurred, the failure type will be in {@link #failureType}. The {@link #result}
89 * property of this object may be examined to perform custom postprocessing.</div></li>
94 * @cfg {Object} scope The scope in which to call the configured <tt>success</tt> and <tt>failure</tt>
95 * callback functions (the <tt>this</tt> reference for the callback functions).
99 * @cfg {String} waitMsg The message to be displayed by a call to {@link Ext.window.MessageBox#wait}
100 * during the time the action is being processed.
104 * @cfg {String} waitTitle The title to be displayed by a call to {@link Ext.window.MessageBox#wait}
105 * during the time the action is being processed.
109 * @cfg {Boolean} submitEmptyText If set to <tt>true</tt>, the emptyText value will be sent with the form
110 * when it is submitted. Defaults to <tt>true</tt>.
112 submitEmptyText : true,
115 * The type of action this Action instance performs.
116 * Currently only "submit" and "load" are supported.
121 * The type of failure detected will be one of these: {@link Ext.form.action.Action#CLIENT_INVALID},
122 * {@link Ext.form.action.Action#SERVER_INVALID}, {@link Ext.form.action.Action#CONNECT_FAILURE}, or
123 * {@link Ext.form.action.Action#LOAD_FAILURE}. Usage:
125 var fp = new Ext.form.Panel({
131 if(fp.getForm().isValid()){
132 fp.getForm().submit({
133 url: 'form-submit.php',
134 waitMsg: 'Submitting your data...',
135 success: function(form, action){
136 // server responded with success = true
137 var result = action.{@link #result};
139 failure: function(form, action){
140 if (action.{@link #failureType} === {@link Ext.form.action.Action#CONNECT_FAILURE}) {
141 Ext.Msg.alert('Error',
142 'Status:'+action.{@link #response}.status+': '+
143 action.{@link #response}.statusText);
145 if (action.failureType === {@link Ext.form.action.Action#SERVER_INVALID}){
146 // server responded with success = false
147 Ext.Msg.alert('Invalid', action.{@link #result}.errormsg);
156 fp.getForm().reset();
160 * @property failureType
165 * The raw XMLHttpRequest object used to perform the action.
171 * The decoded response object containing a boolean <tt>success</tt> property and
172 * other, action-specific properties.
178 * Creates new Action.
179 * @param {Object} config (optional) Config object.
181 constructor: function(config) {
183 Ext.apply(this, config);
186 // Normalize the params option to an Object
187 var params = config.params;
188 if (Ext.isString(params)) {
189 this.params = Ext.Object.fromQueryString(params);
194 * Invokes this action using the current configuration.
201 * Callback method that gets invoked when the action completes successfully. Must be implemented by subclasses.
202 * @param {Object} response
207 * @method handleResponse
208 * Handles the raw response and builds a result object from it. Must be implemented by subclasses.
209 * @param {Object} response
214 * Handles a failure response.
215 * @param {Object} response
217 onFailure : function(response){
218 this.response = response;
219 this.failureType = Ext.form.action.Action.CONNECT_FAILURE;
220 this.form.afterAction(this, false);
225 * Validates that a response contains either responseText or responseXML and invokes
226 * {@link #handleResponse} to build the result object.
227 * @param {Object} response The raw response object.
228 * @return {Object/Boolean} result The result object as built by handleResponse, or <tt>true</tt> if
229 * the response had empty responseText and responseXML.
231 processResponse : function(response){
232 this.response = response;
233 if (!response.responseText && !response.responseXML) {
236 return (this.result = this.handleResponse(response));
241 * Build the URL for the AJAX request. Used by the standard AJAX submit and load actions.
242 * @return {String} The URL.
245 return this.url || this.form.url;
250 * Determine the HTTP method to be used for the request.
251 * @return {String} The HTTP method
253 getMethod: function() {
254 return (this.method || this.form.method || 'POST').toUpperCase();
259 * Get the set of parameters specified in the BasicForm's baseParams and/or the params option.
260 * Items in params override items of the same name in baseParams.
261 * @return {Object} the full set of parameters
263 getParams: function() {
264 return Ext.apply({}, this.params, this.form.baseParams);
269 * Creates a callback object.
271 createCallback: function() {
276 success: me.onSuccess,
277 failure: me.onFailure,
279 timeout: (this.timeout * 1000) || (form.timeout * 1000),
280 upload: form.fileUpload ? me.onSuccess : undef
286 * @property CLIENT_INVALID
287 * Failure type returned when client side validation of the Form fails
288 * thus aborting a submit action. Client side validation is performed unless
289 * {@link Ext.form.action.Submit#clientValidation} is explicitly set to <tt>false</tt>.
293 CLIENT_INVALID: 'client',
296 * @property SERVER_INVALID
297 * <p>Failure type returned when server side processing fails and the {@link #result}'s
298 * <tt>success</tt> property is set to <tt>false</tt>.</p>
299 * <p>In the case of a form submission, field-specific error messages may be returned in the
300 * {@link #result}'s <tt>errors</tt> property.</p>
304 SERVER_INVALID: 'server',
307 * @property CONNECT_FAILURE
308 * Failure type returned when a communication error happens when attempting
309 * to send a request to the remote server. The {@link #response} may be examined to
310 * provide further information.
314 CONNECT_FAILURE: 'connect',
317 * @property LOAD_FAILURE
318 * Failure type returned when the response's <tt>success</tt>
319 * property is set to <tt>false</tt>, or no field values are returned in the response's
320 * <tt>data</tt> property.