angular.compile.html

<h1>angular.compile</h1>
<div class="angular-compile"><fieldset class="workInProgress"><legend>Work in Progress</legend>
This page is currently being revised. It might be incomplete or contain inaccuracies.</fieldset>
<h2>Description</h2>
<div class="description"><p>Compiles a piece of HTML string or DOM into a template and produces a template function, which
can then be used to link <a href="#!angular.scope"><code>scope</code></a> and the template together.</p>

<p>The compilation is a process of walking the DOM tree and trying to match DOM elements to
<a href="#!angular.markup"><code>markup</code></a>, <a href="#!angular.attrMarkup"><code>attrMarkup</code></a>,
<a href="#!angular.widget"><code>widgets</code></a>, and <a href="#!angular.directive"><code>directives</code></a>. For each match it
executes coresponding markup, attrMarkup, widget or directive template function and collects the
instance functions into a single template function which is then returned.</p>

<p>The template function can then be used once to produce the view or as it is the case with
<a href="#!angular.widget.@ng:repeat"><code>repeater</code></a> many-times, in which case each call results in a view
that is a DOM clone of the original template.</p><div ng:non-bindable><pre class="brush: js; html-script: true;">
    //copile the entire window.document and give me the scope bound to this template.
    var rootSscope = angular.compile(window.document)();

    //compile a piece of html
    var rootScope2 = angular.compile(''&lt;div ng:click="clicked = true"&gt;click me&lt;/div&gt;')();

    //compile a piece of html and retain reference to both the dom and scope
    var template = angular.element('&lt;div ng:click="clicked = true"&gt;click me&lt;/div&gt;'),
        scoope = angular.compile(view)();
    //at this point template was transformed into a view
   </pre></div></div>
<h2>Usage</h2>
<div class="usage"><div ng:non-bindable=""><pre class="brush: js; html-script: true;">angular.compile(element);</pre>
</div>
<h3>Parameters</h3>
<ul class="parameters"><li><code ng:non-bindable="">element – {string|DOMElement} – </code>
<p>Element or HTML to compile into a template function.</p></li>
</ul>
<h3>Returns</h3>
<div class="returns"><code ng:non-bindable="">{function([scope][, cloneAttachFn])}</code>
– <p>a template function which is used to bind template
(a DOM element/tree) to a scope. Where:</p>

<ul>
<li><code>scope</code> - A <a href="#!angular.scope"><code>scope</code></a> to bind to. If none specified, then a new
          root scope is created.</li>
<li><p><code>cloneAttachFn</code> - If <code>cloneAttachFn</code> is provided, then the link function will clone the
          <code>template</code> and call the <code>cloneAttachFn</code> function allowing the caller to attach the
          cloned elements to the DOM document at the approriate place. The <code>cloneAttachFn</code> is
          called as: <br/> <code>cloneAttachFn(clonedElement, scope)</code> where:</p>

<ul><li><code>clonedElement</code> - is a clone of the original <code>element</code> passed into the compiler.</li>
<li><code>scope</code> - is the current scope with which the linking function is working with.</li></ul></li>
</ul>

<p>Calling the template function returns the scope to which the element is bound to. It is either
the same scope as the one passed into the template function, or if none were provided it's the
newly create scope.</p>

<p>If you need access to the bound view, there are two ways to do it:</p>

<ul>
<li>If you are not asking the linking function to clone the template, create the DOM element(s)
before you send them to the compiler and keep this reference around.</li>
</ul><div ng:non-bindable><pre class="brush: js; html-script: true;">
    var view = angular.element('&lt;p&gt;{{total}}&lt;/p&gt;'),
        scope = angular.compile(view)();
  </pre></div><ul>
<li>if on the other hand, you need the element to be cloned, the view reference from the original
example would not point to the clone, but rather to the original template that was cloned. In
this case, you can access the clone via the cloneAttachFn:</li>
</ul><div ng:non-bindable><pre class="brush: js; html-script: true;">
    var original = angular.element('&lt;p&gt;{{total}}&lt;/p&gt;'),
        scope = someParentScope.$new(),
        clone;

    angular.compile(original)(scope, function(clonedElement, scope) {
      clone = clonedElement;
      //attach the clone to DOM document at the right place
    });

    //now we have reference to the cloned DOM via `clone`
  </pre></div></div>
</div>
</div>