Built-in directives - AngularJS Full Tutorial

AngularJS - Built-in directives

Start

Angular expressions - Text vs. Number

This example demonstrates how Angular expressions are evaluated when using type="text" and type="number" for the input element. Consider the following controller and view:

Controller


var app = angular.module('app', []);

 app.controller('ctrl', function($scope) {
     $scope.textInput = {
         value: '5'
     };     
     $scope.numberInput = {
         value: 5
     };
 });

View

<div ng-app="app" ng-controller="ctrl">
    <input type="text" ng-model="textInput.value">
    { { textInput.value + 5 } }
    <input type="number" ng-model="numberInput.value">
    { { numberInput.value + 5 } }
</div>

When using + in an expression bound to text input, the operator will concatenate the strings (first example), displaying 55 on the screen*.
When using + in an expression bound to number input, the operator return the sum of the numbers (second example), displaying 10 on the screen*.

* - That is until the user changes the value in the input field, afterward the display will change accordingly.

Working Example (opens new window)

ngIf

ng-if (opens new window) is a directive similar to ng-show (opens new window) but inserts or removes the element from the DOM instead of simply hiding it. Angular 1.1.5 introduced ng-If directive. You can Use ng-if directive above 1.1.5 versions. This is useful because Angular will not process digests for elements inside a removed ng-if reducing the workload of Angular especially for complex data bindings.

Unlike ng-show, the ng-if directive creates a child scope which uses prototypal inheritance. This means that setting a primitive value on the child scope will not apply to the parent. To set a primitive on the parent scope the $parent property on the child scope will have to be used.

JavaScript

angular.module('MyApp', []);

angular.module('MyApp').controller('myController', ['$scope', '$window', function myController($scope, $window) {
    $scope.currentUser= $window.localStorage.getItem('userName');
}]);

View

<div ng-controller="myController">
    <div ng-if="currentUser">
        Hello, { {currentUser} }
    </div>
    <div ng-if="!currentUser">
        <a href="/login">Log In</a>
        <a href="/register">Register</a>
    </div>
</div>

DOM If `currentUser` Is Not Undefined

<div ng-controller="myController">
    <div ng-if="currentUser">
        Hello, { {currentUser} }
    </div>
    <!-- ng-if: !currentUser -->
</div>

DOM If `currentUser` Is Undefined

<div ng-controller="myController">
    <!-- ng-if: currentUser -->
    <div ng-if="!currentUser">
        <a href="/login">Log In</a>
        <a href="/register">Register</a>
    </div>
</div>

Working Example (opens new window)

Function Promise

The ngIf directive accepts functions as well, which logically require to return true or false.

<div ng-if="myFunction()">
    <span>Span text</span>
</div>

The span text will only appear if the function returns true.

$scope.myFunction = function() {
    var result = false;
    // Code to determine the boolean value of result 
    return result;
};

As any Angular expression the function accepts any kind of variables.

ngRepeat

ng-repeat is a built in directive in Angular which lets you iterate an array or an object and gives you the ability to repeat an element once for each item in the collection.

ng-repeat an array

<ul>
    <li ng-repeat="item in itemCollection">
       { {item.Name} }
    </li>
</ul>

Where:
item = individual item in the collection
itemCollection = The array you are iterating

ng-repeat an object

<ul>
    <li ng-repeat="(key, value) in myObject">
       { {key} } : { {value} }
    </li>
</ul>

Where:
key = the property name
value = the value of the property
myObject = the object you are iterating

filter your ng-repeat by user input

<input type="text" ng-model="searchText">
<ul>
    <li ng-repeat="string in stringArray | filter:searchText">
       { {string} }
    </li>
</ul>

Where:
searchText = the text that the user wants to filter the list by
stringArray = an array of strings, e.g. ['string', 'array']

You can also display or reference the filtered items elsewhere by assigning the filter output an alias with as aliasName, like so:

<input type="text" ng-model="searchText">
<ul>
    <li ng-repeat="string in stringArray | filter:searchText as filteredStrings">
       { {string} }
    </li>
</ul>
<p>There are { {filteredStrings.length} } matching results</p>

ng-repeat-start and ng-repeat-end

To repeat multiple DOM elements by defining a start and an end point you can use the ng-repeat-start and ng-repeat-end directives.

<ul>
    <li ng-repeat-start="item in [{a: 1, b: 2}, {a: 3, b:4}]">
        { {item.a} }
    </li>
    <li ng-repeat-end>
        { {item.b} }
    </li>
</ul>

Output:

It is important to always close ng-repeat-start with ng-repeat-end.

Variables

ng-repeat also exposes these variables inside the expression

