[extjs.git] / extjs / classic / classic / src / form / field / Field.js

/**\r
 * This mixin provides a common interface for the logical behavior and state of form fields, including:\r
 *\r
 * - Getter and setter methods for field values\r
 * - Events and methods for tracking value and validity changes\r
 * - Methods for triggering validation\r
 *\r
 * **NOTE**: When implementing custom fields, it is most likely that you will want to extend the {@link Ext.form.field.Base}\r
 * component class rather than using this mixin directly, as BaseField contains additional logic for generating an\r
 * actual DOM complete with {@link Ext.form.Labelable label and error message} display and a form input field,\r
 * plus methods that bind the Field value getters and setters to the input field's value.\r
 *\r
 * If you do want to implement this mixin directly and don't want to extend {@link Ext.form.field.Base}, then\r
 * you will most likely want to override the following methods with custom implementations: {@link #getValue},\r
 * {@link #setValue}, and {@link #getErrors}. Other methods may be overridden as needed but their base\r
 * implementations should be sufficient for common cases. You will also need to make sure that {@link #initField}\r
 * is called during the component's initialization.\r
 */\r
Ext.define('Ext.form.field.Field', {\r
    mixinId: 'field',\r
\r
    /**\r
     * @property {Boolean} isFormField\r
     * Flag denoting that this component is a Field. Always true.\r
     */\r
    isFormField : true,\r
\r
    config: {\r
        /**\r
         * @cfg {Boolean/String} validation\r
         * This property, when a `String`, contributes its value to the error state of this\r
         * instance as reported by `getErrors`.\r
         */\r
        validation: null,\r
\r
        /**\r
         * @cfg {Ext.data.Field} validationField\r
         * When binding is used with a model, this maps to the underlying {@link Ext.data.field.Field} if\r
         * it is available. This can be used to validate the value against the model field without needing\r
         * to push the value back into the model.\r
         *\r
         * @private\r
         */\r
        validationField: null\r
    },\r
\r
    /**\r
     * @cfg {Object} value\r
     * A value to initialize this field with.\r
     */\r
\r
    /**\r
     * @cfg {String} name\r
     * The name of the field. By default this is used as the parameter name when including the\r
     * {@link #getSubmitData field value} in a {@link Ext.form.Basic#submit form submit()}. To prevent the field from\r
     * being included in the form submit, set {@link #submitValue} to false.\r
     */\r
\r
    /**\r
     * @cfg {Boolean} disabled\r
     * True to disable the field. Disabled Fields will not be {@link Ext.form.Basic#submit submitted}.\r
     */\r
    disabled : false,\r
\r
    /**\r
     * @cfg {Boolean} submitValue\r
     * Setting this to false will prevent the field from being {@link Ext.form.Basic#submit submitted} even when it is\r
     * not disabled.\r
     */\r
    submitValue: true,\r
\r
    /**\r
     * @cfg {Boolean} validateOnChange\r
     * Specifies whether this field should be validated immediately whenever a change in its value is detected.\r
     * If the validation results in a change in the field's validity, a {@link #validitychange} event will be\r
     * fired. This allows the field to show feedback about the validity of its contents immediately as the user is\r
     * typing.\r
     *\r
     * When set to false, feedback will not be immediate. However the form will still be validated before submitting if\r
     * the clientValidation option to {@link Ext.form.Basic#doAction} is enabled, or if the field or form are validated\r
     * manually.\r
     *\r
     * See also {@link Ext.form.field.Base#checkChangeEvents} for controlling how changes to the field's value are\r
     * detected.\r
     */\r
    validateOnChange: true,\r
\r
    /**\r
     * @cfg {String[]/String} valuePublishEvent\r
     * The event name(s) to use to publish the {@link #value}\r
     * {@link Ext.form.field.Base#bind} for this field.\r
     * @since 5.0.1\r
     */\r
    valuePublishEvent: 'change',\r
\r
    /**\r
     * @private\r
     */\r
    suspendCheckChange: 0,\r
    \r
    /**\r
     * @property {Boolean} dirty\r
     * The dirty state of the field.\r
     * @private\r
     */\r
    dirty: false,\r
\r
    /**\r
     * @event change\r
     * Fires when the value of a field is changed. The value of a field is \r
     * checked for changes when the field's {@link #setValue} method \r
     * is called and when any of the events listed in \r
     * {@link Ext.form.field.Base#checkChangeEvents checkChangeEvents} are fired.\r
     * @param {Ext.form.field.Field} this\r
     * @param {Object} newValue The new value\r
     * @param {Object} oldValue The original value\r
     */\r
\r
    /**\r
     * @event validitychange\r
     * Fires when a change in the field's validity is detected.\r
     * @param {Ext.form.field.Field} this\r
     * @param {Boolean} isValid Whether or not the field is now valid\r
     */\r
\r
    /**\r
     * @event dirtychange\r
     * Fires when a change in the field's {@link #isDirty} state is detected.\r
     * @param {Ext.form.field.Field} this\r
     * @param {Boolean} isDirty Whether or not the field is now dirty\r
     */\r
\r
    /**\r
     * Initializes this Field mixin on the current instance. Components using this mixin should call this method during\r
     * their own initialization process.\r
     */\r
    initField: function() {\r
        var me = this,\r
            valuePublishEvent = me.valuePublishEvent,\r
            len, i;\r
\r
        me.initValue();\r
        \r
        //<debug>\r
        var badNames = [\r
            'tagName',\r
            'nodeName',\r
            'children',\r
            'childNodes'\r
        ], name = this.name;\r
            \r
        if (name && Ext.Array.indexOf(badNames, name) > -1) {\r
            Ext.log.warn(\r
                ['It is recommended to not use "', name, '" as a field name, because it ',\r
                'can cause naming collisions during form submission.'].join('')\r
            );\r
        }\r
        //</debug>\r
\r
        // Vast majority of cases won't be an array\r
        if (Ext.isString(valuePublishEvent)) {\r
            me.on(valuePublishEvent, me.publishValue, me);\r
        } else {\r
            for (i = 0, len = valuePublishEvent.length; i < len; ++i) {\r
                me.on(valuePublishEvent[i], me.publishValue, me);\r
            }\r
        }\r
    },\r
\r
    /**\r
     * Initializes the field's value based on the initial config.\r
     */\r
    initValue: function() {\r
        var me = this;\r
\r
        // Set the initial value if we have one.\r
        // Prevent validation on initial set.\r
        if ('value' in me) {\r
            me.suspendCheckChange++;\r
            me.setValue(me.value);\r
            me.suspendCheckChange--;\r
        }\r
        \r
        /**\r
         * @property {Object} originalValue\r
         * The original value of the field as configured in the {@link #value} configuration, or as loaded by the last\r
         * form load operation if the form's {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad} setting is `true`.\r
         */\r
        me.initialValue = me.originalValue = me.lastValue = me.getValue();\r
    },\r
\r
    // Fields can be editors, and some editors may not have a name property that maps\r
    // to its data index, so it's necessary in these cases to look it up by its dataIndex\r
    // property.  See EXTJSIV-11650.\r
    getFieldIdentifier: function () {\r
        return this.isEditorComponent ? this.dataIndex : this.name;\r
    },\r
\r
    /**\r
     * Returns the {@link Ext.form.field.Field#name name} attribute of the field. This is used as the parameter name\r
     * when including the field value in a {@link Ext.form.Basic#submit form submit()}.\r
     * @return {String} name The field {@link Ext.form.field.Field#name name}\r
     */\r
    getName: function() {\r
        return this.name;\r
    },\r
\r
    /**\r
     * Returns the current data value of the field. The type of value returned is particular to the type of the\r
     * particular field (e.g. a Date object for {@link Ext.form.field.Date}).\r
     * @return {Object} value The field value\r
     */\r
    getValue: function() {\r
        return this.value;\r
    },\r
\r
    /**\r
     * Sets a data value into the field and runs the change detection and validation.\r
     * @param {Object} value The value to set\r
     * @return {Ext.form.field.Field} this\r
     */\r
    setValue: function(value) {\r
        var me = this;\r
        me.value = value;\r
        me.checkChange();\r
        return me;\r
    },\r
\r
    /**\r
     * Returns whether two field {@link #getValue values} are logically equal. Field implementations may override this\r
     * to provide custom comparison logic appropriate for the particular field's data type.\r
     * @param {Object} value1 The first value to compare\r
     * @param {Object} value2 The second value to compare\r
     * @return {Boolean} True if the values are equal, false if inequal.\r
     */\r
    isEqual: function(value1, value2) {\r
        return String(value1) === String(value2);\r
    },\r
\r
    /**\r
     * Returns whether two values are logically equal.\r
     * Similar to {@link #isEqual}, however null or undefined values will be treated as empty strings.\r
     * @private\r
     * @param {Object} value1 The first value to compare\r
     * @param {Object} value2 The second value to compare\r
     * @return {Boolean} True if the values are equal, false if inequal.\r
     */\r
    isEqualAsString: function(value1, value2){\r
        return String(Ext.valueFrom(value1, '')) === String(Ext.valueFrom(value2, ''));\r
    },\r
\r
    /**\r
     * Returns the parameter(s) that would be included in a standard form submit for this field. Typically this will be\r
     * an object with a single name-value pair, the name being this field's {@link #getName name} and the value being\r
     * its current stringified value. More advanced field implementations may return more than one name-value pair.\r
     *\r
     * Note that the values returned from this method are not guaranteed to have been successfully {@link #validate\r
     * validated}.\r
     *\r
     * @return {Object} A mapping of submit parameter names to values; each value should be a string, or an array of\r
     * strings if that particular name has multiple values. It can also return null if there are no parameters to be\r
     * submitted.\r
     */\r
    getSubmitData: function() {\r
        var me = this,\r
            data = null;\r
        if (!me.disabled && me.submitValue) {\r
            data = {};\r
            data[me.getName()] = '' + me.getValue();\r
        }\r
        return data;\r
    },\r
\r
    /**\r
     * Returns the value(s) that should be saved to the {@link Ext.data.Model} instance for this field, when {@link\r
     * Ext.form.Basic#updateRecord} is called. Typically this will be an object with a single name-value pair, the name\r
     * being this field's {@link #getName name} and the value being its current data value. More advanced field\r
     * implementations may return more than one name-value pair. The returned values will be saved to the corresponding\r
     * field names in the Model.\r
     *\r
     * Note that the values returned from this method are not guaranteed to have been successfully {@link #validate\r
     * validated}.\r
     *\r
     * @return {Object} A mapping of submit parameter names to values; each value should be a string, or an array of\r
     * strings if that particular name has multiple values. It can also return null if there are no parameters to be\r
     * submitted.\r
     */\r
    getModelData: function(includeEmptyText, /*private*/ isSubmitting) {\r
        var me = this,\r
            data = null;\r
        \r
        // Note that we need to check if this operation is being called from a Submit action because displayfields aren't\r
        // to be submitted,  but they can call this to get their model data.\r
        if (!me.disabled && (me.submitValue || !isSubmitting)) {\r
            data = {};\r
            data[me.getFieldIdentifier()] = me.getValue();\r
        }\r
        return data;\r
    },\r
\r
    /**\r
     * Resets the current field value to the originally loaded value and clears any validation messages. See {@link\r
     * Ext.form.Basic}.{@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad}\r
     */\r
    reset: function(){\r
        var me = this;\r
\r
        me.beforeReset();\r
        me.setValue(me.originalValue);\r
        me.clearInvalid();\r
        // delete here so we reset back to the original state\r
        delete me.wasValid;\r
    },\r
    \r
    /**\r
     * Template method before a field is reset.\r
     * @protected\r
     */\r
    beforeReset: Ext.emptyFn,\r
\r
    /**\r
     * Resets the field's {@link #originalValue} property so it matches the current {@link #getValue value}. This is\r
     * called by {@link Ext.form.Basic}.{@link Ext.form.Basic#setValues setValues} if the form's\r
     * {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad} property is set to true.\r
     */\r
    resetOriginalValue: function() {\r
        this.originalValue = this.getValue();\r
        this.checkDirty();\r
    },\r
\r
    /**\r
     * Checks whether the value of the field has changed since the last time it was checked.\r
     * If the value has changed, it:\r
     *\r
     * 1. Fires the {@link #change change event},\r
     * 2. Performs validation if the {@link #validateOnChange} config is enabled, firing the\r
     *    {@link #validitychange validitychange event} if the validity has changed, and\r
     * 3. Checks the {@link #isDirty dirty state} of the field and fires the {@link #dirtychange dirtychange event}\r
     *    if it has changed.\r
     */\r
    checkChange: function() {\r
        var me = this,\r
            newVal, oldVal;\r
            \r
        if (!me.suspendCheckChange) {\r
            newVal = me.getValue();\r
            oldVal = me.lastValue;\r
                \r
            if (!me.destroyed && me.didValueChange(newVal, oldVal)) {\r
                me.lastValue = newVal;\r
                me.fireEvent('change', me, newVal, oldVal);\r
                me.onChange(newVal, oldVal);\r
            }\r
        }\r
    },\r
    \r
    /**\r
     * @private\r
     * Checks if the value has changed. Allows subclasses to override for\r
     * any more complex logic.\r
     */\r
    didValueChange: function(newVal, oldVal){\r
        return !this.isEqual(newVal, oldVal);\r
    },\r
\r
    /**\r
     * @private\r
     * Called when the field's value changes. Performs validation if the {@link #validateOnChange}\r
     * config is enabled, and invokes the dirty check.\r
     */\r
    onChange: function (newVal) {\r
        var me = this;\r
\r
        if (me.validateOnChange) {\r
            me.validate();\r
        }\r
\r
        me.checkDirty();\r
    },\r
\r
    /**\r
     * Publish the value of this field.\r
     *\r
     * @private\r
     */\r
    publishValue: function () {\r
        var me = this;\r
\r
        if (me.rendered && !me.getErrors().length) {\r
            me.publishState('value', me.getValue());\r
        }\r
    },\r
\r
    /**\r
     * Returns true if the value of this Field has been changed from its {@link #originalValue}.\r
     * Will always return false if the field is disabled.\r
     *\r
     * Note that if the owning {@link Ext.form.Basic form} was configured with\r
     * {@link Ext.form.Basic#trackResetOnLoad trackResetOnLoad} then the {@link #originalValue} is updated when\r
     * the values are loaded by {@link Ext.form.Basic}.{@link Ext.form.Basic#setValues setValues}.\r
     * @return {Boolean} True if this field has been changed from its original value (and is not disabled),\r
     * false otherwise.\r
     */\r
    isDirty : function() {\r
        var me = this;\r
        return !me.disabled && !me.isEqual(me.getValue(), me.originalValue);\r
    },\r
\r
    /**\r
     * Checks the {@link #isDirty} state of the field and if it has changed since the last time it was checked,\r
     * fires the {@link #dirtychange} event.\r
     */\r
    checkDirty: function() {\r
        var me = this,\r
            isDirty = me.isDirty();\r
        \r
        if (isDirty !== me.wasDirty) {\r
            me.dirty = isDirty;\r
            me.fireEvent('dirtychange', me, isDirty);\r
            me.onDirtyChange(isDirty);\r
            me.wasDirty = isDirty;\r
        }\r
    },\r
\r
    /**\r
     * @method\r
     * @private\r
     * Called when the field's dirty state changes.\r
     * @param {Boolean} isDirty\r
     */\r
    onDirtyChange: Ext.emptyFn,\r
\r
    /**\r
     * Runs this field's validators and returns an array of error messages for any validation failures. This is called\r
     * internally during validation and would not usually need to be used manually.\r
     *\r
     * Each subclass should override or augment the return value to provide their own errors.\r
     *\r
     * @param {Object} value The value to get errors for (defaults to the current field value)\r
     * @return {String[]} All error messages for this field; an empty Array if none.\r
     */\r
    getErrors: function (value) {\r
        var errors = [],\r
            validationField = this.getValidationField(),\r
            validation = this.getValidation(),\r
            result;\r
\r
        if (validationField) {\r
            result = validationField.validate(value);\r
            if (result !== true) {\r
                errors.push(result);\r
            }\r
        }\r
\r
        if (validation && validation !== true) {\r
            errors.push(validation);\r
        }\r
\r
        return errors;\r
    },\r
\r
    /**\r
     * Returns whether or not the field value is currently valid by {@link #getErrors validating} the field's current\r
     * value. The {@link #validitychange} event will not be fired; use {@link #validate} instead if you want the event\r
     * to fire. **Note**: {@link #disabled} fields are always treated as valid.\r
     *\r
     * Implementations are encouraged to ensure that this method does not have side-effects such as triggering error\r
     * message display.\r
     *\r
     * @return {Boolean} True if the value is valid, else false\r
     */\r
    isValid : function() {\r
        var me = this;\r
        return me.disabled || Ext.isEmpty(me.getErrors());\r
    },\r
\r
    /**\r
     * Returns whether or not the field value is currently valid by {@link #getErrors validating} the field's current\r
     * value, and fires the {@link #validitychange} event if the field's validity has changed since the last validation.\r
     * **Note**: {@link #disabled} fields are always treated as valid.\r
     *\r
     * Custom implementations of this method are allowed to have side-effects such as triggering error message display.\r
     * To validate without side-effects, use {@link #isValid}.\r
     *\r
     * @return {Boolean} True if the value is valid, else false\r
     */\r
    validate : function() {\r
        return this.checkValidityChange(this.isValid());\r
    },\r
\r
    checkValidityChange: function(isValid) {\r
        var me = this;\r
\r
        if (isValid !== me.wasValid) {\r
            me.wasValid = isValid;\r
            me.fireEvent('validitychange', me, isValid);\r
        }\r
        return isValid;\r
    },\r
\r
    /**\r
     * A utility for grouping a set of modifications which may trigger value changes into a single transaction, to\r
     * prevent excessive firing of {@link #change} events. This is useful for instance if the field has sub-fields which\r
     * are being updated as a group; you don't want the container field to check its own changed state for each subfield\r
     * change.\r
     * @param {Function} fn The function to call with change checks suspended.\r
     */\r
    batchChanges: function(fn) {\r
        try {\r
            this.suspendCheckChange++;\r
            fn();\r
        }\r
        catch (pseudo) {  //required with IE when using 'try'\r
            throw pseudo;\r
        }\r
        finally {\r
            this.suspendCheckChange--;\r
        }\r
        this.checkChange();\r
    },\r
\r
    /**\r
     * Returns whether this Field is a file upload field; if it returns true, forms will use special techniques for\r
     * {@link Ext.form.Basic#submit submitting the form} via AJAX. See {@link Ext.form.Basic#hasUpload} for details. If\r
     * this returns true, the {@link #extractFileInput} method must also be implemented to return the corresponding file\r
     * input element.\r
     * @return {Boolean}\r
     */\r
    isFileUpload: function() {\r
        return false;\r
    },\r
\r
    /**\r
     * Only relevant if the instance's {@link #isFileUpload} method returns true. Returns a reference to the file input\r
     * DOM element holding the user's selected file. The input will be appended into the submission form and will not be\r
     * returned, so this method should also create a replacement.\r
     * @return {HTMLElement}\r
     */\r
    extractFileInput: function() {\r
        return null;\r
    },\r
\r
    /**\r
     * @method\r
     * Display one or more error messages associated with this field, using \r
     * {@link Ext.form.Labelable#msgTarget} to determine how to display the messages and \r
     * applying {@link Ext.form.Labelable#invalidCls} to the field's UI element.\r
     *\r
     *     var formPanel = Ext.create('Ext.form.Panel', {\r
     *         title: 'Contact Info',\r
     *         width: 300,\r
     *         bodyPadding: 10,\r
     *         renderTo: Ext.getBody(),\r
     *         items: [{\r
     *             xtype: 'textfield',\r
     *             name: 'name',\r
     *             id: 'nameId',\r
     *             fieldLabel: 'Name'\r
     *         }],\r
     *         bbar: [{\r
     *             text: 'Mark both fields invalid',\r
     *             handler: function() {\r
     *                 var nameField = formPanel.getForm().findField('name');\r
     *                 nameField.markInvalid('Name invalid message');\r
     *     \r
     *                 // multiple error string syntax\r
     *                 // nameField.markInvalid(['First message', 'Second message']);\r
     *             }\r
     *         }]\r
     *     });\r
     * \r
     * **Note**: this method does not cause the Field's {@link #validate} or \r
     * {@link #isValid} methods to return `false` if the value does _pass_ validation. \r
     * So simply marking a Field as invalid will not prevent submission of forms\r
     * submitted with the {@link Ext.form.action.Submit#clientValidation} option set.\r
     * \r
     * @param {String/String[]} errors The validation message(s) to display.\r
     */\r
    markInvalid: Ext.emptyFn,\r
\r
    /**\r
     * @method clearInvalid\r
     * Clear any invalid styles/messages for this field. Components using this mixin should implement this method to\r
     * update the components rendering to clear any existing messages.\r
     *\r
     * **Note**: this method does not cause the Field's {@link #validate} or {@link #isValid} methods to return `true`\r
     * if the value does not _pass_ validation. So simply clearing a field's errors will not necessarily allow\r
     * submission of forms submitted with the {@link Ext.form.action.Submit#clientValidation} option set.\r
     */\r
    clearInvalid: Ext.emptyFn,\r
\r
    updateValidation: function(validation, oldValidation) {\r
        // Only validate if the validation is changing, not when we initial set it,\r
        // otherwise it will mark the field invalid as soon as it is bound.\r
        if (oldValidation) {\r
            this.validate();    \r
        }\r
    },\r
\r
    privates: {\r
        resetToInitialValue: function() {\r
            var me = this,\r
                originalValue = me.originalValue;\r
\r
            me.originalValue = me.initialValue;\r
            me.reset();\r
            me.originalValue = originalValue;\r
        }\r
     }\r
});\r