Upgrade to ExtJS 3.3.1 - Released 11/30/2010
[extjs.git] / docs / source / FormLayout.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.layout.FormLayout"></div>/**
16  * @class Ext.layout.FormLayout
17  * @extends Ext.layout.AnchorLayout
18  * <p>This layout manager is specifically designed for rendering and managing child Components of
19  * {@link Ext.form.FormPanel forms}. It is responsible for rendering the labels of
20  * {@link Ext.form.Field Field}s.</p>
21  *
22  * <p>This layout manager is used when a Container is configured with the <tt>layout:'form'</tt>
23  * {@link Ext.Container#layout layout} config option, and should generally not need to be created directly
24  * via the new keyword. See <tt><b>{@link Ext.Container#layout}</b></tt> for additional details.</p>
25  *
26  * <p>In an application, it will usually be preferrable to use a {@link Ext.form.FormPanel FormPanel}
27  * (which is configured with FormLayout as its layout class by default) since it also provides built-in
28  * functionality for {@link Ext.form.BasicForm#doAction loading, validating and submitting} the form.</p>
29  *
30  * <p>A {@link Ext.Container Container} <i>using</i> the FormLayout layout manager (e.g.
31  * {@link Ext.form.FormPanel} or specifying <tt>layout:'form'</tt>) can also accept the following
32  * layout-specific config properties:<div class="mdetail-params"><ul>
33  * <li><b><tt>{@link Ext.form.FormPanel#hideLabels hideLabels}</tt></b></li>
34  * <li><b><tt>{@link Ext.form.FormPanel#labelAlign labelAlign}</tt></b></li>
35  * <li><b><tt>{@link Ext.form.FormPanel#labelPad labelPad}</tt></b></li>
36  * <li><b><tt>{@link Ext.form.FormPanel#labelSeparator labelSeparator}</tt></b></li>
37  * <li><b><tt>{@link Ext.form.FormPanel#labelWidth labelWidth}</tt></b></li>
38  * </ul></div></p>
39  *
40  * <p>Any Component (including Fields) managed by FormLayout accepts the following as a config option:
41  * <div class="mdetail-params"><ul>
42  * <li><b><tt>{@link Ext.Component#anchor anchor}</tt></b></li>
43  * </ul></div></p>
44  *
45  * <p>Any Component managed by FormLayout may be rendered as a form field (with an associated label) by
46  * configuring it with a non-null <b><tt>{@link Ext.Component#fieldLabel fieldLabel}</tt></b>. Components configured
47  * in this way may be configured with the following options which affect the way the FormLayout renders them:
48  * <div class="mdetail-params"><ul>
49  * <li><b><tt>{@link Ext.Component#clearCls clearCls}</tt></b></li>
50  * <li><b><tt>{@link Ext.Component#fieldLabel fieldLabel}</tt></b></li>
51  * <li><b><tt>{@link Ext.Component#hideLabel hideLabel}</tt></b></li>
52  * <li><b><tt>{@link Ext.Component#itemCls itemCls}</tt></b></li>
53  * <li><b><tt>{@link Ext.Component#labelSeparator labelSeparator}</tt></b></li>
54  * <li><b><tt>{@link Ext.Component#labelStyle labelStyle}</tt></b></li>
55  * </ul></div></p>
56  *
57  * <p>Example usage:</p>
58  * <pre><code>
59 // Required if showing validation messages
60 Ext.QuickTips.init();
61
62 // While you can create a basic Panel with layout:'form', practically
63 // you should usually use a FormPanel to also get its form functionality
64 // since it already creates a FormLayout internally.
65 var form = new Ext.form.FormPanel({
66     title: 'Form Layout',
67     bodyStyle: 'padding:15px',
68     width: 350,
69     defaultType: 'textfield',
70     defaults: {
71         // applied to each contained item
72         width: 230,
73         msgTarget: 'side'
74     },
75     items: [{
76             fieldLabel: 'First Name',
77             name: 'first',
78             allowBlank: false,
79             {@link Ext.Component#labelSeparator labelSeparator}: ':' // override labelSeparator layout config
80         },{
81             fieldLabel: 'Last Name',
82             name: 'last'
83         },{
84             fieldLabel: 'Email',
85             name: 'email',
86             vtype:'email'
87         }, {
88             xtype: 'textarea',
89             hideLabel: true,     // override hideLabels layout config
90             name: 'msg',
91             anchor: '100% -53'
92         }
93     ],
94     buttons: [
95         {text: 'Save'},
96         {text: 'Cancel'}
97     ],
98     layoutConfig: {
99         {@link #labelSeparator}: '~' // superseded by assignment below
100     },
101     // config options applicable to container when layout='form':
102     hideLabels: false,
103     labelAlign: 'left',   // or 'right' or 'top'
104     {@link Ext.form.FormPanel#labelSeparator labelSeparator}: '>>', // takes precedence over layoutConfig value
105     labelWidth: 65,       // defaults to 100
106     labelPad: 8           // defaults to 5, must specify labelWidth to be honored
107 });
108 </code></pre>
109  */
110 Ext.layout.FormLayout = Ext.extend(Ext.layout.AnchorLayout, {
111
112     <div id="cfg-Ext.layout.FormLayout-labelSeparator"></div>/**
113      * @cfg {String} labelSeparator
114      * See {@link Ext.form.FormPanel}.{@link Ext.form.FormPanel#labelSeparator labelSeparator}.  Configuration
115      * of this property at the <b>container</b> level takes precedence.
116      */
117     labelSeparator : ':',
118
119     <div id="prop-Ext.layout.FormLayout-labelStyle"></div>/**
120      * Read only. The CSS style specification string added to field labels in this layout if not
121      * otherwise {@link Ext.Component#labelStyle specified by each contained field}.
122      * @type String
123      * @property labelStyle
124      */
125
126     <div id="cfg-Ext.layout.FormLayout-trackLabels"></div>/**
127      * @cfg {Boolean} trackLabels
128      * True to show/hide the field label when the field is hidden. Defaults to <tt>true</tt>.
129      */
130     trackLabels: true,
131
132     type: 'form',
133
134     onRemove: function(c){
135         Ext.layout.FormLayout.superclass.onRemove.call(this, c);
136         if(this.trackLabels){
137             c.un('show', this.onFieldShow, this);
138             c.un('hide', this.onFieldHide, this);
139         }
140         // check for itemCt, since we may be removing a fieldset or something similar
141         var el = c.getPositionEl(),
142             ct = c.getItemCt && c.getItemCt();
143         if (c.rendered && ct) {
144             if (el && el.dom) {
145                 el.insertAfter(ct);
146             }
147             Ext.destroy(ct);
148             Ext.destroyMembers(c, 'label', 'itemCt');
149             if (c.customItemCt) {
150                 Ext.destroyMembers(c, 'getItemCt', 'customItemCt');
151             }
152         }
153     },
154
155     // private
156     setContainer : function(ct){
157         Ext.layout.FormLayout.superclass.setContainer.call(this, ct);
158         if(ct.labelAlign){
159             ct.addClass('x-form-label-'+ct.labelAlign);
160         }
161
162         if(ct.hideLabels){
163             Ext.apply(this, {
164                 labelStyle: 'display:none',
165                 elementStyle: 'padding-left:0;',
166                 labelAdjust: 0
167             });
168         }else{
169             this.labelSeparator = Ext.isDefined(ct.labelSeparator) ? ct.labelSeparator : this.labelSeparator;
170             ct.labelWidth = ct.labelWidth || 100;
171             if(Ext.isNumber(ct.labelWidth)){
172                 var pad = Ext.isNumber(ct.labelPad) ? ct.labelPad : 5;
173                 Ext.apply(this, {
174                     labelAdjust: ct.labelWidth + pad,
175                     labelStyle: 'width:' + ct.labelWidth + 'px;',
176                     elementStyle: 'padding-left:' + (ct.labelWidth + pad) + 'px'
177                 });
178             }
179             if(ct.labelAlign == 'top'){
180                 Ext.apply(this, {
181                     labelStyle: 'width:auto;',
182                     labelAdjust: 0,
183                     elementStyle: 'padding-left:0;'
184                 });
185             }
186         }
187     },
188
189     // private
190     isHide: function(c){
191         return c.hideLabel || this.container.hideLabels;
192     },
193
194     onFieldShow: function(c){
195         c.getItemCt().removeClass('x-hide-' + c.hideMode);
196
197         // Composite fields will need to layout after the container is made visible
198         if (c.isComposite) {
199             c.doLayout();
200         }
201     },
202
203     onFieldHide: function(c){
204         c.getItemCt().addClass('x-hide-' + c.hideMode);
205     },
206
207     //private
208     getLabelStyle: function(s){
209         var ls = '', items = [this.labelStyle, s];
210         for (var i = 0, len = items.length; i < len; ++i){
211             if (items[i]){
212                 ls += items[i];
213                 if (ls.substr(-1, 1) != ';'){
214                     ls += ';';
215                 }
216             }
217         }
218         return ls;
219     },
220
221     <div id="cfg-Ext.layout.FormLayout-fieldTpl"></div>/**
222      * @cfg {Ext.Template} fieldTpl
223      * A {@link Ext.Template#compile compile}d {@link Ext.Template} for rendering
224      * the fully wrapped, labeled and styled form Field. Defaults to:</p><pre><code>
225 new Ext.Template(
226     &#39;&lt;div class="x-form-item {itemCls}" tabIndex="-1">&#39;,
227         &#39;&lt;&#108;abel for="{id}" style="{labelStyle}" class="x-form-item-&#108;abel">{&#108;abel}{labelSeparator}&lt;/&#108;abel>&#39;,
228         &#39;&lt;div class="x-form-element" id="x-form-el-{id}" style="{elementStyle}">&#39;,
229         &#39;&lt;/div>&lt;div class="{clearCls}">&lt;/div>&#39;,
230     '&lt;/div>'
231 );
232 </code></pre>
233      * <p>This may be specified to produce a different DOM structure when rendering form Fields.</p>
234      * <p>A description of the properties within the template follows:</p><div class="mdetail-params"><ul>
235      * <li><b><tt>itemCls</tt></b> : String<div class="sub-desc">The CSS class applied to the outermost div wrapper
236      * that contains this field label and field element (the default class is <tt>'x-form-item'</tt> and <tt>itemCls</tt>
237      * will be added to that). If supplied, <tt>itemCls</tt> at the field level will override the default <tt>itemCls</tt>
238      * supplied at the container level.</div></li>
239      * <li><b><tt>id</tt></b> : String<div class="sub-desc">The id of the Field</div></li>
240      * <li><b><tt>{@link #labelStyle}</tt></b> : String<div class="sub-desc">
241      * A CSS style specification string to add to the field label for this field (defaults to <tt>''</tt> or the
242      * {@link #labelStyle layout's value for <tt>labelStyle</tt>}).</div></li>
243      * <li><b><tt>label</tt></b> : String<div class="sub-desc">The text to display as the label for this
244      * field (defaults to <tt>''</tt>)</div></li>
245      * <li><b><tt>{@link #labelSeparator}</tt></b> : String<div class="sub-desc">The separator to display after
246      * the text of the label for this field (defaults to a colon <tt>':'</tt> or the
247      * {@link #labelSeparator layout's value for labelSeparator}). To hide the separator use empty string ''.</div></li>
248      * <li><b><tt>elementStyle</tt></b> : String<div class="sub-desc">The styles text for the input element's wrapper.</div></li>
249      * <li><b><tt>clearCls</tt></b> : String<div class="sub-desc">The CSS class to apply to the special clearing div
250      * rendered directly after each form field wrapper (defaults to <tt>'x-form-clear-left'</tt>)</div></li>
251      * </ul></div>
252      * <p>Also see <tt>{@link #getTemplateArgs}</tt></p>
253      */
254
255     /**
256      * @private
257      *
258      */
259     renderItem : function(c, position, target){
260         if(c && (c.isFormField || c.fieldLabel) && c.inputType != 'hidden'){
261             var args = this.getTemplateArgs(c);
262             if(Ext.isNumber(position)){
263                 position = target.dom.childNodes[position] || null;
264             }
265             if(position){
266                 c.itemCt = this.fieldTpl.insertBefore(position, args, true);
267             }else{
268                 c.itemCt = this.fieldTpl.append(target, args, true);
269             }
270             if(!c.getItemCt){
271                 // Non form fields don't have getItemCt, apply it here
272                 // This will get cleaned up in onRemove
273                 Ext.apply(c, {
274                     getItemCt: function(){
275                         return c.itemCt;
276                     },
277                     customItemCt: true
278                 });
279             }
280             c.label = c.getItemCt().child('label.x-form-item-label');
281             if(!c.rendered){
282                 c.render('x-form-el-' + c.id);
283             }else if(!this.isValidParent(c, target)){
284                 Ext.fly('x-form-el-' + c.id).appendChild(c.getPositionEl());
285             }
286             if(this.trackLabels){
287                 if(c.hidden){
288                     this.onFieldHide(c);
289                 }
290                 c.on({
291                     scope: this,
292                     show: this.onFieldShow,
293                     hide: this.onFieldHide
294                 });
295             }
296             this.configureItem(c);
297         }else {
298             Ext.layout.FormLayout.superclass.renderItem.apply(this, arguments);
299         }
300     },
301
302     <div id="method-Ext.layout.FormLayout-getTemplateArgs"></div>/**
303      * <p>Provides template arguments for rendering the fully wrapped, labeled and styled form Field.</p>
304      * <p>This method returns an object hash containing properties used by the layout's {@link #fieldTpl}
305      * to create a correctly wrapped, labeled and styled form Field. This may be overriden to
306      * create custom layouts. The properties which must be returned are:</p><div class="mdetail-params"><ul>
307      * <li><b><tt>itemCls</tt></b> : String<div class="sub-desc">The CSS class applied to the outermost div wrapper
308      * that contains this field label and field element (the default class is <tt>'x-form-item'</tt> and <tt>itemCls</tt>
309      * will be added to that). If supplied, <tt>itemCls</tt> at the field level will override the default <tt>itemCls</tt>
310      * supplied at the container level.</div></li>
311      * <li><b><tt>id</tt></b> : String<div class="sub-desc">The id of the Field</div></li>
312      * <li><b><tt>{@link #labelStyle}</tt></b> : String<div class="sub-desc">
313      * A CSS style specification string to add to the field label for this field (defaults to <tt>''</tt> or the
314      * {@link #labelStyle layout's value for <tt>labelStyle</tt>}).</div></li>
315      * <li><b><tt>label</tt></b> : String<div class="sub-desc">The text to display as the label for this
316      * field (defaults to the field's configured fieldLabel property)</div></li>
317      * <li><b><tt>{@link #labelSeparator}</tt></b> : String<div class="sub-desc">The separator to display after
318      * the text of the label for this field (defaults to a colon <tt>':'</tt> or the
319      * {@link #labelSeparator layout's value for labelSeparator}). To hide the separator use empty string ''.</div></li>
320      * <li><b><tt>elementStyle</tt></b> : String<div class="sub-desc">The styles text for the input element's wrapper.</div></li>
321      * <li><b><tt>clearCls</tt></b> : String<div class="sub-desc">The CSS class to apply to the special clearing div
322      * rendered directly after each form field wrapper (defaults to <tt>'x-form-clear-left'</tt>)</div></li>
323      * </ul></div>
324      * @param (Ext.form.Field} field The {@link Ext.form.Field Field} being rendered.
325      * @return {Object} An object hash containing the properties required to render the Field.
326      */
327     getTemplateArgs: function(field) {
328         var noLabelSep = !field.fieldLabel || field.hideLabel;
329
330         return {
331             id            : field.id,
332             label         : field.fieldLabel,
333             itemCls       : (field.itemCls || this.container.itemCls || '') + (field.hideLabel ? ' x-hide-label' : ''),
334             clearCls      : field.clearCls || 'x-form-clear-left',
335             labelStyle    : this.getLabelStyle(field.labelStyle),
336             elementStyle  : this.elementStyle || '',
337             labelSeparator: noLabelSep ? '' : (Ext.isDefined(field.labelSeparator) ? field.labelSeparator : this.labelSeparator)
338         };
339     },
340
341     // private
342     adjustWidthAnchor: function(value, c){
343         if(c.label && !this.isHide(c) && (this.container.labelAlign != 'top')){
344             var adjust = Ext.isIE6 || (Ext.isIE && !Ext.isStrict);
345             return value - this.labelAdjust + (adjust ? -3 : 0);
346         }
347         return value;
348     },
349
350     adjustHeightAnchor : function(value, c){
351         if(c.label && !this.isHide(c) && (this.container.labelAlign == 'top')){
352             return value - c.label.getHeight();
353         }
354         return value;
355     },
356
357     // private
358     isValidParent : function(c, target){
359         return target && this.container.getEl().contains(c.getPositionEl());
360     }
361
362     <div id="prop-Ext.layout.FormLayout-activeItem"></div>/**
363      * @property activeItem
364      * @hide
365      */
366 });
367
368 Ext.Container.LAYOUTS['form'] = Ext.layout.FormLayout;
369 </pre>    
370 </body>
371 </html>