docs/source/BasicForm.html

   1 <html>\r
   2 <head>\r
   3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />    \r
   4   <title>The source code</title>\r
   5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />\r
   6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>\r
   7 </head>\r
   8 <body  onload="prettyPrint();">\r
   9     <pre class="prettyprint lang-js"><div id="cls-Ext.form.BasicForm"></div>/**
  10  * @class Ext.form.BasicForm
  11  * @extends Ext.util.Observable
  12  * <p>Encapsulates the DOM &lt;form> element at the heart of the {@link Ext.form.FormPanel FormPanel} class, and provides
  13  * input field management, validation, submission, and form loading services.</p>
  14  * <p>By default, Ext Forms are submitted through Ajax, using an instance of {@link Ext.form.Action.Submit}.
  15  * To enable normal browser submission of an Ext Form, use the {@link #standardSubmit} config option.</p>
  16  * <p><b><u>File Uploads</u></b></p>
  17  * <p>{@link #fileUpload File uploads} are not performed using Ajax submission, that
  18  * is they are <b>not</b> performed using XMLHttpRequests. Instead the form is submitted in the standard
  19  * manner with the DOM <tt>&lt;form></tt> element temporarily modified to have its
  20  * <a href="http://www.w3.org/TR/REC-html40/present/frames.html#adef-target">target</a> set to refer
  21  * to a dynamically generated, hidden <tt>&lt;iframe></tt> which is inserted into the document
  22  * but removed after the return data has been gathered.</p>
  23  * <p>The server response is parsed by the browser to create the document for the IFRAME. If the
  24  * server is using JSON to send the return object, then the
  25  * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17">Content-Type</a> header
  26  * must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.</p>
  27  * <p>Characters which are significant to an HTML parser must be sent as HTML entities, so encode
  28  * "&lt;" as "&amp;lt;", "&amp;" as "&amp;amp;" etc.</p>
  29  * <p>The response text is retrieved from the document, and a fake XMLHttpRequest object
  30  * is created containing a <tt>responseText</tt> property in order to conform to the
  31  * requirements of event handlers and callbacks.</p>
  32  * <p>Be aware that file upload packets are sent with the content type <a href="http://www.faqs.org/rfcs/rfc2388.html">multipart/form</a>
  33  * and some server technologies (notably JEE) may require some custom processing in order to
  34  * retrieve parameter names and parameter values from the packet content.</p>
  35  * @constructor
  36  * @param {Mixed} el The form element or its id
  37  * @param {Object} config Configuration options
  38  */
  39 Ext.form.BasicForm = Ext.extend(Ext.util.Observable, {
  40
  41     constructor: function(el, config){
  42         Ext.apply(this, config);
  43         if(Ext.isString(this.paramOrder)){
  44             this.paramOrder = this.paramOrder.split(/[\s,|]/);
  45         }
  46         <div id="prop-Ext.form.BasicForm-items"></div>/**
  47          * A {@link Ext.util.MixedCollection MixedCollection} containing all the Ext.form.Fields in this form.
  48          * @type MixedCollection
  49          * @property items
  50          */
  51         this.items = new Ext.util.MixedCollection(false, function(o){
  52             return o.getItemId();
  53         });
  54         this.addEvents(
  55             <div id="event-Ext.form.BasicForm-beforeaction"></div>/**
  56              * @event beforeaction
  57              * Fires before any action is performed. Return false to cancel the action.
  58              * @param {Form} this
  59              * @param {Action} action The {@link Ext.form.Action} to be performed
  60              */
  61             'beforeaction',
  62             <div id="event-Ext.form.BasicForm-actionfailed"></div>/**
  63              * @event actionfailed
  64              * Fires when an action fails.
  65              * @param {Form} this
  66              * @param {Action} action The {@link Ext.form.Action} that failed
  67              */
  68             'actionfailed',
  69             <div id="event-Ext.form.BasicForm-actioncomplete"></div>/**
  70              * @event actioncomplete
  71              * Fires when an action is completed.
  72              * @param {Form} this
  73              * @param {Action} action The {@link Ext.form.Action} that completed
  74              */
  75             'actioncomplete'
  76         );
  77
  78         if(el){
  79             this.initEl(el);
  80         }
  81         Ext.form.BasicForm.superclass.constructor.call(this);
  82     },
  83
  84     <div id="cfg-Ext.form.BasicForm-method"></div>/**
  85      * @cfg {String} method
  86      * The request method to use (GET or POST) for form actions if one isn't supplied in the action options.
  87      */
  88     <div id="cfg-Ext.form.BasicForm-reader"></div>/**
  89      * @cfg {DataReader} reader
  90      * An Ext.data.DataReader (e.g. {@link Ext.data.XmlReader}) to be used to read
  91      * data when executing 'load' actions. This is optional as there is built-in
  92      * support for processing JSON.  For additional information on using an XMLReader
  93      * see the example provided in examples/form/xml-form.html.
  94      */
  95     <div id="cfg-Ext.form.BasicForm-errorReader"></div>/**
  96      * @cfg {DataReader} errorReader
  97      * <p>An Ext.data.DataReader (e.g. {@link Ext.data.XmlReader}) to be used to
  98      * read field error messages returned from 'submit' actions. This is optional
  99      * as there is built-in support for processing JSON.</p>
 100      * <p>The Records which provide messages for the invalid Fields must use the
 101      * Field name (or id) as the Record ID, and must contain a field called 'msg'
 102      * which contains the error message.</p>
 103      * <p>The errorReader does not have to be a full-blown implementation of a
 104      * DataReader. It simply needs to implement a <tt>read(xhr)</tt> function
 105      * which returns an Array of Records in an object with the following
 106      * structure:</p><pre><code>
 107 {
 108     records: recordArray
 109 }
 110 </code></pre>
 111      */
 112     <div id="cfg-Ext.form.BasicForm-url"></div>/**
 113      * @cfg {String} url
 114      * The URL to use for form actions if one isn't supplied in the
 115      * <code>{@link #doAction doAction} options</code>.
 116      */
 117     <div id="cfg-Ext.form.BasicForm-fileUpload"></div>/**
 118      * @cfg {Boolean} fileUpload
 119      * Set to true if this form is a file upload.
 120      * <p>File uploads are not performed using normal 'Ajax' techniques, that is they are <b>not</b>
 121      * performed using XMLHttpRequests. Instead the form is submitted in the standard manner with the
 122      * DOM <tt>&lt;form></tt> element temporarily modified to have its
 123      * <a href="http://www.w3.org/TR/REC-html40/present/frames.html#adef-target">target</a> set to refer
 124      * to a dynamically generated, hidden <tt>&lt;iframe></tt> which is inserted into the document
 125      * but removed after the return data has been gathered.</p>
 126      * <p>The server response is parsed by the browser to create the document for the IFRAME. If the
 127      * server is using JSON to send the return object, then the
 128      * <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.17">Content-Type</a> header
 129      * must be set to "text/html" in order to tell the browser to insert the text unchanged into the document body.</p>
 130      * <p>Characters which are significant to an HTML parser must be sent as HTML entities, so encode
 131      * "&lt;" as "&amp;lt;", "&amp;" as "&amp;amp;" etc.</p>
 132      * <p>The response text is retrieved from the document, and a fake XMLHttpRequest object
 133      * is created containing a <tt>responseText</tt> property in order to conform to the
 134      * requirements of event handlers and callbacks.</p>
 135      * <p>Be aware that file upload packets are sent with the content type <a href="http://www.faqs.org/rfcs/rfc2388.html">multipart/form</a>
 136      * and some server technologies (notably JEE) may require some custom processing in order to
 137      * retrieve parameter names and parameter values from the packet content.</p>
 138      */
 139     <div id="cfg-Ext.form.BasicForm-baseParams"></div>/**
 140      * @cfg {Object} baseParams
 141      * <p>Parameters to pass with all requests. e.g. baseParams: {id: '123', foo: 'bar'}.</p>
 142      * <p>Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode}.</p>
 143      */
 144     <div id="cfg-Ext.form.BasicForm-timeout"></div>/**
 145      * @cfg {Number} timeout Timeout for form actions in seconds (default is 30 seconds).
 146      */
 147     timeout: 30,
 148
 149     <div id="cfg-Ext.form.BasicForm-api"></div>/**
 150      * @cfg {Object} api (Optional) If specified load and submit actions will be handled
 151      * with {@link Ext.form.Action.DirectLoad} and {@link Ext.form.Action.DirectSubmit}.
 152      * Methods which have been imported by Ext.Direct can be specified here to load and submit
 153      * forms.
 154      * Such as the following:<pre><code>
 155 api: {
 156     load: App.ss.MyProfile.load,
 157     submit: App.ss.MyProfile.submit
 158 }
 159 </code></pre>
 160      * <p>Load actions can use <code>{@link #paramOrder}</code> or <code>{@link #paramsAsHash}</code>
 161      * to customize how the load method is invoked.
 162      * Submit actions will always use a standard form submit. The formHandler configuration must
 163      * be set on the associated server-side method which has been imported by Ext.Direct</p>
 164      */
 165
 166     <div id="cfg-Ext.form.BasicForm-paramOrder"></div>/**
 167      * @cfg {Array/String} paramOrder <p>A list of params to be executed server side.
 168      * Defaults to <tt>undefined</tt>. Only used for the <code>{@link #api}</code>
 169      * <code>load</code> configuration.</p>
 170      * <br><p>Specify the params in the order in which they must be executed on the
 171      * server-side as either (1) an Array of String values, or (2) a String of params
 172      * delimited by either whitespace, comma, or pipe. For example,
 173      * any of the following would be acceptable:</p><pre><code>
 174 paramOrder: ['param1','param2','param3']
 175 paramOrder: 'param1 param2 param3'
 176 paramOrder: 'param1,param2,param3'
 177 paramOrder: 'param1|param2|param'
 178      </code></pre>
 179      */
 180     paramOrder: undefined,
 181
 182     <div id="cfg-Ext.form.BasicForm-paramsAsHash"></div>/**
 183      * @cfg {Boolean} paramsAsHash Only used for the <code>{@link #api}</code>
 184      * <code>load</code> configuration. Send parameters as a collection of named
 185      * arguments (defaults to <tt>false</tt>). Providing a
 186      * <tt>{@link #paramOrder}</tt> nullifies this configuration.
 187      */
 188     paramsAsHash: false,
 189
 190     <div id="cfg-Ext.form.BasicForm-waitTitle"></div>/**
 191      * @cfg {String} waitTitle
 192      * The default title to show for the waiting message box (defaults to <tt>'Please Wait...'</tt>)
 193      */
 194     waitTitle: 'Please Wait...',
 195
 196     // private
 197     activeAction : null,
 198
 199     <div id="cfg-Ext.form.BasicForm-trackResetOnLoad"></div>/**
 200      * @cfg {Boolean} trackResetOnLoad If set to <tt>true</tt>, {@link #reset}() resets to the last loaded
 201      * or {@link #setValues}() data instead of when the form was first created.  Defaults to <tt>false</tt>.
 202      */
 203     trackResetOnLoad : false,
 204
 205     <div id="cfg-Ext.form.BasicForm-standardSubmit"></div>/**
 206      * @cfg {Boolean} standardSubmit
 207      * <p>If set to <tt>true</tt>, standard HTML form submits are used instead
 208      * of XHR (Ajax) style form submissions. Defaults to <tt>false</tt>.</p>
 209      * <br><p><b>Note:</b> When using <code>standardSubmit</code>, the
 210      * <code>options</code> to <code>{@link #submit}</code> are ignored because
 211      * Ext's Ajax infrastracture is bypassed. To pass extra parameters (e.g.
 212      * <code>baseParams</code> and <code>params</code>), utilize hidden fields
 213      * to submit extra data, for example:</p>
 214      * <pre><code>
 215 new Ext.FormPanel({
 216     standardSubmit: true,
 217     baseParams: {
 218         foo: 'bar'
 219     },
 220     {@link url}: 'myProcess.php',
 221     items: [{
 222         xtype: 'textfield',
 223         name: 'userName'
 224     }],
 225     buttons: [{
 226         text: 'Save',
 227         handler: function(){
 228             var fp = this.ownerCt.ownerCt,
 229                 form = fp.getForm();
 230             if (form.isValid()) {
 231                 // check if there are baseParams and if
 232                 // hiddent items have been added already
 233                 if (fp.baseParams && !fp.paramsAdded) {
 234                     // add hidden items for all baseParams
 235                     for (i in fp.baseParams) {
 236                         fp.add({
 237                             xtype: 'hidden',
 238                             name: i,
 239                             value: fp.baseParams[i]
 240                         });
 241                     }
 242                     fp.doLayout();
 243                     // set a custom flag to prevent re-adding
 244                     fp.paramsAdded = true;
 245                 }
 246                 form.{@link #submit}();
 247             }
 248         }
 249     }]
 250 });
 251      * </code></pre>
 252      */
 253     <div id="prop-Ext.form.BasicForm-waitMsgTarget"></div>/**
 254      * By default wait messages are displayed with Ext.MessageBox.wait. You can target a specific
 255      * element by passing it or its id or mask the form itself by passing in true.
 256      * @type Mixed
 257      * @property waitMsgTarget
 258      */
 259
 260     // private
 261     initEl : function(el){
 262         this.el = Ext.get(el);
 263         this.id = this.el.id || Ext.id();
 264         if(!this.standardSubmit){
 265             this.el.on('submit', this.onSubmit, this);
 266         }
 267         this.el.addClass('x-form');
 268     },
 269
 270     <div id="method-Ext.form.BasicForm-getEl"></div>/**
 271      * Get the HTML form Element
 272      * @return Ext.Element
 273      */
 274     getEl: function(){
 275         return this.el;
 276     },
 277
 278     // private
 279     onSubmit : function(e){
 280         e.stopEvent();
 281     },
 282
 283     // private
 284     destroy: function() {
 285         this.items.each(function(f){
 286             Ext.destroy(f);
 287         });
 288         if(this.el){
 289             this.el.removeAllListeners();
 290             this.el.remove();
 291         }
 292         this.purgeListeners();
 293     },
 294
 295     <div id="method-Ext.form.BasicForm-isValid"></div>/**
 296      * Returns true if client-side validation on the form is successful.
 297      * @return Boolean
 298      */
 299     isValid : function(){
 300         var valid = true;
 301         this.items.each(function(f){
 302            if(!f.validate()){
 303                valid = false;
 304            }
 305         });
 306         return valid;
 307     },
 308
 309     <div id="method-Ext.form.BasicForm-isDirty"></div>/**
 310      * <p>Returns true if any fields in this form have changed from their original values.</p>
 311      * <p>Note that if this BasicForm was configured with {@link #trackResetOnLoad} then the
 312      * Fields' <i>original values</i> are updated when the values are loaded by {@link #setValues}
 313      * or {@link #loadRecord}.</p>
 314      * @return Boolean
 315      */
 316     isDirty : function(){
 317         var dirty = false;
 318         this.items.each(function(f){
 319            if(f.isDirty()){
 320                dirty = true;
 321                return false;
 322            }
 323         });
 324         return dirty;
 325     },
 326
 327     <div id="method-Ext.form.BasicForm-doAction"></div>/**
 328      * Performs a predefined action ({@link Ext.form.Action.Submit} or
 329      * {@link Ext.form.Action.Load}) or a custom extension of {@link Ext.form.Action}
 330      * to perform application-specific processing.
 331      * @param {String/Object} actionName The name of the predefined action type,
 332      * or instance of {@link Ext.form.Action} to perform.
 333      * @param {Object} options (optional) The options to pass to the {@link Ext.form.Action}.
 334      * All of the config options listed below are supported by both the
 335      * {@link Ext.form.Action.Submit submit} and {@link Ext.form.Action.Load load}
 336      * actions unless otherwise noted (custom actions could also accept
 337      * other config options):<ul>
 338      *
 339      * <li><b>url</b> : String<div class="sub-desc">The url for the action (defaults
 340      * to the form's {@link #url}.)</div></li>
 341      *
 342      * <li><b>method</b> : String<div class="sub-desc">The form method to use (defaults
 343      * to the form's method, or POST if not defined)</div></li>
 344      *
 345      * <li><b>params</b> : String/Object<div class="sub-desc"><p>The params to pass
 346      * (defaults to the form's baseParams, or none if not defined)</p>
 347      * <p>Parameters are encoded as standard HTTP parameters using {@link Ext#urlEncode}.</p></div></li>
 348      *
 349      * <li><b>headers</b> : Object<div class="sub-desc">Request headers to set for the action
 350      * (defaults to the form's default headers)</div></li>
 351      *
 352      * <li><b>success</b> : Function<div class="sub-desc">The callback that will
 353      * be invoked after a successful response (see top of
 354      * {@link Ext.form.Action.Submit submit} and {@link Ext.form.Action.Load load}
 355      * for a description of what constitutes a successful response).
 356      * The function is passed the following parameters:<ul>
 357      * <li><tt>form</tt> : Ext.form.BasicForm<div class="sub-desc">The form that requested the action</div></li>
 358      * <li><tt>action</tt> : The {@link Ext.form.Action Action} object which performed the operation.
 359      * <div class="sub-desc">The action object contains these properties of interest:<ul>
 360      * <li><tt>{@link Ext.form.Action#response response}</tt></li>
 361      * <li><tt>{@link Ext.form.Action#result result}</tt> : interrogate for custom postprocessing</li>
 362      * <li><tt>{@link Ext.form.Action#type type}</tt></li>
 363      * </ul></div></li></ul></div></li>
 364      *
 365      * <li><b>failure</b> : Function<div class="sub-desc">The callback that will be invoked after a
 366      * failed transaction attempt. The function is passed the following parameters:<ul>
 367      * <li><tt>form</tt> : The {@link Ext.form.BasicForm} that requested the action.</li>
 368      * <li><tt>action</tt> : The {@link Ext.form.Action Action} object which performed the operation.
 369      * <div class="sub-desc">The action object contains these properties of interest:<ul>
 370      * <li><tt>{@link Ext.form.Action#failureType failureType}</tt></li>
 371      * <li><tt>{@link Ext.form.Action#response response}</tt></li>
 372      * <li><tt>{@link Ext.form.Action#result result}</tt> : interrogate for custom postprocessing</li>
 373      * <li><tt>{@link Ext.form.Action#type type}</tt></li>
 374      * </ul></div></li></ul></div></li>
 375      *
 376      * <li><b>scope</b> : Object<div class="sub-desc">The scope in which to call the
 377      * callback functions (The <tt>this</tt> reference for the callback functions).</div></li>
 378      *
 379      * <li><b>clientValidation</b> : Boolean<div class="sub-desc">Submit Action only.
 380      * Determines whether a Form's fields are validated in a final call to
 381      * {@link Ext.form.BasicForm#isValid isValid} prior to submission. Set to <tt>false</tt>
 382      * to prevent this. If undefined, pre-submission field validation is performed.</div></li></ul>
 383      *
 384      * @return {BasicForm} this
 385      */
 386     doAction : function(action, options){
 387         if(Ext.isString(action)){
 388             action = new Ext.form.Action.ACTION_TYPES[action](this, options);
 389         }
 390         if(this.fireEvent('beforeaction', this, action) !== false){
 391             this.beforeAction(action);
 392             action.run.defer(100, action);
 393         }
 394         return this;
 395     },
 396
 397     <div id="method-Ext.form.BasicForm-submit"></div>/**
 398      * Shortcut to {@link #doAction do} a {@link Ext.form.Action.Submit submit action}.
 399      * @param {Object} options The options to pass to the action (see {@link #doAction} for details).<br>
 400      * <p><b>Note:</b> this is ignored when using the {@link #standardSubmit} option.</p>
 401      * <p>The following code:</p><pre><code>
 402 myFormPanel.getForm().submit({
 403     clientValidation: true,
 404     url: 'updateConsignment.php',
 405     params: {
 406         newStatus: 'delivered'
 407     },
 408     success: function(form, action) {
 409        Ext.Msg.alert('Success', action.result.msg);
 410     },
 411     failure: function(form, action) {
 412         switch (action.failureType) {
 413             case Ext.form.Action.CLIENT_INVALID:
 414                 Ext.Msg.alert('Failure', 'Form fields may not be submitted with invalid values');
 415                 break;
 416             case Ext.form.Action.CONNECT_FAILURE:
 417                 Ext.Msg.alert('Failure', 'Ajax communication failed');
 418                 break;
 419             case Ext.form.Action.SERVER_INVALID:
 420                Ext.Msg.alert('Failure', action.result.msg);
 421        }
 422     }
 423 });
 424 </code></pre>
 425      * would process the following server response for a successful submission:<pre><code>
 426 {
 427     "success":true, // note this is Boolean, not string
 428     "msg":"Consignment updated"
 429 }
 430 </code></pre>
 431      * and the following server response for a failed submission:<pre><code>
 432 {
 433     "success":false, // note this is Boolean, not string
 434     "msg":"You do not have permission to perform this operation"
 435 }
 436 </code></pre>
 437      * @return {BasicForm} this
 438      */
 439     submit : function(options){
 440         if(this.standardSubmit){
 441             var v = this.isValid();
 442             if(v){
 443                 var el = this.el.dom;
 444                 if(this.url && Ext.isEmpty(el.action)){
 445                     el.action = this.url;
 446                 }
 447                 el.submit();
 448             }
 449             return v;
 450         }
 451         var submitAction = String.format('{0}submit', this.api ? 'direct' : '');
 452         this.doAction(submitAction, options);
 453         return this;
 454     },
 455
 456     <div id="method-Ext.form.BasicForm-load"></div>/**
 457      * Shortcut to {@link #doAction do} a {@link Ext.form.Action.Load load action}.
 458      * @param {Object} options The options to pass to the action (see {@link #doAction} for details)
 459      * @return {BasicForm} this
 460      */
 461     load : function(options){
 462         var loadAction = String.format('{0}load', this.api ? 'direct' : '');
 463         this.doAction(loadAction, options);
 464         return this;
 465     },
 466
 467     <div id="method-Ext.form.BasicForm-updateRecord"></div>/**
 468      * Persists the values in this form into the passed {@link Ext.data.Record} object in a beginEdit/endEdit block.
 469      * @param {Record} record The record to edit
 470      * @return {BasicForm} this
 471      */
 472     updateRecord : function(record){
 473         record.beginEdit();
 474         var fs = record.fields;
 475         fs.each(function(f){
 476             var field = this.findField(f.name);
 477             if(field){
 478                 record.set(f.name, field.getValue());
 479             }
 480         }, this);
 481         record.endEdit();
 482         return this;
 483     },
 484
 485     <div id="method-Ext.form.BasicForm-loadRecord"></div>/**
 486      * Loads an {@link Ext.data.Record} into this form by calling {@link #setValues} with the
 487      * {@link Ext.data.Record#data record data}.
 488      * See also {@link #trackResetOnLoad}.
 489      * @param {Record} record The record to load
 490      * @return {BasicForm} this
 491      */
 492     loadRecord : function(record){
 493         this.setValues(record.data);
 494         return this;
 495     },
 496
 497     // private
 498     beforeAction : function(action){
 499         var o = action.options;
 500         if(o.waitMsg){
 501             if(this.waitMsgTarget === true){
 502                 this.el.mask(o.waitMsg, 'x-mask-loading');
 503             }else if(this.waitMsgTarget){
 504                 this.waitMsgTarget = Ext.get(this.waitMsgTarget);
 505                 this.waitMsgTarget.mask(o.waitMsg, 'x-mask-loading');
 506             }else{
 507                 Ext.MessageBox.wait(o.waitMsg, o.waitTitle || this.waitTitle);
 508             }
 509         }
 510     },
 511
 512     // private
 513     afterAction : function(action, success){
 514         this.activeAction = null;
 515         var o = action.options;
 516         if(o.waitMsg){
 517             if(this.waitMsgTarget === true){
 518                 this.el.unmask();
 519             }else if(this.waitMsgTarget){
 520                 this.waitMsgTarget.unmask();
 521             }else{
 522                 Ext.MessageBox.updateProgress(1);
 523                 Ext.MessageBox.hide();
 524             }
 525         }
 526         if(success){
 527             if(o.reset){
 528                 this.reset();
 529             }
 530             Ext.callback(o.success, o.scope, [this, action]);
 531             this.fireEvent('actioncomplete', this, action);
 532         }else{
 533             Ext.callback(o.failure, o.scope, [this, action]);
 534             this.fireEvent('actionfailed', this, action);
 535         }
 536     },
 537
 538     <div id="method-Ext.form.BasicForm-findField"></div>/**
 539      * Find a {@link Ext.form.Field} in this form.
 540      * @param {String} id The value to search for (specify either a {@link Ext.Component#id id},
 541      * {@link Ext.grid.Column#dataIndex dataIndex}, {@link Ext.form.Field#getName name or hiddenName}).
 542      * @return Field
 543      */
 544     findField : function(id){
 545         var field = this.items.get(id);
 546         if(!Ext.isObject(field)){
 547             this.items.each(function(f){
 548                 if(f.isFormField && (f.dataIndex == id || f.id == id || f.getName() == id)){
 549                     field = f;
 550                     return false;
 551                 }
 552             });
 553         }
 554         return field || null;
 555     },
 556
 557
 558     <div id="method-Ext.form.BasicForm-markInvalid"></div>/**
 559      * Mark fields in this form invalid in bulk.
 560      * @param {Array/Object} errors Either an array in the form [{id:'fieldId', msg:'The message'},...] or an object hash of {id: msg, id2: msg2}
 561      * @return {BasicForm} this
 562      */
 563     markInvalid : function(errors){
 564         if(Ext.isArray(errors)){
 565             for(var i = 0, len = errors.length; i < len; i++){
 566                 var fieldError = errors[i];
 567                 var f = this.findField(fieldError.id);
 568                 if(f){
 569                     f.markInvalid(fieldError.msg);
 570                 }
 571             }
 572         }else{
 573             var field, id;
 574             for(id in errors){
 575                 if(!Ext.isFunction(errors[id]) && (field = this.findField(id))){
 576                     field.markInvalid(errors[id]);
 577                 }
 578             }
 579         }
 580         return this;
 581     },
 582
 583     <div id="method-Ext.form.BasicForm-setValues"></div>/**
 584      * Set values for fields in this form in bulk.
 585      * @param {Array/Object} values Either an array in the form:<pre><code>
 586 [{id:'clientName', value:'Fred. Olsen Lines'},
 587  {id:'portOfLoading', value:'FXT'},
 588  {id:'portOfDischarge', value:'OSL'} ]</code></pre>
 589      * or an object hash of the form:<pre><code>
 590 {
 591     clientName: 'Fred. Olsen Lines',
 592     portOfLoading: 'FXT',
 593     portOfDischarge: 'OSL'
 594 }</code></pre>
 595      * @return {BasicForm} this
 596      */
 597     setValues : function(values){
 598         if(Ext.isArray(values)){ // array of objects
 599             for(var i = 0, len = values.length; i < len; i++){
 600                 var v = values[i];
 601                 var f = this.findField(v.id);
 602                 if(f){
 603                     f.setValue(v.value);
 604                     if(this.trackResetOnLoad){
 605                         f.originalValue = f.getValue();
 606                     }
 607                 }
 608             }
 609         }else{ // object hash
 610             var field, id;
 611             for(id in values){
 612                 if(!Ext.isFunction(values[id]) && (field = this.findField(id))){
 613                     field.setValue(values[id]);
 614                     if(this.trackResetOnLoad){
 615                         field.originalValue = field.getValue();
 616                     }
 617                 }
 618             }
 619         }
 620         return this;
 621     },
 622
 623     <div id="method-Ext.form.BasicForm-getValues"></div>/**
 624      * <p>Returns the fields in this form as an object with key/value pairs as they would be submitted using a standard form submit.
 625      * If multiple fields exist with the same name they are returned as an array.</p>
 626      * <p><b>Note:</b> The values are collected from all enabled HTML input elements within the form, <u>not</u> from
 627      * the Ext Field objects. This means that all returned values are Strings (or Arrays of Strings) and that the
 628      * value can potentially be the emptyText of a field.</p>
 629      * @param {Boolean} asString (optional) Pass true to return the values as a string. (defaults to false, returning an Object)
 630      * @return {String/Object}
 631      */
 632     getValues : function(asString){
 633         var fs = Ext.lib.Ajax.serializeForm(this.el.dom);
 634         if(asString === true){
 635             return fs;
 636         }
 637         return Ext.urlDecode(fs);
 638     },
 639
 640     <div id="method-Ext.form.BasicForm-getFieldValues"></div>/**
 641      * Retrieves the fields in the form as a set of key/value pairs, using the {@link Ext.form.Field#getValue getValue()} method.
 642      * If multiple fields exist with the same name they are returned as an array.
 643      * @param {Boolean} dirtyOnly (optional) True to return only fields that are dirty.
 644      * @return {Object} The values in the form
 645      */
 646     getFieldValues : function(dirtyOnly){
 647         var o = {},
 648             n,
 649             key,
 650             val;
 651         this.items.each(function(f){
 652             if(dirtyOnly !== true || f.isDirty()){
 653                 n = f.getName();
 654                 key = o[n];
 655                 val = f.getValue();
 656
 657                 if(Ext.isDefined(key)){
 658                     if(Ext.isArray(key)){
 659                         o[n].push(val);
 660                     }else{
 661                         o[n] = [key, val];
 662                     }
 663                 }else{
 664                     o[n] = val;
 665                 }
 666             }
 667         });
 668         return o;
 669     },
 670
 671     <div id="method-Ext.form.BasicForm-clearInvalid"></div>/**
 672      * Clears all invalid messages in this form.
 673      * @return {BasicForm} this
 674      */
 675     clearInvalid : function(){
 676         this.items.each(function(f){
 677            f.clearInvalid();
 678         });
 679         return this;
 680     },
 681
 682     <div id="method-Ext.form.BasicForm-reset"></div>/**
 683      * Resets this form.
 684      * @return {BasicForm} this
 685      */
 686     reset : function(){
 687         this.items.each(function(f){
 688             f.reset();
 689         });
 690         return this;
 691     },
 692
 693     <div id="method-Ext.form.BasicForm-add"></div>/**
 694      * Add Ext.form Components to this form's Collection. This does not result in rendering of
 695      * the passed Component, it just enables the form to validate Fields, and distribute values to
 696      * Fields.
 697      * <p><b>You will not usually call this function. In order to be rendered, a Field must be added
 698      * to a {@link Ext.Container Container}, usually an {@link Ext.form.FormPanel FormPanel}.
 699      * The FormPanel to which the field is added takes care of adding the Field to the BasicForm's
 700      * collection.</b></p>
 701      * @param {Field} field1
 702      * @param {Field} field2 (optional)
 703      * @param {Field} etc (optional)
 704      * @return {BasicForm} this
 705      */
 706     add : function(){
 707         this.items.addAll(Array.prototype.slice.call(arguments, 0));
 708         return this;
 709     },
 710
 711
 712     <div id="method-Ext.form.BasicForm-remove"></div>/**
 713      * Removes a field from the items collection (does NOT remove its markup).
 714      * @param {Field} field
 715      * @return {BasicForm} this
 716      */
 717     remove : function(field){
 718         this.items.remove(field);
 719         return this;
 720     },
 721
 722     <div id="method-Ext.form.BasicForm-render"></div>/**
 723      * Iterates through the {@link Ext.form.Field Field}s which have been {@link #add add}ed to this BasicForm,
 724      * checks them for an id attribute, and calls {@link Ext.form.Field#applyToMarkup} on the existing dom element with that id.
 725      * @return {BasicForm} this
 726      */
 727     render : function(){
 728         this.items.each(function(f){
 729             if(f.isFormField && !f.rendered && document.getElementById(f.id)){ // if the element exists
 730                 f.applyToMarkup(f.id);
 731             }
 732         });
 733         return this;
 734     },
 735
 736     <div id="method-Ext.form.BasicForm-applyToFields"></div>/**
 737      * Calls {@link Ext#apply} for all fields in this form with the passed object.
 738      * @param {Object} values
 739      * @return {BasicForm} this
 740      */
 741     applyToFields : function(o){
 742         this.items.each(function(f){
 743            Ext.apply(f, o);
 744         });
 745         return this;
 746     },
 747
 748     <div id="method-Ext.form.BasicForm-applyIfToFields"></div>/**
 749      * Calls {@link Ext#applyIf} for all field in this form with the passed object.
 750      * @param {Object} values
 751      * @return {BasicForm} this
 752      */
 753     applyIfToFields : function(o){
 754         this.items.each(function(f){
 755            Ext.applyIf(f, o);
 756         });
 757         return this;
 758     },
 759
 760     callFieldMethod : function(fnName, args){
 761         args = args || [];
 762         this.items.each(function(f){
 763             if(Ext.isFunction(f[fnName])){
 764                 f[fnName].apply(f, args);
 765             }
 766         });
 767         return this;
 768     }
 769 });
 770
 771 // back compat
 772 Ext.BasicForm = Ext.form.BasicForm;</pre>    \r
 773 </body>\r
 774 </html>