X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..HEAD:/src/form/field/VTypes.js

diff --git a/src/form/field/VTypes.js b/src/form/field/VTypes.js
index 1beba733..d6828b57 100644
--- a/src/form/field/VTypes.js
+++ b/src/form/field/VTypes.js
@@ -13,38 +13,67 @@ If you are unsure which license is appropriate for your use, please contact the
 
 */
 /**
- * @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
+ * @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.
@@ -59,13 +88,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.
          */
@@ -73,16 +108,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,
 
@@ -95,9 +129,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"',
 
@@ -110,15 +144,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,
 
@@ -131,15 +164,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
     };