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