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>