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