add extjs 6.0.1 sources

[extjs.git] / extjs / classic / classic / src / form / FieldContainer.js

/**\r
 * FieldContainer is a derivation of {@link Ext.container.Container Container} that implements the\r
 * {@link Ext.form.Labelable Labelable} mixin. This allows it to be configured so that it is rendered with\r
 * a {@link #fieldLabel field label} and optional {@link #msgTarget error message} around its sub-items.\r
 * This is useful for arranging a group of fields or other components within a single item in a form, so\r
 * that it lines up nicely with other fields. A common use is for grouping a set of related fields under\r
 * a single label in a form.\r
 * \r
 * The container's configured {@link #cfg-items} will be layed out within the field body area according to the\r
 * configured {@link #layout} type. The default layout is `'autocontainer'`.\r
 * \r
 * Like regular fields, FieldContainer can inherit its decoration configuration from the\r
 * {@link Ext.form.Panel#fieldDefaults fieldDefaults} of an enclosing FormPanel. In addition,\r
 * FieldContainer itself can pass {@link #fieldDefaults} to any {@link Ext.form.Labelable fields}\r
 * it may itself contain.\r
 * \r
 * If you are grouping a set of {@link Ext.form.field.Checkbox Checkbox} or {@link Ext.form.field.Radio Radio}\r
 * fields in a single labeled container, consider using a {@link Ext.form.CheckboxGroup}\r
 * or {@link Ext.form.RadioGroup} instead as they are specialized for handling those types.\r
 *\r
 * # Example\r
 * \r
 *     @example\r
 *     Ext.create('Ext.form.Panel', {\r
 *         title: 'FieldContainer Example',\r
 *         width: 550,\r
 *         bodyPadding: 10,\r
 * \r
 *         items: [{\r
 *             xtype: 'fieldcontainer',\r
 *             fieldLabel: 'Last Three Jobs',\r
 *             labelWidth: 100,\r
 * \r
 *             // The body area will contain three text fields, arranged\r
 *             // horizontally, separated by draggable splitters.\r
 *             layout: 'hbox',\r
 *             items: [{\r
 *                 xtype: 'textfield',\r
 *                 flex: 1\r
 *             }, {\r
 *                 xtype: 'splitter'\r
 *             }, {\r
 *                 xtype: 'textfield',\r
 *                 flex: 1\r
 *             }, {\r
 *                 xtype: 'splitter'\r
 *             }, {\r
 *                 xtype: 'textfield',\r
 *                 flex: 1\r
 *             }]\r
 *         }],\r
 *         renderTo: Ext.getBody()\r
 *     });\r
 * \r
 * # Usage of fieldDefaults\r
 *\r
 *     @example\r
 *     Ext.create('Ext.form.Panel', {\r
 *         title: 'FieldContainer Example',\r
 *         width: 350,\r
 *         bodyPadding: 10,\r
 * \r
 *         items: [{\r
 *             xtype: 'fieldcontainer',\r
 *             fieldLabel: 'Your Name',\r
 *             labelWidth: 75,\r
 *             defaultType: 'textfield',\r
 * \r
 *             // Arrange fields vertically, stretched to full width\r
 *             layout: 'anchor',\r
 *             defaults: {\r
 *                 layout: '100%'\r
 *             },\r
 * \r
 *             // These config values will be applied to both sub-fields, except\r
 *             // for Last Name which will use its own msgTarget.\r
 *             fieldDefaults: {\r
 *                 msgTarget: 'under',\r
 *                 labelAlign: 'top'\r
 *             },\r
 * \r
 *             items: [{\r
 *                 fieldLabel: 'First Name',\r
 *                 name: 'firstName'\r
 *             }, {\r
 *                 fieldLabel: 'Last Name',\r
 *                 name: 'lastName',\r
 *                 msgTarget: 'under'\r
 *             }]\r
 *         }],\r
 *         renderTo: Ext.getBody()\r
 *     });\r
 */\r
