From 3d6a099d6e40f1e12f6349843218987d472d0f3c Mon Sep 17 00:00:00 2001
From: Misko Hevery
Date: Thu, 4 Nov 2010 17:41:14 -0700
Subject: changed to showdown from markup. added validator overview

---
 src/Angular.js    | 63 ++++++++++++++++++++++++++++++++++++++++++++++++-------
 src/validators.js | 56 +++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 112 insertions(+), 7 deletions(-)

(limited to 'src')

diff --git a/src/Angular.js b/src/Angular.js
index 0e26a829..9177853a 100644
--- a/src/Angular.js
+++ b/src/Angular.js
@@ -93,6 +93,59 @@ var _undefined        = undefined,
     angularAttrMarkup = extensionMap(angular, 'attrMarkup'),
     angularDirective  = extensionMap(angular, 'directive'),
     angularWidget     = extensionMap(angular, 'widget', lowercase),
+    
+    /**
+     * @ngdoc overview
+     * @name angular.validator
+     * @namespace Namespace for all filters.
+     * @description
+     * # Overview
+     * Validators are a standard way to check the user input against a specific criteria. For 
+     * example, you might need to check that an input field contains a well-formed phone number.
+     * 
+     * # Syntax
+     * Attach a validator on user input widgets using the `ng:validate` attribute.
+     * 
+     * <WIKI:SOURCE>
+     *    Change me: &lt;input type="text" name="number" ng:validate="integer" value="123"&gt;
+     * </WIKI:SOURCE>
+     * 
+     * # Writing your own Validators
+     * Writing your own validator is easy. To make a function available as a 
+     * validator, just define the JavaScript function on the `angular.validator` 
+     * object. <angular/> passes in the input to validate as the first argument 
+     * to your function. Any additional validator arguments are passed in as 
+     * additional arguments to your function.
+     * 
+     * You can use these variables in the function:
+     *
+     * * `this` — The current scope.
+     * * `this.$element` — The DOM element containing the binding. This allows the filter to manipulate
+     *   the DOM in addition to transforming the input.
+     *   
+     * In this example we have written a upsTrackingNo validator. 
+     * It marks the input text "valid" only when the user enters a well-formed 
+     * UPS tracking number.
+     * 
+     * <pre>
+     * angular.validator('upsTrackingNo', function(input, format) {
+     *  var regexp = new RegExp("^" + format.replace(/9/g, '\\d') + "$");
+     *  return input.match(regexp) ? "" : "The format must match " + format;
+     * });
+     * </pre>
+     * 
+     * @example
+     * <script>
+     *  angular.validator('upsTrackingNo', function(input, format) {
+     *    var regexp = new RegExp("^" + format.replace(/9/g, '\\d') + "$");
+     *    return input.match(regexp)?"":"The format must match " + format;
+     *  });
+     * </script>
+     * <input type="text" name="trackNo" size="40"
+     *       ng:validate="upsTrackingNo:'1Z 999 999 99 9999 999 9'" 
+     *       value="1Z 123 456 78 9012 345 6"/>
+     * 
+     */
     angularValidator  = extensionMap(angular, 'validator'),
 
 
@@ -139,13 +192,13 @@ var _undefined        = undefined,
      * You can use these variables in the function:
      *
      * * `this` — The current scope.
-     * * `$element` — The DOM element containing the binding. This allows the filter to manipulate
+     * * `this.$element` — The DOM element containing the binding. This allows the filter to manipulate
      *   the DOM in addition to transforming the input.
      *
      *
      * @example
          <script type="text/javascript">
-           angular.filter.reverse = function(input, uppercase, color) {
+           angular.filter('reverse', function(input, uppercase, color) {
              var out = "";
              for (var i = 0; i < input.length; i++) {
                out = input.charAt(i) + out;
@@ -157,7 +210,7 @@ var _undefined        = undefined,
                this.$element.css('color', color);
              }
              return out;
-           };
+           });
          </script>
        The following example filter reverses a text string. In addition, it conditionally makes the
        text upper-case (to demonstrate optional arguments) and assigns color (to demonstrate DOM
@@ -169,10 +222,6 @@ var _undefined        = undefined,
          <span ng:non-bindable="true">{{"hello"|reverse:true:"blue"}}</span>:
            {{"hello"|reverse:true:"blue"}}
 
-     * @TODO: I completely dropped a mention of using the other option (setter method), it's
-     * confusing to have two ways to do the same thing. I just wonder if we should prefer using the
-     * setter way over direct assignment because in the future we might want to be able to intercept
-     * filter registrations for some reason.
      */
     angularFilter     = extensionMap(angular, 'filter'),
     angularFormatter  = extensionMap(angular, 'formatter'),
diff --git a/src/validators.js b/src/validators.js
index fd18d66c..a1543f41 100644
--- a/src/validators.js
+++ b/src/validators.js
@@ -84,6 +84,62 @@ extend(angularValidator, {
     }
   },
 
+  /**
+   * @ngdoc validator
+   * @name angular.validator.asynchronous
+   * @description
+   * Use asynchronous validator if the validation can not be computed 
+   * immediately, but is provided through a callback. The widget 
+   * automatically shows a spinning indicator while the validity of 
+   * the widget is computed. This validator caches the result.
+   * 
+   * @param {string} value value to validate
+   * @param {function(inputToValidate,validationDone)} validate function to call to validate the state
+   *         of the input.
+   * @param {function(data)=} [update=noop] function to call when state of the 
+   *    validator changes
+   *    
+   * @paramDescription
+   * The `validate` function (specified by you) is called as 
+   * `validate(inputToValidate, validationDone)`:
+   * 
+   *    * `inputToValidate`: value of the input box.
+   *    * `validationDone`: `function(error, data){...}`
+   *       * `error`: error text to display if validation fails
+   *       * `data`: data object to pass to update function
+   *       
+   * The `update` function is optionally specified by you and is
+   * called by <angular/> on input change. Since the 
+   * asynchronous validator caches the results, the update 
+   * function can be called without a call to `validate` 
+   * function. The function is called as `update(data)`:
+   * 
+   *    * `data`: data object as passed from validate function
+   * 
+   * @css ng-input-indicator-wait
+   * 
+   * @exampleDescription
+   * <pre>
+   * function myValidator (value, callback) {
+   *  // simulate delayed response, validate on even input length
+   *  setTimeout(function(){
+   *    callback(value.length % 2);
+   *  }, 2000);
+   * };
+   * </pre>
+   * 
+   * @example
+   * <script>
+   *   function myValidator(value, callback) {
+   *    setTimeout(function(){
+   *      callback(value.length % 2);
+   *    }, 2000);
+   *  }
+   * </script>
+   *  This input is validated asynchronously:
+   *  <input name="text" ng:validate="asynchronous:$window.myValidator">
+   * 
+   */
   /*
    * cache is attached to the element
    * cache: {
-- 
cgit v1.2.3