/** + + + +The source code + + + + +/*! + * Ext JS Library 3.2.1 + * Copyright(c) 2006-2010 Ext JS, Inc. + * licensing@extjs.com + * http://www.extjs.com/license + */ +/** * @class Ext.form.Field * @extends Ext.BoxComponent * Base class for form fields that provides default event handling, sizing, value handling and other functionality. @@ -15,9 +22,15 @@ * @xtype field */ Ext.form.Field = Ext.extend(Ext.BoxComponent, { + /** + *The label Element associated with this Field. Only available after this Field has been rendered by a + * {@link form Ext.layout.FormLayout} layout manager.
+ * @type Ext.Element + * @property label + */ /** * @cfg {String} inputType The type attribute for input fields -- e.g. radio, text, password, file (defaults - * to "text"). The types "file" and "password" must be used to render those field types currently -- there are + * to 'text'). The types 'file' and 'password' must be used to render those field types currently -- there are * no separate Ext components for those. Note that if you use inputType:'file', {@link #emptyText} * is not supported and should be avoided. */ @@ -29,32 +42,37 @@ Ext.form.Field = Ext.extend(Ext.BoxComponent, { * @cfg {Mixed} value A value to initialize this field with (defaults to undefined). */ /** - * @cfg {String} name The field's HTML name attribute (defaults to ""). + * @cfg {String} name The field's HTML name attribute (defaults to ''). * Note: this property must be set if this field is to be automatically included with * {@link Ext.form.BasicForm#submit form submit()}. */ /** - * @cfg {String} cls A custom CSS class to apply to the field's underlying element (defaults to ""). + * @cfg {String} cls A custom CSS class to apply to the field's underlying element (defaults to ''). */ /** - * @cfg {String} invalidClass The CSS class to use when marking a field invalid (defaults to "x-form-invalid") + * @cfg {String} invalidClass The CSS class to use when marking a field invalid (defaults to 'x-form-invalid') */ - invalidClass : "x-form-invalid", + invalidClass : 'x-form-invalid', /** * @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") + * (defaults to 'The value in this field is invalid') */ - invalidText : "The value in this field is invalid", + invalidText : 'The value in this field is invalid', /** - * @cfg {String} focusClass The CSS class to use when the field receives focus (defaults to "x-form-focus") + * @cfg {String} focusClass The CSS class to use when the field receives focus (defaults to 'x-form-focus') + */ + focusClass : 'x-form-focus', + /** + * @cfg {Boolean} preventMark + * true to disable {@link #markInvalid marking the field invalid}. + * Defaults to false. */ - focusClass : "x-form-focus", /** * @cfg {String/Boolean} validationEvent The event that should initiate field validation. Set to false to disable - automatic validation (defaults to "keyup"). + automatic validation (defaults to 'keyup'). */ - validationEvent : "keyup", + validationEvent : 'keyup', /** * @cfg {Boolean} validateOnBlur Whether the field should validate when it loses focus (defaults to true). */ @@ -68,25 +86,24 @@ Ext.form.Field = Ext.extend(Ext.BoxComponent, { * @cfg {String/Object} autoCreateA {@link Ext.DomHelper DomHelper} element spec, or true for a default * element spec. Used to create the {@link Ext.Component#getEl Element} which will encapsulate this Component. * See {@link Ext.Component#autoEl autoEl} for details. Defaults to:
- *+ *{tag: "input", type: "text", size: "20", autocomplete: "off"}*/ - defaultAutoCreate : {tag: "input", type: "text", size: "20", autocomplete: "off"}, + defaultAutoCreate : {tag: 'input', type: 'text', size: '20', autocomplete: 'off'}, /** - * @cfg {String} fieldClass The default CSS class for the field (defaults to "x-form-field") + * @cfg {String} fieldClass The default CSS class for the field (defaults to 'x-form-field') */ - fieldClass : "x-form-field", + fieldClass : 'x-form-field', /** - * @cfg {String} msgTarget The location where error text should display. Should be one of the following values - * (defaults to 'qtip'): - *{tag: 'input', type: 'text', size: '20', autocomplete: 'off'}-Value Description ------------ ---------------------------------------------------------------------- -qtip Display a quick tip when the user hovers over the field -title Display a default browser title attribute popup -under Add a block div beneath the field containing the error text -side Add an error icon to the right of the field with a popup on hover -[element id] Add the error text directly to the innerHTML of the specified element -+ * @cfg {String} msgTargetThe location where the message text set through {@link #markInvalid} should display. + * Must be one of the following values:
+ *+ *
qtipDisplay a quick tip containing the message when the user hovers over the field. This is the default. + *{@link Ext.QuickTips#init Ext.QuickTips.init} must have been called for this setting to work. + **/ msgTarget : 'qtip', /** @@ -110,10 +127,18 @@ side Add an error icon to the right of the field with a popup on hover * disabled Fields will not be {@link Ext.form.BasicForm#submit submitted}. */ disabled : false, + /** + * @cfg {Boolean} submitValue False to clear the name attribute on the field so that it is not submitted during a form post. + * Defaults to true. + */ + submitValue: true, // private isFormField : true, + // private + msgDisplay: '', + // private hasFocus : false, @@ -194,9 +219,9 @@ var form = new Ext.form.FormPanel({ /** * Returns the {@link Ext.form.Field#name name} or {@link Ext.form.ComboBox#hiddenName hiddenName} * attribute of the field if available. - * @return {String} name The field {@link Ext.form.Field#name name} or {@link Ext.form.ComboBox#hiddenName hiddenName} + * @return {String} name The field {@link Ext.form.Field#name name} or {@link Ext.form.ComboBox#hiddenName hiddenName} */ - getName: function(){ + getName : function(){ return this.rendered && this.el.dom.name ? this.el.dom.name : this.name || this.id || ''; }, @@ -214,7 +239,9 @@ var form = new Ext.form.FormPanel({ this.autoEl = cfg; } Ext.form.Field.superclass.onRender.call(this, ct, position); - + if(this.submitValue === false){ + this.el.dom.removeAttribute('name'); + } var type = this.el.dom.type; if(type){ if(type == 'password'){ @@ -223,7 +250,7 @@ var form = new Ext.form.FormPanel({ this.el.addClass('x-form-'+type); } if(this.readOnly){ - this.el.dom.readOnly = true; + this.setReadOnly(true); } if(this.tabIndex !== undefined){ this.el.dom.setAttribute('tabIndex', this.tabIndex); @@ -234,7 +261,7 @@ var form = new Ext.form.FormPanel({ // private getItemCt : function(){ - return this.el.up('.x-form-item', 4); + return this.itemCt; }, // private @@ -271,6 +298,17 @@ var form = new Ext.form.FormPanel({ return String(this.getValue()) !== String(this.originalValue); }, + /** + * Sets the read only state of this field. + * @param {Boolean} readOnly Whether the field should be read only. + */ + setReadOnly : function(readOnly){ + if(this.rendered){ + this.el.dom.readOnly = readOnly; + } + this.readOnly = readOnly; + }, + // private afterRender : function(){ Ext.form.Field.superclass.afterRender.call(this); @@ -281,7 +319,7 @@ var form = new Ext.form.FormPanel({ // private fireKey : function(e){ if(e.isSpecialKey()){ - this.fireEvent("specialkey", this, e); + this.fireEvent('specialkey', this, e); } }, @@ -296,23 +334,34 @@ var form = new Ext.form.FormPanel({ // private initEvents : function(){ - this.mon(this.el, Ext.EventManager.useKeydown ? "keydown" : "keypress", this.fireKey, this); + this.mon(this.el, Ext.EventManager.useKeydown ? 'keydown' : 'keypress', this.fireKey, this); this.mon(this.el, 'focus', this.onFocus, this); - // fix weird FF/Win editor issue when changing OS window focus - var o = this.inEditor && Ext.isWindows && Ext.isGecko ? {buffer:10} : null; - this.mon(this.el, 'blur', this.onBlur, this, o); + // 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) + this.mon(this.el, 'blur', this.onBlur, this, this.inEditor ? {buffer:10} : null); }, + // private + preFocus: Ext.emptyFn, + // private onFocus : function(){ + this.preFocus(); if(this.focusClass){ this.el.addClass(this.focusClass); } if(!this.hasFocus){ this.hasFocus = true; + /** + *- + *
titleDisplay the message in a default browser title attribute popup.- + *
underAdd a block div beneath the field containing the error message.- + *
sideAdd an error icon to the right of the field, displaying the message in a popup on hover.- + *
[element id]Add the error message directly to the innerHTML of the specified element.The value that the Field had at the time it was last focused. This is the value that is passed + * to the {@link #change} event which is fired if the value has been changed when the Field is blurred.
+ *This will be undefined until the Field has been visited. Compare {@link #originalValue}.
+ * @type mixed + * @property startValue + */ this.startValue = this.getValue(); - this.fireEvent("focus", this); + this.fireEvent('focus', this); } }, @@ -326,18 +375,24 @@ var form = new Ext.form.FormPanel({ this.el.removeClass(this.focusClass); } this.hasFocus = false; - if(this.validationEvent !== false && this.validateOnBlur && this.validationEvent != "blur"){ + if(this.validationEvent !== false && (this.validateOnBlur || this.validationEvent == 'blur')){ this.validate(); } var v = this.getValue(); if(String(v) !== String(this.startValue)){ this.fireEvent('change', this, v, this.startValue); } - this.fireEvent("blur", this); + this.fireEvent('blur', this); + this.postBlur(); }, + // private + postBlur : Ext.emptyFn, + /** - * Returns whether or not the field value is currently valid + * Returns whether or not the field value is currently valid by + * {@link #validateValue validating} the {@link #processValue processed value} + * of the field. Note: {@link #disabled} fields are ignored. * @param {Boolean} preventMark True to disable marking the field invalid * @return {Boolean} True if the value is valid, else false */ @@ -364,62 +419,128 @@ var form = new Ext.form.FormPanel({ return false; }, - // protected - should be overridden by subclasses if necessary to prepare raw values for validation + /** + * This method should only be overridden if necessary to prepare raw values + * for validation (see {@link #validate} and {@link #isValid}). This method + * is expected to return the processed value for the field which will + * be used for validation (see validateValue method). + * @param {Mixed} value + */ processValue : function(value){ return value; }, - // private - // Subclasses should provide the validation implementation by overriding this - validateValue : function(value){ - return true; + /** + * Uses getErrors to build an array of validation errors. If any errors are found, markInvalid is called + * with the first 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 getErrors should be + * overridden instead. + * @param {Mixed} The current value of the field + * @return {Boolean} True if all validations passed, false if one or more failed + */ + validateValue : function(value) { + //currently, we only show 1 error at a time for a field, so just use the first one + var error = this.getErrors(value)[0]; + + if (error == undefined) { + return true; + } else { + this.markInvalid(error); + return false; + } + }, + + /** + * 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 + * @return {Array} All error messages for this field + */ + getErrors: function() { + return []; + }, + + /** + * Gets the active error message for this field. + * @return {String} Returns the active error message on the field, if there is no error, an empty string is returned. + */ + getActiveError : function(){ + return this.activeError || ''; }, /** - * Mark this field as invalid, using {@link #msgTarget} to determine how to display the error and - * applying {@link #invalidClass} to the field's element. + *Display an error message associated with this field, using {@link #msgTarget} to determine how to + * display the message and applying {@link #invalidClass} to the field's UI element.
+ *Note: this method does not cause the Field's {@link #validate} method to return
+ * {@link #isValid invalid}. * @param {String} msg (optional) The validation message (defaults to {@link #invalidText}) */ markInvalid : function(msg){ - if(!this.rendered || this.preventMark){ // not rendered - return; - } - msg = msg || this.invalidText; - - var mt = this.getMessageHandler(); - if(mt){ - mt.mark(this, msg); - }else if(this.msgTarget){ - this.el.addClass(this.invalidClass); - var t = Ext.getDom(this.msgTarget); - if(t){ - t.innerHTML = msg; - t.style.display = this.msgDisplay; + //don't set the error icon if we're not rendered or marking is prevented + if (this.rendered && !this.preventMark) { + msg = msg || this.invalidText; + + var mt = this.getMessageHandler(); + if(mt){ + mt.mark(this, msg); + }else if(this.msgTarget){ + this.el.addClass(this.invalidClass); + var t = Ext.getDom(this.msgTarget); + if(t){ + t.innerHTML = msg; + t.style.display = this.msgDisplay; + } } } - this.fireEvent('invalid', this, msg); + + this.setActiveError(msg); }, - + /** * Clear any invalid styles/messages for this field */ clearInvalid : function(){ - if(!this.rendered || this.preventMark){ // not rendered - return; - } - this.el.removeClass(this.invalidClass); - var mt = this.getMessageHandler(); - if(mt){ - mt.clear(this); - }else if(this.msgTarget){ + //don't remove the error icon if we're not rendered or marking is prevented + if (this.rendered && !this.preventMark) { this.el.removeClass(this.invalidClass); - var t = Ext.getDom(this.msgTarget); - if(t){ - t.innerHTML = ''; - t.style.display = 'none'; + var mt = this.getMessageHandler(); + if(mt){ + mt.clear(this); + }else if(this.msgTarget){ + this.el.removeClass(this.invalidClass); + var t = Ext.getDom(this.msgTarget); + if(t){ + t.innerHTML = ''; + t.style.display = 'none'; + } } } - this.fireEvent('valid', this); + + this.unsetActiveError(); + }, + + /** + * Sets the current activeError to the given string. Fires the 'invalid' event. + * This does not set up the error icon, only sets the message and fires the event. To show the error icon, + * use markInvalid instead, which calls this method internally + * @param {String} msg The error message + * @param {Boolean} suppressEvent True to suppress the 'invalid' event from being fired + */ + setActiveError: function(msg, suppressEvent) { + this.activeError = msg; + if (suppressEvent !== true) this.fireEvent('invalid', this, msg); + }, + + /** + * Clears the activeError and fires the 'valid' event. This is called internally by clearInvalid and would not + * usually need to be called manually + * @param {Boolean} suppressEvent True to suppress the 'invalid' event from being fired + */ + unsetActiveError: function(suppressEvent) { + delete this.activeError; + if (suppressEvent !== true) this.fireEvent('valid', this); }, // private @@ -433,7 +554,12 @@ var form = new Ext.form.FormPanel({ this.el.findParent('.x-form-field-wrap', 5, true); // else direct field wrap }, - // private + // Alignment for 'under' target + alignErrorEl : function(){ + this.errorEl.setWidth(this.getErrorCt().getWidth(true) - 20); + }, + + // Alignment for 'side' target alignErrorIcon : function(){ this.errorIcon.alignTo(this.el, 'tl-tr', [2, 0]); }, @@ -471,7 +597,7 @@ var form = new Ext.form.FormPanel({ * @return {Mixed} value The field value that is set */ setRawValue : function(v){ - return (this.el.dom.value = (Ext.isEmpty(v) ? '' : v)); + return this.rendered ? (this.el.dom.value = (Ext.isEmpty(v) ? '' : v)) : ''; }, /** @@ -491,26 +617,6 @@ var form = new Ext.form.FormPanel({ // private, does not work for all fields append : function(v){ this.setValue([this.getValue(), v].join('')); - }, - - // private - adjustSize : function(w, h){ - var s = Ext.form.Field.superclass.adjustSize.call(this, w, h); - s.width = this.adjustWidth(this.el.dom.tagName, s.width); - if(this.offsetCt){ - var ct = this.getItemCt(); - s.width -= ct.getFrameWidth('lr'); - s.height -= ct.getFrameWidth('tb'); - } - return s; - }, - - // private - adjustWidth : function(tag, w){ - if(typeof w == 'number' && (Ext.isIE && (Ext.isIE6 || !Ext.isStrict)) && /input|textarea/i.test(tag) && !this.inEditor){ - return w - 3; - } - return w; } /** @@ -560,8 +666,12 @@ Ext.form.MessageTargets = { return; } field.errorEl = elp.createChild({cls:'x-form-invalid-msg'}); - field.errorEl.setWidth(elp.getWidth(true)-20); + field.on('resize', field.alignErrorEl, field); + field.on('destroy', function(){ + Ext.destroy(this.errorEl); + }, field); } + field.alignErrorEl(); field.errorEl.update(msg); Ext.form.Field.msgFx[field.msgFx].show(field.errorEl, field); }, @@ -579,24 +689,31 @@ Ext.form.MessageTargets = { field.el.addClass(field.invalidClass); if(!field.errorIcon){ var elp = field.getErrorCt(); - if(!elp){ // field has no container el + // field has no container el + if(!elp){ field.el.dom.title = msg; return; } field.errorIcon = elp.createChild({cls:'x-form-invalid-icon'}); + if (field.ownerCt) { + field.ownerCt.on('afterlayout', field.alignErrorIcon, field); + field.ownerCt.on('expand', field.alignErrorIcon, field); + } + field.on('resize', field.alignErrorIcon, field); + field.on('destroy', function(){ + Ext.destroy(this.errorIcon); + }, field); } field.alignErrorIcon(); field.errorIcon.dom.qtip = msg; field.errorIcon.dom.qclass = 'x-form-invalid-tip'; field.errorIcon.show(); - field.on('resize', field.alignErrorIcon, field); }, clear: function(field){ field.el.removeClass(field.invalidClass); if(field.errorIcon){ field.errorIcon.dom.qtip = ''; field.errorIcon.hide(); - field.un('resize', field.alignErrorIcon, field); }else{ field.el.dom.title = ''; } @@ -639,6 +756,6 @@ Ext.form.Field.msgFx = { } }; Ext.reg('field', Ext.form.Field); - - + + \ No newline at end of filefalse+ * 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.