Skip to content

Commit ef4bb28

Browse files
mheverymhevery
committed
Change API angular.compile(element)([scope], [element/true])
1 parent 496e6bf commit ef4bb28

15 files changed

Lines changed: 524 additions & 461 deletions

‎CHANGELOG.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@
88
recommended way to deal with initializing scope is to put it in the root constructor controller.
99
To migrate simply remove the call to $init() and move any code you had before $init() to the
1010
root controller.
11+
- Change API angular.compile(..) to angular.compile(element)([scope], [element/true])
1112

1213

1314
<a name="0.9.11"><a/>

‎src/Angular.js‎

Lines changed: 40 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -793,21 +793,50 @@ function merge(src, dst) {
793793
* @function
794794
*
795795
* @description
796-
* Compiles a piece of HTML or DOM into a {@link angular.scope scope} object.
796+
* Compiles a piece of HTML string or DOM into a view and produces a linking function, which can
797+
* then be used to link {@link angular.scope scope} and the template together. The compilation
798+
* process walks the DOM tree and tries to match DOM elements to {@link angular.markup markup},
799+
* {@link angular.attrMarkup attrMarkup}, {@link angular.widget widgets}, and
800+
* {@link angular.directive directives}. For each match it executes coresponding markup, \
801+
* attrMarkup, widget or directive template function and collects the instance functions into a
802+
* single linking function which is then returned. The linking function can then be used
803+
* many-times-over on clones of compiled DOM structure, (For example when compiling
804+
* {@link angular.widget.@ng:repeat repeater} the resulting linking function is called once for
805+
* each item in the collection. The `ng:repeat` does this by cloning the template DOM once for
806+
* each item in collection and then calling the linking function to link the cloned template
807+
* with the a new scope for each item in the collection.)
808+
*
797809
<pre>
798-
var scope1 = angular.compile(window.document);
810+
var mvc1 = angular.compile(window.document)();
811+
mvc1.view; // compiled view elment
812+
mvc1.scope; // scope bound to the element
799813
800-
var scope2 = angular.compile('<div ng:click="clicked = true">click me</div>');
814+
var mvc2 = angular.compile('<div ng:click="clicked = true">click me</div>')();
801815
</pre>
802816
*
803-
* @param {string|DOMElement} element Element to compile.
804-
* @param {Object=} parentScope Scope to become the parent scope of the newly compiled scope.
805-
* @returns {Object} Compiled scope object.
817+
* @param {string|DOMElement} element Element or HTML to compile into a template function.
818+
* @returns {function([scope][, element])} a template function which is used to bind element
819+
* and scope. Where:
820+
*
821+
* * `scope` - {@link angular.scope scope} A scope to bind to. If none specified, then a new
822+
* root scope is created.
823+
* * `element` - {@link angular.element element} Element to use as the template. If none
824+
* specified then reuse the element from `angular.compile(element)`. If `true`
825+
* then clone the `angular.compile(element)`. The element must be either the same
826+
* element as `angular.compile(element)` or an identical clone to
827+
* `angular.compile(element)`. Using an element with differnt structure will cause
828+
* unpredictable behavior.
829+
*
830+
* Calling the template function returns object: `{scope:?, view:?}`, where:
831+
*
832+
* * `view` - the DOM element which represents the compiled template. Either same or clone of
833+
* `element` specifed in compile or template function.
834+
* * `scope` - scope to which the element is bound to. Either a root scope or scope specified
835+
* in the template function.
806836
*/
807-
function compile(element, parentScope) {
808-
var compiler = new Compiler(angularTextMarkup, angularAttrMarkup, angularDirective, angularWidget),
809-
$element = jqLite(element);
810-
return compiler.compile($element)($element, parentScope);
837+
function compile(element) {
838+
return new Compiler(angularTextMarkup, angularAttrMarkup, angularDirective, angularWidget)
839+
.compile(element);
811840
}
812841
/////////////////////////////////////////////////
813842

@@ -989,7 +1018,7 @@ function toKeyValue(obj) {
9891018
function angularInit(config){
9901019
if (config.autobind) {
9911020
// TODO default to the source of angular.js
992-
var scope = compile(window.document, _null, {'$config':config}),
1021+
var scope = compile(window.document)(null, createScope({'$config':config})),
9931022
$browser = scope.$service('$browser');
9941023

9951024
if (config.css)

‎src/Compiler.js‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -80,30 +80,30 @@ function Compiler(markup, attrMarkup, directives, widgets){
8080
}
8181

8282
Compiler.prototype = {
83-
compile: function(element) {
84-
element = jqLite(element);
83+
compile: function(templateElement) {
84+
templateElement = jqLite(templateElement);
8585
var index = 0,
8686
template,
87-
parent = element.parent();
87+
parent = templateElement.parent();
8888
if (parent && parent[0]) {
8989
parent = parent[0];
9090
for(var i = 0; i < parent.childNodes.length; i++) {
91-
if (parent.childNodes[i] == element[0]) {
91+
if (parent.childNodes[i] == templateElement[0]) {
9292
index = i;
9393
}
9494
}
9595
}
96-
template = this.templatize(element, index, 0) || new Template();
97-
return function(element, parentScope){
98-
element = jqLite(element);
99-
var scope = parentScope && parentScope.$eval
100-
? parentScope
101-
: createScope(parentScope);
96+
template = this.templatize(templateElement, index, 0) || new Template();
97+
return function(scope, element){
98+
scope = scope || createScope();
99+
element = element === true
100+
? templateElement.cloneNode()
101+
: (jqLite(element) || templateElement);
102102
element.data($$scope, scope);
103103
template.attach(element, scope);
104104
scope.$element = element;
105105
scope.$eval();
106-
return scope;
106+
return {scope:scope, view:element};
107107
};
108108
},
109109

‎src/widgets.js‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -676,7 +676,7 @@ angularWidget('ng:include', function(element){
676676
xhr('GET', src, function(code, response){
677677
element.html(response);
678678
childScope = useScope || createScope(scope);
679-
compiler.compile(element)(element, childScope);
679+
compiler.compile(element)(childScope);
680680
scope.$eval(onloadExp);
681681
});
682682
} else {
@@ -793,7 +793,7 @@ var ngSwitch = angularWidget('ng:switch', function (element){
793793
var caseElement = switchCase.element.cloneNode();
794794
element.append(caseElement);
795795
childScope.$tryEval(switchCase.change, element);
796-
switchCase.template(caseElement, childScope);
796+
switchCase.template(childScope, caseElement);
797797
}
798798
});
799799
});
@@ -945,7 +945,7 @@ angularWidget("@ng:repeat", function(expression, element){
945945
(index == collectionLength - 1 ? 'last' : 'middle');
946946
lastElement.after(cloneElement = element.cloneNode());
947947
cloneElement.attr('ng:repeat-index', index);
948-
linker(cloneElement, childScope);
948+
linker(childScope, cloneElement);
949949
children.push(childScope);
950950
}
951951
childScope.$eval();
@@ -1067,7 +1067,7 @@ angularWidget('ng:view', function(element) {
10671067
if (src) {
10681068
$xhr('GET', src, function(code, response){
10691069
element.html(response);
1070-
compiler.compile(element)(element, childScope);
1070+
compiler.compile(element)(childScope);
10711071
});
10721072
} else {
10731073
element.html('');

0 commit comments

Comments
 (0)