docs/source/Basic.html

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