Upgrade to ExtJS 3.2.0 - Released 03/30/2010
[extjs.git] / src / widgets / form / Form.js
1 /*!
2  * Ext JS Library 3.2.0
3  * Copyright(c) 2006-2010 Ext JS, Inc.
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         this.form.destroy(true);
205         Ext.FormPanel.superclass.beforeDestroy.call(this);
206     },
207
208     // Determine if a Component is usable as a form Field.
209     isField : function(c) {
210         return !!c.setValue && !!c.getValue && !!c.markInvalid && !!c.clearInvalid;
211     },
212
213     // private
214     initEvents : function(){
215         Ext.FormPanel.superclass.initEvents.call(this);
216         // Listeners are required here to catch bubbling events from children.
217         this.on({
218             scope: this,
219             add: this.onAddEvent,
220             remove: this.onRemoveEvent
221         });
222         if(this.monitorValid){ // initialize after render
223             this.startMonitoring();
224         }
225     },
226
227     // private
228     onAdd: function(c){
229         Ext.FormPanel.superclass.onAdd.call(this, c);
230         this.processAdd(c);
231     },
232
233     // private
234     onAddEvent: function(ct, c){
235         if(ct !== this){
236             this.processAdd(c);
237         }
238     },
239
240     // private
241     processAdd : function(c){
242         // If a single form Field, add it
243         if(this.isField(c)){
244             this.form.add(c);
245         // If a Container, add any Fields it might contain
246         }else if(c.findBy){
247             this.applySettings(c);
248             this.form.add.apply(this.form, c.findBy(this.isField));
249         }
250     },
251
252     // private
253     onRemove: function(c){
254         Ext.FormPanel.superclass.onRemove.call(this, c);
255         this.processRemove(c);
256     },
257
258     onRemoveEvent: function(ct, c){
259         if(ct !== this){
260             this.processRemove(c);
261         }
262     },
263
264     // private
265     processRemove: function(c){
266         if(!this.destroying){
267             // If a single form Field, remove it
268             if(this.isField(c)){
269                 this.form.remove(c);
270             // If a Container, its already destroyed by the time it gets here.  Remove any references to destroyed fields.
271             }else if (c.findBy){
272                 Ext.each(c.findBy(this.isField), this.form.remove, this.form);
273             }
274         }
275     },
276
277     /**
278      * Starts monitoring of the valid state of this form. Usually this is done by passing the config
279      * option "monitorValid"
280      */
281     startMonitoring : function(){
282         if(!this.validTask){
283             this.validTask = new Ext.util.TaskRunner();
284             this.validTask.start({
285                 run : this.bindHandler,
286                 interval : this.monitorPoll || 200,
287                 scope: this
288             });
289         }
290     },
291
292     /**
293      * Stops monitoring of the valid state of this form
294      */
295     stopMonitoring : function(){
296         if(this.validTask){
297             this.validTask.stopAll();
298             this.validTask = null;
299         }
300     },
301
302     /**
303      * This is a proxy for the underlying BasicForm's {@link Ext.form.BasicForm#load} call.
304      * @param {Object} options The options to pass to the action (see {@link Ext.form.BasicForm#doAction} for details)
305      */
306     load : function(){
307         this.form.load.apply(this.form, arguments);
308     },
309
310     // private
311     onDisable : function(){
312         Ext.FormPanel.superclass.onDisable.call(this);
313         if(this.form){
314             this.form.items.each(function(){
315                  this.disable();
316             });
317         }
318     },
319
320     // private
321     onEnable : function(){
322         Ext.FormPanel.superclass.onEnable.call(this);
323         if(this.form){
324             this.form.items.each(function(){
325                  this.enable();
326             });
327         }
328     },
329
330     // private
331     bindHandler : function(){
332         var valid = true;
333         this.form.items.each(function(f){
334             if(!f.isValid(true)){
335                 valid = false;
336                 return false;
337             }
338         });
339         if(this.fbar){
340             var fitems = this.fbar.items.items;
341             for(var i = 0, len = fitems.length; i < len; i++){
342                 var btn = fitems[i];
343                 if(btn.formBind === true && btn.disabled === valid){
344                     btn.setDisabled(!valid);
345                 }
346             }
347         }
348         this.fireEvent('clientvalidation', this, valid);
349     }
350 });
351 Ext.reg('form', Ext.FormPanel);
352
353 Ext.form.FormPanel = Ext.FormPanel;