dev_guide.templates.validators.html

<h1>Developer Guide: Templates: Understanding Angular Validators</h1>
<div class="developer-guide-templates-understanding-angular-validators"><fieldset class="workInProgress"><legend>Work in Progress</legend>
This page is currently being revised. It might be incomplete or contain inaccuracies.</fieldset>
<p>Angular validators are attributes that test the validity of different types of user input. Angular
provides a set of built-in input validators:</p>

<ul>
<li><a href="#!/api/angular.validator.phone"><code>phone number</code></a></li>
<li><a href="#!/api/angular.validator.number"><code>number</code></a></li>
<li><a href="#!/api/angular.validator.integer"><code>integer</code></a></li>
<li><a href="#!/api/angular.validator.date"><code>date</code></a></li>
<li><a href="#!/api/angular.validator.email"><code>email address</code></a></li>
<li><a href="#!/api/angular.validator.json"><code>JSON</code></a></li>
<li><a href="#!/api/angular.validator.regexp"><code>regular expressions</code></a></li>
<li><a href="#!/api/angular.validator.url"><code>URLs</code></a></li>
<li><a href="#!/api/angular.validator.asynchronous"><code>asynchronous</code></a></li>
</ul>

<p>You can also create your own custom validators.</p>

<h2>Using Angular Validators</h2>

<p>You can use angular validators in HTML template bindings, and in JavaScript:</p>

<ul>
<li>Validators in HTML Template Bindings</li>
</ul><div ng:non-bindable><pre class="brush: js; html-script: true;">
&lt;input ng:validator="validator_type:parameters" [...]&gt;
</pre></div><ul>
<li>Validators in JavaScript</li>
</ul><div ng:non-bindable><pre class="brush: js;">
angular.validator.[validator_type](parameters)
</pre></div><p>The following example shows how to use the built-in angular integer validator:</p><doc:example>
<pre class="doc-source">
 Change me: &lt;input type="text" name="number" ng:validate="integer" value="123"&gt;
</pre>
<pre class="doc-scenario">
 it('should validate the default number string', function() {
   expect(element('input[name=number]').attr('class')).
      not().toMatch(/ng-validation-error/);
 });
 it('should not validate "foo"', function() {
   input('number').enter('foo');
   expect(element('input[name=number]').attr('class')).
      toMatch(/ng-validation-error/);
 });
</pre>
</doc:example><h2>Creating an Angular Validator</h2>

<p>To create a custom validator, you simply add your validator code as a method onto the
<code>angular.validator</code> object and provide input(s) for the validator function. Each input provided is
treated as an argument to the validator function.  Any additional inputs should be separated by
commas.</p>

<p>The following bit of pseudo-code shows how to set up a custom validator:</p><div ng:non-bindable><pre class="brush: js;">
angular.validator('your_validator', function(input [,additional params]) {
        [your validation code];
        if ( [validation succeeds] ) {
                return false;
        } else {
                return true; // No error message specified
                          }
}
</pre></div><p>Note that this validator returns "true" when the user's input is incorrect, as in "Yes, it's true,
there was a problem with that input". If you prefer to provide more information when a validator
detects a problem with input, you can specify an error message in the validator that angular will
display when the user hovers over the input widget.</p>

<p>To specify an error message, replace "<code>return true;</code>" with an error string, for example:</p>

<pre><code>  return "Must be a value between 1 and 5!";
</code></pre>

<p>Following is a sample UPS Tracking Number validator:</p><doc:example>
<pre class="doc-source">
&lt;script&gt;
angular.validator('upsTrackingNo', function(input, format) {
  var regexp = new RegExp("^" + format.replace(/9/g, '\\d') + "$");
  return input.match(regexp)?"":"The format must match " + format;
});
&lt;/script&gt;
&lt;input type="text" name="trackNo" size="40"
     ng:validate="upsTrackingNo:'1Z 999 999 99 9999 999 9'"
     value="1Z 123 456 78 9012 345 6"/&gt;
</pre>
<pre class="doc-scenario">
it('should validate correct UPS tracking number', function() {
 expect(element('input[name=trackNo]').attr('class')).
    not().toMatch(/ng-validation-error/);
});

it('should not validate in correct UPS tracking number', function() {
 input('trackNo').enter('foo');
 expect(element('input[name=trackNo]').attr('class')).
    toMatch(/ng-validation-error/);
});
</pre>
</doc:example><p>In this sample validator, we specify a regular expression against which to test the user's input.
Note that when the user's input matches <code>regexp</code>, the function returns "false" (""); otherwise it
returns the specified error message ("true").</p>

<p>Note: you can also access the current angular scope and DOM element objects in your validator
functions as follows:</p>

<ul>
<li><code>this</code> ===  The current angular scope.</li>
<li><code>this.$element</code> ===  The DOM element that contains the binding. This allows the filter to
manipulate the DOM in addition to transforming the input.</li>
</ul>

<h3>Related Topics</h3>

<ul>
<li><a href="#!/guide/dev_guide.templates">Angular Templates</a></li>
</ul>

<h3>Related API</h3>

<ul>
<li><a href="#!/api/angular.validator"><code>Validator API</code></a></li>
</ul></div>