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