feat(input): Allow custom events and timeouts to trigger model updates

By default, any change on the content will trigger an immediate model update
and form validation. Now you can override this behavior using the
`ng-update-model-on` attribute to bind only to a comma-delimited list of events.

I.e. `ng-update-model-on="blur"` will update and validate only after the control
loses focus.

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-update-model-on="default,mousedown"`

Also, a `ng-update-model-debounce` attribute will allow defering the actual model
update some time after the last trigger event takes place (debouncing). This
feature is not available in radio buttons.

I.e. `ng-update-model-debounce="500"`

Custom debouncing timeouts can be set for each event if you use an object
in `ng-update-model-on`.

I.e. `ng-update-model-on="{default: 500, blur: 0}"`

You can specify both attributes in any tag so they became the default settings
for any child control, although they can be overriden.

Closes angular#1285

Author: lrlopez

angularFiles.js

@@ -63,6 +63,7 @@ angularFiles = {
     'src/ng/directive/ngStyle.js',
     'src/ng/directive/ngSwitch.js',
     'src/ng/directive/ngTransclude.js',
+    'src/ng/directive/ngUpdateModel.js',
     'src/ng/directive/script.js',
     'src/ng/directive/select.js',
     'src/ng/directive/style.js'

docs/content/guide/forms.ngdoc

@@ -180,6 +180,46 @@ This allows us to extend the above example with these features:
 </example>
 
 
+# Non-immediate (debounced) or custom triggered model updates
+
+By default, any change on the content will trigger a model update and form validation. You can override this behavior using the `ng-update-model-on`
+attribute to bind only to a comma-delimited list of events. I.e. `ng-update-model-on="blur"` will update and validate only after the control loses
+focus.
+
+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-update-model-on="default,mousedown"`
+
+You can delay the model update/validation using `ng-update-model-debounce`. I.e. `ng-update-model-debounce="500"` will wait for half a second since
+the last content change before triggering the model update and form validation. This debouncing feature is not available on radio buttons.
+
+Custom debouncing timeouts can be set for each event for each event if you use an object in `ng-update-model-on`.
+I.e. `ng-update-model-on="{default: 500, blur: 0}"`
+
+Using the object notation allows any valid Angular expression to be used inside, including data and function calls from the scope.
+
+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
+overriden.
+
+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).
+
+<doc:example>
+<doc:source>
+<div ng-controller="ControllerUpdateOn">
+  <form name="form" class="css-form" ng-update-model-on="blur">
+    Name:
+    <input type="text" ng-model="user.name" name="uName" /><br />
+  </form>
+  <pre>model = {{user | json}}</pre>
+</div>
+<script>
+  function ControllerUpdateOn($scope) {
+    $scope.user = {};
+  }
+</script>
+</doc:source>
+</doc:example>
+
 
 # Custom Validation
 

src/AngularPublic.js

@@ -48,6 +48,8 @@
     ngValueDirective,
     ngAttributeAliasDirectives,
     ngEventDirectives,
+    ngUpdateModelOnDirective,
+    ngUpdateModelDebounceDirective,
 
     $AnchorScrollProvider,
     $AnimateProvider,
