expression.ngdoc

@ngdoc overview
@name Developer Guide: Expressions
@description

Expressions are JavaScript-like code snippets that are usually placed in bindings such as `{{
expression }}`. Expressions are processed by the {@link api/ng.$parse $parse}
service. Expressions are often post processed using {@link filter filters} to create a more user-friendly format.

For example, these are all valid expressions in angular:

  * `1+2`
  * `user.name`


## Angular Expressions vs. JS Expressions

It might be tempting to think of Angular view expressions as JavaScript expressions, but that is
not entirely correct, since Angular does not use a JavaScript `eval()` to evaluate expressions.
You can think of Angular expressions as JavaScript expressions with following differences:

  * **Attribute Evaluation:** evaluation of all properties are against the scope doing the
    evaluation, unlike in JavaScript where the expressions are evaluated against the global
    `window`.

  * **Forgiving:** expression evaluation is forgiving to `undefined` and `null`, unlike in JavaScript,
    where trying to evaluate undefined properties can generate `ReferenceError` or `TypeError`.

  * **No Control Flow Statements:** you cannot do any of the following in angular expression:
    conditionals, loops, or throw.

If, on the other hand, you do want to run arbitrary JavaScript code, you should make it a
controller method and call the method. If you want to `eval()` an angular expression from
JavaScript, use the {@link api/ng.$rootScope.Scope#methods_$eval `$eval()`} method.

## Example
<doc:example>
<doc:source>
 1+2={{1+2}}
</doc:source>
<doc:scenario>
 it('should calculate expression in binding', function() {
   expect(binding('1+2')).toEqual('3');
 });
</doc:scenario>
</doc:example>

You can try evaluating different expressions here:

<doc:example>
<doc:source>
 <script>
   function Cntl2($scope) {
     var exprs = $scope.exprs = [];
     $scope.expr = '3*10|currency';
     $scope.addExp = function(expr) {
        exprs.push(expr);
     };

     $scope.removeExp = function(index) {
       exprs.splice(index, 1);
     };
   }
 </script>
 <div ng-controller="Cntl2" class="expressions">
   Expression:
   <input type='text' ng-model="expr" size="80"/>
   <button ng-click="addExp(expr)">Evaluate</button>
   <ul>
    <li ng-repeat="expr in exprs track by $index">
      [ <a href="" ng-click="removeExp($index)">X</a> ]
      <tt>{{expr}}</tt> => <span ng-bind="$parent.$eval(expr)"></span>
     </li>
   </ul>
 </div>
</doc:source>
<doc:scenario>
 it('should allow user expression testing', function() {
    element('.expressions :button').click();
    var li = using('.expressions ul').repeater('li');
    expect(li.count()).toBe(1);
    expect(li.row(0)).toEqual(["3*10|currency", "$30.00"]);
 });
</doc:scenario>
</doc:example>


# Property Evaluation

Evaluation of all properties takes place against a scope. Unlike JavaScript, where names default
to global window properties, Angular expressions have to use {@link api/ng.$window
`$window`} to refer to the global `window` object. For example, if you want to call `alert()`, which is
defined on `window`, in an expression you must use `$window.alert()`. This is done intentionally to
prevent accidental access to the global state (a common source of subtle bugs).

<doc:example>
<doc:source>
 <script>
   function Cntl1($window, $scope){
     $scope.name = 'World';

     $scope.greet = function() {
       ($window.mockWindow || $window).alert('Hello ' + $scope.name);
     }
   }
 </script>
 <div class="example2" ng-controller="Cntl1">
   Name: <input ng-model="name" type="text"/>
   <button ng-click="greet()">Greet</button>
 </div>
</doc:source>
<doc:scenario>
 it('should calculate expression in binding', function() {
   var alertText;
   this.addFutureAction('set mock', function($window, $document, done) {
     $window.mockWindow = {
       alert: function(text){ alertText = text; }
     };
     done();
   });
   element(':button:contains(Greet)').click();
   expect(this.addFuture('alert text', function(done) {
     done(null, alertText);
   })).toBe('Hello World');
 });
</doc:scenario>
</doc:example>

## Forgiving

Expression evaluation is forgiving to undefined and null. In JavaScript, evaluating `a.b.c` throws
an exception if `a` is not an object. While this makes sense for a general purpose language, the
expression evaluations are primarily used for data binding, which often look like this:

        {{a.b.c}}

It makes more sense to show nothing than to throw an exception if `a` is undefined (perhaps we are
waiting for the server response, and it will become defined soon). If expression evaluation wasn't
forgiving we'd have to write bindings that clutter the code, for example: `{{((a||{}).b||{}).c}}`

Similarly, invoking a function `a.b.c()` on undefined or null simply returns undefined.


## No Control Flow Statements

You cannot write a control flow statement in an expression. The reason behind this is core to the
Angular philosophy that application logic should be in controllers, not in the view. If you need a
conditional, loop, or to throw from a view expression, delegate to a JavaScript method instead.