Upgrade to ExtJS 4.0.7 - Released 10/19/2011
[extjs.git] / docs / source / VTypes.html
index f0967b1..4fd12b1 100644 (file)
@@ -1,36 +1,82 @@
-<!DOCTYPE html><html><head><title>Sencha Documentation Project</title><link rel="stylesheet" href="../reset.css" type="text/css"><link rel="stylesheet" href="../prettify.css" type="text/css"><link rel="stylesheet" href="../prettify_sa.css" type="text/css"><script type="text/javascript" src="../prettify.js"></script></head><body onload="prettyPrint()"><pre class="prettyprint"><pre><span id='Ext-form.field.VTypes'>/**
-</span> * @class Ext.form.field.VTypes
- * &lt;p&gt;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.&lt;/p&gt;
- * &lt;p&gt;To add custom VTypes specify the &lt;code&gt;{@link Ext.form.field.Text#vtype vtype}&lt;/code&gt; validation
- * test function, and optionally specify any corresponding error text to display and any keystroke
- * filtering mask to apply. For example:&lt;/p&gt;
- * &lt;pre&gt;&lt;code&gt;
-// 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 &quot;12:34 PM&quot;.',
-    // vtype Mask property: The keystroke filter mask
-    timeMask: /[\d\s:amp]/i
-});
- * &lt;/code&gt;&lt;/pre&gt;
- * Another example:
- * &lt;pre&gt;&lt;code&gt;
-// 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
-});
- * &lt;/code&gt;&lt;/pre&gt;
- * @singleton
+<!DOCTYPE html>
+<html>
+<head>
+  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+  <title>The source code</title>
+  <link href="../resources/prettify/prettify.css" type="text/css" rel="stylesheet" />
+  <script type="text/javascript" src="../resources/prettify/prettify.js"></script>
+  <style type="text/css">
+    .highlight { display: block; background-color: #ddd; }
+  </style>
+  <script type="text/javascript">
+    function highlight() {
+      document.getElementById(location.hash.replace(/#/, "")).className = "highlight";
+    }
+  </script>
+</head>
+<body onload="prettyPrint(); highlight();">
+  <pre class="prettyprint lang-js"><span id='Ext-form-field-VTypes'>/**
+</span> * @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 &quot;12:34 PM&quot;.',
+ *         // 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.
@@ -44,35 +90,40 @@ Ext.define('Ext.form.field.VTypes', (function(){
         singleton: true,
         alternateClassName: 'Ext.form.VTypes',
 
-<span id='Ext-form.field.VTypes-method-email'>        /**
-</span>         * 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 &lt;a href=&quot;http://en.wikipedia.org/wiki/E-mail_address&quot;&gt;Wikipedia article on email addresses&lt;/a&gt;
-         * for additional information.  This implementation is intended to validate the following emails:&lt;tt&gt;
-         * 'barney@example.de', 'barney.rubble@example.com', 'barney-rubble@example.coop', 'barney+rubble@example.com'
-         * &lt;/tt&gt;.
+<span id='Ext-form-field-VTypes-method-email'>        /**
+</span>         * 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.
          */
         'email' : function(v){
             return email.test(v);
         },
-<span id='Ext-form.field.VTypes-property-emailText'>        /**
-</span>         * The error text to display when the email validation function returns false.  Defaults to:
-         * &lt;tt&gt;'This field should be an e-mail address in the format &quot;user@example.com&quot;'&lt;/tt&gt;
-         * @type String
+<span id='Ext-form-field-VTypes-property-emailText'>        /**
+</span>         * @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 &quot;user@example.com&quot;'
          */
         'emailText' : 'This field should be an e-mail address in the format &quot;user@example.com&quot;',