Variable	Type	Details
`$index`	Number	Equals to the index of the current iteration ($index===0 will evaluate to true at the first iterated element; see `$first`)
`$first`	Boolean	Evaluates to true at the first iterated element
`$last`	Boolean	Evaluates to true at the last iterated element
`$middle`	Boolean	Evaluates to true if the element is between the `$first` and `$last`
`$even`	Boolean	Evaluates to true at an even numbered iteration (equivalent to `$index%2===0`)
`$odd`	Boolean	Evaluates to true at an odd numbered iteration (equivalent to `$index%2===1`)

Performance considerations

Rendering ngRepeat can become slow, especially when using large collections.

If the objects in the collection have an identifier property, you should always track by the identifier instead of the whole object, which is the default functionality. If no identifier is present, you can always use the built-in $index.

<div ng-repeat="item in itemCollection track by item.id">
<div ng-repeat="item in itemCollection track by $index">

Scope of ngRepeat

ngRepeat will always create an isolated child scope so care must be taken if the parent scope needs to be accessed inside the repeat.

Here is a simple example showing how you can set a value in your parent scope from a click event inside of ngRepeat.

scope val:  { {val} }<br/>
ctrlAs val: { {ctrl.val} }
<ul>
    <li ng-repeat="item in itemCollection">
        <a href="#" ng-click="$parent.val=item.value; ctrl.val=item.value;">
            { {item.label} } { {item.value} }
        </a>
    </li>
</ul>

$scope.val = 0;
this.val = 0;

$scope.itemCollection = [{
    id: 0,
    value: 4.99,
    label: 'Football'
},
{
    id: 1,
    value: 6.99,
    label: 'Baseball'
},
{
    id: 2,
    value: 9.99,
    label: 'Basketball'
}];

If there was only val = item.value at ng-click it won't update the val in the parent scope because of the isolated scope. That's why the parent scope is accessed with $parent reference or with the controllerAs syntax (e.g. ng-controller="mainController as ctrl").

Nested ng-repeat

You can also use nested ng-repeat.

<div ng-repeat="values in test">
    <div ng-repeat="i in values">
      [{ {$parent.$index} },{ {$index} }] { {i} }
    </div>
</div>

var app = angular.module("myApp", []);
app.controller("ctrl", function($scope) {
  $scope.test = [
    ['a', 'b', 'c'],
    ['d', 'e', 'f']
  ];
});

Here to access the index of parent ng-repeat inside child ng-repeat, you can use $parent.$index.

ngCloak

