docs/source/Form.html

   1 <html>
   2 <head>
   3   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   4   <title>The source code</title>
   5     <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
   6     <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
   7 </head>
   8 <body  onload="prettyPrint();">
   9     <pre class="prettyprint lang-js">/*!
  10  * Ext JS Library 3.3.1
  11  * Copyright(c) 2006-2010 Sencha Inc.
  12  * licensing@sencha.com
  13  * http://www.sencha.com/license
  14  */
  15 <div id="cls-Ext.form.FormPanel"></div>/**
  16  * @class Ext.form.FormPanel
  17  * @extends Ext.Panel
  18  * <p>Standard form container.</p>
  19  *
  20  * <p><b><u>Layout</u></b></p>
  21  * <p>By default, FormPanel is configured with <tt>layout:'form'</tt> to use an {@link Ext.layout.FormLayout}
  22  * layout manager, which styles and renders fields and labels correctly. When nesting additional Containers
  23  * within a FormPanel, you should ensure that any descendant Containers which host input Fields use the
  24  * {@link Ext.layout.FormLayout} layout manager.</p>
  25  *
  26  * <p><b><u>BasicForm</u></b></p>
  27  * <p>Although <b>not listed</b> as configuration options of FormPanel, the FormPanel class accepts all
  28  * of the config options required to configure its internal {@link Ext.form.BasicForm} for:
  29  * <div class="mdetail-params"><ul>
  30  * <li>{@link Ext.form.BasicForm#fileUpload file uploads}</li>
  31  * <li>functionality for {@link Ext.form.BasicForm#doAction loading, validating and submitting} the form</li>
  32  * </ul></div>
  33  *
  34  * <p><b>Note</b>: If subclassing FormPanel, any configuration options for the BasicForm must be applied to
  35  * the <tt><b>initialConfig</b></tt> property of the FormPanel. Applying {@link Ext.form.BasicForm BasicForm}
  36  * configuration settings to <b><tt>this</tt></b> will <b>not</b> affect the BasicForm's configuration.</p>
  37  *
  38  * <p><b><u>Form Validation</u></b></p>
  39  * <p>For information on form validation see the following:</p>
  40  * <div class="mdetail-params"><ul>
  41  * <li>{@link Ext.form.TextField}</li>
  42  * <li>{@link Ext.form.VTypes}</li>
  43  * <li>{@link Ext.form.BasicForm#doAction BasicForm.doAction <b>clientValidation</b> notes}</li>
  44  * <li><tt>{@link Ext.form.FormPanel#monitorValid monitorValid}</tt></li>
  45  * </ul></div>
  46  *
  47  * <p><b><u>Form Submission</u></b></p>
  48  * <p>By default, Ext Forms are submitted through Ajax, using {@link Ext.form.Action}. To enable normal browser
  49  * submission of the {@link Ext.form.BasicForm BasicForm} contained in this FormPanel, see the
  50  * <tt><b>{@link Ext.form.BasicForm#standardSubmit standardSubmit}</b></tt> option.</p>
  51  *
  52  * @constructor
  53  * @param {Object} config Configuration options
  54  * @xtype form
  55  */
  56 Ext.FormPanel = Ext.extend(Ext.Panel, {
  57     <div id="cfg-Ext.form.FormPanel-formId"></div>/**
  58      * @cfg {String} formId (optional) The id of the FORM tag (defaults to an auto-generated id).
  59      */
  60     <div id="cfg-Ext.form.FormPanel-hideLabels"></div>/**
  61      * @cfg {Boolean} hideLabels
  62      * <p><tt>true</tt> to hide field labels by default (sets <tt>display:none</tt>). Defaults to
  63      * <tt>false</tt>.</p>
  64      * <p>Also see {@link Ext.Component}.<tt>{@link Ext.Component#hideLabel hideLabel}</tt>.
  65      */
  66     <div id="cfg-Ext.form.FormPanel-labelPad"></div>/**
  67      * @cfg {Number} labelPad
  68      * The default padding in pixels for field labels (defaults to <tt>5</tt>). <tt>labelPad</tt> only
  69      * applies if <tt>{@link #labelWidth}</tt> is also specified, otherwise it will be ignored.
  70      */
  71     <div id="cfg-Ext.form.FormPanel-labelSeparator"></div>/**
  72      * @cfg {String} labelSeparator
  73      * See {@link Ext.Component}.<tt>{@link Ext.Component#labelSeparator labelSeparator}</tt>
  74      */
  75     <div id="cfg-Ext.form.FormPanel-labelWidth"></div>/**
  76      * @cfg {Number} labelWidth The width of labels in pixels. This property cascades to child containers
  77      * and can be overridden on any child container (e.g., a fieldset can specify a different <tt>labelWidth</tt>
  78      * for its fields) (defaults to <tt>100</tt>).
  79      */
  80     <div id="cfg-Ext.form.FormPanel-itemCls"></div>/**
  81      * @cfg {String} itemCls A css class to apply to the x-form-item of fields. This property cascades to child containers.
  82      */
  83     <div id="cfg-Ext.form.FormPanel-buttons"></div>/**
  84      * @cfg {Array} buttons
  85      * An array of {@link Ext.Button}s or {@link Ext.Button} configs used to add buttons to the footer of this FormPanel.<br>
  86      * <p>Buttons in the footer of a FormPanel may be configured with the option <tt>formBind: true</tt>. This causes
  87      * the form's {@link #monitorValid valid state monitor task} to enable/disable those Buttons depending on
  88      * the form's valid/invalid state.</p>
  89      */
  90
  91
  92     <div id="cfg-Ext.form.FormPanel-minButtonWidth"></div>/**
  93      * @cfg {Number} minButtonWidth Minimum width of all buttons in pixels (defaults to <tt>75</tt>).
  94      */
  95     minButtonWidth : 75,
  96
  97     <div id="cfg-Ext.form.FormPanel-labelAlign"></div>/**
  98      * @cfg {String} labelAlign The label alignment value used for the <tt>text-align</tt> specification
  99      * for the <b>container</b>. Valid values are <tt>"left</tt>", <tt>"top"</tt> or <tt>"right"</tt>
 100      * (defaults to <tt>"left"</tt>). This property cascades to child <b>containers</b> and can be
 101      * overridden on any child <b>container</b> (e.g., a fieldset can specify a different <tt>labelAlign</tt>
 102      * for its fields).
 103      */
 104     labelAlign : 'left',
 105
 106     <div id="cfg-Ext.form.FormPanel-monitorValid"></div>/**
 107      * @cfg {Boolean} monitorValid If <tt>true</tt>, the form monitors its valid state <b>client-side</b> and
 108      * regularly fires the {@link #clientvalidation} event passing that state.<br>
 109      * <p>When monitoring valid state, the FormPanel enables/disables any of its configured
 110      * {@link #buttons} which have been configured with <code>formBind: true</code> depending
 111      * on whether the {@link Ext.form.BasicForm#isValid form is valid} or not. Defaults to <tt>false</tt></p>
 112      */
 113     monitorValid : false,
 114
 115     <div id="cfg-Ext.form.FormPanel-monitorPoll"></div>/**
 116      * @cfg {Number} monitorPoll The milliseconds to poll valid state, ignored if monitorValid is not true (defaults to 200)
 117      */
 118     monitorPoll : 200,
 119
 120     <div id="cfg-Ext.form.FormPanel-layout"></div>/**
 121      * @cfg {String} layout Defaults to <tt>'form'</tt>.  Normally this configuration property should not be altered.
 122      * For additional details see {@link Ext.layout.FormLayout} and {@link Ext.Container#layout Ext.Container.layout}.
 123      */
 124     layout : 'form',
 125
 126     // private
 127     initComponent : function(){
 128         this.form = this.createForm();
 129         Ext.FormPanel.superclass.initComponent.call(this);
 130
 131         this.bodyCfg = {
 132             tag: 'form',
 133             cls: this.baseCls + '-body',
 134             method : this.method || 'POST',
 135             id : this.formId || Ext.id()
 136         };
 137         if(this.fileUpload) {
 138             this.bodyCfg.enctype = 'multipart/form-data';
 139         }
 140         this.initItems();
 141
 142         this.addEvents(
 143             <div id="event-Ext.form.FormPanel-clientvalidation"></div>/**
 144              * @event clientvalidation
 145              * If the monitorValid config option is true, this event fires repetitively to notify of valid state
 146              * @param {Ext.form.FormPanel} this
 147              * @param {Boolean} valid true if the form has passed client-side validation
 148              */
 149             'clientvalidation'
 150         );
 151
 152         this.relayEvents(this.form, ['beforeaction', 'actionfailed', 'actioncomplete']);
 153     },
 154
 155     // private
 156     createForm : function(){
 157         var config = Ext.applyIf({listeners: {}}, this.initialConfig);
 158         return new Ext.form.BasicForm(null, config);
 159     },
 160
 161     // private
 162     initFields : function(){
 163         var f = this.form;
 164         var formPanel = this;
 165         var fn = function(c){
 166             if(formPanel.isField(c)){
 167                 f.add(c);
 168             }else if(c.findBy && c != formPanel){
 169                 formPanel.applySettings(c);
 170                 //each check required for check/radio groups.
 171                 if(c.items && c.items.each){
 172                     c.items.each(fn, this);
 173                 }
 174             }
 175         };
 176         this.items.each(fn, this);
 177     },
 178
 179     // private
 180     applySettings: function(c){
 181         var ct = c.ownerCt;
 182         Ext.applyIf(c, {
 183             labelAlign: ct.labelAlign,
 184             labelWidth: ct.labelWidth,
 185             itemCls: ct.itemCls
 186         });
 187     },
 188
 189     // private
 190     getLayoutTarget : function(){
 191         return this.form.el;
 192     },
 193
 194     <div id="method-Ext.form.FormPanel-getForm"></div>/**
 195      * Provides access to the {@link Ext.form.BasicForm Form} which this Panel contains.
 196      * @return {Ext.form.BasicForm} The {@link Ext.form.BasicForm Form} which this Panel contains.
 197      */
 198     getForm : function(){
 199         return this.form;
 200     },
 201
 202     // private
 203     onRender : function(ct, position){
 204         this.initFields();
 205         Ext.FormPanel.superclass.onRender.call(this, ct, position);
 206         this.form.initEl(this.body);
 207     },
 208
 209     // private
 210     beforeDestroy : function(){
 211         this.stopMonitoring();
 212         this.form.destroy(true);
 213         Ext.FormPanel.superclass.beforeDestroy.call(this);
 214     },
 215
 216     // Determine if a Component is usable as a form Field.
 217     isField : function(c) {
 218         return !!c.setValue && !!c.getValue && !!c.markInvalid && !!c.clearInvalid;
 219     },
 220
 221     // private
 222     initEvents : function(){
 223         Ext.FormPanel.superclass.initEvents.call(this);
 224         // Listeners are required here to catch bubbling events from children.
 225         this.on({
 226             scope: this,
 227             add: this.onAddEvent,
 228             remove: this.onRemoveEvent
 229         });
 230         if(this.monitorValid){ // initialize after render
 231             this.startMonitoring();
 232         }
 233     },
 234
 235     // private
 236     onAdd: function(c){
 237         Ext.FormPanel.superclass.onAdd.call(this, c);
 238         this.processAdd(c);
 239     },
 240
 241     // private
 242     onAddEvent: function(ct, c){
 243         if(ct !== this){
 244             this.processAdd(c);
 245         }
 246     },
 247
 248     // private
 249     processAdd : function(c){
 250         // If a single form Field, add it
 251         if(this.isField(c)){
 252             this.form.add(c);
 253         // If a Container, add any Fields it might contain
 254         }else if(c.findBy){
 255             this.applySettings(c);
 256             this.form.add.apply(this.form, c.findBy(this.isField));
 257         }
 258     },
 259
 260     // private
 261     onRemove: function(c){
 262         Ext.FormPanel.superclass.onRemove.call(this, c);
 263         this.processRemove(c);
 264     },
 265
 266     onRemoveEvent: function(ct, c){
 267         if(ct !== this){
 268             this.processRemove(c);
 269         }
 270     },
 271
 272     // private
 273     processRemove: function(c){
 274         if(!this.destroying){
 275             // If a single form Field, remove it
 276             if(this.isField(c)){
 277                 this.form.remove(c);
 278             // If a Container, its already destroyed by the time it gets here.  Remove any references to destroyed fields.
 279             }else if (c.findBy){
 280                 Ext.each(c.findBy(this.isField), this.form.remove, this.form);
 281                 /*
 282                  * This isn't the most efficient way of getting rid of the items, however it's the most
 283                  * correct, which in this case is most important.
 284                  */
 285                 this.form.cleanDestroyed();
 286             }
 287         }
 288     },
 289
 290     <div id="method-Ext.form.FormPanel-startMonitoring"></div>/**
 291      * Starts monitoring of the valid state of this form. Usually this is done by passing the config
 292      * option "monitorValid"
 293      */
 294     startMonitoring : function(){
 295         if(!this.validTask){
 296             this.validTask = new Ext.util.TaskRunner();
 297             this.validTask.start({
 298                 run : this.bindHandler,
 299                 interval : this.monitorPoll || 200,
 300                 scope: this
 301             });
 302         }
 303     },
 304
 305     <div id="method-Ext.form.FormPanel-stopMonitoring"></div>/**
 306      * Stops monitoring of the valid state of this form
 307      */
 308     stopMonitoring : function(){
 309         if(this.validTask){
 310             this.validTask.stopAll();
 311             this.validTask = null;
 312         }
 313     },
 314
 315     <div id="method-Ext.form.FormPanel-load"></div>/**
 316      * This is a proxy for the underlying BasicForm's {@link Ext.form.BasicForm#load} call.
 317      * @param {Object} options The options to pass to the action (see {@link Ext.form.BasicForm#doAction} for details)
 318      */
 319     load : function(){
 320         this.form.load.apply(this.form, arguments);
 321     },
 322
 323     // private
 324     onDisable : function(){
 325         Ext.FormPanel.superclass.onDisable.call(this);
 326         if(this.form){
 327             this.form.items.each(function(){
 328                  this.disable();
 329             });
 330         }
 331     },
 332
 333     // private
 334     onEnable : function(){
 335         Ext.FormPanel.superclass.onEnable.call(this);
 336         if(this.form){
 337             this.form.items.each(function(){
 338                  this.enable();
 339             });
 340         }
 341     },
 342
 343     // private
 344     bindHandler : function(){
 345         var valid = true;
 346         this.form.items.each(function(f){
 347             if(!f.isValid(true)){
 348                 valid = false;
 349                 return false;
 350             }
 351         });
 352         if(this.fbar){
 353             var fitems = this.fbar.items.items;
 354             for(var i = 0, len = fitems.length; i < len; i++){
 355                 var btn = fitems[i];
 356                 if(btn.formBind === true && btn.disabled === valid){
 357                     btn.setDisabled(!valid);
 358                 }
 359             }
 360         }
 361         this.fireEvent('clientvalidation', this, valid);
 362     }
 363 });
 364 Ext.reg('form', Ext.FormPanel);
 365
 366 Ext.form.FormPanel = Ext.FormPanel;
 367 </pre>
 368 </body>
 369 </html>