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