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