add extjs 6.0.1 sources

[extjs.git] / extjs / modern / modern / src / form / FieldSet.js

/**\r
 * A FieldSet is a great way to visually separate elements of a form. It's normally used when you have a form with\r
 * fields that can be divided into groups - for example a customer's billing details in one fieldset and their shipping\r
 * address in another. A fieldset can be used inside a form or on its own elsewhere in your app. Fieldsets can\r
 * optionally have a title at the top and instructions at the bottom. Here's how we might create a FieldSet inside a\r
 * form:\r
 *\r
 *     @example\r
 *     Ext.create('Ext.form.Panel', {\r
 *         fullscreen: true,\r
 *         items: [\r
 *             {\r
 *                 xtype: 'fieldset',\r
 *                 title: 'About You',\r
 *                 instructions: 'Tell us all about yourself',\r
 *                 items: [\r
 *                     {\r
 *                         xtype: 'textfield',\r
 *                         name : 'firstName',\r
 *                         label: 'First Name'\r
 *                     },\r
 *                     {\r
 *                         xtype: 'textfield',\r
 *                         name : 'lastName',\r
 *                         label: 'Last Name'\r
 *                     }\r
 *                 ]\r
 *             }\r
 *         ]\r
 *     });\r
 *\r
 * Above we created a {@link Ext.form.Panel form} with a fieldset that contains two text fields. In this case, all\r
 * of the form fields are in the same fieldset, but for longer forms we may choose to use multiple fieldsets. We also\r
 * configured a {@link #title} and {@link #instructions} to give the user more information on filling out the form if\r
 * required.\r
 */\r
Ext.define('Ext.form.FieldSet', {\r
    extend  : 'Ext.Container',\r
    alias   : 'widget.fieldset',\r
    requires: ['Ext.Title'],\r
\r
    config: {\r
        /**\r
         * @cfg\r
         * @inheritdoc\r
         */\r
        baseCls: Ext.baseCSSPrefix + 'form-fieldset',\r
\r
        /**\r
         * @cfg {String} title\r
         * Optional fieldset title, rendered just above the grouped fields.\r
         *\r
         * ## Example\r
         *\r
         *     Ext.create('Ext.form.Fieldset', {\r
         *         fullscreen: true,\r
         *\r
         *         title: 'Login',\r
         *\r
         *         items: [{\r
         *             xtype: 'textfield',\r
         *             label: 'Email'\r
         *         }]\r
         *     });\r
         * \r
         * @accessor\r
         */\r
        title: null,\r
\r
        /**\r
         * @cfg {String} instructions\r
         * Optional fieldset instructions, rendered just below the grouped fields.\r
         *\r
         * ## Example\r
         *\r
         *     Ext.create('Ext.form.Fieldset', {\r
         *         fullscreen: true,\r
         *\r
         *         instructions: 'Please enter your email address.',\r
         *\r
         *         items: [{\r
         *             xtype: 'textfield',\r
         *             label: 'Email'\r
         *         }]\r
         *     });\r
         * \r
         * @accessor\r
         */\r
        instructions: null\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    applyTitle: function(title) {\r
        if (typeof title == 'string') {\r
            title = {title: title};\r
        }\r
\r
        Ext.applyIf(title, {\r
            docked : 'top',\r
            baseCls: this.getBaseCls() + '-title'\r
        });\r
\r
        return Ext.factory(title, Ext.Title, this._title);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateTitle: function(newTitle, oldTitle) {\r
        if (newTitle) {\r
            this.add(newTitle);\r
        }\r
        if (oldTitle) {\r
            this.remove(oldTitle);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    getTitle: function() {\r
        var title = this._title;\r
\r
        if (title && title instanceof Ext.Title) {\r
            return title.getTitle();\r
        }\r
\r
        return title;\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    applyInstructions: function(instructions) {\r
        if (typeof instructions == 'string') {\r
            instructions = {title: instructions};\r
        }\r
\r
        Ext.applyIf(instructions, {\r
            docked : 'bottom',\r
            baseCls: this.getBaseCls() + '-instructions'\r
        });\r
\r
        return Ext.factory(instructions, Ext.Title, this._instructions);\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    updateInstructions: function(newInstructions, oldInstructions) {\r
        if (newInstructions) {\r
            this.add(newInstructions);\r
        }\r
        if (oldInstructions) {\r
            this.remove(oldInstructions);\r
        }\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    getInstructions: function() {\r
        var instructions = this._instructions;\r
\r
        if (instructions && instructions instanceof Ext.Title) {\r
            return instructions.getTitle();\r
        }\r
\r
        return instructions;\r
    },\r
\r
    /**\r
     * A convenient method to disable all fields in this FieldSet\r
     * @return {Ext.form.FieldSet} This FieldSet\r
     */\r
     \r
    updateDisabled: function(newDisabled) {\r
        this.getFieldsAsArray().forEach(function(field) {\r
            field.setDisabled(newDisabled);\r
        });\r
\r
        return this;\r
    },\r
\r
    /**\r
     * @private\r
     */\r
    getFieldsAsArray: function() {\r
        var fields = [],\r
            getFieldsFrom = function(item) {\r
                if (item.isField) {\r
                    fields.push(item);\r
                }\r
\r
                if (item.isContainer) {\r
                    item.getItems().each(getFieldsFrom);\r
                }\r
            };\r
\r
        this.getItems().each(getFieldsFrom);\r
\r
        return fields;\r
    }\r
});\r