dev_guide.compiler.understanding_compiler.html

<h1>Developer Guide: Angular HTML Compiler: Understanding How the Compiler Works</h1>
<div class="developer-guide-angular-html-compiler-understanding-how-the-compiler-works"><fieldset class="workInProgress"><legend>Work in Progress</legend>
This page is currently being revised. It might be incomplete or contain inaccuracies.</fieldset>
<p>Every <a href="#!/api/angular.widget"><code>widget</code></a>, <a href="#!/api/angular.directive"><code>directive</code></a> and <a href="#!/guide/dev_guide.compiler.markup">markup</a> is defined with a compile function, which the angular compiler
executes on each widget or directive it encounters. The compile function optionally returns a link
function.  This compilation process happens automatically when the page is loaded when you specify
<code>ng:autobind</code> in the script tag from which you load the angular script file.  (See <a href="#!/guide/dev_guide.bootstrap">Initializing Angular</a>.)</p>

<p>The compile and link functions are related as follows:</p>

<ul>
<li><strong>compile function</strong> — Registers a listener for the widget, directive, or markup expression. The
compiler calls this function exactly once.</li>
<li><strong>link function</strong> — Sets up the listener registered by the compile function. This function can be
called multiple times, once per cloned DOM element. For example, in the case of the <a href="#!/api/angular.widget.@ng:repeat"><code>repeater widget</code></a> used in a list element (<code>&lt;li ng:repeat="[item in
dataset]"</code>), the link function gets called to set up a listener on each element in the list.</li>
</ul>

<p>Note that angular's built-in widgets, directives, and markup have predefined compile and link
functions that you don't need to modify. When you create your own widgets, directives, or markup,
you must write compile and link functions for them. Refer to the <a href="#!/api/angular.compile"><code>Compiler API</code></a> for details.</p>

<p>When the angular compiler compiles a page, it proceeds through 3 phases: Compile, Create Root
Scope, and Link:</p>

<ol>
<li><p>Compile Phase</p>

<ol><li>Recursively traverse the DOM, depth-first.</li>
<li>Look for a matching compile function of type widget, then markup, then directive.</li>
<li>If a compile function is found then execute it.</li>
<li>When the compile function completes, it should return a link function. Aggregate this link
function with all link functions returned previously by step 3.</li>
<li>Repeat steps 3 and 4 for all compile functions found.</li></ol></li>
</ol>

<p>The result of the compilation phase is an aggregate link function, which comprises all of the
individual link functions.</p>

<ol>
<li><p>Create Root Scope Phase</p></li>
<li><p>Inject all services into the root scope.</p></li>
<li><p>Link Phase</p>

<ol><li>Execute the aggregate link function with the root scope. The aggregate link function calls
all of the individual link functions that were generated in the compile phase.</li>
<li>If there are any clones of the DOM caused by repeating elements, call the link function
multiple times, one for each repeating item.</li></ol></li>
</ol>

<p>Note that while the compile function is executed exactly once, the link function can be executed
multiple times, for example, once for each iteration in a repeater.</p>

<p>The angular compiler exposes methods that you will need to make use of when writing your own
widgets and directives.  For information on these methods, see the <a href="#!/api/angular.compile"><code>Compiler API doc</code></a>.</p>

<h3>Related Topics</h3>

<ul>
<li><a href="#!/guide/dev_guide.compiler">Angular HTML Compiler</a></li>
<li><a href="#!/guide/dev_guide.compiler.extending_compiler">Extending the Angular Compiler</a></li>
<li><a href="#!/guide/dev_guide.compiler.testing_dom_element">Testing a New DOM Element</a></li>
</ul>

<h3>Related API</h3>

<ul>
<li><a href="#!/api/angular.compile"><code>angular.compile()</code></a></li>
</ul></div>