Loading …

There was an error loading this resource. Please try again later.

ngInclude

- directive in module ng

Contents

Overview

Fetches, compiles and includes an external HTML fragment.

By default, the template URL is restricted to the same domain and protocol as the application document. This is done by calling $sce.getTrustedResourceUrl on it. To load templates from other domains or protocols you may either add them to your trusted resource URL list or wrap them as trusted values. Refer to AngularJS's Strict Contextual Escaping.

In addition, the browser's Same Origin Policy and Cross-Origin Resource Sharing (CORS) policy may further restrict whether the template is successfully loaded. For example, ngInclude won't work for cross-domain requests on all browsers and for file:// access on some browsers.

Directive Info

This directive creates new scope.
This directive executes at priority level -400.

Usage

as element:

<ng-include
  src="string"
  [onload="string"]
  [autoscroll="string"]>
...
</ng-include>

as attribute:

<ANY
  ng-include="string"
  [onload="string"]
  [autoscroll="string"]>
...
</ANY>

as CSS class:

<ANY class="ng-include: string; [onload: string;] [autoscroll: string;]"> ... </ANY>

Arguments

Param Type Details

ngInclude | src

Param	Type	Details
ngInclude \| src	string	AngularJS expression evaluating to URL. If the source is a string constant, make sure you wrap it in single quotes, e.g. `src="'myPartialTemplate.html'"`.
onload (optional)	string	Expression to evaluate when a new partial is loaded. Note: When using onload on SVG elements in IE11, the browser will try to call a function with the name on the window element, which will usually throw a "function is undefined" error. To fix this, you can instead use `data-onload` or a different form that matches `onload`.
autoscroll (optional)	string	Whether `ngInclude` should call $anchorScroll to scroll the viewport after the content is loaded. `- If the attribute is not set, disable scrolling. - If the attribute is set without value, enable scrolling. - Otherwise enable scrolling only if the expression evaluates to truthy value.`

string

AngularJS expression evaluating to URL. If the source is a string constant, make sure you wrap it in single quotes, e.g. src="'myPartialTemplate.html'".

onload

(optional)

string

Expression to evaluate when a new partial is loaded.

Note: When using onload on SVG elements in IE11, the browser will try to call a function with the name on the window element, which will usually throw a "function is undefined" error. To fix this, you can instead use data-onload or a different form that matches onload.

autoscroll

(optional)

string

Whether ngInclude should call $anchorScroll to scroll the viewport after the content is loaded.

- If the attribute is not set, disable scrolling.
- If the attribute is set without value, enable scrolling.
- Otherwise enable scrolling only if the expression evaluates to truthy value.

Events

$includeContentRequested

Emitted every time the ngInclude content is requested.

Type:

emit

Target:

the scope ngInclude was declared in

Parameters

Param	Type	Details
angularEvent	Object	Synthetic event object.
src	String	URL of content to load.

$includeContentLoaded

Emitted every time the ngInclude content is reloaded.

Type:

emit

Target:

the current ngInclude scope

Parameters

Param	Type	Details
angularEvent	Object	Synthetic event object.
src	String	URL of content to load.

$includeContentError

Emitted when a template HTTP request yields an erroneous response (status < 200 || status > 299)

Type:

emit

Target:

the scope ngInclude was declared in

Parameters

Param	Type	Details
angularEvent	Object	Synthetic event object.
src	String	URL of content to load.

Animations

Animation	Occurs
enter	when the expression changes, on the new include
leave	when the expression changes, on the old include

The enter and leave animation occur concurrently.

Click here to learn more about the steps involved in the animation.

Example

<div ng-controller="ExampleController">
  <select ng-model="template" ng-options="t.name for t in templates">
   <option value="">(blank)</option>
  </select>
  url of the template: <code>{{template.url}}</code>
  <hr/>
  <div class="slide-animate-container">
    <div class="slide-animate" ng-include="template.url"></div>
  </div>
</div>

angular.module('includeExample', ['ngAnimate'])
.controller('ExampleController', ['$scope', function($scope) {
  $scope.templates =
    [{ name: 'template1.html', url: 'template1.html'},
     { name: 'template2.html', url: 'template2.html'}];
  $scope.template = $scope.templates[0];
}]);

Content of template1.html

Content of template2.html

.slide-animate-container {
  position:relative;
  background:white;
  border:1px solid black;
  height:40px;
  overflow:hidden;
}

.slide-animate {
  padding:10px;
}

.slide-animate.ng-enter, .slide-animate.ng-leave {
  transition:all cubic-bezier(0.250, 0.460, 0.450, 0.940) 0.5s;

  position:absolute;
  top:0;
  left:0;
  right:0;
  bottom:0;
  display:block;
  padding:10px;
}

.slide-animate.ng-enter {
  top:-50px;
}
.slide-animate.ng-enter.ng-enter-active {
  top:0;
}

.slide-animate.ng-leave {
  top:0;
}
.slide-animate.ng-leave.ng-leave-active {
  top:50px;
}

var templateSelect = element(by.model('template'));
var includeElem = element(by.css('[ng-include]'));

it('should load template1.html', function() {
  expect(includeElem.getText()).toMatch(/Content of template1.html/);
});

it('should load template2.html', function() {
  if (browser.params.browser === 'firefox') {
    // Firefox can't handle using selects
    // See https://github.com/angular/protractor/issues/480
    return;
  }
  templateSelect.click();
  templateSelect.all(by.css('option')).get(2).click();
  expect(includeElem.getText()).toMatch(/Content of template2.html/);
});

it('should change to blank', function() {
  if (browser.params.browser === 'firefox') {
    // Firefox can't handle using selects
    return;
  }
  templateSelect.click();
  templateSelect.all(by.css('option')).get(0).click();
  expect(includeElem.isPresent()).toBe(false);
});