extjs/modern/modern/src/form/FieldSet.js

   1 /**
   2  * A FieldSet is a great way to visually separate elements of a form. It's normally used when you have a form with
   3  * fields that can be divided into groups - for example a customer's billing details in one fieldset and their shipping
   4  * address in another. A fieldset can be used inside a form or on its own elsewhere in your app. Fieldsets can
   5  * optionally have a title at the top and instructions at the bottom. Here's how we might create a FieldSet inside a
   6  * form:
   7  *
   8  *     @example
   9  *     Ext.create('Ext.form.Panel', {
  10  *         fullscreen: true,
  11  *         items: [
  12  *             {
  13  *                 xtype: 'fieldset',
  14  *                 title: 'About You',
  15  *                 instructions: 'Tell us all about yourself',
  16  *                 items: [
  17  *                     {
  18  *                         xtype: 'textfield',
  19  *                         name : 'firstName',
  20  *                         label: 'First Name'
  21  *                     },
  22  *                     {
  23  *                         xtype: 'textfield',
  24  *                         name : 'lastName',
  25  *                         label: 'Last Name'
  26  *                     }
  27  *                 ]
  28  *             }
  29  *         ]
  30  *     });
  31  *
  32  * Above we created a {@link Ext.form.Panel form} with a fieldset that contains two text fields. In this case, all
  33  * of the form fields are in the same fieldset, but for longer forms we may choose to use multiple fieldsets. We also
  34  * configured a {@link #title} and {@link #instructions} to give the user more information on filling out the form if
  35  * required.
  36  */
  37 Ext.define('Ext.form.FieldSet', {
  38     extend  : 'Ext.Container',
  39     alias   : 'widget.fieldset',
  40     requires: ['Ext.Title'],
  41
  42     config: {
  43         /**
  44          * @cfg
  45          * @inheritdoc
  46          */
  47         baseCls: Ext.baseCSSPrefix + 'form-fieldset',
  48
  49         /**
  50          * @cfg {String} title
  51          * Optional fieldset title, rendered just above the grouped fields.
  52          *
  53          * ## Example
  54          *
  55          *     Ext.create('Ext.form.Fieldset', {
  56          *         fullscreen: true,
  57          *
  58          *         title: 'Login',
  59          *
  60          *         items: [{
  61          *             xtype: 'textfield',
  62          *             label: 'Email'
  63          *         }]
  64          *     });
  65          *
  66          * @accessor
  67          */
  68         title: null,
  69
  70         /**
  71          * @cfg {String} instructions
  72          * Optional fieldset instructions, rendered just below the grouped fields.
  73          *
  74          * ## Example
  75          *
  76          *     Ext.create('Ext.form.Fieldset', {
  77          *         fullscreen: true,
  78          *
  79          *         instructions: 'Please enter your email address.',
  80          *
  81          *         items: [{
  82          *             xtype: 'textfield',
  83          *             label: 'Email'
  84          *         }]
  85          *     });
  86          *
  87          * @accessor
  88          */
  89         instructions: null
  90     },
  91
  92     /**
  93      * @private
  94      */
  95     applyTitle: function(title) {
  96         if (typeof title == 'string') {
  97             title = {title: title};
  98         }
  99
 100         Ext.applyIf(title, {
 101             docked : 'top',
 102             baseCls: this.getBaseCls() + '-title'
 103         });
 104
 105         return Ext.factory(title, Ext.Title, this._title);
 106     },
 107
 108     /**
 109      * @private
 110      */
 111     updateTitle: function(newTitle, oldTitle) {
 112         if (newTitle) {
 113             this.add(newTitle);
 114         }
 115         if (oldTitle) {
 116             this.remove(oldTitle);
 117         }
 118     },
 119
 120     /**
 121      * @private
 122      */
 123     getTitle: function() {
 124         var title = this._title;
 125
 126         if (title && title instanceof Ext.Title) {
 127             return title.getTitle();
 128         }
 129
 130         return title;
 131     },
 132
 133     /**
 134      * @private
 135      */
 136     applyInstructions: function(instructions) {
 137         if (typeof instructions == 'string') {
 138             instructions = {title: instructions};
 139         }
 140
 141         Ext.applyIf(instructions, {
 142             docked : 'bottom',
 143             baseCls: this.getBaseCls() + '-instructions'
 144         });
 145
 146         return Ext.factory(instructions, Ext.Title, this._instructions);
 147     },
 148
 149     /**
 150      * @private
 151      */
 152     updateInstructions: function(newInstructions, oldInstructions) {
 153         if (newInstructions) {
 154             this.add(newInstructions);
 155         }
 156         if (oldInstructions) {
 157             this.remove(oldInstructions);
 158         }
 159     },
 160
 161     /**
 162      * @private
 163      */
 164     getInstructions: function() {
 165         var instructions = this._instructions;
 166
 167         if (instructions && instructions instanceof Ext.Title) {
 168             return instructions.getTitle();
 169         }
 170
 171         return instructions;
 172     },
 173
 174     /**
 175      * A convenient method to disable all fields in this FieldSet
 176      * @return {Ext.form.FieldSet} This FieldSet
 177      */
 178
 179     updateDisabled: function(newDisabled) {
 180         this.getFieldsAsArray().forEach(function(field) {
 181             field.setDisabled(newDisabled);
 182         });
 183
 184         return this;
 185     },
 186
 187     /**
 188      * @private
 189      */
 190     getFieldsAsArray: function() {
 191         var fields = [],
 192             getFieldsFrom = function(item) {
 193                 if (item.isField) {
 194                     fields.push(item);
 195                 }
 196
 197                 if (item.isContainer) {
 198                     item.getItems().each(getFieldsFrom);
 199                 }
 200             };
 201
 202         this.getItems().each(getFieldsFrom);
 203
 204         return fields;
 205     }
 206 });