Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit 25e8c59

Browse files
committed
docs(ngModelController): improve $rollbackViewValue description & example
The example has been expanded to make it easier to provoke the behavior that the description is talking about (rollbackViewValue and programmatic model updates) Related #13340
1 parent 6628b4f commit 25e8c59

File tree

1 file changed

+51
-24
lines changed

1 file changed

+51
-24
lines changed

src/ng/directive/ngModel.js

+51-24
Original file line numberDiff line numberDiff line change
@@ -448,11 +448,14 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
448448
* which may be caused by a pending debounced event or because the input is waiting for a some
449449
* future event.
450450
*
451-
* If you have an input that uses `ng-model-options` to set up debounced events or events such
452-
* as blur you can have a situation where there is a period when the `$viewValue`
453-
* is out of synch with the ngModel's `$modelValue`.
451+
* If you have an input that uses `ng-model-options` to set up debounced updates or updates that
452+
* depend on special events such as blur, you can have a situation where there is a period when
453+
* the `$viewValue` is out of sync with the ngModel's `$modelValue`.
454454
*
455-
* In this case, you can run into difficulties if you try to update the ngModel's `$modelValue`
455+
* In this case, you can use `$rollbackViewValue()` to manually cancel the debounced / future update
456+
* and reset the input to the last committed view value.
457+
*
458+
* It is also possible that you run into difficulties if you try to update the ngModel's `$modelValue`
456459
* programmatically before these debounced/future events have resolved/occurred, because Angular's
457460
* dirty checking mechanism is not able to tell whether the model has actually changed or not.
458461
*
@@ -465,39 +468,63 @@ var NgModelController = ['$scope', '$exceptionHandler', '$attrs', '$element', '$
465468
* angular.module('cancel-update-example', [])
466469
*
467470
* .controller('CancelUpdateController', ['$scope', function($scope) {
468-
* $scope.resetWithCancel = function(e) {
469-
* if (e.keyCode == 27) {
470-
* $scope.myForm.myInput1.$rollbackViewValue();
471-
* $scope.myValue = '';
472-
* }
473-
* };
474-
* $scope.resetWithoutCancel = function(e) {
471+
* $scope.model = {};
472+
*
473+
* $scope.setEmpty = function(e, value, rollback) {
475474
* if (e.keyCode == 27) {
476-
* $scope.myValue = '';
475+
* e.preventDefault();
476+
* if (rollback) {
477+
* $scope.myForm[value].$rollbackViewValue();
478+
* }
479+
* $scope.model[value] = '';
477480
* }
478481
* };
479482
* }]);
480483
* </file>
481484
* <file name="index.html">
482485
* <div ng-controller="CancelUpdateController">
483-
* <p>Try typing something in each input. See that the model only updates when you
484-
* blur off the input.
485-
* </p>
486-
* <p>Now see what happens if you start typing then press the Escape key</p>
486+
* <p>Both of these inputs are only updated if they are blurred. Hitting escape should
487+
* empty them. Follow these steps and observe the difference:</p>
488+
* <ol>
489+
* <li>Type something in the input. You will see that the model is not yet updated</li>
490+
* <li>Press the Escape key.
491+
* <ol>
492+
* <li> In the first example, nothing happens, because the model is already '', and no
493+
* update is detected. If you blur the input, the model will be set to the current view.
494+
* </li>
495+
* <li> In the second example, the pending update is cancelled, and the input is set back
496+
* to the last committed view value (''). Blurring the input does nothing.
497+
* </li>
498+
* </ol>
499+
* </li>
500+
* </ol>
487501
*
488502
* <form name="myForm" ng-model-options="{ updateOn: 'blur' }">
489-
* <p id="inputDescription1">With $rollbackViewValue()</p>
490-
* <input name="myInput1" aria-describedby="inputDescription1" ng-model="myValue"
491-
* ng-keydown="resetWithCancel($event)"><br/>
492-
* myValue: "{{ myValue }}"
503+
* <div>
504+
* <p id="inputDescription1">Without $rollbackViewValue():</p>
505+
* <input name="value1" aria-describedby="inputDescription1" ng-model="model.value1"
506+
* ng-keydown="setEmpty($event, 'value1')">
507+
* value1: "{{ model.value1 }}"
508+
* </div>
493509
*
494-
* <p id="inputDescription2">Without $rollbackViewValue()</p>
495-
* <input name="myInput2" aria-describedby="inputDescription2" ng-model="myValue"
496-
* ng-keydown="resetWithoutCancel($event)"><br/>
497-
* myValue: "{{ myValue }}"
510+
* <div>
511+
* <p id="inputDescription2">With $rollbackViewValue():</p>
512+
* <input name="value2" aria-describedby="inputDescription2" ng-model="model.value2"
513+
* ng-keydown="setEmpty($event, 'value2', true)">
514+
* value2: "{{ model.value2 }}"
515+
* </div>
498516
* </form>
499517
* </div>
500518
* </file>
519+
<file name="style.css">
520+
div {
521+
display: table-cell;
522+
}
523+
div:nth-child(1) {
524+
padding-right: 30px;
525+
}
526+
527+
</file>
501528
* </example>
502529
*/
503530
this.$rollbackViewValue = function() {

0 commit comments

Comments
 (0)