From a3a37c2063a9098539a59444b8e4a52959f3ee24 Mon Sep 17 00:00:00 2001 From: Misko Hevery Date: Wed, 29 Feb 2012 11:29:46 -0800 Subject: doc(compiler): rewrite --- docs/content/guide/compiler.ngdoc | 143 +++++++++++++++++++++ docs/content/guide/dev_guide.compiler.ngdoc | 24 ---- .../dev_guide.compiler.testing_dom_element.ngdoc | 16 --- ...dev_guide.compiler.understanding_compiler.ngdoc | 34 ----- 4 files changed, 143 insertions(+), 74 deletions(-) create mode 100644 docs/content/guide/compiler.ngdoc delete mode 100644 docs/content/guide/dev_guide.compiler.ngdoc delete mode 100644 docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc delete mode 100644 docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc (limited to 'docs/content/guide') diff --git a/docs/content/guide/compiler.ngdoc b/docs/content/guide/compiler.ngdoc new file mode 100644 index 00000000..90dc4d61 --- /dev/null +++ b/docs/content/guide/compiler.ngdoc @@ -0,0 +1,143 @@ +@ngdoc overview +@name Developer Guide: HTML Compiler +@description + +# Overview + +Angular's {@link api/angular.module.ng.$compile HTML compiler} allows the developer to teach the +browser new HTML syntax. The compiler allows you to attach behavior to any HTML element or attribute +and even create new HTML element or attributes with custom behavior. Angular calls these behavior +extensions {@link api/angular.module.ng.$compileProvider.directive directives}. + +HTML has a lot of constructs for formatting the HTML for static documents in declarative fashion. +For example if something needs to be centered, there is no need to provide instructions to the +browser how the window size needs to be divided in half so that center is found, and that this +center needs to be aligned with the text's center. Simply add `align="center"` attribute to any +element to achieve the desired behavior. Such is the power of declarative language. + +But the declarative language is also limited, since it does not allow you to teach the browser new +syntax. For example there is no easy way to get the browser to align the text at 1/3 the position +instead of 1/2. What is needed is a way to teach browser new HTML syntax. + +Angular comes pre-bundled with common directives which are useful for building any app. We also +expect that you will create directives that are specific to your app. These extension become a +Domain Specific Language for building your application. + +All of this compilation takes place in the web browser; no server side or pre-compilation step is +involved. + + +# Compiler + +Compiler is an angular service which traverses the DOM looking for attributes. The compilation +process happens into two phases. + + 1. **Compile:** traverse the DOM and collect all of the directives. The result is a linking + function. + + 2. **Link:** combine the directives with a scope and produce a live view. Any changes in the + scope model are reflected in the view, and any user interactions with the view are reflected + in the scope model. Making the scope model a single source of truth. + +Some directives such {@link api/angular.module.ng.$compileProvider.directive.ng:repeat +`ng-repeat`} clone DOM elements once for each item in collection. Having a compile and link phase +improves performance since the cloned template only needs to be compiled once, and then linked +once for each clone instance. + + +# Directive + +Directive is a behavior which should be triggered when specific HTML constructs are encountered in +compilation process. The directives can be placed in element names, attributes, class names, as +well as comments. Here are some equivalent examples of invoking {@link +api/angular.module.ng.$compileProvider.directive.ng:bind `ng-bind`} directive. + +
+  
+  
+  
+  
+
+ +Directive is just a function which executes when the compiler encounters it in the DOM. See {@link +api/angular.module.ng.$compileProvider.directive directive API} for in depth documentation on how +to write directives. + +Here is a directive which makes any element draggable. Notice the `draggable` attribute on the +`` element. + + + + + Drag ME + + + + +The presence of `draggable` attribute an any element gives the element new behavior. The beauty of +this approach is that we have thought the browser a new trick, we have extended the vocabulary of +what browser understands in a way, which is natural to anyone who is familiar with HTML +principles. + + +# Understanding View + +There are many templating systems out there. Most of them consume a static string template and +combine it with data, resulting in a new string. The resulting text is then `innerHTML`ed into +an element. + + + +This means that any changes to the data, need to be re-merged with the template and then +`innerHTML`ed into the DOM. Some of the issues are: reading user input and merging it with data, +clobbering user input by overwriting it, managing the whole update process, and lack of behavior +expressiveness. + +Angular is different. Angular compiler consumes DOM with directives, not string templates. The +result is a linking function, which when combined with a scope model results in live view. The +view and scope model bindings are transparent, no action from the developer is needed to update +the view. And because no `innerHTML` is used there are no issues of clobbering user input. +Furthermore, angular directives can contain not just text bindings, but behavioral constructs as +well. + + + +The Angular approach produces stable DOM. This means that the DOM element instance bound to model +item instance does not change for the lifetime of the binding. This means that the code can get +hold of the elements and register event handlers and know that the reference will not be destroyed +by template data merge. + + diff --git a/docs/content/guide/dev_guide.compiler.ngdoc b/docs/content/guide/dev_guide.compiler.ngdoc deleted file mode 100644 index f52928a6..00000000 --- a/docs/content/guide/dev_guide.compiler.ngdoc +++ /dev/null @@ -1,24 +0,0 @@ -@ngdoc overview -@name Developer Guide: Angular HTML Compiler -@description - -The core of Angular is its HTML compiler. The compiler processes Angular -{@link guide/directive directives} allowing them to transform a -static HTML page into a dynamic web application. - -The default HTML transformations that the Angular compiler provides are useful for building generic -apps, but you can also extend the compiler to create a domain-specific language for building -specific types of web applications. - -All compilation takes place in the web browser; no server is involved. - - -## Related Topics - -* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works} -* {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element} - -## Related API - -* {@link api/angular.module.ng.$compile Angular Compiler API} -* {@link guide/directive Directives API} diff --git a/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc b/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc deleted file mode 100644 index 8ffa760e..00000000 --- a/docs/content/guide/dev_guide.compiler.testing_dom_element.ngdoc +++ /dev/null @@ -1,16 +0,0 @@ -@ngdoc overview -@name Developer Guide: Angular HTML Compiler: Testing a New DOM Element -@description - - -"Testing, testing, come in, over?" - - -## Related Topics - -* {@link dev_guide.compiler Angular HTML Compiler} -* {@link dev_guide.compiler.understanding_compiler Understanding How the Compiler Works} - -## Related API - -* {@link api/angular.module.ng.$compile $compile()} diff --git a/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc b/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc deleted file mode 100644 index ea433cc5..00000000 --- a/docs/content/guide/dev_guide.compiler.understanding_compiler.ngdoc +++ /dev/null @@ -1,34 +0,0 @@ -@ngdoc overview -@name Developer Guide: Angular HTML Compiler: Understanding How the Compiler Works -@description - -The {@link api/angular.module.ng.$compile compiler} is responsible for applying -{@link guide/directive directives} to the HTML. The directives -extend the behavior of HTML elements and can effect the DOM structure, presentation, and behavior. -This allows Angular to teach the browser new tricks. - -The compilation starts at the root element and proceeds in a depth-first order. As the compiler -visits each node it collects the directives, orders them by priority and executes their compile -function. The result of the compilation process is a linking function. The linking function -can be used on the template clones to quickly bind the directives with the scope. - -The result of the compilation process is a live view. We say 'live' since any changes to the -model attached to the {@link api/angular.module.ng.$rootScope.Scope scope} are reflected in the view, -and any changes in the view are reflected in the scope. This makes the scope the 'single source of -truth'. - -Since directives allow attachment of behavior to the HTML, the angular philosophy is to use the -HTML as Domain Specific Language (DSL) when building an application. For example it may be useful -to declare `TabPanel` directive, or `KeyboardShortcut` directive when for an application. - -For details on how directives are created see {@link guide/directive -directives} - -## Related Topics - -* {@link dev_guide.compiler Angular HTML Compiler} -* {@link dev_guide.compiler.testing_dom_element Testing a New DOM Element} - -## Related API - -* {@link api/angular.module.ng.$compile $compile()} -- cgit v1.2.3