X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/0494b8d9b9bb03ab6c22b34dae81261e3cd7e3e6..7a654f8d43fdb43d78b63d90528bed6e86b608cc:/src/form/field/Base.js diff --git a/src/form/field/Base.js b/src/form/field/Base.js new file mode 100644 index 00000000..a7f7064c --- /dev/null +++ b/src/form/field/Base.js @@ -0,0 +1,781 @@ +/** + * @class Ext.form.field.Base + * @extends Ext.Component + +Base class for form fields that provides default event handling, rendering, and other common functionality +needed by all form field types. Utilizes the {@link Ext.form.field.Field} mixin for value handling and validation, +and the {@link Ext.form.Labelable} mixin to provide label and error message display. + +In most cases you will want to use a subclass, such as {@link Ext.form.field.Text} or {@link Ext.form.field.Checkbox}, +rather than creating instances of this class directly. However if you are implementing a custom form field, +using this as the parent class is recommended. + +__Values and Conversions__ + +Because BaseField implements the Field mixin, it has a main value that can be initialized with the +{@link #value} config and manipulated via the {@link #getValue} and {@link #setValue} methods. This main +value can be one of many data types appropriate to the current field, for instance a {@link Ext.form.field.Date Date} +field would use a JavaScript Date object as its value type. However, because the field is rendered as a HTML +input, this value data type can not always be directly used in the rendered field. + +Therefore BaseField introduces the concept of a "raw value". This is the value of the rendered HTML input field, +and is normally a String. The {@link #getRawValue} and {@link #setRawValue} methods can be used to directly +work with the raw value, though it is recommended to use getValue and setValue in most cases. + +Conversion back and forth between the main value and the raw value is handled by the {@link #valueToRaw} and +{@link #rawToValue} methods. If you are implementing a subclass that uses a non-String value data type, you +should override these methods to handle the conversion. + +__Rendering__ + +The content of the field body is defined by the {@link #fieldSubTpl} XTemplate, with its argument data +created by the {@link #getSubTplData} method. Override this template and/or method to create custom +field renderings. +{@img Ext.form.BaseField/Ext.form.BaseField.png Ext.form.BaseField BaseField component} +__Example usage:__ + + // A simple subclass of BaseField that creates a HTML5 search field. Redirects to the + // searchUrl when the Enter key is pressed. + Ext.define('Ext.form.SearchField', { + extend: 'Ext.form.field.Base', + alias: 'widget.searchfield', + + inputType: 'search', + + // Config defining the search URL + searchUrl: 'http://www.google.com/search?q={0}', + + // Add specialkey listener + initComponent: function() { + this.callParent(); + this.on('specialkey', this.checkEnterKey, this); + }, + + // Handle enter key presses, execute the search if the field has a value + checkEnterKey: function(field, e) { + var value = this.getValue(); + if (e.getKey() === e.ENTER && !Ext.isEmpty(value)) { + location.href = Ext.String.format(this.searchUrl, value); + } + } + }); + + Ext.create('Ext.form.Panel', { + title: 'BaseField Example', + bodyPadding: 5, + width: 250, + + // Fields will be arranged vertically, stretched to full width + layout: 'anchor', + defaults: { + anchor: '100%' + }, + items: [{ + xtype: 'searchfield', + fieldLabel: 'Search', + name: 'query' + }] + renderTo: Ext.getBody() + }); + + * @constructor + * Creates a new Field + * @param {Object} config Configuration options + * + * @xtype field + * @markdown + * @docauthor Jason Johnston + */ +Ext.define('Ext.form.field.Base', { + extend: 'Ext.Component', + mixins: { + labelable: 'Ext.form.Labelable', + field: 'Ext.form.field.Field' + }, + alias: 'widget.field', + alternateClassName: ['Ext.form.Field', 'Ext.form.BaseField'], + requires: ['Ext.util.DelayedTask', 'Ext.XTemplate', 'Ext.layout.component.field.Field'], + + fieldSubTpl: [ + 'name="{name}" ', + 'size="{size}" ', + 'tabIndex="{tabIdx}" ', + 'class="{fieldCls} {typeCls}" autocomplete="off" />', + { + compiled: true, + disableFormats: true + } + ], + + /** + * @cfg {String} name The name of the field (defaults to undefined). This is used as the parameter + * name when including the field value in a {@link Ext.form.Basic#submit form submit()}. If no name is + * configured, it falls back to the {@link #inputId}. To prevent the field from being included in the + * form submit, set {@link #submitValue} to false. + */ + + /** + * @cfg {String} inputType + *

The type attribute for input fields -- e.g. radio, text, password, file (defaults to 'text'). + * The extended types supported by HTML5 inputs (url, email, etc.) may also be used, though using them + * will cause older browsers to fall back to 'text'.

+ *

The type 'password' must be used to render that field type currently -- there is no separate Ext + * component for that. You can use {@link Ext.form.field.File} which creates a custom-rendered file upload + * field, but if you want a plain unstyled file input you can use a BaseField with inputType:'file'.

+ */ + inputType: 'text', + + /** + * @cfg {Number} tabIndex The tabIndex for this field. Note this only applies to fields that are rendered, + * not those which are built via applyTo (defaults to undefined). + */ + + /** + * @cfg {String} invalidText The error text to use when marking a field invalid and no message is provided + * (defaults to 'The value in this field is invalid') + */ + invalidText : 'The value in this field is invalid', + + /** + * @cfg {String} fieldCls The default CSS class for the field input (defaults to 'x-form-field') + */ + fieldCls : Ext.baseCSSPrefix + 'form-field', + + /** + * @cfg {String} fieldStyle Optional CSS style(s) to be applied to the {@link #inputEl field input element}. + * Should be a valid argument to {@link Ext.core.Element#applyStyles}. Defaults to undefined. See also the + * {@link #setFieldStyle} method for changing the style after initialization. + */ + + /** + * @cfg {String} focusCls The CSS class to use when the field receives focus (defaults to 'x-form-focus') + */ + focusCls : Ext.baseCSSPrefix + 'form-focus', + + /** + * @cfg {String} dirtyCls The CSS class to use when the field value {@link #isDirty is dirty}. + */ + dirtyCls : Ext.baseCSSPrefix + 'form-dirty', + + /** + * @cfg {Array} checkChangeEvents + *

A list of event names that will be listened for on the field's {@link #inputEl input element}, which + * will cause the field's value to be checked for changes. If a change is detected, the + * {@link #change change event} will be fired, followed by validation if the {@link #validateOnChange} + * option is enabled.

+ *

Defaults to ['change', 'propertychange'] in Internet Explorer, and ['change', 'input', + * 'textInput', 'keyup', 'dragdrop'] in other browsers. This catches all the ways that field values + * can be changed in most supported browsers; the only known exceptions at the time of writing are:

+ * + *

If you need to guarantee on-the-fly change notifications including these edge cases, you can call the + * {@link #checkChange} method on a repeating interval, e.g. using {@link Ext.TaskManager}, or if the field is + * within a {@link Ext.form.Panel}, you can use the FormPanel's {@link Ext.form.Panel#pollForChanges} + * configuration to set up such a task automatically.

+ */ + checkChangeEvents: Ext.isIE && (!document.documentMode || document.documentMode < 9) ? + ['change', 'propertychange'] : + ['change', 'input', 'textInput', 'keyup', 'dragdrop'], + + /** + * @cfg {Number} checkChangeBuffer + * Defines a timeout in milliseconds for buffering {@link #checkChangeEvents} that fire in rapid succession. + * Defaults to 50 milliseconds. + */ + checkChangeBuffer: 50, + + componentLayout: 'field', + + /** + * @cfg {Boolean} readOnly true to mark the field as readOnly in HTML + * (defaults to false). + *

Note: this only sets the element's readOnly DOM attribute. + * Setting readOnly=true, for example, will not disable triggering a + * ComboBox or Date; it gives you the option of forcing the user to choose + * via the trigger without typing in the text box. To hide the trigger use + * {@link Ext.form.field.Trigger#hideTrigger hideTrigger}.

+ */ + readOnly : false, + + /** + * @cfg {String} readOnlyCls The CSS class applied to the component's main element when it is {@link #readOnly}. + */ + readOnlyCls: Ext.baseCSSPrefix + 'form-readonly', + + /** + * @cfg {String} inputId + * The id that will be given to the generated input DOM element. Defaults to an automatically generated id. + * If you configure this manually, you must make sure it is unique in the document. + */ + + /** + * @cfg {Boolean} validateOnBlur + * Whether the field should validate when it loses focus (defaults to true). This will cause fields + * to be validated as the user steps through the fields in the form regardless of whether they are making + * changes to those fields along the way. See also {@link #validateOnChange}. + */ + validateOnBlur: true, + + // private + hasFocus : false, + + baseCls: Ext.baseCSSPrefix + 'field', + + maskOnDisable: false, + + // private + initComponent : function() { + var me = this; + + me.callParent(); + + me.subTplData = me.subTplData || {}; + + me.addEvents( + /** + * @event focus + * Fires when this field receives input focus. + * @param {Ext.form.field.Base} this + */ + 'focus', + /** + * @event blur + * Fires when this field loses input focus. + * @param {Ext.form.field.Base} this + */ + 'blur', + /** + * @event specialkey + * Fires when any key related to navigation (arrows, tab, enter, esc, etc.) is pressed. + * To handle other keys see {@link Ext.panel.Panel#keys} or {@link Ext.util.KeyMap}. + * You can check {@link Ext.EventObject#getKey} to determine which key was pressed. + * For example: 

+var form = new Ext.form.Panel({
+    ...
+    items: [{
+            fieldLabel: 'Field 1',
+            name: 'field1',
+            allowBlank: false
+        },{
+            fieldLabel: 'Field 2',
+            name: 'field2',
+            listeners: {
+                specialkey: function(field, e){
+                    // e.HOME, e.END, e.PAGE_UP, e.PAGE_DOWN,
+                    // e.TAB, e.ESC, arrow keys: e.LEFT, e.RIGHT, e.UP, e.DOWN
+                    if (e.{@link Ext.EventObject#getKey getKey()} == e.ENTER) {
+                        var form = field.up('form').getForm();
+                        form.submit();
+                    }
+                }
+            }
+        }
+    ],
+    ...
+});
+             *
+ * @param {Ext.form.field.Base} this + * @param {Ext.EventObject} e The event object + */ + 'specialkey' + ); + + // Init mixins + me.initLabelable(); + me.initField(); + + // Default name to inputId + if (!me.name) { + me.name = me.getInputId(); + } + }, + + /** + * Returns the input id for this field. If none was specified via the {@link #inputId} config, + * then an id will be automatically generated. + */ + getInputId: function() { + return this.inputId || (this.inputId = Ext.id()); + }, + + /** + * @protected Creates and returns the data object to be used when rendering the {@link #fieldSubTpl}. + * @return {Object} The template data + */ + getSubTplData: function() { + var me = this, + type = me.inputType, + inputId = me.getInputId(); + + return Ext.applyIf(me.subTplData, { + id: inputId, + name: me.name || inputId, + type: type, + size: me.size || 20, + cls: me.cls, + fieldCls: me.fieldCls, + tabIdx: me.tabIndex, + typeCls: Ext.baseCSSPrefix + 'form-' + (type === 'password' ? 'text' : type) + }); + }, + + /** + * @protected + * Gets the markup to be inserted into the outer template's bodyEl. For fields this is the + * actual input element. + */ + getSubTplMarkup: function() { + return this.getTpl('fieldSubTpl').apply(this.getSubTplData()); + }, + + initRenderTpl: function() { + var me = this; + if (!me.hasOwnProperty('renderTpl')) { + me.renderTpl = me.getTpl('labelableRenderTpl'); + } + return me.callParent(); + }, + + initRenderData: function() { + return Ext.applyIf(this.callParent(), this.getLabelableRenderData()); + }, + + /** + * Set the {@link #fieldStyle CSS style} of the {@link #inputEl field input element}. + * @param {String/Object/Function} style The style(s) to apply. Should be a valid argument to + * {@link Ext.core.Element#applyStyles}. + */ + setFieldStyle: function(style) { + var me = this, + inputEl = me.inputEl; + if (inputEl) { + inputEl.applyStyles(style); + } + me.fieldStyle = style; + }, + + // private + onRender : function() { + var me = this, + fieldStyle = me.fieldStyle, + renderSelectors = me.renderSelectors; + + Ext.applyIf(renderSelectors, me.getLabelableSelectors()); + + Ext.applyIf(renderSelectors, { + /** + * @property inputEl + * @type Ext.core.Element + * The input Element for this Field. Only available after the field has been rendered. + */ + inputEl: '.' + me.fieldCls + }); + + me.callParent(arguments); + + // Make the stored rawValue get set as the input element's value + me.setRawValue(me.rawValue); + + if (me.readOnly) { + me.setReadOnly(true); + } + if (me.disabled) { + me.disable(); + } + if (fieldStyle) { + me.setFieldStyle(fieldStyle); + } + + me.renderActiveError(); + }, + + initAria: function() { + var me = this; + me.callParent(); + + // Associate the field to the error message element + me.getActionEl().dom.setAttribute('aria-describedby', Ext.id(me.errorEl)); + }, + + getFocusEl: function() { + return this.inputEl; + }, + + isFileUpload: function() { + return this.inputType === 'file'; + }, + + extractFileInput: function() { + var me = this, + fileInput = me.isFileUpload() ? me.inputEl.dom : null, + clone; + if (fileInput) { + clone = fileInput.cloneNode(true); + fileInput.parentNode.replaceChild(clone, fileInput); + me.inputEl = Ext.get(clone); + } + return fileInput; + }, + + // private override to use getSubmitValue() as a convenience + getSubmitData: function() { + var me = this, + data = null, + val; + if (!me.disabled && me.submitValue && !me.isFileUpload()) { + val = me.getSubmitValue(); + if (val !== null) { + data = {}; + data[me.getName()] = val; + } + } + return data; + }, + + /** + *

Returns the value that would be included in a standard form submit for this field. This will be combined + * with the field's name to form a name=value pair in the {@link #getSubmitData submitted parameters}. + * If an empty string is returned then just the name= will be submitted; if null is returned + * then nothing will be submitted.

+ *

Note that the value returned will have been {@link #processRawValue processed} but may or may not have + * been successfully {@link #validate validated}.

+ * @return {String} The value to be submitted, or null. + */ + getSubmitValue: function() { + return this.processRawValue(this.getRawValue()); + }, + + /** + * Returns the raw value of the field, without performing any normalization, conversion, or validation. + * To get a normalized and converted value see {@link #getValue}. + * @return {String} value The raw String value of the field + */ + getRawValue: function() { + var me = this, + v = (me.inputEl ? me.inputEl.getValue() : Ext.value(me.rawValue, '')); + me.rawValue = v; + return v; + }, + + /** + * Sets the field's raw value directly, bypassing {@link #valueToRaw value conversion}, change detection, and + * validation. To set the value with these additional inspections see {@link #setValue}. + * @param {Mixed} value The value to set + * @return {Mixed} value The field value that is set + */ + setRawValue: function(value) { + var me = this; + value = Ext.value(value, ''); + me.rawValue = value; + + // Some Field subclasses may not render an inputEl + if (me.inputEl) { + me.inputEl.dom.value = value; + } + return value; + }, + + /** + *

Converts a mixed-type value to a raw representation suitable for displaying in the field. This allows + * controlling how value objects passed to {@link #setValue} are shown to the user, including localization. + * For instance, for a {@link Ext.form.field.Date}, this would control how a Date object passed to {@link #setValue} + * would be converted to a String for display in the field.

+ *

See {@link #rawToValue} for the opposite conversion.

+ *

The base implementation simply does a standard toString conversion, and converts + * {@link Ext#isEmpty empty values} to an empty string.

+ * @param {Mixed} value The mixed-type value to convert to the raw representation. + * @return {Mixed} The converted raw value. + */ + valueToRaw: function(value) { + return '' + Ext.value(value, ''); + }, + + /** + *

Converts a raw input field value into a mixed-type value that is suitable for this particular field type. + * This allows controlling the normalization and conversion of user-entered values into field-type-appropriate + * values, e.g. a Date object for {@link Ext.form.field.Date}, and is invoked by {@link #getValue}.

+ *

It is up to individual implementations to decide how to handle raw values that cannot be successfully + * converted to the desired object type.

+ *

See {@link #valueToRaw} for the opposite conversion.

+ *

The base implementation does no conversion, returning the raw value untouched.

+ * @param {Mixed} rawValue + * @return {Mixed} The converted value. + */ + rawToValue: function(rawValue) { + return rawValue; + }, + + /** + * Performs any necessary manipulation of a raw field value to prepare it for {@link #rawToValue conversion} + * and/or {@link #validate validation}, for instance stripping out ignored characters. In the base implementation + * it does nothing; individual subclasses may override this as needed. + * @param {Mixed} value The unprocessed string value + * @return {Mixed} The processed string value + */ + processRawValue: function(value) { + return value; + }, + + /** + * 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}), as the result of calling {@link #rawToValue} on + * the field's {@link #processRawValue processed} String value. To return the raw String value, see {@link #getRawValue}. + * @return {Mixed} value The field value + */ + getValue: function() { + var me = this, + val = me.rawToValue(me.processRawValue(me.getRawValue())); + me.value = val; + return val; + }, + + /** + * Sets a data value into the field and runs the change detection and validation. To set the value directly + * without these inspections see {@link #setRawValue}. + * @param {Mixed} value The value to set + * @return {Ext.form.field.Field} this + */ + setValue: function(value) { + var me = this; + me.setRawValue(me.valueToRaw(value)); + return me.mixins.field.setValue.call(me, value); + }, + + + //private + onDisable: function() { + var me = this, + inputEl = me.inputEl; + me.callParent(); + if (inputEl) { + inputEl.dom.disabled = true; + } + }, + + //private + onEnable: function() { + var me = this, + inputEl = me.inputEl; + me.callParent(); + if (inputEl) { + inputEl.dom.disabled = false; + } + }, + + /** + * Sets the read only state of this field. + * @param {Boolean} readOnly Whether the field should be read only. + */ + setReadOnly: function(readOnly) { + var me = this, + inputEl = me.inputEl; + if (inputEl) { + inputEl.dom.readOnly = readOnly; + inputEl.dom.setAttribute('aria-readonly', readOnly); + } + me[readOnly ? 'addCls' : 'removeCls'](me.readOnlyCls); + me.readOnly = readOnly; + }, + + // private + fireKey: function(e){ + if(e.isSpecialKey()){ + this.fireEvent('specialkey', this, Ext.create('Ext.EventObjectImpl', e)); + } + }, + + // private + initEvents : function(){ + var me = this, + inputEl = me.inputEl, + onChangeTask, + onChangeEvent; + if (inputEl) { + me.mon(inputEl, Ext.EventManager.getKeyEvent(), me.fireKey, me); + me.mon(inputEl, 'focus', me.onFocus, me); + + // standardise buffer across all browsers + OS-es for consistent event order. + // (the 10ms buffer for Editors fixes a weird FF/Win editor issue when changing OS window focus) + me.mon(inputEl, 'blur', me.onBlur, me, me.inEditor ? {buffer:10} : null); + + // listen for immediate value changes + onChangeTask = Ext.create('Ext.util.DelayedTask', me.checkChange, me); + me.onChangeEvent = onChangeEvent = function() { + onChangeTask.delay(me.checkChangeBuffer); + }; + Ext.each(me.checkChangeEvents, function(eventName) { + if (eventName === 'propertychange') { + me.usesPropertychange = true; + } + me.mon(inputEl, eventName, onChangeEvent); + }, me); + } + me.callParent(); + }, + + doComponentLayout: function() { + var me = this, + inputEl = me.inputEl, + usesPropertychange = me.usesPropertychange, + ename = 'propertychange', + onChangeEvent = me.onChangeEvent; + + // In IE if propertychange is one of the checkChangeEvents, we need to remove + // the listener prior to layout and re-add it after, to prevent it from firing + // needlessly for attribute and style changes applied to the inputEl. + if (usesPropertychange) { + me.mun(inputEl, ename, onChangeEvent); + } + me.callParent(arguments); + if (usesPropertychange) { + me.mon(inputEl, ename, onChangeEvent); + } + }, + + // private + preFocus: Ext.emptyFn, + + // private + onFocus: function() { + var me = this, + focusCls = me.focusCls, + inputEl = me.inputEl; + me.preFocus(); + if (focusCls && inputEl) { + inputEl.addCls(focusCls); + } + if (!me.hasFocus) { + me.hasFocus = true; + me.fireEvent('focus', me); + } + }, + + // private + beforeBlur : Ext.emptyFn, + + // private + onBlur : function(){ + var me = this, + focusCls = me.focusCls, + inputEl = me.inputEl; + me.beforeBlur(); + if (focusCls && inputEl) { + inputEl.removeCls(focusCls); + } + if (me.validateOnBlur) { + me.validate(); + } + me.hasFocus = false; + me.fireEvent('blur', me); + me.postBlur(); + }, + + // private + postBlur : Ext.emptyFn, + + + /** + * @private Called when the field's dirty state changes. Adds/removes the {@link #dirtyCls} on the main element. + * @param {Boolean} isDirty + */ + onDirtyChange: function(isDirty) { + this[isDirty ? 'addCls' : 'removeCls'](this.dirtyCls); + }, + + + /** + * Returns whether or not the field value is currently valid by + * {@link #getErrors validating} the {@link #processRawValue processed raw value} + * of the field. Note: {@link #disabled} fields are always treated as valid. + * @return {Boolean} True if the value is valid, else false + */ + isValid : function() { + var me = this; + return me.disabled || me.validateValue(me.processRawValue(me.getRawValue())); + }, + + + /** + *

Uses {@link #getErrors} to build an array of validation errors. If any errors are found, they are passed + * to {@link #markInvalid} and false is returned, otherwise true is returned.

+ *

Previously, subclasses were invited to provide an implementation of this to process validations - from 3.2 + * onwards {@link #getErrors} should be overridden instead.

+ * @param {Mixed} value The value to validate + * @return {Boolean} True if all validations passed, false if one or more failed + */ + validateValue: function(value) { + var me = this, + errors = me.getErrors(value), + isValid = Ext.isEmpty(errors); + if (!me.preventMark) { + if (isValid) { + me.clearInvalid(); + } else { + me.markInvalid(errors); + } + } + + return isValid; + }, + + /** + *

Display one or more error messages associated with this field, using {@link #msgTarget} to determine how to + * display the messages and applying {@link #invalidCls} to the field's UI element.

+ *

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/Array} errors The validation message(s) to display. + */ + markInvalid : function(errors) { + // Save the message and fire the 'invalid' event + var me = this, + oldMsg = me.getActiveError(); + me.setActiveErrors(Ext.Array.from(errors)); + if (oldMsg !== me.getActiveError()) { + me.doComponentLayout(); + } + }, + + /** + *

Clear any invalid styles/messages for this field.

+ *

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 : function() { + // Clear the message and fire the 'valid' event + var me = this, + hadError = me.hasActiveError(); + me.unsetActiveError(); + if (hadError) { + me.doComponentLayout(); + } + }, + + /** + * @private Overrides the method from the Ext.form.Labelable mixin to also add the invalidCls to the inputEl, + * as that is required for proper styling in IE with nested fields (due to lack of child selector) + */ + renderActiveError: function() { + var me = this, + hasError = me.hasActiveError(); + if (me.inputEl) { + // Add/remove invalid class + me.inputEl[hasError ? 'addCls' : 'removeCls'](me.invalidCls + '-field'); + } + me.mixins.labelable.renderActiveError.call(me); + }, + + + getActionEl: function() { + return this.inputEl || this.el; + } + +});