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