feat(ngModelOptions): Model update behavior can now be customized

docs/content/guide/forms.ngdoc

@@ -181,6 +181,82 @@ This allows us to extend the above example with these features:
 
 
 
+# Custom triggers
+
+By default, any change to the content will trigger a model update and form validation. You can
+override this behavior using the {@link ng.directive:ngModelOptions ngModelOptions} directive to
+bind only to specified list of events. I.e. `ng-model-options="{ updateOn: "blur" }"` will update
+and validate only after the control loses focus. You can set several events using a space delimited
+list. I.e. `ng-model-options="{ updateOn: 'mousedown blur' }"`
+
+If you want to keep the default behavior and just add new events that may trigger the model update
+and validation, add "default" as one of the specified events.
+
+I.e. `ng-model-options="{ updateOn: 'default blur' }"`
+
+The following example shows how to override immediate updates. Changes on the inputs within the form will update the model 
+only when the control loses focus (blur event).
+
+<example>
+  <file name="index.html">
+    <div ng-controller="ControllerUpdateOn">
+      <form>
+        Name:
+        <input type="text" ng-model="user.name" ng-model-options="{ updateOn: "blur" }" /><br />
+        Other data:
+        <input type="text" ng-model="user.data" /><br />
+      </form>
+      <pre>username = "{{user.name}}"</pre>
+    </div>
+  </file>
+  <file name="script.js">
+    function ControllerUpdateOn($scope) {
+      $scope.user = {};
+    }
+  </file>
+</example>
+
+
+
+# Non-immediate (debounced) model updates
+
+You can delay the model update/validation by using the `debounce` key with the
+{@link ng.directive:ngModelOptions ngModelOptions} directive. This delay will also apply to
+parsers, validators and model flags like `$dirty` or `$pristine`.
+
+I.e. `ng-model-options="{ debounce: 500 }"` will wait for half a second since
+the last content change before triggering the model update and form validation.
+
+If custom triggers are used, custom debouncing timeouts can be set for each event using an object
+in `debounce`. This can be useful to force immediate updates on some specific circumstances
+(like blur events).
+
+I.e. `ng-model-options="{ updateOn: 'default blur', debounce: { default: 500, blur: 0 } }"`
+
+If those attributes are added to an element, they will be applied to all the child elements and controls that inherit from it unless they are
+overridden.
+
+This example shows how to debounce model changes. Model will be updated only 250 milliseconds after last change.
+
+<example>
+  <file name="index.html">
+    <div ng-controller="ControllerUpdateOn">
+      <form>
+        Name:
+        <input type="text" ng-model="user.name" ng-model-options="{ debounce: 250 }" /><br />
+      </form>
+      <pre>username = "{{user.name}}"</pre>
+    </div>
+  </file>
+  <file name="script.js">
+    function ControllerUpdateOn($scope) {
+      $scope.user = {};
+    }
+  </file>
+</example>
+
+
+
 # Custom Validation
 
 Angular provides basic implementation for most common html5 {@link ng.directive:input input}

src/AngularPublic.js

@@ -46,6 +46,7 @@
     requiredDirective,
     requiredDirective,
     ngValueDirective,
+    ngModelOptionsDirective,
     ngAttributeAliasDirectives,
     ngEventDirectives,
 
@@ -183,7 +184,8 @@ function publishExternalAPI(angular){
             ngChange: ngChangeDirective,
             required: requiredDirective,
             ngRequired: requiredDirective,
-            ngValue: ngValueDirective
+            ngValue: ngValueDirective,
+            ngModelOptions: ngModelOptionsDirective
         }).
         directive({
           ngInclude: ngIncludeFillContentDirective