docs(guide/forms, input): add information how to modify built-in vali…

…dators

Closes angular#5757
Closes angular#7798

docs/content/guide/forms.ngdoc

@@ -384,6 +384,50 @@ In the following example we create two directives:
   </file>
 </example>
 
+# Modifying built-in validators
+
+Since Angular itself uses `$validators`, you can easily replace or remove built-in validators,
+should you find it necessary. The following example shows you how to overwrite the email validator
+in `input[email]` from a custom directive so that it requires a specific top-level domain,
+`example.com` to be present.
+Note that you can alternatively use `ng-pattern` to further restrict the validation.
+
+<example module="form-example-modify-validators">
+  <file name="index.html">
+    <form name="form" class="css-form" novalidate>
+      <div>
+        Overwritten Email:
+        <input type="email" ng-model="myEmail" overwrite-email name="overwrittenEmail" />
+        <span ng-show="form.overwrittenEmail.$error.email">This email format is invalid!</span><br>
+        Model: {{myEmail}}
+        </div>
+    </form>
+  </file>
+
+  <file name="script.js">
+    var app = angular.module('form-example-modify-validators', []);
+
+    app.directive('overwriteEmail', function() {
+      var EMAIL_REGEXP = /^[a-z0-9!#$%&'*+/=?^_`{|}~.-]+@example\.com$/i;
+
+      return {
+        require: 'ngModel',
+        restrict: '',
+        link: function(scope, elm, attrs, ctrl) {
+          // only apply the validator if ngModel is present and Angular has added the email validator
+          if (ctrl && ctrl.$validators.email) {
+
+            // this will overwrite the default Angular email validator
+            ctrl.$validators.email = function(modelValue) {
+              return ctrl.$isEmpty(modelValue) || EMAIL_REGEXP.test(modelValue);
+            };
+          }
+        }
+      };
+    });
+  </file>
+</example>
+
 
 # Implementing custom form controls (using `ngModel`)
 Angular implements all of the basic HTML form controls ({@link ng.directive:input input}, {@link ng.directive:select select}, {@link ng.directive:textarea textarea}), which should be sufficient for most cases.

src/ng/directive/input.js

@@ -651,6 +651,12 @@ var inputType = {
    * Text input with URL validation. Sets the `url` validation error key if the content is not a
    * valid URL.
    *
+   * <div class="alert alert-warning">
+   * **Note:** `input[url]` uses a regex to validate urls that is derived from the regex
+   * used in Chromium. If you need stricter validation, you can use `ng-pattern` or modify
+   * the built-in validators (see the {@link guide/forms Forms guide})
+   * </div>
+   *
    * @param {string} ngModel Assignable angular expression to data-bind to.
    * @param {string=} name Property name of the form under which the control is published.
    * @param {string=} required Sets `required` validation error key if the value is not entered.
@@ -728,6 +734,12 @@ var inputType = {
    * Text input with email validation. Sets the `email` validation error key if not a valid email
    * address.
    *
+   * <div class="alert alert-warning">
+   * **Note:** `input[email]` uses a regex to validate email addresses that is derived from the regex
+   * used in Chromium. If you need stricter validation (e.g. requiring a top-level domain), you can
+   * use `ng-pattern` or modify the built-in validators (see the {@link guide/forms Forms guide})
+   * </div>
+   *
    * @param {string} ngModel Assignable angular expression to data-bind to.
    * @param {string=} name Property name of the form under which the control is published.
    * @param {string=} required Sets `required` validation error key if the value is not entered.