docs/source/Basic.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-Basic'>/**
  19 </span> * @class Ext.form.Basic
  20  * @extends Ext.util.Observable
  21  *
  22  * Provides input field management, validation, submission, and form loading services for the collection
  23  * of {@link Ext.form.field.Field Field} instances within a {@link Ext.container.Container}. It is recommended
  24  * that you use a {@link Ext.form.Panel} as the form container, as that has logic to automatically
  25  * hook up an instance of {@link Ext.form.Basic} (plus other conveniences related to field configuration.)
  26  *
  27  * ## Form Actions
  28  *
  29  * The Basic class delegates the handling of form loads and submits to instances of {@link Ext.form.action.Action}.
  30  * See the various Action implementations for specific details of each one's functionality, as well as the
  31  * documentation for {@link #doAction} which details the configuration options that can be specified in
  32  * each action call.
  33  *
  34  * The default submit Action is {@link Ext.form.action.Submit}, which uses an Ajax request to submit the
  35  * form's values to a configured URL. To enable normal browser submission of an Ext form, use the
  36  * {@link #standardSubmit} config option.
  37  *
  38  * ## File uploads
  39  *
  40  * File uploads are not performed using normal 'Ajax' techniques; see the description for
  41  * {@link #hasUpload} for details. If you're using file uploads you should read the method description.
  42  *
  43  * ## Example usage:
  44  *
  45  *     Ext.create('Ext.form.Panel', {
  46  *         title: 'Basic Form',
  47  *         renderTo: Ext.getBody(),
  48  *         bodyPadding: 5,
  49  *         width: 350,
  50  *
  51  *         // Any configuration items here will be automatically passed along to
  52  *         // the Ext.form.Basic instance when it gets created.
  53  *
  54  *         // The form will submit an AJAX request to this URL when submitted
  55  *         url: 'save-form.php',
  56  *
  57  *         items: [{
  58  *             fieldLabel: 'Field',
  59  *             name: 'theField'
  60  *         }],
  61  *
  62  *         buttons: [{
  63  *             text: 'Submit',
  64  *             handler: function() {
  65  *                 // The getForm() method returns the Ext.form.Basic instance:
  66  *                 var form = this.up('form').getForm();
  67  *                 if (form.isValid()) {
  68  *                     // Submit the Ajax request and handle the response
  69  *                     form.submit({
  70  *                         success: function(form, action) {
  71  *                            Ext.Msg.alert('Success', action.result.msg);
  72  *                         },
  73  *                         failure: function(form, action) {
  74  *                             Ext.Msg.alert('Failed', action.result.msg);
  75  *                         }
  76  *                     });
  77  *                 }
  78  *             }
  79  *         }]
  80  *     });
  81  *
  82  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
  83  */
  84 Ext.define('Ext.form.Basic', {
  85     extend: 'Ext.util.Observable',
  86     alternateClassName: 'Ext.form.BasicForm',
  87     requires: ['Ext.util.MixedCollection', 'Ext.form.action.Load', 'Ext.form.action.Submit',
  88                'Ext.window.MessageBox', 'Ext.data.Errors', 'Ext.util.DelayedTask'],
  89
  90 <span id='Ext-form-Basic-method-constructor'>    /**
  91 </span>     * Creates new form.
  92      * @param {Ext.container.Container} owner The component that is the container for the form, usually a {@link Ext.form.Panel}
  93      * @param {Object} config Configuration options. These are normally specified in the config to the
  94      * {@link Ext.form.Panel} constructor, which passes them along to the BasicForm automatically.
  95      */
  96     constructor: function(owner, config) {
  97         var me = this,
  98             onItemAddOrRemove = me.onItemAddOrRemove;
  99
 100 <span id='Ext-form-Basic-property-owner'>        /**
 101 </span>         * @property owner
 102          * @type Ext.container.Container
 103          * The container component to which this BasicForm is attached.
 104          */
 105         me.owner = owner;
 106
 107         // Listen for addition/removal of fields in the owner container
 108         me.mon(owner, {
 109             add: onItemAddOrRemove,
 110             remove: onItemAddOrRemove,
 111             scope: me
 112         });
 113
 114         Ext.apply(me, config);
 115
 116         // Normalize the paramOrder to an Array
 117         if (Ext.isString(me.paramOrder)) {
 118             me.paramOrder = me.paramOrder.split(/[\s,|]/);
 119         }
 120
 121         me.checkValidityTask = Ext.create('Ext.util.DelayedTask', me.checkValidity, me);
 122
 123         me.addEvents(
 124 <span id='Ext-form-Basic-event-beforeaction'>            /**
 125 </span>             * @event beforeaction
 126              * Fires before any action is performed. Return false to cancel the action.
 127              * @param {Ext.form.Basic} this
 128              * @param {Ext.form.action.Action} action The {@link Ext.form.action.Action} to be performed
 129              */
 130             'beforeaction',
 131 <span id='Ext-form-Basic-event-actionfailed'>            /**
 132 </span>             * @event actionfailed
 133              * Fires when an action fails.
 134              * @param {Ext.form.Basic} this
 135              * @param {Ext.form.action.Action} action The {@link Ext.form.action.Action} that failed
 136              */
 137             'actionfailed',
 138 <span id='Ext-form-Basic-event-actioncomplete'>            /**
 139 </span>             * @event actioncomplete
 140              * Fires when an action is completed.
 141              * @param {Ext.form.Basic} this
 142              * @param {Ext.form.action.Action} action The {@link Ext.form.action.Action} that completed
 143              */
 144             'actioncomplete',
 145 <span id='Ext-form-Basic-event-validitychange'>            /**
 146 </span>             * @event validitychange
 147              * Fires when the validity of the entire form changes.
 148              * @param {Ext.form.Basic} this
 149              * @param {Boolean} valid &lt;tt&gt;true&lt;/tt&gt; if the form is now valid, &lt;tt&gt;false&lt;/tt&gt; if it is now invalid.
 150              */
 151             'validitychange',
 152 <span id='Ext-form-Basic-event-dirtychange'>            /**
 153 </span>             * @event dirtychange
 154              * Fires when the dirty state of the entire form changes.
 155              * @param {Ext.form.Basic} this
 156              * @param {Boolean} dirty &lt;tt&gt;true&lt;/tt&gt; if the form is now dirty, &lt;tt&gt;false&lt;/tt&gt; if it is no longer dirty.
 157              */
 158             'dirtychange'
 159         );
 160         me.callParent();
 161     },
 162
 163 <span id='Ext-form-Basic-method-initialize'>    /**
 164 </span>     * Do any post constructor initialization
 165      * @private
 166      */
 167     initialize: function(){
 168         this.initialized = true;
 169         this.onValidityChange(!this.hasInvalidField());
 170     },
 171
 172 <span id='Ext-form-Basic-cfg-method'>    /**
 173 </span>     * @cfg {String} method
 174      * The request method to use (GET or POST) for form actions if one isn't supplied in the action options.
 175      */
 176
 177 <span id='Ext-form-Basic-cfg-reader'>    /**
 178 </span>     * @cfg {Ext.data.reader.Reader} reader
 179      * An Ext.data.DataReader (e.g. {@link Ext.data.reader.Xml}) to be used to read
 180      * data when executing 'load' actions. This is optional as there is built-in
 181      * support for processing JSON responses.
 182      */
 183
 184 <span id='Ext-form-Basic-cfg-errorReader'>    /**
 185 </span>     * @cfg {Ext.data.reader.Reader} errorReader
 186      * &lt;p&gt;An Ext.data.DataReader (e.g. {@link Ext.data.reader.Xml}) to be used to
 187      * read field error messages returned from 'submit' actions. This is optional
 188      * as there is built-in support for processing JSON responses.&lt;/p&gt;
 189      * &lt;p&gt;The Records which provide messages for the invalid Fields must use the
 190      * Field name (or id) as the Record ID, and must contain a field called 'msg'
 191      * which contains the error message.&lt;/p&gt;
 192      * &lt;p&gt;The errorReader does not have to be a full-blown implementation of a
 193      * Reader. It simply needs to implement a &lt;tt&gt;read(xhr)&lt;/tt&gt; function
 194      * which returns an Array of Records in an object with the following
 195      * structure:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;
 196 {
 197     records: recordArray
 198 }
 199 &lt;/code&gt;&lt;/pre&gt;
 200      */
 201
 202 <span id='Ext-form-Basic-cfg-url'>    /**
 203 </span>     * @cfg {String} url
 204      * The URL to use for form actions if one isn't supplied in the
 205      * {@link #doAction doAction} options.
 206      */
 207
 208 <span id='Ext-form-Basic-cfg-baseParams'>    /**
 209 </span>     * @cfg {Object} baseParams
 210      * &lt;p&gt;Parameters to pass with all requests. e.g. baseParams: {id: '123', foo: 'bar'}.&lt;/p&gt;
 211      * &lt;p&gt;Parameters are encoded as standard HTTP parameters using {@link Ext.Object#toQueryString}.&lt;/p&gt;
 212      */
 213
 214 <span id='Ext-form-Basic-cfg-timeout'>    /**
 215 </span>     * @cfg {Number} timeout Timeout for form actions in seconds (default is 30 seconds).
 216      */
 217     timeout: 30,
 218
 219 <span id='Ext-form-Basic-cfg-api'>    /**
 220 </span>     * @cfg {Object} api (Optional) If specified, load and submit actions will be handled
 221      * with {@link Ext.form.action.DirectLoad} and {@link Ext.form.action.DirectLoad}.
 222      * Methods which have been imported by {@link Ext.direct.Manager} can be specified here to load and submit
 223      * forms.
 224      * Such as the following:&lt;pre&gt;&lt;code&gt;
 225 api: {
 226     load: App.ss.MyProfile.load,
 227     submit: App.ss.MyProfile.submit
 228 }
 229 &lt;/code&gt;&lt;/pre&gt;
 230      * &lt;p&gt;Load actions can use &lt;code&gt;{@link #paramOrder}&lt;/code&gt; or &lt;code&gt;{@link #paramsAsHash}&lt;/code&gt;
 231      * to customize how the load method is invoked.
 232      * Submit actions will always use a standard form submit. The &lt;tt&gt;formHandler&lt;/tt&gt; configuration must
 233      * be set on the associated server-side method which has been imported by {@link Ext.direct.Manager}.&lt;/p&gt;
 234      */
 235
 236 <span id='Ext-form-Basic-cfg-paramOrder'>    /**
 237 </span>     * @cfg {String/String[]} paramOrder &lt;p&gt;A list of params to be executed server side.
 238      * Defaults to &lt;tt&gt;undefined&lt;/tt&gt;. Only used for the &lt;code&gt;{@link #api}&lt;/code&gt;
 239      * &lt;code&gt;load&lt;/code&gt; configuration.&lt;/p&gt;
 240      * &lt;p&gt;Specify the params in the order in which they must be executed on the
 241      * server-side as either (1) an Array of String values, or (2) a String of params
 242      * delimited by either whitespace, comma, or pipe. For example,
 243      * any of the following would be acceptable:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;
 244 paramOrder: ['param1','param2','param3']
 245 paramOrder: 'param1 param2 param3'
 246 paramOrder: 'param1,param2,param3'
 247 paramOrder: 'param1|param2|param'
 248      &lt;/code&gt;&lt;/pre&gt;
 249      */
 250
 251 <span id='Ext-form-Basic-cfg-paramsAsHash'>    /**
 252 </span>     * @cfg {Boolean} paramsAsHash
 253      * Only used for the &lt;code&gt;{@link #api}&lt;/code&gt;
 254      * &lt;code&gt;load&lt;/code&gt; configuration. If &lt;tt&gt;true&lt;/tt&gt;, parameters will be sent as a
 255      * single hash collection of named arguments. Providing a
 256      * &lt;tt&gt;{@link #paramOrder}&lt;/tt&gt; nullifies this configuration.
 257      */
 258     paramsAsHash: false,
 259
 260 <span id='Ext-form-Basic-cfg-waitTitle'>    /**
 261 </span>     * @cfg {String} waitTitle
 262      * The default title to show for the waiting message box
 263      */
 264     waitTitle: 'Please Wait...',
 265
 266 <span id='Ext-form-Basic-cfg-trackResetOnLoad'>    /**
 267 </span>     * @cfg {Boolean} trackResetOnLoad
 268      * If set to true, {@link #reset}() resets to the last loaded or {@link #setValues}() data instead of
 269      * when the form was first created.
 270      */
 271     trackResetOnLoad: false,
 272
 273 <span id='Ext-form-Basic-cfg-standardSubmit'>    /**
 274 </span>     * @cfg {Boolean} standardSubmit
 275      * If set to true, a standard HTML form submit is used instead of a XHR (Ajax) style form submission.
 276      * All of the field values, plus any additional params configured via {@link #baseParams}
 277      * and/or the `options` to {@link #submit}, will be included in the values submitted in the form.
 278      */
 279
 280 <span id='Ext-form-Basic-cfg-waitMsgTarget'>    /**
 281 </span>     * @cfg {String/HTMLElement/Ext.Element} waitMsgTarget
 282      * By default wait messages are displayed with Ext.MessageBox.wait. You can target a specific
 283      * element by passing it or its id or mask the form itself by passing in true.
 284      */
 285
 286
 287     // Private
 288     wasDirty: false,
 289
 290
 291 <span id='Ext-form-Basic-method-destroy'>    /**
 292 </span>     * Destroys this object.
 293      */
 294     destroy: function() {
 295         this.clearListeners();
 296         this.checkValidityTask.cancel();
 297     },
 298
 299 <span id='Ext-form-Basic-method-onItemAddOrRemove'>    /**
 300 </span>     * @private
 301      * Handle addition or removal of descendant items. Invalidates the cached list of fields
 302      * so that {@link #getFields} will do a fresh query next time it is called. Also adds listeners
 303      * for state change events on added fields, and tracks components with formBind=true.
 304      */
 305     onItemAddOrRemove: function(parent, child) {
 306         var me = this,
 307             isAdding = !!child.ownerCt,
 308             isContainer = child.isContainer;
 309
 310         function handleField(field) {
 311             // Listen for state change events on fields
 312             me[isAdding ? 'mon' : 'mun'](field, {
 313                 validitychange: me.checkValidity,
 314                 dirtychange: me.checkDirty,
 315                 scope: me,
 316                 buffer: 100 //batch up sequential calls to avoid excessive full-form validation
 317             });
 318             // Flush the cached list of fields
 319             delete me._fields;
 320         }
 321
 322         if (child.isFormField) {
 323             handleField(child);
 324         } else if (isContainer) {
 325             // Walk down
 326             if (child.isDestroyed) {
 327                 // the container is destroyed, this means we may have child fields, so here
 328                 // we just invalidate all the fields to be sure.
 329                 delete me._fields;
 330             } else {
 331                 Ext.Array.forEach(child.query('[isFormField]'), handleField);
 332             }
 333         }
 334
 335         // Flush the cached list of formBind components
 336         delete this._boundItems;
 337
 338         // Check form bind, but only after initial add. Batch it to prevent excessive validation
 339         // calls when many fields are being added at once.
 340         if (me.initialized) {
 341             me.checkValidityTask.delay(10);
 342         }
 343     },
 344
 345 <span id='Ext-form-Basic-method-getFields'>    /**
 346 </span>     * Return all the {@link Ext.form.field.Field} components in the owner container.
 347      * @return {Ext.util.MixedCollection} Collection of the Field objects
 348      */
 349     getFields: function() {
 350         var fields = this._fields;
 351         if (!fields) {
 352             fields = this._fields = Ext.create('Ext.util.MixedCollection');
 353             fields.addAll(this.owner.query('[isFormField]'));
 354         }
 355         return fields;
 356     },
 357
 358 <span id='Ext-form-Basic-method-getBoundItems'>    /**
 359 </span>     * @private
 360      * Finds and returns the set of all items bound to fields inside this form
 361      * @return {Ext.util.MixedCollection} The set of all bound form field items
 362      */
 363     getBoundItems: function() {
 364         var boundItems = this._boundItems;
 365
 366         if (!boundItems || boundItems.getCount() === 0) {
 367             boundItems = this._boundItems = Ext.create('Ext.util.MixedCollection');
 368             boundItems.addAll(this.owner.query('[formBind]'));
 369         }
 370
 371         return boundItems;
 372     },
 373
 374 <span id='Ext-form-Basic-method-hasInvalidField'>    /**
 375 </span>     * Returns true if the form contains any invalid fields. No fields will be marked as invalid
 376      * as a result of calling this; to trigger marking of fields use {@link #isValid} instead.
 377      */
 378     hasInvalidField: function() {
 379         return !!this.getFields().findBy(function(field) {
 380             var preventMark = field.preventMark,
 381                 isValid;
 382             field.preventMark = true;
 383             isValid = field.isValid();
 384             field.preventMark = preventMark;
 385             return !isValid;
 386         });
 387     },
 388
 389 <span id='Ext-form-Basic-method-isValid'>    /**
 390 </span>     * Returns true if client-side validation on the form is successful. Any invalid fields will be
 391      * marked as invalid. If you only want to determine overall form validity without marking anything,
 392      * use {@link #hasInvalidField} instead.
 393      * @return Boolean
 394      */
 395     isValid: function() {
 396         var me = this,
 397             invalid;
 398         me.batchLayouts(function() {
 399             invalid = me.getFields().filterBy(function(field) {
 400                 return !field.validate();
 401             });
 402         });
 403         return invalid.length &lt; 1;
 404     },
 405
 406 <span id='Ext-form-Basic-method-checkValidity'>    /**
 407 </span>     * Check whether the validity of the entire form has changed since it was last checked, and
 408      * if so fire the {@link #validitychange validitychange} event. This is automatically invoked
 409      * when an individual field's validity changes.
 410      */
 411     checkValidity: function() {
 412         var me = this,
 413             valid = !me.hasInvalidField();
 414         if (valid !== me.wasValid) {
 415             me.onValidityChange(valid);
 416             me.fireEvent('validitychange', me, valid);
 417             me.wasValid = valid;
 418         }
 419     },
 420
 421 <span id='Ext-form-Basic-method-onValidityChange'>    /**
 422 </span>     * @private
 423      * Handle changes in the form's validity. If there are any sub components with
 424      * formBind=true then they are enabled/disabled based on the new validity.
 425      * @param {Boolean} valid
 426      */
 427     onValidityChange: function(valid) {
 428         var boundItems = this.getBoundItems();
 429         if (boundItems) {
 430             boundItems.each(function(cmp) {
 431                 if (cmp.disabled === valid) {
 432                     cmp.setDisabled(!valid);
 433                 }
 434             });
 435         }
 436     },
 437
 438 <span id='Ext-form-Basic-method-isDirty'>    /**
 439 </span>     * &lt;p&gt;Returns true if any fields in this form have changed from their original values.&lt;/p&gt;
 440      * &lt;p&gt;Note that if this BasicForm was configured with {@link #trackResetOnLoad} then the
 441      * Fields' &lt;em&gt;original values&lt;/em&gt; are updated when the values are loaded by {@link #setValues}
 442      * or {@link #loadRecord}.&lt;/p&gt;
 443      * @return Boolean
 444      */
 445     isDirty: function() {
 446         return !!this.getFields().findBy(function(f) {
 447             return f.isDirty();
 448         });
 449     },
 450
 451 <span id='Ext-form-Basic-method-checkDirty'>    /**
 452 </span>     * Check whether the dirty state of the entire form has changed since it was last checked, and
 453      * if so fire the {@link #dirtychange dirtychange} event. This is automatically invoked
 454      * when an individual field's dirty state changes.
 455      */
 456     checkDirty: function() {
 457         var dirty = this.isDirty();
 458         if (dirty !== this.wasDirty) {
 459             this.fireEvent('dirtychange', this, dirty);
 460             this.wasDirty = dirty;
 461         }
 462     },
 463
 464 <span id='Ext-form-Basic-method-hasUpload'>    /**
 465 </span>     * &lt;p&gt;Returns true if the form contains a file upload field. This is used to determine the
 466      * method for submitting the form: File uploads are not performed using normal 'Ajax' techniques,
 467      * that is they are &lt;b&gt;not&lt;/b&gt; performed using XMLHttpRequests. Instead a hidden &lt;tt&gt;&amp;lt;form&gt;&lt;/tt&gt;
 468      * element containing all the fields is created temporarily and submitted with its
 469      * &lt;a href=&quot;http://www.w3.org/TR/REC-html40/present/frames.html#adef-target&quot;&gt;target&lt;/a&gt; set to refer
 470      * to a dynamically generated, hidden &lt;tt&gt;&amp;lt;iframe&gt;&lt;/tt&gt; which is inserted into the document
 471      * but removed after the return data has been gathered.&lt;/p&gt;
 472      * &lt;p&gt;The server response is parsed by the browser to create the document for the IFRAME. If the
 473      * server is using JSON to send the return object, then the
 474      * &lt;a href=&quot;http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17&quot;&gt;Content-Type&lt;/a&gt; header
 475      * must be set to &quot;text/html&quot; in order to tell the browser to insert the text unchanged into the document body.&lt;/p&gt;
 476      * &lt;p&gt;Characters which are significant to an HTML parser must be sent as HTML entities, so encode
 477      * &quot;&amp;lt;&quot; as &quot;&amp;amp;lt;&quot;, &quot;&amp;amp;&quot; as &quot;&amp;amp;amp;&quot; etc.&lt;/p&gt;
 478      * &lt;p&gt;The response text is retrieved from the document, and a fake XMLHttpRequest object
 479      * is created containing a &lt;tt&gt;responseText&lt;/tt&gt; property in order to conform to the
 480      * requirements of event handlers and callbacks.&lt;/p&gt;
 481      * &lt;p&gt;Be aware that file upload packets are sent with the content type &lt;a href=&quot;http://www.faqs.org/rfcs/rfc2388.html&quot;&gt;multipart/form&lt;/a&gt;
 482      * and some server technologies (notably JEE) may require some custom processing in order to
 483      * retrieve parameter names and parameter values from the packet content.&lt;/p&gt;
 484      * @return Boolean
 485      */
 486     hasUpload: function() {
 487         return !!this.getFields().findBy(function(f) {
 488             return f.isFileUpload();
 489         });
 490     },
 491
 492 <span id='Ext-form-Basic-method-doAction'>    /**
 493 </span>     * Performs a predefined action (an implementation of {@link Ext.form.action.Action})
 494      * to perform application-specific processing.
 495      * @param {String/Ext.form.action.Action} action The name of the predefined action type,
 496      * or instance of {@link Ext.form.action.Action} to perform.
 497      * @param {Object} options (optional) The options to pass to the {@link Ext.form.action.Action}
 498      * that will get created, if the &lt;tt&gt;action&lt;/tt&gt; argument is a String.
 499      * &lt;p&gt;All of the config options listed below are supported by both the
 500      * {@link Ext.form.action.Submit submit} and {@link Ext.form.action.Load load}
 501      * actions unless otherwise noted (custom actions could also accept
 502      * other config options):&lt;/p&gt;&lt;ul&gt;
 503      *
 504      * &lt;li&gt;&lt;b&gt;url&lt;/b&gt; : String&lt;div class=&quot;sub-desc&quot;&gt;The url for the action (defaults
 505      * to the form's {@link #url}.)&lt;/div&gt;&lt;/li&gt;
 506      *
 507      * &lt;li&gt;&lt;b&gt;method&lt;/b&gt; : String&lt;div class=&quot;sub-desc&quot;&gt;The form method to use (defaults
 508      * to the form's method, or POST if not defined)&lt;/div&gt;&lt;/li&gt;
 509      *
 510      * &lt;li&gt;&lt;b&gt;params&lt;/b&gt; : String/Object&lt;div class=&quot;sub-desc&quot;&gt;&lt;p&gt;The params to pass
 511      * (defaults to the form's baseParams, or none if not defined)&lt;/p&gt;
 512      * &lt;p&gt;Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode Ext.Object.toQueryString}.&lt;/p&gt;&lt;/div&gt;&lt;/li&gt;
 513      *
 514      * &lt;li&gt;&lt;b&gt;headers&lt;/b&gt; : Object&lt;div class=&quot;sub-desc&quot;&gt;Request headers to set for the action.&lt;/div&gt;&lt;/li&gt;
 515      *
 516      * &lt;li&gt;&lt;b&gt;success&lt;/b&gt; : Function&lt;div class=&quot;sub-desc&quot;&gt;The callback that will
 517      * be invoked after a successful response (see top of
 518      * {@link Ext.form.action.Submit submit} and {@link Ext.form.action.Load load}
 519      * for a description of what constitutes a successful response).
 520      * The function is passed the following parameters:&lt;ul&gt;
 521      * &lt;li&gt;&lt;tt&gt;form&lt;/tt&gt; : The {@link Ext.form.Basic} that requested the action.&lt;/li&gt;
 522      * &lt;li&gt;&lt;tt&gt;action&lt;/tt&gt; : The {@link Ext.form.action.Action Action} object which performed the operation.
 523      * &lt;div class=&quot;sub-desc&quot;&gt;The action object contains these properties of interest:&lt;ul&gt;
 524      * &lt;li&gt;&lt;tt&gt;{@link Ext.form.action.Action#response response}&lt;/tt&gt;&lt;/li&gt;
 525      * &lt;li&gt;&lt;tt&gt;{@link Ext.form.action.Action#result result}&lt;/tt&gt; : interrogate for custom postprocessing&lt;/li&gt;
 526      * &lt;li&gt;&lt;tt&gt;{@link Ext.form.action.Action#type type}&lt;/tt&gt;&lt;/li&gt;
 527      * &lt;/ul&gt;&lt;/div&gt;&lt;/li&gt;&lt;/ul&gt;&lt;/div&gt;&lt;/li&gt;
 528      *
 529      * &lt;li&gt;&lt;b&gt;failure&lt;/b&gt; : Function&lt;div class=&quot;sub-desc&quot;&gt;The callback that will be invoked after a
 530      * failed transaction attempt. The function is passed the following parameters:&lt;ul&gt;
 531      * &lt;li&gt;&lt;tt&gt;form&lt;/tt&gt; : The {@link Ext.form.Basic} that requested the action.&lt;/li&gt;
 532      * &lt;li&gt;&lt;tt&gt;action&lt;/tt&gt; : The {@link Ext.form.action.Action Action} object which performed the operation.
 533      * &lt;div class=&quot;sub-desc&quot;&gt;The action object contains these properties of interest:&lt;ul&gt;
 534      * &lt;li&gt;&lt;tt&gt;{@link Ext.form.action.Action#failureType failureType}&lt;/tt&gt;&lt;/li&gt;
 535      * &lt;li&gt;&lt;tt&gt;{@link Ext.form.action.Action#response response}&lt;/tt&gt;&lt;/li&gt;
 536      * &lt;li&gt;&lt;tt&gt;{@link Ext.form.action.Action#result result}&lt;/tt&gt; : interrogate for custom postprocessing&lt;/li&gt;
 537      * &lt;li&gt;&lt;tt&gt;{@link Ext.form.action.Action#type type}&lt;/tt&gt;&lt;/li&gt;
 538      * &lt;/ul&gt;&lt;/div&gt;&lt;/li&gt;&lt;/ul&gt;&lt;/div&gt;&lt;/li&gt;
 539      *
 540      * &lt;li&gt;&lt;b&gt;scope&lt;/b&gt; : Object&lt;div class=&quot;sub-desc&quot;&gt;The scope in which to call the
 541      * callback functions (The &lt;tt&gt;this&lt;/tt&gt; reference for the callback functions).&lt;/div&gt;&lt;/li&gt;
 542      *
 543      * &lt;li&gt;&lt;b&gt;clientValidation&lt;/b&gt; : Boolean&lt;div class=&quot;sub-desc&quot;&gt;Submit Action only.
 544      * Determines whether a Form's fields are validated in a final call to
 545      * {@link Ext.form.Basic#isValid isValid} prior to submission. Set to &lt;tt&gt;false&lt;/tt&gt;
 546      * to prevent this. If undefined, pre-submission field validation is performed.&lt;/div&gt;&lt;/li&gt;&lt;/ul&gt;
 547      *
 548      * @return {Ext.form.Basic} this
 549      */
 550     doAction: function(action, options) {
 551         if (Ext.isString(action)) {
 552             action = Ext.ClassManager.instantiateByAlias('formaction.' + action, Ext.apply({}, options, {form: this}));
 553         }
 554         if (this.fireEvent('beforeaction', this, action) !== false) {
 555             this.beforeAction(action);
 556             Ext.defer(action.run, 100, action);
 557         }
 558         return this;
 559     },
 560
 561 <span id='Ext-form-Basic-method-submit'>    /**
 562 </span>     * Shortcut to {@link #doAction do} a {@link Ext.form.action.Submit submit action}. This will use the
 563      * {@link Ext.form.action.Submit AJAX submit action} by default. If the {@link #standardSubmit} config is
 564      * enabled it will use a standard form element to submit, or if the {@link #api} config is present it will
 565      * use the {@link Ext.form.action.DirectLoad Ext.direct.Direct submit action}.
 566      * @param {Object} options The options to pass to the action (see {@link #doAction} for details).&lt;br&gt;
 567      * &lt;p&gt;The following code:&lt;/p&gt;&lt;pre&gt;&lt;code&gt;
 568 myFormPanel.getForm().submit({
 569     clientValidation: true,
 570     url: 'updateConsignment.php',
 571     params: {
 572         newStatus: 'delivered'
 573     },
 574     success: function(form, action) {
 575        Ext.Msg.alert('Success', action.result.msg);
 576     },
 577     failure: function(form, action) {
 578         switch (action.failureType) {
 579             case Ext.form.action.Action.CLIENT_INVALID:
 580                 Ext.Msg.alert('Failure', 'Form fields may not be submitted with invalid values');
 581                 break;
 582             case Ext.form.action.Action.CONNECT_FAILURE:
 583                 Ext.Msg.alert('Failure', 'Ajax communication failed');
 584                 break;
 585             case Ext.form.action.Action.SERVER_INVALID:
 586                Ext.Msg.alert('Failure', action.result.msg);
 587        }
 588     }
 589 });
 590 &lt;/code&gt;&lt;/pre&gt;
 591      * would process the following server response for a successful submission:&lt;pre&gt;&lt;code&gt;
 592 {
 593     &quot;success&quot;:true, // note this is Boolean, not string
 594     &quot;msg&quot;:&quot;Consignment updated&quot;
 595 }
 596 &lt;/code&gt;&lt;/pre&gt;
 597      * and the following server response for a failed submission:&lt;pre&gt;&lt;code&gt;
 598 {
 599     &quot;success&quot;:false, // note this is Boolean, not string
 600     &quot;msg&quot;:&quot;You do not have permission to perform this operation&quot;
 601 }
 602 &lt;/code&gt;&lt;/pre&gt;
 603      * @return {Ext.form.Basic} this
 604      */
 605     submit: function(options) {
 606         return this.doAction(this.standardSubmit ? 'standardsubmit' : this.api ? 'directsubmit' : 'submit', options);
 607     },
 608
 609 <span id='Ext-form-Basic-method-load'>    /**
 610 </span>     * Shortcut to {@link #doAction do} a {@link Ext.form.action.Load load action}.
 611      * @param {Object} options The options to pass to the action (see {@link #doAction} for details)
 612      * @return {Ext.form.Basic} this
 613      */
 614     load: function(options) {
 615         return this.doAction(this.api ? 'directload' : 'load', options);
 616     },
 617
 618 <span id='Ext-form-Basic-method-updateRecord'>    /**
 619 </span>     * Persists the values in this form into the passed {@link Ext.data.Model} object in a beginEdit/endEdit block.
 620      * @param {Ext.data.Model} record The record to edit
 621      * @return {Ext.form.Basic} this
 622      */
 623     updateRecord: function(record) {
 624         var fields = record.fields,
 625             values = this.getFieldValues(),
 626             name,
 627             obj = {};
 628
 629         fields.each(function(f) {
 630             name = f.name;
 631             if (name in values) {
 632                 obj[name] = values[name];
 633             }
 634         });
 635
 636         record.beginEdit();
 637         record.set(obj);
 638         record.endEdit();
 639
 640         return this;
 641     },
 642
 643 <span id='Ext-form-Basic-method-loadRecord'>    /**
 644 </span>     * Loads an {@link Ext.data.Model} into this form by calling {@link #setValues} with the
 645      * {@link Ext.data.Model#raw record data}.
 646      * See also {@link #trackResetOnLoad}.
 647      * @param {Ext.data.Model} record The record to load
 648      * @return {Ext.form.Basic} this
 649      */
 650     loadRecord: function(record) {
 651         this._record = record;
 652         return this.setValues(record.data);
 653     },
 654
 655 <span id='Ext-form-Basic-method-getRecord'>    /**
 656 </span>     * Returns the last Ext.data.Model instance that was loaded via {@link #loadRecord}
 657      * @return {Ext.data.Model} The record
 658      */
 659     getRecord: function() {
 660         return this._record;
 661     },
 662
 663 <span id='Ext-form-Basic-method-beforeAction'>    /**
 664 </span>     * @private
 665      * Called before an action is performed via {@link #doAction}.
 666      * @param {Ext.form.action.Action} action The Action instance that was invoked
 667      */
 668     beforeAction: function(action) {
 669         var waitMsg = action.waitMsg,
 670             maskCls = Ext.baseCSSPrefix + 'mask-loading',
 671             waitMsgTarget;
 672
 673         // Call HtmlEditor's syncValue before actions
 674         this.getFields().each(function(f) {
 675             if (f.isFormField &amp;&amp; f.syncValue) {
 676                 f.syncValue();
 677             }
 678         });
 679
 680         if (waitMsg) {
 681             waitMsgTarget = this.waitMsgTarget;
 682             if (waitMsgTarget === true) {
 683                 this.owner.el.mask(waitMsg, maskCls);
 684             } else if (waitMsgTarget) {
 685                 waitMsgTarget = this.waitMsgTarget = Ext.get(waitMsgTarget);
 686                 waitMsgTarget.mask(waitMsg, maskCls);
 687             } else {
 688                 Ext.MessageBox.wait(waitMsg, action.waitTitle || this.waitTitle);
 689             }
 690         }
 691     },
 692
 693 <span id='Ext-form-Basic-method-afterAction'>    /**
 694 </span>     * @private
 695      * Called after an action is performed via {@link #doAction}.
 696      * @param {Ext.form.action.Action} action The Action instance that was invoked
 697      * @param {Boolean} success True if the action completed successfully, false, otherwise.
 698      */
 699     afterAction: function(action, success) {
 700         if (action.waitMsg) {
 701             var MessageBox = Ext.MessageBox,
 702                 waitMsgTarget = this.waitMsgTarget;
 703             if (waitMsgTarget === true) {
 704                 this.owner.el.unmask();
 705             } else if (waitMsgTarget) {
 706                 waitMsgTarget.unmask();
 707             } else {
 708                 MessageBox.updateProgress(1);
 709                 MessageBox.hide();
 710             }
 711         }
 712         if (success) {
 713             if (action.reset) {
 714                 this.reset();
 715             }
 716             Ext.callback(action.success, action.scope || action, [this, action]);
 717             this.fireEvent('actioncomplete', this, action);
 718         } else {
 719             Ext.callback(action.failure, action.scope || action, [this, action]);
 720             this.fireEvent('actionfailed', this, action);
 721         }
 722     },
 723
 724
 725 <span id='Ext-form-Basic-method-findField'>    /**
 726 </span>     * Find a specific {@link Ext.form.field.Field} in this form by id or name.
 727      * @param {String} id The value to search for (specify either a {@link Ext.Component#id id} or
 728      * {@link Ext.form.field.Field#getName name or hiddenName}).
 729      * @return Ext.form.field.Field The first matching field, or &lt;tt&gt;null&lt;/tt&gt; if none was found.
 730      */
 731     findField: function(id) {
 732         return this.getFields().findBy(function(f) {
 733             return f.id === id || f.getName() === id;
 734         });
 735     },
 736
 737
 738 <span id='Ext-form-Basic-method-markInvalid'>    /**
 739 </span>     * Mark fields in this form invalid in bulk.
 740      * @param {Object/Object[]/Ext.data.Errors} errors
 741      * Either an array in the form &lt;code&gt;[{id:'fieldId', msg:'The message'}, ...]&lt;/code&gt;,
 742      * an object hash of &lt;code&gt;{id: msg, id2: msg2}&lt;/code&gt;, or a {@link Ext.data.Errors} object.
 743      * @return {Ext.form.Basic} this
 744      */
 745     markInvalid: function(errors) {
 746         var me = this;
 747
 748         function mark(fieldId, msg) {
 749             var field = me.findField(fieldId);
 750             if (field) {
 751                 field.markInvalid(msg);
 752             }
 753         }
 754
 755         if (Ext.isArray(errors)) {
 756             Ext.each(errors, function(err) {
 757                 mark(err.id, err.msg);
 758             });
 759         }
 760         else if (errors instanceof Ext.data.Errors) {
 761             errors.each(function(err) {
 762                 mark(err.field, err.message);
 763             });
 764         }
 765         else {
 766             Ext.iterate(errors, mark);
 767         }
 768         return this;
 769     },
 770
 771 <span id='Ext-form-Basic-method-setValues'>    /**
 772 </span>     * Set values for fields in this form in bulk.
 773      * @param {Object/Object[]} values Either an array in the form:&lt;pre&gt;&lt;code&gt;
 774 [{id:'clientName', value:'Fred. Olsen Lines'},
 775  {id:'portOfLoading', value:'FXT'},
 776  {id:'portOfDischarge', value:'OSL'} ]&lt;/code&gt;&lt;/pre&gt;
 777      * or an object hash of the form:&lt;pre&gt;&lt;code&gt;
 778 {
 779     clientName: 'Fred. Olsen Lines',
 780     portOfLoading: 'FXT',
 781     portOfDischarge: 'OSL'
 782 }&lt;/code&gt;&lt;/pre&gt;
 783      * @return {Ext.form.Basic} this
 784      */
 785     setValues: function(values) {
 786         var me = this;
 787
 788         function setVal(fieldId, val) {
 789             var field = me.findField(fieldId);
 790             if (field) {
 791                 field.setValue(val);
 792                 if (me.trackResetOnLoad) {
 793                     field.resetOriginalValue();
 794                 }
 795             }
 796         }
 797
 798         if (Ext.isArray(values)) {
 799             // array of objects
 800             Ext.each(values, function(val) {
 801                 setVal(val.id, val.value);
 802             });
 803         } else {
 804             // object hash
 805             Ext.iterate(values, setVal);
 806         }
 807         return this;
 808     },
 809
 810 <span id='Ext-form-Basic-method-getValues'>    /**
 811 </span>     * Retrieves the fields in the form as a set of key/value pairs, using their
 812      * {@link Ext.form.field.Field#getSubmitData getSubmitData()} method to collect the values.
 813      * If multiple fields return values under the same name those values will be combined into an Array.
 814      * This is similar to {@link #getFieldValues} except that this method collects only String values for
 815      * submission, while getFieldValues collects type-specific data values (e.g. Date objects for date fields.)
 816      * @param {Boolean} asString (optional) If true, will return the key/value collection as a single
 817      * URL-encoded param string. Defaults to false.
 818      * @param {Boolean} dirtyOnly (optional) If true, only fields that are dirty will be included in the result.
 819      * Defaults to false.
 820      * @param {Boolean} includeEmptyText (optional) If true, the configured emptyText of empty fields will be used.
 821      * Defaults to false.
 822      * @return {String/Object}
 823      */
 824     getValues: function(asString, dirtyOnly, includeEmptyText, useDataValues) {
 825         var values = {};
 826
 827         this.getFields().each(function(field) {
 828             if (!dirtyOnly || field.isDirty()) {
 829                 var data = field[useDataValues ? 'getModelData' : 'getSubmitData'](includeEmptyText);
 830                 if (Ext.isObject(data)) {
 831                     Ext.iterate(data, function(name, val) {
 832                         if (includeEmptyText &amp;&amp; val === '') {
 833                             val = field.emptyText || '';
 834                         }
 835                         if (name in values) {
 836                             var bucket = values[name],
 837                                 isArray = Ext.isArray;
 838                             if (!isArray(bucket)) {
 839                                 bucket = values[name] = [bucket];
 840                             }
 841                             if (isArray(val)) {
 842                                 values[name] = bucket.concat(val);
 843                             } else {
 844                                 bucket.push(val);
 845                             }
 846                         } else {
 847                             values[name] = val;
 848                         }
 849                     });
 850                 }
 851             }
 852         });
 853
 854         if (asString) {
 855             values = Ext.Object.toQueryString(values);
 856         }
 857         return values;
 858     },
 859
 860 <span id='Ext-form-Basic-method-getFieldValues'>    /**
 861 </span>     * Retrieves the fields in the form as a set of key/value pairs, using their
 862      * {@link Ext.form.field.Field#getModelData getModelData()} method to collect the values.
 863      * If multiple fields return values under the same name those values will be combined into an Array.
 864      * This is similar to {@link #getValues} except that this method collects type-specific data values
 865      * (e.g. Date objects for date fields) while getValues returns only String values for submission.
 866      * @param {Boolean} dirtyOnly (optional) If true, only fields that are dirty will be included in the result.
 867      * Defaults to false.
 868      * @return {Object}
 869      */
 870     getFieldValues: function(dirtyOnly) {
 871         return this.getValues(false, dirtyOnly, false, true);
 872     },
 873
 874 <span id='Ext-form-Basic-method-clearInvalid'>    /**
 875 </span>     * Clears all invalid field messages in this form.
 876      * @return {Ext.form.Basic} this
 877      */
 878     clearInvalid: function() {
 879         var me = this;
 880         me.batchLayouts(function() {
 881             me.getFields().each(function(f) {
 882                 f.clearInvalid();
 883             });
 884         });
 885         return me;
 886     },
 887
 888 <span id='Ext-form-Basic-method-reset'>    /**
 889 </span>     * Resets all fields in this form.
 890      * @return {Ext.form.Basic} this
 891      */
 892     reset: function() {
 893         var me = this;
 894         me.batchLayouts(function() {
 895             me.getFields().each(function(f) {
 896                 f.reset();
 897             });
 898         });
 899         return me;
 900     },
 901
 902 <span id='Ext-form-Basic-method-applyToFields'>    /**
 903 </span>     * Calls {@link Ext#apply Ext.apply} for all fields in this form with the passed object.
 904      * @param {Object} obj The object to be applied
 905      * @return {Ext.form.Basic} this
 906      */
 907     applyToFields: function(obj) {
 908         this.getFields().each(function(f) {
 909             Ext.apply(f, obj);
 910         });
 911         return this;
 912     },
 913
 914 <span id='Ext-form-Basic-method-applyIfToFields'>    /**
 915 </span>     * Calls {@link Ext#applyIf Ext.applyIf} for all field in this form with the passed object.
 916      * @param {Object} obj The object to be applied
 917      * @return {Ext.form.Basic} this
 918      */
 919     applyIfToFields: function(obj) {
 920         this.getFields().each(function(f) {
 921             Ext.applyIf(f, obj);
 922         });
 923         return this;
 924     },
 925
 926 <span id='Ext-form-Basic-method-batchLayouts'>    /**
 927 </span>     * @private
 928      * Utility wrapper that suspends layouts of all field parent containers for the duration of a given
 929      * function. Used during full-form validation and resets to prevent huge numbers of layouts.
 930      * @param {Function} fn
 931      */
 932     batchLayouts: function(fn) {
 933         var me = this,
 934             suspended = new Ext.util.HashMap();
 935
 936         // Temporarily suspend layout on each field's immediate owner so we don't get a huge layout cascade
 937         me.getFields().each(function(field) {
 938             var ownerCt = field.ownerCt;
 939             if (!suspended.contains(ownerCt)) {
 940                 suspended.add(ownerCt);
 941                 ownerCt.oldSuspendLayout = ownerCt.suspendLayout;
 942                 ownerCt.suspendLayout = true;
 943             }
 944         });
 945
 946         // Invoke the function
 947         fn();
 948
 949         // Un-suspend the container layouts
 950         suspended.each(function(id, ct) {
 951             ct.suspendLayout = ct.oldSuspendLayout;
 952             delete ct.oldSuspendLayout;
 953         });
 954
 955         // Trigger a single layout
 956         me.owner.doComponentLayout();
 957     }
 958 });
 959 </pre>
 960 </body>
 961 </html>