/**
- * @class Ext.form.field.Text
- * @extends Ext.form.field.Base
-
-A basic text field. Can be used as a direct replacement for traditional text inputs,
-or as the base class for more sophisticated input controls (like {@link Ext.form.field.TextArea}
-and {@link Ext.form.field.ComboBox}). Has support for empty-field placeholder values (see {@link #emptyText}).
-
-#Validation#
-
-The Text field has a useful set of validations built in:
-
-- {@link #allowBlank} for making the field required
-- {@link #minLength} for requiring a minimum value length
-- {@link #maxLength} for setting a maximum value length (with {@link #enforceMaxLength} to add it
- as the `maxlength` attribute on the input element)
-- {@link regex} to specify a custom regular expression for validation
-
-In addition, custom validations may be added:
-
-- {@link #vtype} specifies a virtual type implementation from {@link Ext.form.field.VTypes} which can contain
- custom validation logic
-- {@link #validator} allows a custom arbitrary function to be called during validation
-
-The details around how and when each of these validation options get used are described in the
-documentation for {@link #getErrors}.
-
-By default, the field value is checked for validity immediately while the user is typing in the
-field. This can be controlled with the {@link #validateOnChange}, {@link #checkChangeEvents}, and
-{@link #checkChangeBugger} configurations. Also see the details on Form Validation in the
-{@link Ext.form.Panel} class documentation.
-
-#Masking and Character Stripping#
-
-Text fields can be configured with custom regular expressions to be applied to entered values before
-validation: see {@link #maskRe} and {@link #stripCharsRe} for details.
-{@img Ext.form.Text/Ext.form.Text.png Ext.form.Text component}
-#Example usage:#
-
- Ext.create('Ext.form.Panel', {
- title: 'Contact Info',
- width: 300,
- bodyPadding: 10,
- renderTo: Ext.getBody(),
- items: [{
- xtype: 'textfield',
- name: 'name',
- fieldLabel: 'Name',
- allowBlank: false // requires a non-empty value
- }, {
- xtype: 'textfield',
- name: 'email',
- fieldLabel: 'Email Address',
- vtype: 'email' // requires value to be a valid email address format
- }]
- });
-
- * @constructor Creates a new TextField
- * @param {Object} config Configuration options
+
+
+
+
+ The source code
+
+
+
+
+
+
+
/**
+ * @docauthor Jason Johnston <jason@sencha.com>
+ *
+ * A basic text field. Can be used as a direct replacement for traditional text inputs,
+ * or as the base class for more sophisticated input controls (like {@link Ext.form.field.TextArea}
+ * and {@link Ext.form.field.ComboBox}). Has support for empty-field placeholder values (see {@link #emptyText}).
+ *
+ * # Validation
+ *
+ * The Text field has a useful set of validations built in:
+ *
+ * - {@link #allowBlank} for making the field required
+ * - {@link #minLength} for requiring a minimum value length
+ * - {@link #maxLength} for setting a maximum value length (with {@link #enforceMaxLength} to add it
+ * as the `maxlength` attribute on the input element)
+ * - {@link #regex} to specify a custom regular expression for validation
+ *
+ * In addition, custom validations may be added:
+ *
+ * - {@link #vtype} specifies a virtual type implementation from {@link Ext.form.field.VTypes} which can contain
+ * custom validation logic
+ * - {@link #validator} allows a custom arbitrary function to be called during validation
+ *
+ * The details around how and when each of these validation options get used are described in the
+ * documentation for {@link #getErrors}.
+ *
+ * By default, the field value is checked for validity immediately while the user is typing in the
+ * field. This can be controlled with the {@link #validateOnChange}, {@link #checkChangeEvents}, and
+ * {@link #checkChangeBuffer} configurations. Also see the details on Form Validation in the
+ * {@link Ext.form.Panel} class documentation.
+ *
+ * # Masking and Character Stripping
*
- * @xtype textfield
- * @markdown
- * @docauthor Jason Johnston <jason@sencha.com>
+ * Text fields can be configured with custom regular expressions to be applied to entered values before
+ * validation: see {@link #maskRe} and {@link #stripCharsRe} for details.
+ *
+ * # Example usage
+ *
+ * @example
+ * Ext.create('Ext.form.Panel', {
+ * title: 'Contact Info',
+ * width: 300,
+ * bodyPadding: 10,
+ * renderTo: Ext.getBody(),
+ * items: [{
+ * xtype: 'textfield',
+ * name: 'name',
+ * fieldLabel: 'Name',
+ * allowBlank: false // requires a non-empty value
+ * }, {
+ * xtype: 'textfield',
+ * name: 'email',
+ * fieldLabel: 'Email Address',
+ * vtype: 'email' // requires value to be a valid email address format
+ * }]
+ * });
*/
Ext.define('Ext.form.field.Text', {
extend:'Ext.form.field.Base',
@@ -68,162 +78,169 @@ Ext.define('Ext.form.field.Text', {
requires: ['Ext.form.field.VTypes', 'Ext.layout.component.field.Text'],
alternateClassName: ['Ext.form.TextField', 'Ext.form.Text'],
- /**
- * @cfg {String} vtypeText A custom error message to display in place of the default message provided
- * for the <b><code>{@link #vtype}</code></b> currently set for this field (defaults to <tt>undefined</tt>).
- * <b>Note</b>: only applies if <b><code>{@link #vtype}</code></b> is set, else ignored.
+ /**
+ * @cfg {String} vtypeText
+ * A custom error message to display in place of the default message provided for the **`{@link #vtype}`** currently
+ * set for this field. **Note**: only applies if **`{@link #vtype}`** is set, else ignored.
*/
-
- /**
- * @cfg {RegExp} stripCharsRe A JavaScript RegExp object used to strip unwanted content from the value
- * before validation (defaults to <tt>undefined</tt>).
+
+ /**
+ * @cfg {RegExp} stripCharsRe
+ * A JavaScript RegExp object used to strip unwanted content from the value
+ * before validation. If <tt>stripCharsRe</tt> is specified,
+ * every character matching <tt>stripCharsRe</tt> will be removed before fed to validation.
+ * This does not change the value of the field.
*/
- /**
- * @cfg {Number} size An initial value for the 'size' attribute on the text input element. This is only
- * used if the field has no configured {@link #width} and is not given a width by its container's layout.
- * Defaults to <tt>20</tt>.
+ /**
+ * @cfg {Number} size
+ * An initial value for the 'size' attribute on the text input element. This is only used if the field has no
+ * configured {@link #width} and is not given a width by its container's layout. Defaults to 20.
*/
size: 20,
- /**
- * @cfg {Boolean} grow <tt>true</tt> if this field should automatically grow and shrink to its content
- * (defaults to <tt>false</tt>)
+ /**
+ * @cfg {Boolean} [grow=false]
+ * true if this field should automatically grow and shrink to its content
*/
- /**
- * @cfg {Number} growMin The minimum width to allow when <code><b>{@link #grow}</b> = true</code> (defaults
- * to <tt>30</tt>)
+ /**
+ * @cfg {Number} growMin
+ * The minimum width to allow when `{@link #grow} = true`
*/
growMin : 30,
-
- /**
- * @cfg {Number} growMax The maximum width to allow when <code><b>{@link #grow}</b> = true</code> (defaults
- * to <tt>800</tt>)
+
+ /**
+ * @cfg {Number} growMax
+ * The maximum width to allow when `{@link #grow} = true`
*/
growMax : 800,
- /**
+ /**
* @cfg {String} growAppend
- * A string that will be appended to the field's current value for the purposes of calculating the target
- * field size. Only used when the {@link #grow} config is <tt>true</tt>. Defaults to a single capital "W"
- * (the widest character in common fonts) to leave enough space for the next typed character and avoid the
- * field value shifting before the width is adjusted.
+ * A string that will be appended to the field's current value for the purposes of calculating the target field
+ * size. Only used when the {@link #grow} config is true. Defaults to a single capital "W" (the widest character in
+ * common fonts) to leave enough space for the next typed character and avoid the field value shifting before the
+ * width is adjusted.
*/
growAppend: 'W',
-
- /**
- * @cfg {String} vtype A validation type name as defined in {@link Ext.form.field.VTypes} (defaults to <tt>undefined</tt>)
+
+ /**
+ * @cfg {String} vtype
+ * A validation type name as defined in {@link Ext.form.field.VTypes}
*/
- /**
- * @cfg {RegExp} maskRe An input mask regular expression that will be used to filter keystrokes that do
- * not match (defaults to <tt>undefined</tt>)
+ /**
+ * @cfg {RegExp} maskRe An input mask regular expression that will be used to filter keystrokes (character being
+ * typed) that do not match.
+ * Note: It dose not filter characters already in the input.
*/
- /**
- * @cfg {Boolean} disableKeyFilter Specify <tt>true</tt> to disable input keystroke filtering (defaults
- * to <tt>false</tt>)
+ /**
+ * @cfg {Boolean} [disableKeyFilter=false]
+ * Specify true to disable input keystroke filtering
*/
- /**
- * @cfg {Boolean} allowBlank Specify <tt>false</tt> to validate that the value's length is > 0 (defaults to
- * <tt>true</tt>)
+ /**
+ * @cfg {Boolean} allowBlank
+ * Specify false to validate that the value's length is > 0
*/
allowBlank : true,
-
- /**
- * @cfg {Number} minLength Minimum input field length required (defaults to <tt>0</tt>)
+
+ /**
+ * @cfg {Number} minLength
+ * Minimum input field length required
*/
minLength : 0,
-
- /**
- * @cfg {Number} maxLength Maximum input field length allowed by validation (defaults to Number.MAX_VALUE).
- * This behavior is intended to provide instant feedback to the user by improving usability to allow pasting
- * and editing or overtyping and back tracking. To restrict the maximum number of characters that can be
- * entered into the field use the <tt><b>{@link Ext.form.field.Text#enforceMaxLength enforceMaxLength}</b></tt> option.
+
+ /**
+ * @cfg {Number} maxLength
+ * Maximum input field length allowed by validation (defaults to Number.MAX_VALUE). This behavior is intended to
+ * provide instant feedback to the user by improving usability to allow pasting and editing or overtyping and back
+ * tracking. To restrict the maximum number of characters that can be entered into the field use the **{@link
+ * Ext.form.field.Text#enforceMaxLength enforceMaxLength}** option.
*/
maxLength : Number.MAX_VALUE,
-
- /**
- * @cfg {Boolean} enforceMaxLength True to set the maxLength property on the underlying input field. Defaults to <tt>false</tt>
+
+ /**
+ * @cfg {Boolean} enforceMaxLength
+ * True to set the maxLength property on the underlying input field. Defaults to false
*/
- /**
- * @cfg {String} minLengthText Error text to display if the <b><tt>{@link #minLength minimum length}</tt></b>
- * validation fails (defaults to <tt>'The minimum length for this field is {minLength}'</tt>)
+ /**
+ * @cfg {String} minLengthText
+ * Error text to display if the **{@link #minLength minimum length}** validation fails.
*/
minLengthText : 'The minimum length for this field is {0}',
-
- /**
- * @cfg {String} maxLengthText Error text to display if the <b><tt>{@link #maxLength maximum length}</tt></b>
- * validation fails (defaults to <tt>'The maximum length for this field is {maxLength}'</tt>)
+
+ /**
+ * @cfg {String} maxLengthText
+ * Error text to display if the **{@link #maxLength maximum length}** validation fails
*/
maxLengthText : 'The maximum length for this field is {0}',
-
- /**
- * @cfg {Boolean} selectOnFocus <tt>true</tt> to automatically select any existing field text when the field
- * receives input focus (defaults to <tt>false</tt>)
+
+ /**
+ * @cfg {Boolean} [selectOnFocus=false]
+ * true to automatically select any existing field text when the field receives input focus
*/
-
- /**
- * @cfg {String} blankText The error text to display if the <b><tt>{@link #allowBlank}</tt></b> validation
- * fails (defaults to <tt>'This field is required'</tt>)
+
+ /**
+ * @cfg {String} blankText
+ * The error text to display if the **{@link #allowBlank}** validation fails
*/
blankText : 'This field is required',
-
- /**
+
+ /**
* @cfg {Function} validator
- * <p>A custom validation function to be called during field validation ({@link #getErrors})
- * (defaults to <tt>undefined</tt>). If specified, this function will be called first, allowing the
- * developer to override the default validation process.</p>
- * <br><p>This function will be passed the following Parameters:</p>
- * <div class="mdetail-params"><ul>
- * <li><code>value</code>: <i>Mixed</i>
- * <div class="sub-desc">The current field value</div></li>
- * </ul></div>
- * <br><p>This function is to Return:</p>
- * <div class="mdetail-params"><ul>
- * <li><code>true</code>: <i>Boolean</i>
- * <div class="sub-desc"><code>true</code> if the value is valid</div></li>
- * <li><code>msg</code>: <i>String</i>
- * <div class="sub-desc">An error message if the value is invalid</div></li>
- * </ul></div>
- */
-
- /**
- * @cfg {RegExp} regex A JavaScript RegExp object to be tested against the field value during validation
- * (defaults to <tt>undefined</tt>). If the test fails, the field will be marked invalid using
- * <b><tt>{@link #regexText}</tt></b>.
- */
-
- /**
- * @cfg {String} regexText The error text to display if <b><tt>{@link #regex}</tt></b> is used and the
- * test fails during validation (defaults to <tt>''</tt>)
+ * A custom validation function to be called during field validation ({@link #getErrors}).
+ * If specified, this function will be called first, allowing the developer to override the default validation
+ * process.
+ *
+ * This function will be passed the following parameters:
+ *
+ * @cfg {Object} validator.value The current field value
+ * @cfg {Boolean/String} validator.return
+ *
+ * - True if the value is valid
+ * - An error message if the value is invalid
+ */
+
+ /**
+ * @cfg {RegExp} regex A JavaScript RegExp object to be tested against the field value during validation.
+ * If the test fails, the field will be marked invalid using
+ * either <b><tt>{@link #regexText}</tt></b> or <b><tt>{@link #invalidText}</tt></b>.
+ */
+
+ /**
+ * @cfg {String} regexText
+ * The error text to display if **{@link #regex}** is used and the test fails during validation
*/
regexText : '',
-
- /**
+
+ /**
* @cfg {String} emptyText
- * <p>The default text to place into an empty field (defaults to <tt>undefined</tt>).</p>
- * <p>Note that normally this value will be submitted to the server if this field is enabled; to prevent this
- * you can set the {@link Ext.form.action.Action#submitEmptyText submitEmptyText} option of
- * {@link Ext.form.Basic#submit} to <tt>false</tt>.</p>
- * <p>Also note that if you use <tt>{@link #inputType inputType}:'file'</tt>, {@link #emptyText} is not
- * supported and should be avoided.</p>
+ * The default text to place into an empty field.
+ *
+ * Note that normally this value will be submitted to the server if this field is enabled; to prevent this you can
+ * set the {@link Ext.form.action.Action#submitEmptyText submitEmptyText} option of {@link Ext.form.Basic#submit} to
+ * false.
+ *
+ * Also note that if you use {@link #inputType inputType}:'file', {@link #emptyText} is not supported and should be
+ * avoided.
*/
- /**
- * @cfg {String} emptyCls The CSS class to apply to an empty field to style the <b><tt>{@link #emptyText}</tt></b>
- * (defaults to <tt>'x-form-empty-field'</tt>). This class is automatically added and removed as needed
- * depending on the current field value.
+ /**
+ * @cfg {String} [emptyCls='x-form-empty-field']
+ * The CSS class to apply to an empty field to style the **{@link #emptyText}**.
+ * This class is automatically added and removed as needed depending on the current field value.
*/
emptyCls : Ext.baseCSSPrefix + 'form-empty-field',
ariaRole: 'textbox',
- /**
- * @cfg {Boolean} enableKeyEvents <tt>true</tt> to enable the proxying of key events for the HTML input field (defaults to <tt>false</tt>)
+ /**
+ * @cfg {Boolean} [enableKeyEvents=false]
+ * true to enable the proxying of key events for the HTML input field
*/
componentLayout: 'textfield',
@@ -231,37 +248,33 @@ Ext.define('Ext.form.field.Text', {
initComponent : function(){
this.callParent();
this.addEvents(
- /**
+ /**
* @event autosize
- * Fires when the <tt><b>{@link #autoSize}</b></tt> function is triggered and the field is
- * resized according to the {@link #grow}/{@link #growMin}/{@link #growMax} configs as a result.
- * This event provides a hook for the developer to apply additional logic at runtime to resize the
- * field if needed.
+ * Fires when the **{@link #autoSize}** function is triggered and the field is resized according to the
+ * {@link #grow}/{@link #growMin}/{@link #growMax} configs as a result. This event provides a hook for the
+ * developer to apply additional logic at runtime to resize the field if needed.
* @param {Ext.form.field.Text} this This text field
* @param {Number} width The new field width
*/
'autosize',
- /**
+ /**
* @event keydown
- * Keydown input field event. This event only fires if <tt><b>{@link #enableKeyEvents}</b></tt>
- * is set to true.
+ * Keydown input field event. This event only fires if **{@link #enableKeyEvents}** is set to true.
* @param {Ext.form.field.Text} this This text field
* @param {Ext.EventObject} e
*/
'keydown',
- /**
+ /**
* @event keyup
- * Keyup input field event. This event only fires if <tt><b>{@link #enableKeyEvents}</b></tt>
- * is set to true.
+ * Keyup input field event. This event only fires if **{@link #enableKeyEvents}** is set to true.
* @param {Ext.form.field.Text} this This text field
* @param {Ext.EventObject} e
*/
'keyup',
- /**
+ /**
* @event keypress
- * Keypress input field event. This event only fires if <tt><b>{@link #enableKeyEvents}</b></tt>
- * is set to true.
+ * Keypress input field event. This event only fires if **{@link #enableKeyEvents}** is set to true.
* @param {Ext.form.field.Text} this This text field
* @param {Ext.EventObject} e
*/
@@ -273,7 +286,7 @@ Ext.define('Ext.form.field.Text', {
initEvents : function(){
var me = this,
el = me.inputEl;
-
+
me.callParent();
if(me.selectOnFocus || me.emptyText){
me.mon(el, 'mousedown', me.onMouseDown, me);
@@ -292,14 +305,15 @@ Ext.define('Ext.form.field.Text', {
}
},
- /**
- * @private override - treat undefined and null values as equal to an empty string value
+ /**
+ * @private
+ * Override. Treat undefined and null values as equal to an empty string value.
*/
isEqual: function(value1, value2) {
- return String(Ext.value(value1, '')) === String(Ext.value(value2, ''));
+ return this.isEqualAsString(value1, value2);
},
- /**
+ /**
* @private
* If grow=true, invoke the autoSize method when the field's value is changed.
*/
@@ -307,7 +321,7 @@ Ext.define('Ext.form.field.Text', {
this.callParent();
this.autoSize();
},
-
+
afterRender: function(){
var me = this;
if (me.enforceMaxLength) {
@@ -325,10 +339,10 @@ Ext.define('Ext.form.field.Text', {
}
},
- /**
- * Performs any necessary manipulation of a raw String value to prepare it for {@link #stringToValue conversion}
- * and/or {@link #validate validation}. For text fields this applies the configured {@link #stripCharsRe} to the
- * raw value.
+ /**
+ * Performs any necessary manipulation of a raw String value to prepare it for conversion and/or
+ * {@link #validate validation}. For text fields this applies the configured {@link #stripCharsRe}
+ * to the raw value.
* @param {String} value The unprocessed string value
* @return {String} The processed string value
*/
@@ -336,7 +350,7 @@ Ext.define('Ext.form.field.Text', {
var me = this,
stripRe = me.stripCharsRe,
newValue;
-
+
if (stripRe) {
newValue = value.replace(stripRe, '');
if (newValue !== value) {
@@ -375,10 +389,9 @@ Ext.define('Ext.form.field.Text', {
this.fireEvent('keypress', this, e);
},
- /**
+ /**
* Resets the current field value to the originally-loaded value and clears any validation messages.
- * Also adds <tt><b>{@link #emptyText}</b></tt> and <tt><b>{@link #emptyCls}</b></tt> if the
- * original value was blank.
+ * Also adds **{@link #emptyText}** and **{@link #emptyCls}** if the original value was blank.
*/
reset : function(){
this.callParent();
@@ -392,13 +405,13 @@ Ext.define('Ext.form.field.Text', {
if (me.rendered && emptyText) {
isEmpty = me.getRawValue().length < 1 && !me.hasFocus;
-
+
if (Ext.supports.Placeholder) {
me.inputEl.dom.placeholder = emptyText;
} else if (isEmpty) {
me.setRawValue(emptyText);
}
-
+
//all browsers need this because of a styling issue with chrome + placeholders.
//the text isnt vertically aligned when empty (and using the placeholder)
if (isEmpty) {
@@ -443,16 +456,21 @@ Ext.define('Ext.form.field.Text', {
// private
filterKeys : function(e){
- if(e.ctrlKey){
+ /*
+ * On European keyboards, the right alt key, Alt Gr, is used to type certain special characters.
+ * JS detects a keypress of this as ctrlKey & altKey. As such, we check that alt isn't pressed
+ * so we can still process these special characters.
+ */
+ if (e.ctrlKey && !e.altKey) {
return;
}
var key = e.getKey(),
charCode = String.fromCharCode(e.getCharCode());
-
+
if(Ext.isGecko && (e.isNavKeyPress() || key === e.BACKSPACE || (key === e.DELETE && e.button === -1))){
return;
}
-
+
if(!Ext.isGecko && e.isSpecialKey() && !charCode){
return;
}
@@ -461,11 +479,11 @@ Ext.define('Ext.form.field.Text', {
}
},
- /**
- * Returns the raw String value of the field, without performing any normalization, conversion, or validation.
- * Gets the current value of the input element if the field has been rendered, ignoring the value if it is the
+ /**
+ * Returns the raw String value of the field, without performing any normalization, conversion, or validation. Gets
+ * the current value of the input element if the field has been rendered, ignoring the value if it is the
* {@link #emptyText}. To get a normalized and converted value see {@link #getValue}.
- * @return {String} value The raw String value of the field
+ * @return {String} The raw String value of the field
*/
getRawValue: function() {
var me = this,
@@ -476,80 +494,79 @@ Ext.define('Ext.form.field.Text', {
return v;
},
- /**
+ /**
* Sets a data value into the field and runs the change detection and validation. Also applies any configured
* {@link #emptyText} for text fields. To set the value directly without these inspections see {@link #setRawValue}.
- * @param {Mixed} value The value to set
+ * @param {Object} value The value to set
* @return {Ext.form.field.Text} this
*/
setValue: function(value) {
var me = this,
inputEl = me.inputEl;
-
+
if (inputEl && me.emptyText && !Ext.isEmpty(value)) {
inputEl.removeCls(me.emptyCls);
}
-
+
me.callParent(arguments);
me.applyEmptyText();
return me;
},
- /**
-Validates a value according to the field's validation rules and returns an array of errors
-for any failing validations. Validation rules are processed in the following order:
-
-1. **Field specific validator**
-
- A validator offers a way to customize and reuse a validation specification.
- If a field is configured with a `{@link #validator}`
- function, it will be passed the current field value. The `{@link #validator}`
- function is expected to return either:
-
- - Boolean `true` if the value is valid (validation continues).
- - a String to represent the invalid message if invalid (validation halts).
-
-2. **Basic Validation**
-
- If the `{@link #validator}` has not halted validation,
- basic validation proceeds as follows:
-
- - `{@link #allowBlank}` : (Invalid message = `{@link #emptyText}`)
-
- Depending on the configuration of <code>{@link #allowBlank}</code>, a
- blank field will cause validation to halt at this step and return
- Boolean true or false accordingly.
-
- - `{@link #minLength}` : (Invalid message = `{@link #minLengthText}`)
-
- If the passed value does not satisfy the `{@link #minLength}`
- specified, validation halts.
-
- - `{@link #maxLength}` : (Invalid message = `{@link #maxLengthText}`)
-
- If the passed value does not satisfy the `{@link #maxLength}`
- specified, validation halts.
-
-3. **Preconfigured Validation Types (VTypes)**
-
- If none of the prior validation steps halts validation, a field
- configured with a `{@link #vtype}` will utilize the
- corresponding {@link Ext.form.field.VTypes VTypes} validation function.
- If invalid, either the field's `{@link #vtypeText}` or
- the VTypes vtype Text property will be used for the invalid message.
- Keystrokes on the field will be filtered according to the VTypes
- vtype Mask property.
-
-4. **Field specific regex test**
-
- If none of the prior validation steps halts validation, a field's
- configured <code>{@link #regex}</code> test will be processed.
- The invalid message for this test is configured with `{@link #regexText}`
-
- * @param {Mixed} value The value to validate. The processed raw value will be used if nothing is passed
- * @return {Array} Array of any validation errors
- * @markdown
+ /**
+ * Validates a value according to the field's validation rules and returns an array of errors
+ * for any failing validations. Validation rules are processed in the following order:
+ *
+ * 1. **Field specific validator**
+ *
+ * A validator offers a way to customize and reuse a validation specification.
+ * If a field is configured with a `{@link #validator}`
+ * function, it will be passed the current field value. The `{@link #validator}`
+ * function is expected to return either:
+ *
+ * - Boolean `true` if the value is valid (validation continues).
+ * - a String to represent the invalid message if invalid (validation halts).
+ *
+ * 2. **Basic Validation**
+ *
+ * If the `{@link #validator}` has not halted validation,
+ * basic validation proceeds as follows:
+ *
+ * - `{@link #allowBlank}` : (Invalid message = `{@link #emptyText}`)
+ *
+ * Depending on the configuration of `{@link #allowBlank}`, a
+ * blank field will cause validation to halt at this step and return
+ * Boolean true or false accordingly.
+ *
+ * - `{@link #minLength}` : (Invalid message = `{@link #minLengthText}`)
+ *
+ * If the passed value does not satisfy the `{@link #minLength}`
+ * specified, validation halts.
+ *
+ * - `{@link #maxLength}` : (Invalid message = `{@link #maxLengthText}`)
+ *
+ * If the passed value does not satisfy the `{@link #maxLength}`
+ * specified, validation halts.
+ *
+ * 3. **Preconfigured Validation Types (VTypes)**
+ *
+ * If none of the prior validation steps halts validation, a field
+ * configured with a `{@link #vtype}` will utilize the
+ * corresponding {@link Ext.form.field.VTypes VTypes} validation function.
+ * If invalid, either the field's `{@link #vtypeText}` or
+ * the VTypes vtype Text property will be used for the invalid message.
+ * Keystrokes on the field will be filtered according to the VTypes
+ * vtype Mask property.
+ *
+ * 4. **Field specific regex test**
+ *
+ * If none of the prior validation steps halts validation, a field's
+ * configured <code>{@link #regex}</code> test will be processed.
+ * The invalid message for this test is configured with `{@link #regexText}`
+ *
+ * @param {Object} value The value to validate. The processed raw value will be used if nothing is passed.
+ * @return {String[]} Array of any validation errors
*/
getErrors: function(value) {
var me = this,
@@ -601,10 +618,10 @@ for any failing validations. Validation rules are processed in the following ord
return errors;
},
- /**
+ /**
* Selects text in this field
- * @param {Number} start (optional) The index where the selection should start (defaults to 0)
- * @param {Number} end (optional) The index where the selection should end (defaults to the text length)
+ * @param {Number} [start=0] The index where the selection should start
+ * @param {Number} [end] The index where the selection should end (defaults to the text length)
*/
selectText : function(start, end){
var me = this,
@@ -613,7 +630,7 @@ for any failing validations. Validation rules are processed in the following ord
el = me.inputEl.dom,
undef,
range;
-
+
if (v.length > 0) {
start = start === undef ? 0 : start;
end = end === undef ? v.length : end;
@@ -633,10 +650,9 @@ for any failing validations. Validation rules are processed in the following ord
}
},
- /**
- * Automatically grows the field to accomodate the width of the text up to the maximum field width allowed.
- * This only takes effect if <tt>{@link #grow} = true</tt>, and fires the {@link #autosize} event if the
- * width changes.
+ /**
+ * Automatically grows the field to accomodate the width of the text up to the maximum field width allowed. This
+ * only takes effect if {@link #grow} = true, and fires the {@link #autosize} event if the width changes.
*/
autoSize: function() {
var me = this,
@@ -656,15 +672,17 @@ for any failing validations. Validation rules are processed in the following ord
this.getActionEl().dom.setAttribute('aria-required', this.allowBlank === false);
},
- /**
- * @protected override
- * To get the natural width of the inputEl, we do a simple calculation based on the
- * 'size' config. We use hard-coded numbers to approximate what browsers do natively,
- * to avoid having to read any styles which would hurt performance.
+ /**
+ * To get the natural width of the inputEl, we do a simple calculation based on the 'size' config. We use
+ * hard-coded numbers to approximate what browsers do natively, to avoid having to read any styles which would hurt
+ * performance. Overrides Labelable method.
+ * @protected
*/
getBodyNaturalWidth: function() {
return Math.round(this.size * 6.5) + 20;
}
});
-