Ext.define('Ext.form.FieldContainer', {\r
    extend: 'Ext.container.Container',\r
    mixins: {\r
        labelable: 'Ext.form.Labelable',\r
        fieldAncestor: 'Ext.form.FieldAncestor'\r
    },\r
    requires: 'Ext.layout.component.field.FieldContainer',\r
\r
    alias: 'widget.fieldcontainer',\r
\r
    componentLayout: 'fieldcontainer',\r
\r
    componentCls: Ext.baseCSSPrefix + 'form-fieldcontainer',\r
\r
    shrinkWrap: true,\r
    \r
    autoEl: {\r
        tag: 'div',\r
        role: 'presentation'\r
    },\r
\r
    childEls: [\r
        'containerEl'\r
    ],\r
\r
    /**\r
     * @cfg {Boolean} combineLabels\r
     * If set to true, and there is no defined {@link #fieldLabel}, the field container will automatically\r
     * generate its label by combining the labels of all the fields it contains. Defaults to false.\r
     */\r
    combineLabels: false,\r
\r
    //<locale>\r
    /**\r
     * @cfg {String} labelConnector\r
     * The string to use when joining the labels of individual sub-fields, when {@link #combineLabels} is\r
     * set to true. Defaults to ', '.\r
     */\r
    labelConnector: ', ',\r
    //</locale>\r
\r
    /**\r
     * @cfg {Boolean} combineErrors\r
     * If set to true, the field container will automatically combine and display the validation errors from\r
     * all the fields it contains as a single error on the container, according to the configured\r
     * {@link #msgTarget}. Defaults to false.\r
     */\r
    combineErrors: false,\r
\r
    maskOnDisable: false,\r
    // If we allow this to mark with the invalidCls it will cascade to all\r
    // child fields, let them handle themselves\r
    invalidCls: '',\r
\r
    fieldSubTpl: [\r
        '<div id="{id}-containerEl" data-ref="containerEl" class="{containerElCls}"',\r
            '<tpl if="ariaAttributes">',\r
                '<tpl foreach="ariaAttributes"> {$}="{.}"</tpl>',\r
            '<tpl else>',\r
                ' role="presentation"',\r
            '</tpl>',\r
        '>',\r
            '{%this.renderContainer(out,values)%}',\r
        '</div>'\r
    ],\r
\r
    initComponent: function() {\r
        var me = this;\r
\r
        // Init mixins\r
        me.initLabelable();\r
        me.initFieldAncestor();\r
        \r
        me.callParent();\r
        me.initMonitor();\r
    },\r
    \r
    /**\r
     * @protected\r
     * Called when a {@link Ext.form.Labelable} instance is added to the container's subtree.\r
     * @param {Ext.form.Labelable} labelItem The instance that was added\r
     */\r
    onAdd: function(labelItem) {\r
        var me = this;\r
\r
        // Fix for https://sencha.jira.com/browse/EXTJSIV-6424 Which was *sneakily* fixed fixed in version 37\r
        // In FF < 37, positioning absolutely within a TD positions relative to the TR!\r
        // So we must add the width of a visible, left-aligned label cell to the x coordinate.\r
        if (labelItem.isLabelable && Ext.isGecko && Ext.firefoxVersion < 37 && me.layout.type === 'absolute' && !me.hideLabel && me.labelAlign !== 'top') {\r
            labelItem.x += (me.labelWidth + me.labelPad);\r
        }\r
        me.callParent(arguments);\r
        if (labelItem.isLabelable && me.combineLabels) {\r
            labelItem.oldHideLabel = labelItem.hideLabel;\r
            labelItem.hideLabel = true;\r
        }\r
        me.updateLabel();\r
    },\r
\r
    /**\r
     * @protected\r
     * Called when a {@link Ext.form.Labelable} instance is removed from the container's subtree.\r
     * @param {Ext.form.Labelable} labelItem The instance that was removed\r
     */\r
    onRemove: function(labelItem, isDestroying) {\r
        var me = this;\r
        me.callParent(arguments);\r
        if (!isDestroying) {\r
            if (labelItem.isLabelable && me.combineLabels) {\r
                labelItem.hideLabel = labelItem.oldHideLabel;\r
            }\r
            me.updateLabel();\r
        }   \r
    },\r
\r
    initRenderData: function() {\r
        var me = this,\r
            data = me.callParent();\r
\r
        data.containerElCls = me.containerElCls;\r
        data = Ext.applyIf(data, me.getLabelableRenderData());\r
        data.tipAnchorTarget = me.id + '-containerEl';\r
        return data;\r
    },\r
\r
    /**\r
     * Returns the combined field label if {@link #combineLabels} is set to true and if there is no\r
     * set {@link #fieldLabel}. Otherwise returns the fieldLabel like normal. You can also override\r
     * this method to provide a custom generated label.\r
     * @template\r
     * @return {String} The label, or empty string if none.\r
     */\r
    getFieldLabel: function() {\r
        var label = this.fieldLabel || '';\r
        if (!label && this.combineLabels) {\r
            label = Ext.Array.map(this.query('[isFieldLabelable]'), function(field) {\r
                return field.getFieldLabel();\r
            }).join(this.labelConnector);\r
        }\r
        return label;\r
    },\r
\r
    getSubTplData: function() {\r
        var ret = this.initRenderData();\r
\r
        Ext.apply(ret, this.subTplData);\r
        return ret;\r
    },\r
\r
    getSubTplMarkup: function(fieldData) {\r
        var me = this,\r
            tpl = me.getTpl('fieldSubTpl'),\r
            html;\r
\r
        if (!tpl.renderContent) {\r
            me.setupRenderTpl(tpl);\r
        }\r
\r
        html = tpl.apply(me.getSubTplData(fieldData));\r
        return html;\r
    },\r
\r
    /**\r
     * @private\r
     * Updates the content of the labelEl if it is rendered\r
     */\r
    updateLabel: function() {\r
        var me = this,\r
            label = me.labelEl;\r
            \r
        if (label) {\r
            me.setFieldLabel(me.getFieldLabel());\r
        }\r
    },\r
\r
\r
    /**\r
     * @private\r
     * Fired when the error message of any field within the container changes, and updates the\r
     * combined error message to match.\r
     */\r
    onFieldErrorChange: function() {\r
        if (this.combineErrors) {\r
            var me = this,\r
                oldError = me.getActiveError(),\r
                invalidFields = Ext.Array.filter(me.query('[isFormField]'), function(field) {\r
                    return field.hasActiveError();\r
                }),\r
                newErrors = me.getCombinedErrors(invalidFields);\r
\r
            if (newErrors) {\r
                me.setActiveErrors(newErrors);\r
            } else {\r
                me.unsetActiveError();\r
            }\r
\r
            if (oldError !== me.getActiveError()) {\r
                me.updateLayout();\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Takes an Array of invalid {@link Ext.form.field.Field} objects and builds a combined list of error\r
     * messages from them. Defaults to prepending each message by the field name and a colon. This\r
     * can be overridden to provide custom combined error message handling, for instance changing\r
     * the format of each message or sorting the array (it is sorted in order of appearance by default).\r
     * @param {Ext.form.field.Field[]} invalidFields An Array of the sub-fields which are currently invalid.\r
     * @return {String[]} The combined list of error messages\r
     */\r
    getCombinedErrors: function(invalidFields) {\r
        var errors = [],\r
            f,\r
            fLen   = invalidFields.length,\r
            field,\r
            activeErrors, a, aLen,\r
            error, label;\r
\r
        for (f = 0; f < fLen; f++) {\r
            field = invalidFields[f];\r
            activeErrors = field.getActiveErrors();\r
            aLen         = activeErrors.length;\r
\r
            for (a = 0; a < aLen; a++) {\r
                error = activeErrors[a];\r
                label = field.getFieldLabel();\r
\r
                errors.push((label ? label + ': ' : '') + error);\r
            }\r
        }\r
\r
        return errors;\r
    },\r
\r
    privates: {\r
        applyTargetCls: function(targetCls) {\r
            var containerElCls = this.containerElCls;\r
\r
            this.containerElCls = containerElCls ? containerElCls + ' ' + targetCls : targetCls;\r
        },\r
\r
        getTargetEl: function() {\r
            return this.containerEl;\r
        },\r
\r
        initRenderTpl: function() {\r
            var me = this;\r
            if (!me.hasOwnProperty('renderTpl')) {\r
                me.renderTpl = me.getTpl('labelableRenderTpl');\r
            }\r
            return me.callParent();\r
        }\r
    }\r
});\r