src/widgets/form/Form.js

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