Compiles a piece of HTML string or DOM into a template and produces a template function, which
can then be used to link scope
and the template together.
The compilation is a process of walking the DOM tree and trying to match DOM elements to
markup
, attrMarkup
,
widgets
, and directives
. For each match it
executes corresponding markup, attrMarkup, widget or directive template function and collects the
instance functions into a single template function which is then returned.
The template function can then be used once to produce the view or as it is the case with
repeater
many-times, in which case each call results in a view
that is a DOM clone of the original template.
// compile the entire window.document and give me the scope bound to this template. var rootScope = angular.compile(window.document)(); // compile a piece of html var rootScope2 = angular.compile('<div ng:click="clicked = true">click me</div>')(); // compile a piece of html and retain reference to both the dom and scope var template = angular.element('<div ng:click="clicked = true">click me</div>'), scope = angular.compile(template)(); // at this point template was transformed into a view
angular.compile(element);
element – {string|DOMElement} –
Element or HTML to compile into a template function.
{function([scope][, cloneAttachFn])}
– a template function which is used to bind template (a DOM element/tree) to a scope. Where:
scope
- A Scope
to bind to. If none specified, then a new
root scope is created.cloneAttachFn
- If cloneAttachFn
is provided, then the link function will clone the
template
and call the cloneAttachFn
function allowing the caller to attach the
cloned elements to the DOM document at the appropriate place. The cloneAttachFn
is
called as:
cloneAttachFn(clonedElement, scope)
where:
clonedElement
- is a clone of the original element
passed into the compiler.scope
- is the current scope with which the linking function is working with.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.
If you need access to the bound view, there are two ways to do it:
var view = angular.element('<p>{{total}}</p>'), scope = angular.compile(view)();
var original = angular.element('<p>{{total}}</p>'), 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`
Compiler Methods For Widgets and Directives:
The following methods are available for use when you write your own widgets, directives, and markup. (Recall that the compile function's this is a reference to the compiler.)
compile(element)
- returns linker -
Invoke a new instance of the compiler to compile a DOM element and return a linker function.
You can apply the linker function to the original element or a clone of the original element.
The linker function returns a scope.
comment(commentText)
- returns element - Create a comment element.
element(elementName)
- returns element - Create an element by name.
text(text)
- returns element - Create a text element.
descend([set])
- returns descend state (true or false). Get or set the current descend
state. If true the compiler will descend to children elements.
directives([set])
- returns directive state (true or false). Get or set the current
directives processing state. The compiler will process directives only when directives set to
true.
For information on how the compiler works, see the Angular HTML Compiler section of the Developer Guide.