@@ -183,6 +185,8 @@ function publishExternalAPI(angular){
             ngChange: ngChangeDirective,
             required: requiredDirective,
             ngRequired: requiredDirective,
+            ngUpdateModelOn: ngUpdateModelOnDirective,
+            ngUpdateModelDebounce: ngUpdateModelDebounceDirective,
             ngValue: ngValueDirective
         }).
         directive({

src/ng/directive/input.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * @ngdoc directive
+ * @name ng.directive:ngUpdateModelOn
+ * @restrict A
+ *
+ * @description
+ * The `ngUpdateModelOn` directive changes default behavior of model updates. You can customize
+ * which events will be bound to the `input` elements so that the model update will
+ * only be triggered when they occur.
+ *
+ * This option will be applicable to those `input` elements that descend from the
+ * element containing the directive. So, if you use `ngUpdateModelOn` on a `form`
+ * element, the default behavior will be used on the `input` elements within.
+ *
+ *  See {@link guide/forms this link} for more information about debouncing and custom
+ *  events.
+ *
+ * @element ANY
+ * @param {string} ngUpdateModelOn Allows specifying an event or a comma-delimited list of events
+ *    that will trigger a model update. If it is not set, it defaults to any inmediate change. If
+ *    the list contains "default", the original behavior is also kept. You can also specify an
+ *    object in which the key is the event and the value the particular debouncing timeout to be
+ *    applied to it.
+ */
+
+var SIMPLEOBJECT_TEST = /^\s*?\{(.*)\}\s*?$/;
+
+var NgUpdateModelOnController = ['$attrs', '$scope',
+    function UpdateModelOnController($attrs, $scope) {
+
+  var attr = $attrs['ngUpdateModelOn'];
+  var updateModelOnValue;
+  var updateModelDebounceValue;
+
+  if (SIMPLEOBJECT_TEST.test(attr)) {
+    updateModelDebounceValue = $scope.$eval(attr);
+    var keys = [];
+    for(var k in updateModelDebounceValue) {
+      keys.push(k);
+    }
+    updateModelOnValue = keys.join(',');
+  }
+  else {
+    updateModelOnValue = attr;
+  }
+
+  this.$getEventList = function() {
+    return updateModelOnValue;
+  };
+
+  this.$getDebounceTimeout = function() {
+    return updateModelDebounceValue;
+  };
+}];
+
+var ngUpdateModelOnDirective = [function() {
+  return {
+    restrict: 'A',
+    controller: NgUpdateModelOnController
+  };
+}];
+
+
+/**
+ * @ngdoc directive
+ * @name ng.directive:ngUpdateModelDebounce
+ * @restrict A
+ *
+ * @description
+ * The `ngUpdateModelDebounce` directive allows specifying a debounced timeout to model updates so they
+ * are not triggerer instantly but after the timer has expired.
+ *
+ * If you need to specify different timeouts for each event, you can use
+ * {@link ng.directive:ngUpdateModelOn ngUpdateModelOn} directive which the object notation.
+ *
+ * @element ANY
+ * @param {integer} ngUpdateModelDebounce Time in milliseconds to wait since the last registered
+   *    content change before triggering a model update.
+ */
+var NgUpdateModelDebounceController = ['$attrs',
+    function UpdateModelDebounceController($attrs) {
+
+  var updateModelDefaultTimeoutValue = $attrs['ngUpdateModelDebounce'];
+
+  this.$getDefaultTimeout = function() {
+    return updateModelDefaultTimeoutValue;
+  };
+}];
+
+var ngUpdateModelDebounceDirective = [function() {
+  return {
+    restrict: 'A',
+    controller: NgUpdateModelDebounceController
+  };
+}];

src/ng/directive/ngUpdateModel.js

@@ -26,8 +26,8 @@ function $TimeoutProvider() {
       *
       * You can also use `$timeout` to debounce the call of a function using the returned promise
       * as the fourth parameter in the next call. See the following example:
-      * 
-      * <pre>
+      *
+      * ```js
       *   var debounce;
       *   var doRealSave = function() {
       *      // Save model to DB
@@ -36,13 +36,13 @@ function $TimeoutProvider() {
       *      // debounce call for 2 seconds
       *      debounce = $timeout(doRealSave, 2000, false, debounce);
       *   }
-      * </pre>
+      * ```
       *
       * And in the form:
       *
-      * <pre>
+      * ```html
       *   <input type="text" ng-model="name" ng-change="save()">
-      * </pre>
+      * ```
       *
       * @param {function()} fn A function, whose execution should be delayed.
       * @param {number=} [delay=0] Delay in milliseconds.