-<span id='Ext-form.field.VTypes-property-emailMask'>        /**
-</span>         * The keystroke filter mask to be applied on email input.  See the {@link #email} method for
-         * information about more complex email validation. Defaults to:
-         * &lt;tt&gt;/[a-z0-9_\.\-@]/i&lt;/tt&gt;
-         * @type RegExp
+<span id='Ext-form-field-VTypes-property-emailMask'>        /**
+</span>         * @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,
 
-<span id='Ext-form.field.VTypes-method-url'>        /**
+<span id='Ext-form-field-VTypes-method-url'>        /**
 </span>         * The function used to validate URLs
          * @param {String} value The URL
          * @return {Boolean} true if the RegExp test passed, and false if not.
@@ -80,14 +131,14 @@ Ext.define('Ext.form.field.VTypes', (function(){
         'url' : function(v){
             return url.test(v);
         },
-<span id='Ext-form.field.VTypes-property-urlText'>        /**
-</span>         * The error text to display when the url validation function returns false.  Defaults to:
-         * &lt;tt&gt;'This field should be a URL in the format &quot;http:/'+'/www.example.com&quot;'&lt;/tt&gt;
-         * @type String
+<span id='Ext-form-field-VTypes-property-urlText'>        /**
+</span>         * @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 &quot;http:/'+'/www.example.com&quot;'
          */
         'urlText' : 'This field should be a URL in the format &quot;http:/'+'/www.example.com&quot;',
 
-<span id='Ext-form.field.VTypes-method-alpha'>        /**
+<span id='Ext-form-field-VTypes-method-alpha'>        /**
 </span>         * The function used to validate alpha values
          * @param {String} value The value
          * @return {Boolean} true if the RegExp test passed, and false if not.
@@ -95,20 +146,19 @@ Ext.define('Ext.form.field.VTypes', (function(){
         'alpha' : function(v){
             return alpha.test(v);
         },
-<span id='Ext-form.field.VTypes-property-alphaText'>        /**
-</span>         * The error text to display when the alpha validation function returns false.  Defaults to:
-         * &lt;tt&gt;'This field should only contain letters and _'&lt;/tt&gt;
-         * @type String
+<span id='Ext-form-field-VTypes-property-alphaText'>        /**
+</span>         * @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 _',
-<span id='Ext-form.field.VTypes-property-alphaMask'>        /**
-</span>         * The keystroke filter mask to be applied on alpha input.  Defaults to:
-         * &lt;tt&gt;/[a-z_]/i&lt;/tt&gt;
-         * @type RegExp
+<span id='Ext-form-field-VTypes-property-alphaMask'>        /**
+</span>         * @property {RegExp} alphaMask
+         * The keystroke filter mask to be applied on alpha input. Defaults to: /[a-z_]/i
          */
         'alphaMask' : /[a-z_]/i,
 
-<span id='Ext-form.field.VTypes-method-alphanum'>        /**
+<span id='Ext-form-field-VTypes-method-alphanum'>        /**
 </span>         * The function used to validate alphanumeric values
          * @param {String} value The value
          * @return {Boolean} true if the RegExp test passed, and false if not.
@@ -116,18 +166,19 @@ Ext.define('Ext.form.field.VTypes', (function(){
         'alphanum' : function(v){
             return alphanum.test(v);
         },
-<span id='Ext-form.field.VTypes-property-alphanumText'>        /**
-</span>         * The error text to display when the alphanumeric validation function returns false.  Defaults to:
-         * &lt;tt&gt;'This field should only contain letters, numbers and _'&lt;/tt&gt;
-         * @type String
+<span id='Ext-form-field-VTypes-property-alphanumText'>        /**
+</span>         * @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 _',
-<span id='Ext-form.field.VTypes-property-alphanumMask'>        /**
-</span>         * The keystroke filter mask to be applied on alphanumeric input.  Defaults to:
-         * &lt;tt&gt;/[a-z0-9_]/i&lt;/tt&gt;
-         * @type RegExp
+<span id='Ext-form-field-VTypes-property-alphanumMask'>        /**
+</span>         * @property {RegExp} alphanumMask
+         * The keystroke filter mask to be applied on alphanumeric input. Defaults to: /[a-z0-9_]/i
          */
         'alphanumMask' : /[a-z0-9_]/i
     };
 })());
-</pre></pre></body></html>
\ No newline at end of file
+</pre>
+</body>
+</html>