/**
- * @class Ext.form.field.VTypes
- * <p>This is a singleton object which contains a set of commonly used field validation functions.
- * The validations provided are basic and intended to be easily customizable and extended.</p>
- * <p>To add custom VTypes specify the <code>{@link Ext.form.field.Text#vtype vtype}</code> validation
- * test function, and optionally specify any corresponding error text to display and any keystroke
- * filtering mask to apply. For example:</p>
- * <pre><code>
-// custom Vtype for vtype:'time'
-var timeTest = /^([1-9]|1[0-9]):([0-5][0-9])(\s[a|p]m)$/i;
-Ext.apply(Ext.form.field.VTypes, {
- // vtype validation function
- time: function(val, field) {
- return timeTest.test(val);
- },
- // vtype Text property: The error text to display when the validation function returns false
- timeText: 'Not a valid time. Must be in the format "12:34 PM".',
- // vtype Mask property: The keystroke filter mask
- timeMask: /[\d\s:amp]/i
-});
- * </code></pre>
- * Another example:
- * <pre><code>
-// custom Vtype for vtype:'IPAddress'
-Ext.apply(Ext.form.field.VTypes, {
- IPAddress: function(v) {
- return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(v);
- },
- IPAddressText: 'Must be a numeric IP address',
- IPAddressMask: /[\d\.]/i
-});
- * </code></pre>
- * @singleton
+ * @singleton
+ * @alternateClassName Ext.form.VTypes
+ *
+ * This is a singleton object which contains a set of commonly used field validation functions
+ * and provides a mechanism for creating reusable custom field validations.
+ * The following field validation functions are provided out of the box:
+ *
+ * - {@link #alpha}
+ * - {@link #alphanum}
+ * - {@link #email}
+ * - {@link #url}
+ *
+ * VTypes can be applied to a {@link Ext.form.field.Text Text Field} using the `{@link Ext.form.field.Text#vtype vtype}` configuration:
+ *
+ * Ext.create('Ext.form.field.Text', {
+ * fieldLabel: 'Email Address',
+ * name: 'email',
+ * vtype: 'email' // applies email validation rules to this field
+ * });
+ *
+ * To create custom VTypes:
+ *
+ * // custom Vtype for vtype:'time'
+ * var timeTest = /^([1-9]|1[0-9]):([0-5][0-9])(\s[a|p]m)$/i;
+ * Ext.apply(Ext.form.field.VTypes, {
+ * // vtype validation function
+ * time: function(val, field) {
+ * return timeTest.test(val);
+ * },
+ * // vtype Text property: The error text to display when the validation function returns false
+ * timeText: 'Not a valid time. Must be in the format "12:34 PM".',
+ * // vtype Mask property: The keystroke filter mask
+ * timeMask: /[\d\s:amp]/i
+ * });
+ *
+ * In the above example the `time` function is the validator that will run when field validation occurs,
+ * `timeText` is the error message, and `timeMask` limits what characters can be typed into the field.
+ * Note that the `Text` and `Mask` functions must begin with the same name as the validator function.
+ *
+ * Using a custom validator is the same as using one of the build-in validators - just use the name of the validator function
+ * as the `{@link Ext.form.field.Text#vtype vtype}` configuration on a {@link Ext.form.field.Text Text Field}:
+ *
+ * Ext.create('Ext.form.field.Text', {
+ * fieldLabel: 'Departure Time',
+ * name: 'departureTime',
+ * vtype: 'time' // applies custom time validation rules to this field
+ * });
+ *
+ * Another example of a custom validator:
+ *
+ * // custom Vtype for vtype:'IPAddress'
+ * Ext.apply(Ext.form.field.VTypes, {
+ * IPAddress: function(v) {
+ * return /^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(v);
+ * },
+ * IPAddressText: 'Must be a numeric IP address',
+ * IPAddressMask: /[\d\.]/i
+ * });
+ *
+ * It's important to note that using {@link Ext#apply Ext.apply()} means that the custom validator function
+ * as well as `Text` and `Mask` fields are added as properties of the `Ext.form.field.VTypes` singleton.
*/
Ext.define('Ext.form.field.VTypes', (function(){
// closure these in so they are only created once.
@@ -62,13 +91,19 @@ Ext.define('Ext.form.field.VTypes', (function(){
alternateClassName: 'Ext.form.VTypes',
/**
- * The function used to validate email addresses. Note that this is a very basic validation -- complete
- * validation per the email RFC specifications is very complex and beyond the scope of this class, although
- * this function can be overridden if a more comprehensive validation scheme is desired. See the validation
- * section of the <a href="http://en.wikipedia.org/wiki/E-mail_address">Wikipedia article on email addresses</a>
- * for additional information. This implementation is intended to validate the following emails:<tt>
- * 'barney@example.de', 'barney.rubble@example.com', 'barney-rubble@example.coop', 'barney+rubble@example.com'
- * </tt>.
+ * The function used to validate email addresses. Note that this is a very basic validation - complete
+ * validation per the email RFC specifications is very complex and beyond the scope of this class, although this
+ * function can be overridden if a more comprehensive validation scheme is desired. See the validation section
+ * of the [Wikipedia article on email addresses][1] for additional information. This implementation is intended
+ * to validate the following emails:
+ *
+ * - `barney@example.de`
+ * - `barney.rubble@example.com`
+ * - `barney-rubble@example.coop`
+ * - `barney+rubble@example.com`
+ *
+ * [1]: http://en.wikipedia.org/wiki/E-mail_address
+ *
* @param {String} value The email address
* @return {Boolean} true if the RegExp test passed, and false if not.
*/
@@ -76,16 +111,15 @@ Ext.define('Ext.form.field.VTypes', (function(){
return email.test(v);
},
/**
- * The error text to display when the email validation function returns false. Defaults to:
- * <tt>'This field should be an e-mail address in the format "user@example.com"'</tt>
- * @type String
+ * @property {String} emailText
+ * The error text to display when the email validation function returns false.
+ * Defaults to: 'This field should be an e-mail address in the format "user@example.com"'
*/
'emailText' : 'This field should be an e-mail address in the format "user@example.com"',
/**
- * The keystroke filter mask to be applied on email input. See the {@link #email} method for
- * information about more complex email validation. Defaults to:
- * <tt>/[a-z0-9_\.\-@]/i</tt>
- * @type RegExp
+ * @property {RegExp} emailMask
+ * The keystroke filter mask to be applied on email input. See the {@link #email} method for information about
+ * more complex email validation. Defaults to: /[a-z0-9_\.\-@]/i
*/
'emailMask' : /[a-z0-9_\.\-@\+]/i,
@@ -98,9 +132,9 @@ Ext.define('Ext.form.field.VTypes', (function(){
return url.test(v);
},
/**
- * The error text to display when the url validation function returns false. Defaults to:
- * <tt>'This field should be a URL in the format "http:/'+'/www.example.com"'</tt>
- * @type String
+ * @property {String} urlText
+ * The error text to display when the url validation function returns false.
+ * Defaults to: 'This field should be a URL in the format "http:/'+'/www.example.com"'
*/
'urlText' : 'This field should be a URL in the format "http:/'+'/www.example.com"',
@@ -113,15 +147,14 @@ Ext.define('Ext.form.field.VTypes', (function(){
return alpha.test(v);
},
/**
- * The error text to display when the alpha validation function returns false. Defaults to:
- * <tt>'This field should only contain letters and _'</tt>
- * @type String
+ * @property {String} alphaText
+ * The error text to display when the alpha validation function returns false.
+ * Defaults to: 'This field should only contain letters and _'
*/
'alphaText' : 'This field should only contain letters and _',
/**
- * The keystroke filter mask to be applied on alpha input. Defaults to:
- * <tt>/[a-z_]/i</tt>
- * @type RegExp
+ * @property {RegExp} alphaMask
+ * The keystroke filter mask to be applied on alpha input. Defaults to: /[a-z_]/i
*/
'alphaMask' : /[a-z_]/i,
@@ -134,15 +167,14 @@ Ext.define('Ext.form.field.VTypes', (function(){
return alphanum.test(v);
},
/**
- * The error text to display when the alphanumeric validation function returns false. Defaults to:
- * <tt>'This field should only contain letters, numbers and _'</tt>
- * @type String
+ * @property {String} alphanumText
+ * The error text to display when the alphanumeric validation function returns false.
+ * Defaults to: 'This field should only contain letters, numbers and _'
*/
'alphanumText' : 'This field should only contain letters, numbers and _',
/**
- * The keystroke filter mask to be applied on alphanumeric input. Defaults to:
- * <tt>/[a-z0-9_]/i</tt>
- * @type RegExp
+ * @property {RegExp} alphanumMask
+ * The keystroke filter mask to be applied on alphanumeric input. Defaults to: /[a-z0-9_]/i
*/
'alphanumMask' : /[a-z0-9_]/i
};