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