src/form/action/Action.js

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