docs/source/Form.html

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