This directive allows you to modify the behaviour of ngModel and input directives within your application. You can specify an ngModelOptions directive on any element and the settings affect the ngModel and input directives on all descendent elements.
The ngModelOptions settings are found by evaluating the value of the ngModelOptions attribute as an Angular expression. This expression should evaluate to an object, whose properties contain the settings.
If a setting is not specified as a property on the object for a particular ngModelOptions directive
then it will inherit that setting from the first ngModelOptions directive found by traversing up the
DOM tree. If there is no ancestor element containing an ngModelOptions directive then the settings in
$modelOptions
will be used.
For example given the following fragment of HTML
<div ng-model-options="{ allowInvalid: true }">
<form ng-model-options="{ updateOn: 'blur' }">
<input ng-model-options="{ updateOn: 'default' }" />
</form>
</div>
the input
element will have the following settings
{ allowInvalid: true, updateOn: 'default' }
The updateOn
and debounce
properties allow you to specify a custom list of events that will
trigger a model update and/or a debouncing delay so that the actual update only takes place when
a timer expires; this timer will be reset after another change takes place.
Given the nature of ngModelOptions
, the value displayed inside input fields in the view might
be different from the value in the actual model. This means that if you update the model you
should also invoke $rollbackViewValue
on the relevant input field in
order to make sure it is synchronized with the model and that any debounced action is canceled.
The easiest way to reference the control's $rollbackViewValue
method is by making sure the input is placed inside a form that has a name
attribute. This is
important because form
controllers are published to the related scope under the name in their
name
attribute.
Any pending changes will take place immediately when an enclosing form is submitted via the
submit
event. Note that ngClick
events will occur before the model is updated. Use ngSubmit
to have access to the updated model.
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). If escape
key is
pressed while the input field is focused, the value is reset to the value in the current model.
<div ng-controller="ExampleController">
<form name="userForm">
<label>
Name:
<input type="text" name="userName"
ng-model="user.name"
ng-model-options="{ updateOn: 'blur' }"
ng-keyup="cancel($event)" />
</label><br />
<label>
Other data:
<input type="text" ng-model="user.data" />
</label><br />
</form>
<pre>user.name = <span ng-bind="user.name"></span></pre>
</div>
angular.module('optionsExample', [])
.controller('ExampleController', ['$scope', function($scope) {
$scope.user = { name: 'say', data: '' };
$scope.cancel = function(e) {
if (e.keyCode === 27) {
$scope.userForm.userName.$rollbackViewValue();
}
};
}]);
var model = element(by.binding('user.name'));
var input = element(by.model('user.name'));
var other = element(by.model('user.data'));
it('should allow custom events', function() {
input.sendKeys(' hello');
input.click();
expect(model.getText()).toEqual('say');
other.click();
expect(model.getText()).toEqual('say hello');
});
it('should $rollbackViewValue when model changes', function() {
input.sendKeys(' hello');
expect(input.getAttribute('value')).toEqual('say hello');
input.sendKeys(protractor.Key.ESCAPE);
expect(input.getAttribute('value')).toEqual('say');
other.click();
expect(model.getText()).toEqual('say');
});
The next example shows how to debounce model changes. Model will be updated only 1 sec after last change.
If the Clear
button is pressed, any debounced action is canceled and the value becomes empty.
<div ng-controller="ExampleController">
<form name="userForm">
Name:
<input type="text" name="userName"
ng-model="user.name"
ng-model-options="{ debounce: 1000 }" />
<button ng-click="userForm.userName.$rollbackViewValue(); user.name=''">Clear</button><br />
</form>
<pre>user.name = <span ng-bind="user.name"></span></pre>
</div>
angular.module('optionsExample', [])
.controller('ExampleController', ['$scope', function($scope) {
$scope.user = { name: 'say' };
}]);
The default behaviour in ngModel
is that the model value is set to undefined
when the
validation determines that the value is invalid. By setting the allowInvalid
property to true,
the model will still be updated even if the value is invalid.
By setting the getterSetter
property to true you are telling ngModel that the ngModel
expression
on the scope refers to a "getter/setter" function rather than the value itself.
The following example shows how to bind to getter/setters:
<div ng-controller="ExampleController">
<form name="userForm">
<label>
Name:
<input type="text" name="userName"
ng-model="user.name"
ng-model-options="{ getterSetter: true }" />
</label>
</form>
<pre>user.name = <span ng-bind="user.name()"></span></pre>
</div>
angular.module('getterSetterExample', [])
.controller('ExampleController', ['$scope', function($scope) {
var _name = 'Brian';
$scope.user = {
name: function(newName) {
return angular.isDefined(newName) ? (_name = newName) : _name;
}
};
}]);
You can specify the timezone that date/time input directives expect by providing its name in the
timezone
property.
<ng-model-options
ng-model-options="Object">
...
</ng-model-options>
<ANY
ng-model-options="Object">
...
</ANY>
Param | Type | Details |
---|---|---|
ngModelOptions | Object |
options to apply to the current model. Valid keys are:
|