Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / 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>