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-method-constructor'><span id='Ext-form-FieldSet'>/**
  19 </span></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  * @constructor
  90  * Create a new FieldSet
  91  * @param {Object} config Configuration options
  92  * @xtype fieldset
  93  * @docauthor Jason Johnston &lt;jason@sencha.com&gt;
  94  */
  95 Ext.define('Ext.form.FieldSet', {
  96     extend: 'Ext.container.Container',
  97     alias: 'widget.fieldset',
  98     uses: ['Ext.form.field.Checkbox', 'Ext.panel.Tool', 'Ext.layout.container.Anchor', 'Ext.layout.component.FieldSet'],
  99
 100 <span id='Ext-form-FieldSet-cfg-title'>    /**
 101 </span>     * @cfg {String} title
 102      * A title to be displayed in the fieldset's legend. May contain HTML markup.
 103      */
 104
 105 <span id='Ext-form-FieldSet-cfg-checkboxToggle'>    /**
 106 </span>     * @cfg {Boolean} checkboxToggle
 107      * Set to &lt;tt&gt;true&lt;/tt&gt; to render a checkbox into the fieldset frame just
 108      * in front of the legend to expand/collapse the fieldset when the checkbox is toggled. (defaults
 109      * to &lt;tt&gt;false&lt;/tt&gt;). This checkbox will be included in form submits using the {@link #checkboxName}.
 110      */
 111
 112 <span id='Ext-form-FieldSet-cfg-checkboxName'>    /**
 113 </span>     * @cfg {String} checkboxName
 114      * The name to assign to the fieldset's checkbox if &lt;tt&gt;{@link #checkboxToggle} = true&lt;/tt&gt;
 115      * (defaults to &lt;tt&gt;'[fieldset id]-checkbox'&lt;/tt&gt;).
 116      */
 117
 118 <span id='Ext-form-FieldSet-cfg-collapsible'>    /**
 119 </span>     * @cfg {Boolean} collapsible
 120      * Set to &lt;tt&gt;true&lt;/tt&gt; to make the fieldset collapsible and have the expand/collapse toggle button automatically
 121      * rendered into the legend element, &lt;tt&gt;false&lt;/tt&gt; to keep the fieldset statically sized with no collapse
 122      * button (defaults to &lt;tt&gt;false&lt;/tt&gt;). Another option is to configure &lt;tt&gt;{@link #checkboxToggle}&lt;/tt&gt;.
 123      * Use the {@link #collapsed} config to collapse the fieldset by default.
 124      */
 125
 126 <span id='Ext-form-FieldSet-cfg-collapsed'>    /**
 127 </span>     * @cfg {Boolean} collapsed
 128      * Set to &lt;tt&gt;true&lt;/tt&gt; to render the fieldset as collapsed by default. If {@link #checkboxToggle} is specified,
 129      * the checkbox will also be unchecked by default.
 130      */
 131     collapsed: false,
 132
 133 <span id='Ext-form-FieldSet-property-legend'>    /**
 134 </span>     * @property legend
 135      * @type Ext.Component
 136      * The component for the fieldset's legend. Will only be defined if the configuration requires a legend
 137      * to be created, by setting the {@link #title} or {@link #checkboxToggle} options.
 138      */
 139
 140 <span id='Ext-form-FieldSet-cfg-baseCls'>    /**
 141 </span>     * @cfg {String} baseCls The base CSS class applied to the fieldset (defaults to &lt;tt&gt;'x-fieldset'&lt;/tt&gt;).
 142      */
 143     baseCls: Ext.baseCSSPrefix + 'fieldset',
 144
 145 <span id='Ext-form-FieldSet-cfg-layout'>    /**
 146 </span>     * @cfg {String} layout The {@link Ext.container.Container#layout} for the fieldset's immediate child items.
 147      * Defaults to &lt;tt&gt;'anchor'&lt;/tt&gt;.
 148      */
 149     layout: 'anchor',
 150
 151     componentLayout: 'fieldset',
 152
 153     // No aria role necessary as fieldset has its own recognized semantics
 154     ariaRole: '',
 155
 156     renderTpl: ['&lt;div class=&quot;{baseCls}-body&quot;&gt;&lt;/div&gt;'],
 157
 158     maskOnDisable: false,
 159
 160     getElConfig: function(){
 161         return {tag: 'fieldset', id: this.id};
 162     },
 163
 164     initComponent: function() {
 165         var me = this,
 166             baseCls = me.baseCls;
 167
 168         me.callParent();
 169
 170         // Create the Legend component if needed
 171         me.initLegend();
 172
 173         // Add body el selector
 174         Ext.applyIf(me.renderSelectors, {
 175             body: '.' + baseCls + '-body'
 176         });
 177
 178         if (me.collapsed) {
 179             me.addCls(baseCls + '-collapsed');
 180             me.collapse();
 181         }
 182     },
 183
 184     // private
 185     onRender: function(container, position) {
 186         this.callParent(arguments);
 187         // Make sure the legend is created and rendered
 188         this.initLegend();
 189     },
 190
 191 <span id='Ext-form-FieldSet-method-initLegend'>    /**
 192 </span>     * @private
 193      * Initialize and render the legend component if necessary
 194      */
 195     initLegend: function() {
 196         var me = this,
 197             legendItems,
 198             legend = me.legend;
 199
 200         // Create the legend component if needed and it hasn't been already
 201         if (!legend &amp;&amp; (me.title || me.checkboxToggle || me.collapsible)) {
 202             legendItems = [];
 203
 204             // Checkbox
 205             if (me.checkboxToggle) {
 206                 legendItems.push(me.createCheckboxCmp());
 207             }
 208             // Toggle button
 209             else if (me.collapsible) {
 210                 legendItems.push(me.createToggleCmp());
 211             }
 212
 213             // Title
 214             legendItems.push(me.createTitleCmp());
 215
 216             legend = me.legend = Ext.create('Ext.container.Container', {
 217                 baseCls: me.baseCls + '-header',
 218                 ariaRole: '',
 219                 getElConfig: function(){
 220                     return {tag: 'legend', cls: this.baseCls};
 221                 },
 222                 items: legendItems
 223             });
 224         }
 225
 226         // Make sure legend is rendered if the fieldset is rendered
 227         if (legend &amp;&amp; !legend.rendered &amp;&amp; me.rendered) {
 228             me.legend.render(me.el, me.body); //insert before body element
 229         }
 230     },
 231
 232 <span id='Ext-form-FieldSet-method-createTitleCmp'>    /**
 233 </span>     * @protected
 234      * Creates the legend title component. This is only called internally, but could be overridden in subclasses
 235      * to customize the title component.
 236      * @return Ext.Component
 237      */
 238     createTitleCmp: function() {
 239         var me = this;
 240         me.titleCmp = Ext.create('Ext.Component', {
 241             html: me.title,
 242             cls: me.baseCls + '-header-text'
 243         });
 244         return me.titleCmp;
 245
 246     },
 247
 248 <span id='Ext-form-FieldSet-property-checkboxCmp'>    /**
 249 </span>     * @property checkboxCmp
 250      * @type Ext.form.field.Checkbox
 251      * Refers to the {@link Ext.form.field.Checkbox} component that is added next to the title in the legend. Only
 252      * populated if the fieldset is configured with &lt;tt&gt;{@link #checkboxToggle}:true&lt;/tt&gt;.
 253      */
 254
 255 <span id='Ext-form-FieldSet-method-createCheckboxCmp'>    /**
 256 </span>     * @protected
 257      * Creates the checkbox component. This is only called internally, but could be overridden in subclasses
 258      * to customize the checkbox's configuration or even return an entirely different component type.
 259      * @return Ext.Component
 260      */
 261     createCheckboxCmp: function() {
 262         var me = this,
 263             suffix = '-checkbox';
 264
 265         me.checkboxCmp = Ext.create('Ext.form.field.Checkbox', {
 266             name: me.checkboxName || me.id + suffix,
 267             cls: me.baseCls + '-header' + suffix,
 268             checked: !me.collapsed,
 269             listeners: {
 270                 change: me.onCheckChange,
 271                 scope: me
 272             }
 273         });
 274         return me.checkboxCmp;
 275     },
 276
 277 <span id='Ext-form-FieldSet-property-toggleCmp'>    /**
 278 </span>     * @property toggleCmp
 279      * @type Ext.panel.Tool
 280      * Refers to the {@link Ext.panel.Tool} component that is added as the collapse/expand button next
 281      * to the title in the legend. Only populated if the fieldset is configured with &lt;tt&gt;{@link #collapsible}:true&lt;/tt&gt;.
 282      */
 283
 284 <span id='Ext-form-FieldSet-method-createToggleCmp'>    /**
 285 </span>     * @protected
 286      * Creates the toggle button component. This is only called internally, but could be overridden in
 287      * subclasses to customize the toggle component.
 288      * @return Ext.Component
 289      */
 290     createToggleCmp: function() {
 291         var me = this;
 292         me.toggleCmp = Ext.create('Ext.panel.Tool', {
 293             type: 'toggle',
 294             handler: me.toggle,
 295             scope: me
 296         });
 297         return me.toggleCmp;
 298     },
 299
 300 <span id='Ext-form-FieldSet-method-setTitle'>    /**
 301 </span>     * Sets the title of this fieldset
 302      * @param {String} title The new title
 303      * @return {Ext.form.FieldSet} this
 304      */
 305     setTitle: function(title) {
 306         var me = this;
 307         me.title = title;
 308         me.initLegend();
 309         me.titleCmp.update(title);
 310         return me;
 311     },
 312
 313     getTargetEl : function() {
 314         return this.body || this.frameBody || this.el;
 315     },
 316
 317     getContentTarget: function() {
 318         return this.body;
 319     },
 320
 321 <span id='Ext-form-FieldSet-method-getRefItems'>    /**
 322 </span>     * @private
 323      * Include the legend component in the items for ComponentQuery
 324      */
 325     getRefItems: function(deep) {
 326         var refItems = this.callParent(arguments),
 327             legend = this.legend;
 328
 329         // Prepend legend items to ensure correct order
 330         if (legend) {
 331             refItems.unshift(legend);
 332             if (deep) {
 333                 refItems.unshift.apply(refItems, legend.getRefItems(true));
 334             }
 335         }
 336         return refItems;
 337     },
 338
 339 <span id='Ext-form-FieldSet-method-expand'>    /**
 340 </span>     * Expands the fieldset.
 341      * @return {Ext.form.FieldSet} this
 342      */
 343     expand : function(){
 344         return this.setExpanded(true);
 345     },
 346
 347 <span id='Ext-form-FieldSet-method-collapse'>    /**
 348 </span>     * Collapses the fieldset.
 349      * @return {Ext.form.FieldSet} this
 350      */
 351     collapse : function() {
 352         return this.setExpanded(false);
 353     },
 354
 355 <span id='Ext-form-FieldSet-method-setExpanded'>    /**
 356 </span>     * @private Collapse or expand the fieldset
 357      */
 358     setExpanded: function(expanded) {
 359         var me = this,
 360             checkboxCmp = me.checkboxCmp;
 361
 362         expanded = !!expanded;
 363
 364         if (checkboxCmp) {
 365             checkboxCmp.setValue(expanded);
 366         }
 367
 368         if (expanded) {
 369             me.removeCls(me.baseCls + '-collapsed');
 370         } else {
 371             me.addCls(me.baseCls + '-collapsed');
 372         }
 373         me.collapsed = !expanded;
 374         if (expanded) {
 375             // ensure subitems will get rendered and layed out when expanding
 376             me.getComponentLayout().childrenChanged = true;
 377         }
 378         me.doComponentLayout();
 379         return me;
 380     },
 381
 382 <span id='Ext-form-FieldSet-method-toggle'>    /**
 383 </span>     * Toggle the fieldset's collapsed state to the opposite of what it is currently
 384      */
 385     toggle: function() {
 386         this.setExpanded(!!this.collapsed);
 387     },
 388
 389 <span id='Ext-form-FieldSet-method-onCheckChange'>    /**
 390 </span>     * @private Handle changes in the checkbox checked state
 391      */
 392     onCheckChange: function(cmp, checked) {
 393         this.setExpanded(checked);
 394     },
 395
 396     beforeDestroy : function() {
 397         var legend = this.legend;
 398         if (legend) {
 399             legend.destroy();
 400         }
 401         this.callParent();
 402     }
 403 });
 404 </pre>
 405 </body>
 406 </html>