3 This file is part of Ext JS 4
5 Copyright (c) 2011 Sencha Inc
7 Contact: http://www.sencha.com/contact
9 GNU General Public License Usage
10 This file may be used under the terms of the GNU General Public License version 3.0 as published by the Free Software Foundation and appearing in the file LICENSE included in the packaging of this file. Please review the following information to ensure the GNU General Public License version 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
12 If you are unsure which license is appropriate for your use, please contact the sales department at http://www.sencha.com/contact.
16 * @docauthor Jason Johnston <jason@sencha.com>
18 * A container for grouping sets of fields, rendered as a HTML `fieldset` element. The {@link #title}
19 * config will be rendered as the fieldset's `legend`.
21 * While FieldSets commonly contain simple groups of fields, they are general {@link Ext.container.Container Containers}
22 * and may therefore contain any type of components in their {@link #items}, including other nested containers.
23 * The default {@link #layout} for the FieldSet's items is `'anchor'`, but it can be configured to use any other
26 * FieldSets may also be collapsed if configured to do so; this can be done in two ways:
28 * 1. Set the {@link #collapsible} config to true; this will result in a collapse button being rendered next to
29 * the {@link #title legend title}, or:
30 * 2. Set the {@link #checkboxToggle} config to true; this is similar to using {@link #collapsible} but renders
31 * a {@link Ext.form.field.Checkbox checkbox} in place of the toggle button. The fieldset will be expanded when the
32 * checkbox is checked and collapsed when it is unchecked. The checkbox will also be included in the
33 * {@link Ext.form.Basic#submit form submit parameters} using the {@link #checkboxName} as its parameter name.
38 * Ext.create('Ext.form.Panel', {
39 * title: 'Simple Form with FieldSets',
40 * labelWidth: 75, // label settings here cascade unless overridden
41 * url: 'save-form.php',
43 * bodyStyle: 'padding:5px 5px 0',
45 * renderTo: Ext.getBody(),
46 * layout: 'column', // arrange fieldsets side by side
51 * // Fieldset in Column 1 - collapsible via toggle button
54 * title: 'Fieldset 1',
56 * defaultType: 'textfield',
57 * defaults: {anchor: '100%'},
60 * fieldLabel: 'Field 1',
63 * fieldLabel: 'Field 2',
67 * // Fieldset in Column 2 - collapsible via checkbox, collapsed by default, contains a panel
69 * title: 'Show Panel', // title or checkboxToggle creates fieldset header
71 * checkboxToggle: true,
72 * collapsed: true, // fieldset initially collapsed
77 * title: 'Panel inside a fieldset',
84 Ext.define('Ext.form.FieldSet', {
85 extend: 'Ext.container.Container',
86 alias: 'widget.fieldset',
87 uses: ['Ext.form.field.Checkbox', 'Ext.panel.Tool', 'Ext.layout.container.Anchor', 'Ext.layout.component.FieldSet'],
91 * A title to be displayed in the fieldset's legend. May contain HTML markup.
95 * @cfg {Boolean} [checkboxToggle=false]
96 * Set to true to render a checkbox into the fieldset frame just in front of the legend to expand/collapse the
97 * fieldset when the checkbox is toggled.. This checkbox will be included in form submits using
98 * the {@link #checkboxName}.
102 * @cfg {String} checkboxName
103 * The name to assign to the fieldset's checkbox if {@link #checkboxToggle} = true
104 * (defaults to '[fieldset id]-checkbox').
108 * @cfg {Boolean} [collapsible=false]
109 * Set to true to make the fieldset collapsible and have the expand/collapse toggle button automatically rendered
110 * into the legend element, false to keep the fieldset statically sized with no collapse button.
111 * Another option is to configure {@link #checkboxToggle}. Use the {@link #collapsed} config to collapse the
112 * fieldset by default.
116 * @cfg {Boolean} collapsed
117 * Set to true to render the fieldset as collapsed by default. If {@link #checkboxToggle} is specified, the checkbox
118 * will also be unchecked by default.
123 * @property {Ext.Component} legend
124 * The component for the fieldset's legend. Will only be defined if the configuration requires a legend to be
125 * created, by setting the {@link #title} or {@link #checkboxToggle} options.
129 * @cfg {String} [baseCls='x-fieldset']
130 * The base CSS class applied to the fieldset.
132 baseCls: Ext.baseCSSPrefix + 'fieldset',
135 * @cfg {String} layout
136 * The {@link Ext.container.Container#layout} for the fieldset's immediate child items.
140 componentLayout: 'fieldset',
142 // No aria role necessary as fieldset has its own recognized semantics
145 renderTpl: ['<div id="{id}-body" class="{baseCls}-body"></div>'],
147 maskOnDisable: false,
149 getElConfig: function(){
150 return {tag: 'fieldset', id: this.id};
153 initComponent: function() {
155 baseCls = me.baseCls;
159 // Create the Legend component if needed
163 me.addChildEls('body');
166 me.addCls(baseCls + '-collapsed');
172 onRender: function(container, position) {
173 this.callParent(arguments);
174 // Make sure the legend is created and rendered
180 * Initialize and render the legend component if necessary
182 initLegend: function() {
187 // Create the legend component if needed and it hasn't been already
188 if (!legend && (me.title || me.checkboxToggle || me.collapsible)) {
192 if (me.checkboxToggle) {
193 legendItems.push(me.createCheckboxCmp());
196 else if (me.collapsible) {
197 legendItems.push(me.createToggleCmp());
201 legendItems.push(me.createTitleCmp());
203 legend = me.legend = Ext.create('Ext.container.Container', {
204 baseCls: me.baseCls + '-header',
207 getElConfig: function(){
213 // Gecko3 will kick every <div> out of <legend> and mess up every thing.
214 // So here we change every <div> into <span>s. Therefore the following
215 // clearer is not needed and since div introduces a lot of subsequent
216 // problems, it is actually harmful.
219 cls: Ext.baseCSSPrefix + 'clear'
228 // Make sure legend is rendered if the fieldset is rendered
229 if (legend && !legend.rendered && me.rendered) {
230 me.legend.render(me.el, me.body); //insert before body element
235 * Creates the legend title component. This is only called internally, but could be overridden in subclasses to
236 * customize the title component.
237 * @return Ext.Component
240 createTitleCmp: function() {
242 me.titleCmp = Ext.create('Ext.Component', {
244 getElConfig: function() {
246 tag: Ext.isGecko3 ? 'span' : 'div',
247 cls: me.titleCmp.cls,
251 cls: me.baseCls + '-header-text'
257 * @property {Ext.form.field.Checkbox} checkboxCmp
258 * Refers to the {@link Ext.form.field.Checkbox} component that is added next to the title in the legend. Only
259 * populated if the fieldset is configured with {@link #checkboxToggle}:true.
263 * Creates the checkbox component. This is only called internally, but could be overridden in subclasses to
264 * customize the checkbox's configuration or even return an entirely different component type.
265 * @return Ext.Component
268 createCheckboxCmp: function() {
270 suffix = '-checkbox';
272 me.checkboxCmp = Ext.create('Ext.form.field.Checkbox', {
273 getElConfig: function() {
275 tag: Ext.isGecko3 ? 'span' : 'div',
276 id: me.checkboxCmp.id,
277 cls: me.checkboxCmp.cls
280 name: me.checkboxName || me.id + suffix,
281 cls: me.baseCls + '-header' + suffix,
282 checked: !me.collapsed,
284 change: me.onCheckChange,
288 return me.checkboxCmp;
292 * @property {Ext.panel.Tool} toggleCmp
293 * Refers to the {@link Ext.panel.Tool} component that is added as the collapse/expand button next to the title in
294 * the legend. Only populated if the fieldset is configured with {@link #collapsible}:true.
298 * Creates the toggle button component. This is only called internally, but could be overridden in subclasses to
299 * customize the toggle component.
300 * @return Ext.Component
303 createToggleCmp: function() {
305 me.toggleCmp = Ext.create('Ext.panel.Tool', {
306 getElConfig: function() {
308 tag: Ext.isGecko3 ? 'span' : 'div',
310 cls: me.toggleCmp.cls
321 * Sets the title of this fieldset
322 * @param {String} title The new title
323 * @return {Ext.form.FieldSet} this
325 setTitle: function(title) {
329 me.titleCmp.update(title);
333 getTargetEl : function() {
334 return this.body || this.frameBody || this.el;
337 getContentTarget: function() {
343 * Include the legend component in the items for ComponentQuery
345 getRefItems: function(deep) {
346 var refItems = this.callParent(arguments),
347 legend = this.legend;
349 // Prepend legend items to ensure correct order
351 refItems.unshift(legend);
353 refItems.unshift.apply(refItems, legend.getRefItems(true));
360 * Expands the fieldset.
361 * @return {Ext.form.FieldSet} this
364 return this.setExpanded(true);
368 * Collapses the fieldset.
369 * @return {Ext.form.FieldSet} this
371 collapse : function() {
372 return this.setExpanded(false);
376 * @private Collapse or expand the fieldset
378 setExpanded: function(expanded) {
380 checkboxCmp = me.checkboxCmp;
382 expanded = !!expanded;
385 checkboxCmp.setValue(expanded);
389 me.removeCls(me.baseCls + '-collapsed');
391 me.addCls(me.baseCls + '-collapsed');
393 me.collapsed = !expanded;
395 // ensure subitems will get rendered and layed out when expanding
396 me.getComponentLayout().childrenChanged = true;
398 me.doComponentLayout();
403 * Toggle the fieldset's collapsed state to the opposite of what it is currently
406 this.setExpanded(!!this.collapsed);
411 * Handle changes in the checkbox checked state
413 onCheckChange: function(cmp, checked) {
414 this.setExpanded(checked);
417 beforeDestroy : function() {
418 var legend = this.legend;