Skip to content
This repository was archived by the owner on Apr 12, 2024. It is now read-only.

Commit 9525d0a

Browse files
docs($compile): clarify linking when there are templateUrl directives
Closes #8877 Closes #8631
1 parent e0d49a3 commit 9525d0a

File tree

1 file changed

+19
-4
lines changed

1 file changed

+19
-4
lines changed

src/ng/compile.js

+19-4
Original file line numberDiff line numberDiff line change
@@ -258,9 +258,17 @@
258258
*
259259
*
260260
* #### `templateUrl`
261-
* Same as `template` but the template is loaded from the specified URL. Because
262-
* the template loading is asynchronous the compilation/linking is suspended until the template
263-
* is loaded.
261+
* This is similar to `template` but the template is loaded from the specified URL, asynchronously.
262+
*
263+
* Because template loading is asynchronous the compiler will suspend compilation of directives on that element
264+
* for later when the template has been resolved. In the meantime it will continue to compile and link
265+
* sibling and parent elements as though this element had not contained any directives.
266+
*
267+
* The compiler does not suspend the entire compilation to wait for templates to be loaded because this
268+
* would result in the whole app "stalling" until all templates are loaded asynchronously - even in the
269+
* case when only one deeply nested directive has `templateUrl`.
270+
*
271+
* Template loading is asynchronous even if the template has been preloaded into the {@link $templateCache}
264272
*
265273
* You can specify `templateUrl` as a string representing the URL or as a function which takes two
266274
* arguments `tElement` and `tAttrs` (described in the `compile` function api below) and returns
@@ -387,7 +395,14 @@
387395
*
388396
* #### Post-linking function
389397
*
390-
* Executed after the child elements are linked. It is safe to do DOM transformation in the post-linking function.
398+
* Executed after the child elements are linked.
399+
*
400+
* Note that child elements that contain `templateUrl` directives will not have been compiled
401+
* and linked since they are waiting for their template to load asynchronously and their own
402+
* compilation and linking has been suspended until that occurs.
403+
*
404+
* It is safe to do DOM transformation in the post-linking function on elements that are not waiting
405+
* for their async templates to be resolved.
391406
*
392407
* <a name="Attributes"></a>
393408
* ### Attributes

0 commit comments

Comments
 (0)