Forms and form controls (`input`, `select`, `textarea`) are user's gateway to your application -

that's how your application accepts input from the user.

In order to provide good user experience while gathering user input, it is important to validate

this input and give the user hints on how to correct errors. Angular provides several mechanisms

that make this easier, but keep in mind that while client-side validation plays an important role in

providing good user experience, it can be easily circumvented and thus a server-side validation is

still necessary.

The most important directive is {@link api/angular.module.ng.$compileProvider.directive.ng:model ng-model},

which tells Angular to do two-way data binding. That means, the value in the form control is

synchronized in both directions with the bound model (specified as value of `ng-model` attribute).

<!-- reading these values outside <form> scope is possible only because we defined these objects

on the parent scope, and ng-model only change properties of this object -->

Note, that the `user.name` is updated immediately - that's because of

{@link api/angular.module.ng.$compileProvide.directive.ng:model-instant ng-model-instant}.

Note, that we use `novalidate` to disable browser's native form validation.

Angular sets the model value onto current scope. However it can be confusing where are the scope

borders - in other words, which directives create new scope.

It's crucial to understand how prototypical inheritance works as well as

{@link dev_guide.scopes.internals Angular's scopes}.

In this example, there are actually two directives, that create new scope (`ng-controller` and `form`).

Angular sets the value onto the current scope, so the first input sets value to `scope.user.name`,

where `scope` is the scope on `form` element. Therefore you would not be able to read the value

outside the `form`, because that's a parent scope. That's why we defined the `$scope.user` object

on the parent scope (on `div` element), because `ng-model` access this object through prototypical

inheritance and bind to this object (defined on the parent scope) and we can access it even on

parent scope.

elements, to allow you to style them differently, depending on their state. These css classes are:

Here is the same example with some very basic css, displaying validity of each form control.

Both `user.name` and `user.email` are required, but we display the red background only when they

are dirty, which means the user has already interacted with them.

Name: <input type="text" ng-model="user.name" ng-model-instant required /><br />

# Binding to form / form control state

Each form has an object, that keeps the state of the whole form. This object is an instance of

{@link api/angular.module.ng.$compileProvide.directive.form.FormController FormController}.

In a similar way, each form control with `ng-model` directive has an object, that keeps the state of

the form control. This object is an instance of

{@link api/angular.module.ng.$compileProvide.directive.form.NgModelController NgModelController}.

The css classes used in the previous example are nothing else than just a reflection of these objects.

But using css classes is not flexible enough - we need to do more. So this example shows, how to

access these state objects and how to bind to them.

Note, we added `name` attribute to the form element as well as to the form controls, so that we have access

these objects. When a form has `name` attribute, its `FormController` is published onto the scope.

In a similar way, if a form control has `name` attribute, a reference to its `NgModelController` is

stored on the `FormController`.

**Some changes to notice:**

Name: <input type="text" ng-model="user.name" name="userName" required /><br />

E-mail: <input type="email" ng-model="user.email" name="userEmail" required/><br />

<span ng-show="form.userEmail.$dirty && form.userEmail.$invalid">Invalid:

<span ng-show="form.userEmail.$error.REQUIRED">Please tell us your email.</span>

<span ng-show="form.userEmail.$error.EMAIL">This is not a valid email.</span><br />

</span>

<input type="checkbox" ng-model="user.agree" name="userAgree" required />I agree:

<input ng-show="user.agree" type="text" ng-model="user.agreeSign" ng-model-instant required /><br />

<button ng-click="update(user)" disabled="{{form.$invalid || isUnchanged(user)}}">SAVE</button>

# Advanced / custom validation

types ({@link api/angular.module.ng.$compileProvider.directive.input.text text}, {@link api/angular.module.ng.$compileProvider.directive.input.number number}, {@link api/angular.module.ng.$compileProvider.directive.input.url url}, {@link api/angular.module.ng.$compileProvider.directive.input.email email}, {@link api/angular.module.ng.$compileProvider.directive.input.radio radio}, {@link api/angular.module.ng.$compileProvider.directive.input.checkbox checkbox}), as well as some directives for validation (`required`, `pattern`, `minlength`, `maxlength`, `min`, `max`).

However, when this is not enough for your application, you can simply define a custom directive.

This directive can require `ngModel`, which means it can't exist without `ng-model` and its linking

function gets fourth argument - an instance of `NgModelController`, which is a communication channel

to `ng-model`, that allows you to hook into the validation process.

## Model to View update

Whenever the bound model changes, all functions in {@link api/angular.module.ng.$compileProvider.directive.ng:model.NgModelController#formatters NgModelController#formatters} array are pipe-lined, so that each of these functions has an opportunity to format the value and change validity state of the form control through {@link api/angualar.module.ng.$compileProvider.directive.ng:model.NgModelController#$setValidity NgModelController#$setValidity}.

## View to Model update

In a similar way, whenever a form control calls {@link api/angular.module.ng.$compileProvider.directive.ng:model.NgModelController#setViewValue NgModelController#setViewValue}, all functions in {@link api/angular.module.ng.$compileProvider.directive.ng:model.NgModelController#parsers NgModelController#parsers} array are pipe-lined, so that each of these functions has an opportunity to correct/convert the value and change validity state of the form control through {@link api/angualar.module.ng.$compileProvider.directive.ng:model.NgModelController#setValidity NgModelController#$setValidity}.

In this example we create two simple directives. The first one is `integer` and it validates whether the input is valid integer, so for example `1.23` is an invalid value. Note, that we unshift the array instead of pushing - that's because we want to get a string value, so we need to execute the validation function before a conversion to number happens.

The second directive is `smart-float`. It parses both `1.2` and `1,2` into a valid float number `1.2`. Note, we can't use input type `number` here - browser would not allow user to type invalid number such as `1,2`.

Size (integer 0 - 10): <input type="number" ng-model="size" name="size" min="0" max="10" integer />{{size}}<br />

<span ng-show="form.size.$error.MIN || form.size.$error.MAX">The value must be in range 0 to 10!</span>

Length (float): <input type="text" ng-model="length" name="length" smart-float />{{length}}<br />

Angular has all the basic form controls implemented ({@link api/angular.module.ng.$compileProvider.directive.input input}, {@link api/angular.module.ng.$compileProvider.directive.select select}, {@link api/angular.module.ng.$compileProvider.directive.textarea textarea}), so most of the time you should be just fine with them. However, if you need more flexibility, you can write your own form control - it's gonna be a directive again.

You basically need to do two things to get it working together with `ng-model` binding:

- implement `render` method, that knows how to reflect value change to view,

- call `setViewValue` method, whenever the view value changes - that's usually inside DOM Event listener.

This example shows how easy it is to add a support for binding contentEditable elements.