src/form/action/Action.js

   1 /*
   2
   3 This file is part of Ext JS 4
   4
   5 Copyright (c) 2011 Sencha Inc
   6
   7 Contact:  http://www.sencha.com/contact
   8
   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.
  11
  12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
  13
  14 */
  15 /**
  16  * @class Ext.form.action.Action
  17  * @extends Ext.Base
  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>
  28  */
  29 Ext.define('Ext.form.action.Action', {
  30     alternateClassName: 'Ext.form.Action',
  31
  32     /**
  33      * @cfg {Ext.form.Basic} form The {@link Ext.form.Basic BasicForm} instance that
  34      * is invoking this Action. Required.
  35      */
  36
  37     /**
  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}.
  40      */
  41
  42     /**
  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.
  47      */
  48
  49     /**
  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.
  52      */
  53
  54     /**
  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
  57      * input fields.</p>
  58      * <p>Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode Ext.Object.toQueryString}.</p>
  59      */
  60
  61     /**
  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>
  64      */
  65
  66     /**
  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
  70      * {@link #form}.
  71      */
  72
  73     /**
  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>
  79      * </ul>
  80      */
  81
  82     /**
  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>
  90      * </ul>
  91      */
  92
  93     /**
  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).
  96      */
  97
  98     /**
  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.
 101      */
 102
 103     /**
 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.
 106      */
 107
 108     /**
 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>.
 111      */
 112     submitEmptyText : true,
 113     /**
 114      * @property type
 115      * The type of action this Action instance performs.
 116      * Currently only "submit" and "load" are supported.
 117      * @type {String}
 118      */
 119
 120     /**
 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:
 124      * <pre><code>
 125 var fp = new Ext.form.Panel({
 126 ...
 127 buttons: [{
 128     text: 'Save',
 129     formBind: true,
 130     handler: function(){
 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};
 138                 },
 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);
 144                     }
 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);
 148                     }
 149                 }
 150             });
 151         }
 152     }
 153 },{
 154     text: 'Reset',
 155     handler: function(){
 156         fp.getForm().reset();
 157     }
 158 }]
 159      * </code></pre>
 160      * @property failureType
 161      * @type {String}
 162      */
 163
 164     /**
 165      * The raw XMLHttpRequest object used to perform the action.
 166      * @property response
 167      * @type {Object}
 168      */
 169
 170     /**
 171      * The decoded response object containing a boolean <tt>success</tt> property and
 172      * other, action-specific properties.
 173      * @property result
 174      * @type {Object}
 175      */
 176
 177     /**
 178      * Creates new Action.
 179      * @param {Object} config (optional) Config object.
 180      */
 181     constructor: function(config) {
 182         if (config) {
 183             Ext.apply(this, config);
 184         }
 185
 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);
 190         }
 191     },
 192
 193     /**
 194      * Invokes this action using the current configuration.
 195      */
 196     run: Ext.emptyFn,
 197
 198     /**
 199      * @private
 200      * @method onSuccess
 201      * Callback method that gets invoked when the action completes successfully. Must be implemented by subclasses.
 202      * @param {Object} response
 203      */
 204
 205     /**
 206      * @private
 207      * @method handleResponse
 208      * Handles the raw response and builds a result object from it. Must be implemented by subclasses.
 209      * @param {Object} response
 210      */
 211
 212     /**
 213      * @private
 214      * Handles a failure response.
 215      * @param {Object} response
 216      */
 217     onFailure : function(response){
 218         this.response = response;
 219         this.failureType = Ext.form.action.Action.CONNECT_FAILURE;
 220         this.form.afterAction(this, false);
 221     },
 222
 223     /**
 224      * @private
 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.
 230      */
 231     processResponse : function(response){
 232         this.response = response;
 233         if (!response.responseText && !response.responseXML) {
 234             return true;
 235         }
 236         return (this.result = this.handleResponse(response));
 237     },
 238
 239     /**
 240      * @private
 241      * Build the URL for the AJAX request. Used by the standard AJAX submit and load actions.
 242      * @return {String} The URL.
 243      */
 244     getUrl: function() {
 245         return this.url || this.form.url;
 246     },
 247
 248     /**
 249      * @private
 250      * Determine the HTTP method to be used for the request.
 251      * @return {String} The HTTP method
 252      */
 253     getMethod: function() {
 254         return (this.method || this.form.method || 'POST').toUpperCase();
 255     },
 256
 257     /**
 258      * @private
 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
 262      */
 263     getParams: function() {
 264         return Ext.apply({}, this.params, this.form.baseParams);
 265     },
 266
 267     /**
 268      * @private
 269      * Creates a callback object.
 270      */
 271     createCallback: function() {
 272         var me = this,
 273             undef,
 274             form = me.form;
 275         return {
 276             success: me.onSuccess,
 277             failure: me.onFailure,
 278             scope: me,
 279             timeout: (this.timeout * 1000) || (form.timeout * 1000),
 280             upload: form.fileUpload ? me.onSuccess : undef
 281         };
 282     },
 283
 284     statics: {
 285         /**
 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>.
 290          * @type {String}
 291          * @static
 292          */
 293         CLIENT_INVALID: 'client',
 294
 295         /**
 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>
 301          * @type {String}
 302          * @static
 303          */
 304         SERVER_INVALID: 'server',
 305
 306         /**
 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.
 311          * @type {String}
 312          * @static
 313          */
 314         CONNECT_FAILURE: 'connect',
 315
 316         /**
 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.
 321          * @type {String}
 322          * @static
 323          */
 324         LOAD_FAILURE: 'load'
 325
 326
 327     }
 328 });
 329