Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / FieldSet.html
1 <!DOCTYPE html>
2 <html>
3 <head>
4   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
5   <title>The source code</title>
6   <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
7   <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
8   <style type="text/css">
9     .highlight { display: block; background-color: #ddd; }
10   </style>
11   <script type="text/javascript">
12     function highlight() {
13       document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
14     }
15   </script>
16 </head>
17 <body onload="prettyPrint(); highlight();">
18   <pre class="prettyprint lang-js"><span id='Ext-form-FieldSet'>/**
19 </span> * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
20  *
21  * A container for grouping sets of fields, rendered as a HTML `fieldset` element. The {@link #title}
22  * config will be rendered as the fieldset's `legend`.
23  *
24  * While FieldSets commonly contain simple groups of fields, they are general {@link Ext.container.Container Containers}
25  * and may therefore contain any type of components in their {@link #items}, including other nested containers.
26  * The default {@link #layout} for the FieldSet's items is `'anchor'`, but it can be configured to use any other
27  * layout type.
28  *
29  * FieldSets may also be collapsed if configured to do so; this can be done in two ways:
30  *
31  * 1. Set the {@link #collapsible} config to true; this will result in a collapse button being rendered next to
32  *    the {@link #title legend title}, or:
33  * 2. Set the {@link #checkboxToggle} config to true; this is similar to using {@link #collapsible} but renders
34  *    a {@link Ext.form.field.Checkbox checkbox} in place of the toggle button. The fieldset will be expanded when the
35  *    checkbox is checked and collapsed when it is unchecked. The checkbox will also be included in the
36  *    {@link Ext.form.Basic#submit form submit parameters} using the {@link #checkboxName} as its parameter name.
37  *
38  * # Example usage
39  *
40  *     @example
41  *     Ext.create('Ext.form.Panel', {
42  *         title: 'Simple Form with FieldSets',
43  *         labelWidth: 75, // label settings here cascade unless overridden
44  *         url: 'save-form.php',
45  *         frame: true,
46  *         bodyStyle: 'padding:5px 5px 0',
47  *         width: 550,
48  *         renderTo: Ext.getBody(),
49  *         layout: 'column', // arrange fieldsets side by side
50  *         defaults: {
51  *             bodyPadding: 4
52  *         },
53  *         items: [{
54  *             // Fieldset in Column 1 - collapsible via toggle button
55  *             xtype:'fieldset',
56  *             columnWidth: 0.5,
57  *             title: 'Fieldset 1',
58  *             collapsible: true,
59  *             defaultType: 'textfield',
60  *             defaults: {anchor: '100%'},
61  *             layout: 'anchor',
62  *             items :[{
63  *                 fieldLabel: 'Field 1',
64  *                 name: 'field1'
65  *             }, {
66  *                 fieldLabel: 'Field 2',
67  *                 name: 'field2'
68  *             }]
69  *         }, {
70  *             // Fieldset in Column 2 - collapsible via checkbox, collapsed by default, contains a panel
71  *             xtype:'fieldset',
72  *             title: 'Show Panel', // title or checkboxToggle creates fieldset header
73  *             columnWidth: 0.5,
74  *             checkboxToggle: true,
75  *             collapsed: true, // fieldset initially collapsed
76  *             layout:'anchor',
77  *             items :[{
78  *                 xtype: 'panel',
79  *                 anchor: '100%',
80  *                 title: 'Panel inside a fieldset',
81  *                 frame: true,
82  *                 height: 52
83  *             }]
84  *         }]
85  *     });
86  */
87 Ext.define('Ext.form.FieldSet', {
88     extend: 'Ext.container.Container',
89     alias: 'widget.fieldset',
90     uses: ['Ext.form.field.Checkbox', 'Ext.panel.Tool', 'Ext.layout.container.Anchor', 'Ext.layout.component.FieldSet'],
91
92 <span id='Ext-form-FieldSet-cfg-title'>    /**
93 </span>     * @cfg {String} title
94      * A title to be displayed in the fieldset's legend. May contain HTML markup.
95      */
96
97 <span id='Ext-form-FieldSet-cfg-checkboxToggle'>    /**
98 </span>     * @cfg {Boolean} [checkboxToggle=false]
99      * Set to true to render a checkbox into the fieldset frame just in front of the legend to expand/collapse the
100      * fieldset when the checkbox is toggled.. This checkbox will be included in form submits using
101      * the {@link #checkboxName}.
102      */
103
104 <span id='Ext-form-FieldSet-cfg-checkboxName'>    /**
105 </span>     * @cfg {String} checkboxName
106      * The name to assign to the fieldset's checkbox if {@link #checkboxToggle} = true
107      * (defaults to '[fieldset id]-checkbox').
108      */
109
110 <span id='Ext-form-FieldSet-cfg-collapsible'>    /**
111 </span>     * @cfg {Boolean} [collapsible=false]
112      * Set to true to make the fieldset collapsible and have the expand/collapse toggle button automatically rendered
113      * into the legend element, false to keep the fieldset statically sized with no collapse button.
114      * Another option is to configure {@link #checkboxToggle}. Use the {@link #collapsed} config to collapse the
115      * fieldset by default.
116      */
117
118 <span id='Ext-form-FieldSet-cfg-collapsed'>    /**
119 </span>     * @cfg {Boolean} collapsed
120      * Set to true to render the fieldset as collapsed by default. If {@link #checkboxToggle} is specified, the checkbox
121      * will also be unchecked by default.
122      */
123     collapsed: false,
124
125 <span id='Ext-form-FieldSet-property-legend'>    /**
126 </span>     * @property {Ext.Component} legend
127      * The component for the fieldset's legend. Will only be defined if the configuration requires a legend to be
128      * created, by setting the {@link #title} or {@link #checkboxToggle} options.
129      */
130
131 <span id='Ext-form-FieldSet-cfg-baseCls'>    /**
132 </span>     * @cfg {String} [baseCls='x-fieldset']
133      * The base CSS class applied to the fieldset.
134      */
135     baseCls: Ext.baseCSSPrefix + 'fieldset',
136
137 <span id='Ext-form-FieldSet-cfg-layout'>    /**
138 </span>     * @cfg {String} layout
139      * The {@link Ext.container.Container#layout} for the fieldset's immediate child items.
140      */
141     layout: 'anchor',
142
143     componentLayout: 'fieldset',
144
145     // No aria role necessary as fieldset has its own recognized semantics
146     ariaRole: '',
147
148     renderTpl: ['&lt;div id=&quot;{id}-body&quot; class=&quot;{baseCls}-body&quot;&gt;&lt;/div&gt;'],
149
150     maskOnDisable: false,
151
152     getElConfig: function(){
153         return {tag: 'fieldset', id: this.id};
154     },
155
156     initComponent: function() {
157         var me = this,
158             baseCls = me.baseCls;
159
160         me.callParent();
161
162         // Create the Legend component if needed
163         me.initLegend();
164
165         // Add body el
166         me.addChildEls('body');
167
168         if (me.collapsed) {
169             me.addCls(baseCls + '-collapsed');
170             me.collapse();
171         }
172     },
173
174     // private
175     onRender: function(container, position) {
176         this.callParent(arguments);
177         // Make sure the legend is created and rendered
178         this.initLegend();
179     },
180
181 <span id='Ext-form-FieldSet-method-initLegend'>    /**
182 </span>     * @private
183      * Initialize and render the legend component if necessary
184      */
185     initLegend: function() {
186         var me = this,
187             legendItems,
188             legend = me.legend;
189
190         // Create the legend component if needed and it hasn't been already
191         if (!legend &amp;&amp; (me.title || me.checkboxToggle || me.collapsible)) {
192             legendItems = [];
193
194             // Checkbox
195             if (me.checkboxToggle) {
196                 legendItems.push(me.createCheckboxCmp());
197             }
198             // Toggle button
199             else if (me.collapsible) {
200                 legendItems.push(me.createToggleCmp());
201             }
202
203             // Title
204             legendItems.push(me.createTitleCmp());
205
206             legend = me.legend = Ext.create('Ext.container.Container', {
207                 baseCls: me.baseCls + '-header',
208                 ariaRole: '',
209                 ownerCt: this,
210                 getElConfig: function(){
211                     var result = {
212                         tag: 'legend',
213                         cls: this.baseCls
214                     };
215
216                     // Gecko3 will kick every &lt;div&gt; out of &lt;legend&gt; and mess up every thing.
217                     // So here we change every &lt;div&gt; into &lt;span&gt;s. Therefore the following
218                     // clearer is not needed and since div introduces a lot of subsequent
219                     // problems, it is actually harmful.
220                     if (!Ext.isGecko3) {
221                         result.children = [{
222                             cls: Ext.baseCSSPrefix + 'clear'
223                         }];
224                     }
225                     return result;
226                 },
227                 items: legendItems
228             });
229         }
230
231         // Make sure legend is rendered if the fieldset is rendered
232         if (legend &amp;&amp; !legend.rendered &amp;&amp; me.rendered) {
233             me.legend.render(me.el, me.body); //insert before body element
234         }
235     },
236
237 <span id='Ext-form-FieldSet-method-createTitleCmp'>    /**
238 </span>     * Creates the legend title component. This is only called internally, but could be overridden in subclasses to
239      * customize the title component.
240      * @return Ext.Component
241      * @protected
242      */
243     createTitleCmp: function() {
244         var me = this;
245         me.titleCmp = Ext.create('Ext.Component', {
246             html: me.title,
247             getElConfig: function() {
248                 return {
249                     tag: Ext.isGecko3 ? 'span' : 'div',
250                     cls: me.titleCmp.cls,
251                     id: me.titleCmp.id
252                 };
253             },
254             cls: me.baseCls + '-header-text'
255         });
256         return me.titleCmp;
257     },
258
259 <span id='Ext-form-FieldSet-property-checkboxCmp'>    /**
260 </span>     * @property {Ext.form.field.Checkbox} checkboxCmp
261      * Refers to the {@link Ext.form.field.Checkbox} component that is added next to the title in the legend. Only
262      * populated if the fieldset is configured with {@link #checkboxToggle}:true.
263      */
264
265 <span id='Ext-form-FieldSet-method-createCheckboxCmp'>    /**
266 </span>     * Creates the checkbox component. This is only called internally, but could be overridden in subclasses to
267      * customize the checkbox's configuration or even return an entirely different component type.
268      * @return Ext.Component
269      * @protected
270      */
271     createCheckboxCmp: function() {
272         var me = this,
273             suffix = '-checkbox';
274
275         me.checkboxCmp = Ext.create('Ext.form.field.Checkbox', {
276             getElConfig: function() {
277                 return {
278                     tag: Ext.isGecko3 ? 'span' : 'div',
279                     id: me.checkboxCmp.id,
280                     cls: me.checkboxCmp.cls
281                 };
282             },
283             name: me.checkboxName || me.id + suffix,
284             cls: me.baseCls + '-header' + suffix,
285             checked: !me.collapsed,
286             listeners: {
287                 change: me.onCheckChange,
288                 scope: me
289             }
290         });
291         return me.checkboxCmp;
292     },
293
294 <span id='Ext-form-FieldSet-property-toggleCmp'>    /**
295 </span>     * @property {Ext.panel.Tool} toggleCmp
296      * Refers to the {@link Ext.panel.Tool} component that is added as the collapse/expand button next to the title in
297      * the legend. Only populated if the fieldset is configured with {@link #collapsible}:true.
298      */
299
300 <span id='Ext-form-FieldSet-method-createToggleCmp'>    /**
301 </span>     * Creates the toggle button component. This is only called internally, but could be overridden in subclasses to
302      * customize the toggle component.
303      * @return Ext.Component
304      * @protected
305      */
306     createToggleCmp: function() {
307         var me = this;
308         me.toggleCmp = Ext.create('Ext.panel.Tool', {
309             getElConfig: function() {
310                 return {
311                     tag: Ext.isGecko3 ? 'span' : 'div',
312                     id: me.toggleCmp.id,
313                     cls: me.toggleCmp.cls
314                 };
315             },
316             type: 'toggle',
317             handler: me.toggle,
318             scope: me
319         });
320         return me.toggleCmp;
321     },
322
323 <span id='Ext-form-FieldSet-method-setTitle'>    /**
324 </span>     * Sets the title of this fieldset
325      * @param {String} title The new title
326      * @return {Ext.form.FieldSet} this
327      */
328     setTitle: function(title) {
329         var me = this;
330         me.title = title;
331         me.initLegend();
332         me.titleCmp.update(title);
333         return me;
334     },
335
336     getTargetEl : function() {
337         return this.body || this.frameBody || this.el;
338     },
339
340     getContentTarget: function() {
341         return this.body;
342     },
343
344 <span id='Ext-form-FieldSet-method-getRefItems'>    /**
345 </span>     * @private
346      * Include the legend component in the items for ComponentQuery
347      */
348     getRefItems: function(deep) {
349         var refItems = this.callParent(arguments),
350             legend = this.legend;
351
352         // Prepend legend items to ensure correct order
353         if (legend) {
354             refItems.unshift(legend);
355             if (deep) {
356                 refItems.unshift.apply(refItems, legend.getRefItems(true));
357             }
358         }
359         return refItems;
360     },
361
362 <span id='Ext-form-FieldSet-method-expand'>    /**
363 </span>     * Expands the fieldset.
364      * @return {Ext.form.FieldSet} this
365      */
366     expand : function(){
367         return this.setExpanded(true);
368     },
369
370 <span id='Ext-form-FieldSet-method-collapse'>    /**
371 </span>     * Collapses the fieldset.
372      * @return {Ext.form.FieldSet} this
373      */
374     collapse : function() {
375         return this.setExpanded(false);
376     },
377
378 <span id='Ext-form-FieldSet-method-setExpanded'>    /**
379 </span>     * @private Collapse or expand the fieldset
380      */
381     setExpanded: function(expanded) {
382         var me = this,
383             checkboxCmp = me.checkboxCmp;
384
385         expanded = !!expanded;
386
387         if (checkboxCmp) {
388             checkboxCmp.setValue(expanded);
389         }
390
391         if (expanded) {
392             me.removeCls(me.baseCls + '-collapsed');
393         } else {
394             me.addCls(me.baseCls + '-collapsed');
395         }
396         me.collapsed = !expanded;
397         if (expanded) {
398             // ensure subitems will get rendered and layed out when expanding
399             me.getComponentLayout().childrenChanged = true;
400         }
401         me.doComponentLayout();
402         return me;
403     },
404
405 <span id='Ext-form-FieldSet-method-toggle'>    /**
406 </span>     * Toggle the fieldset's collapsed state to the opposite of what it is currently
407      */
408     toggle: function() {
409         this.setExpanded(!!this.collapsed);
410     },
411
412 <span id='Ext-form-FieldSet-method-onCheckChange'>    /**
413 </span>     * @private
414      * Handle changes in the checkbox checked state
415      */
416     onCheckChange: function(cmp, checked) {
417         this.setExpanded(checked);
418     },
419
420     beforeDestroy : function() {
421         var legend = this.legend;
422         if (legend) {
423             legend.destroy();
424         }
425         this.callParent();
426     }
427 });
428 </pre>
429 </body>
430 </html>