The `ngCloak` directive is used to prevent the Angular html template from being briefly displayed by the browser in its raw (uncompiled) form while your application is loading. - [View source](https://docs.angularjs.org/api/ng/directive/ngCloak)

HTML

<div ng-cloak>
  <h1>Hello { { name } }</h1>
</div>

ngCloak can be applied to the body element, but the preferred usage is to apply multiple ngCloak directives to small portions of the page to permit progressive rendering of the browser view.

The ngCloak directive has no parameters.

Built-In Directives Cheat Sheet

ng-app Sets the AngularJS section.

ng-init Sets a default variable value.

ng-bind Alternative to { { } } template.

ng-bind-template Binds multiple expressions to the view.

ng-non-bindable States that the data isn't bindable.

ng-bind-html Binds inner HTML property of an HTML element.

ng-change Evaluates specified expression when the user changes the input.

ng-checked Sets the checkbox.

ng-class Sets the css class dynamically.

ng-cloak Prevents displaying the content until AngularJS has taken control.

ng-click Executes a method or expression when element is clicked.

ng-controller Attaches a controller class to the view.

ng-disabled Controls the form element's disabled property

ng-form Sets a form

ng-href Dynamically bind AngularJS variables to the href attribute.

ng-include Used to fetch, compile and include an external HTML fragment to your page.

ng-if Remove or recreates an element in the DOM depending on an expression

ng-switch Conditionally switch control based on matching expression.

ng-model Binds an input,select, textarea etc elements with model property.

ng-readonly Used to set readonly attribute to an element.

ng-repeat Used to loop through each item in a collection to create a new template.

ng-selected Used to set selected option in element.

ng-show/ng-hide Show/Hide elements based on an expression.

ng-src Dynamically bind AngularJS variables to the src attribute.

ng-submit Bind angular expressions to onsubmit events.

ng-value Bind angular expressions to the value of .

ng-required Bind angular expressions to onsubmit events.

ng-style Sets CSS style on an HTML element.

ng-pattern Adds the pattern validator to ngModel.

ng-maxlength Adds the maxlength validator to ngModel.

ng-minlength Adds the minlength validator to ngModel.

ng-classeven Works in conjunction with ngRepeat and take effect only on odd (even) rows.

ng-classodd Works in conjunction with ngRepeat and take effect only on odd (even) rows.

ng-cut Used to specify custom behavior on cut event.

ng-copy Used to specify custom behavior on copy event.

ng-paste Used to specify custom behavior on paste event.

ng-options Used to dynamically generate a list of elements for the element.

ng-list Used to convert string into list based on specified delimiter.

ng-open Used to set the open attribute on the element, if the expression inside ngOpen is truthy.

Source (edited a bit) (opens new window)

ng-model-options

ng-model-options allows to change the default behavior of ng-model, this directive allows to register events that will fire when the ng-model is updated and to attach a debounce effect.

This directive accepts an expression that will evaluate to a definition object or a reference to a scope value.

Example:

<input type="text" ng-model="myValue" ng-model-options="{'debounce': 500}">

The above example will attach a debounce effect of 500 milliseconds on myValue, which will cause the model to update 500 ms after the user finished typing over the input (that is, when the myValue finished updating).

Available object properties

`updateOn`: specifies which event should be bound to the input

ng-model-options="{ updateOn: 'blur'}" // will update on blur

`debounce`: specifies a delay of some millisecond towards the model update

ng-model-options="{'debounce': 500}" // will update the model after 1/2 second

`allowInvalid`: a boolean flag allowing for an invalid value to the model, circumventing default form validation, by default these values would be treated as `undefined`.

`getterSetter`: a boolean flag indicating if to treat the `ng-model` as a getter/setter function instead of a plain model value. The function will then run and return the model value. **Example:**

<input type="text" ng-model="myFunc" ng-model-options="{'getterSetter': true}">

$scope.myFunc = function() {return "value";}

`timezone`: defines the timezone for the model if the input is of the `date` or `time`. types

ngInclude

ng-include allows you to delegate the control of one part of the page to a specific controller. You may want to do this because the complexity of that component is becoming such that you want to encapsulate all the logic in a dedicated controller.

An example is:


 <div ng-include
       src="'/gridview'"
       ng-controller='gridController as gc'>
  </div>

Note that the /gridview will need to be served by the web server as a distinct and legitimate url.

Also, note that the src-attribute accepts an Angular expression. This could be a variable or a function call for example or, like in this example, a string constant. In this case you need to make sure to wrap the source URL in single quotes, so it will be evaluated as a string constant. This is a common source of confusion.

Within the /gridview html, you can refer to the gridController as if it were wrapped around the page, eg:

<div class="row">
  <button type="button" class="btn btn-default" ng-click="gc.doSomething()"></button>
</div>

ngCopy

The ngCopy directive specifies behavior to be run on a copy event.

Prevent a user from copying data

<p ng-copy="blockCopy($event)">This paragraph cannot be copied</p>

In the controller

$scope.blockCopy = function(event) {
    event.preventDefault();
    console.log("Copying won't work");
}

ngClick

The ng-click directive attaches a click event to a DOM element.

The ng-click directive allows you to specify custom behavior when an element of DOM is clicked.

It is useful when you want to attach click events on buttons and handle them at your controller.

This directive accepts an expression with the events object available as $event

HTML

<input ng-click="onClick($event)">Click me</input>

Controller

.controller("ctrl", function($scope) {   
    $scope.onClick = function(evt) {
        console.debug("Hello click event: %o ",evt);
    } 
})

HTML

<button ng-click="count = count + 1" ng-init="count=0">
  Increment
</button>
<span>
  count: { {count} }
</span>

HTML

<button ng-click="count()" ng-init="count=0">
  Increment
</button>
<span>
  count: { {count} }
</span>

Controller

...

$scope.count = function(){
    $scope.count = $scope.count + 1;
}
...

When the button is clicked, an invocation of the onClick function will print "Hello click event" followed by the event object.

ngPaste

The ngPaste directive specifies custom behavior to run when a user pastes content

<input ng-paste="paste=true" ng-init="paste=false" placeholder='paste here'>
pasted: { {paste} }

ngOptions

ngOptions is a directive that simplifies the creation of a html dropdown box for the selection of an item from an array that will be stored in a model. The ngOptions attribute is used to dynamically generate a list of <option> elements for the <select> element using the array or object obtained by evaluating the ngOptions comprehension expression.

With ng-options the markup can be reduced to just a select tag and the directive will create the same select:

<select ng-model="selectedFruitNgOptions" 
        ng-options="curFruit as curFruit.label for curFruit in fruit">
</select>

There is anther way of creating select options using ng-repeat, but it is not recommended to use ng-repeat as it is mostly used for general purpose like, the forEach just to loop. Whereas ng-options is specifically for creating select tag options.

Above example using ng-repeat would be

<select ng-model="selectedFruit">
    <option ng-repeat="curFruit in fruit" value="{ {curFruit} }">
        { {curFruit.label} }
    </option>
</select>

FULL EXAMPLE (opens new window)

Lets see the above example in detail also with some variations in it.

Data model for the example:

$scope.fruit = [
    { label: "Apples", value: 4, id: 2 },
    { label: "Oranges", value: 2, id: 1 },
    { label: "Limes", value: 4, id: 4 },
    { label: "Lemons", value: 5, id: 3 }
];

<!-- label for value in array -->
<select ng-options="f.label for f in fruit" ng-model="selectedFruit"></select>