@ngdoc directive
@name ngModel

@element input

@description
The `ngModel` directive binds an `input`,`select`, `textarea` (or custom form control) to a
property on the scope using {@link ngModel.NgModelController NgModelController},
which is created and exposed by this directive.

`ngModel` is responsible for:

- Binding the view into the model, which other directives such as `input`, `textarea` or `select`
require.
- Providing validation behavior (i.e. required, number, email, url).
- Keeping the state of the control (valid/invalid, dirty/pristine, touched/untouched, validation errors).
- Setting related css classes on the element (`ng-valid`, `ng-invalid`, `ng-dirty`, `ng-pristine`, `ng-touched`, `ng-untouched`) including animations.
- Registering the control with its parent {@link ng.directive:form form}.

Note: `ngModel` will try to bind to the property given by evaluating the expression on the
current scope. If the property doesn't already exist on this scope, it will be created
implicitly and added to the scope.

For best practices on using `ngModel`, see:

- [https://github.com/angular/angular.js/wiki/Understanding-Scopes]

For basic examples, how to use `ngModel`, see:

- {@link ng.directive:input input}
- {@link input[text] text}
- {@link input[checkbox] checkbox}
- {@link input[radio] radio}
- {@link input[number] number}
- {@link input[email] email}
- {@link input[url] url}
- {@link input[date] date}
- {@link input[dateTimeLocal] dateTimeLocal}
- {@link input[time] time}
- {@link input[month] month}
- {@link input[week] week}
- {@link ng.directive:select select}
- {@link ng.directive:textarea textarea}

# CSS classes
The following CSS classes are added and removed on the associated input/select/textarea element
depending on the validity of the model.

- `ng-valid` is set if the model is valid.
- `ng-invalid` is set if the model is invalid.
- `ng-pristine` is set if the model is pristine.
- `ng-dirty` is set if the model is dirty.

Keep in mind that ngAnimate can detect each of these classes when added and removed.

## Animation Hooks

Animations within models are triggered when any of the associated CSS classes are added and removed
on the input element which is attached to the model. These classes are: `.ng-pristine`, `.ng-dirty`,
`.ng-invalid` and `.ng-valid` as well as any other validations that are performed on the model itself.
The animations that are triggered within ngModel are similar to how they work in ngClass and
animations can be hooked into using CSS transitions, keyframes as well as JS animations.

The following example shows a simple way to utilize CSS transitions to style an input element
that has been rendered as invalid after it has been validated:

<pre>
//be sure to include ngAnimate as a module to hook into more
//advanced animations
.my-input {
transition:0.5s linear all;
background: white;
}
.my-input.ng-invalid {
background: red;
color:white;
}
</pre>

@example
<example deps="angular-animate.js" animations="true" fixBase="true" module="inputExample">
<file name="index.html">
<script>
angular.module('inputExample', [])
.controller('ExampleController', ['$scope', function($scope) {
$scope.val = '1';
}]);
</script>
<style>
.my-input {
-webkit-transition:all linear 0.5s;
transition:all linear 0.5s;
background: transparent;
}
.my-input.ng-invalid {
color:white;
background: red;
}
</style>
Update input to see transitions when valid/invalid.
Integer is a valid value.
<form name="testForm" ng-controller="ExampleController">
<input ng-model="val" ng-pattern="/^\d+$/" name="anim" class="my-input" />
</form>
</file>
</example>

## Binding to a getter/setter

Sometimes it's helpful to bind `ngModel` to a getter/setter function.  A getter/setter is a
function that returns a representation of the model when called with zero arguments, and sets
the internal state of a model when called with an argument. It's sometimes useful to use this
for models that have an internal representation that's different than what the model exposes
to the view.

<div class="alert alert-success">
**Best Practice:** It's best to keep getters fast because Angular is likely to call them more
frequently than other parts of your code.
</div>

You use this behavior by adding `ng-model-options="{ getterSetter: true }"` to an element that
has `ng-model` attached to it. You can also add `ng-model-options="{ getterSetter: true }"` to
a `<form>`, which will enable this behavior for all `<input>`s within it. See
{@link ng.directive:ngModelOptions `ngModelOptions`} for more.

The following example shows how to use `ngModel` with a getter/setter:

@example
<example name="ngModel-getter-setter" module="getterSetterExample">
<file name="index.html">
<div ng-controller="ExampleController">
<form name="userForm">
Name:
<input type="text" name="userName"
ng-model="user.name"
ng-model-options="{ getterSetter: true }" />
</form>
<pre>user.name = <span ng-bind="user.name()"></span></pre>
</div>
</file>
<file name="app.js">
angular.module('getterSetterExample', [])
.controller('ExampleController', ['$scope', function($scope) {
var _name = 'Brian';
$scope.user = {
name: function (newName) {
if (angular.isDefined(newName)) {
_name = newName;
}
return _name;
}
};
}]);
</file>
</example>
function() {
  return {
    restrict: 'A',
    require: ['ngModel', '^?form', '^?ngModelOptions'],
    controller: NgModelController,
    link: {
      pre: function(scope, element, attr, ctrls) {
        // Pass the ng-model-options to the ng-model controller
        if (ctrls[2]) {
          ctrls[0].$options = ctrls[2].$options;
        }

        // notify others, especially parent forms

        var modelCtrl = ctrls[0],
            formCtrl = ctrls[1] || nullFormCtrl;

        formCtrl.$addControl(modelCtrl);

        scope.$on('$destroy', function() {
          formCtrl.$removeControl(modelCtrl);
        });
      },
      post: function(scope, element, attr, ctrls) {
        var modelCtrl = ctrls[0];
        if (modelCtrl.$options && modelCtrl.$options.updateOn) {
          element.on(modelCtrl.$options.updateOn, function(ev) {
            scope.$apply(function() {
              modelCtrl.$$debounceViewValueCommit(ev && ev.type);
            });
          });
        }

        element.on('blur', function(ev) {
          scope.$apply(function() {
            modelCtrl.$setTouched();
          });
        });
      }
    }
  };
}