new batch of docs

docs/content/guide/dev_guide.compiler.extending_compiler.ngdoc

@@ -0,0 +1,115 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Angular HTML Compiler: Extending the Angular Compiler
+@description
+
+
+Let's say that we want to create a new DOM element called `<my:greeter/>` that displays a greeting.
+We want this HTML source:
+
+
+<pre>
+<div ng:init="salutation='Hello'; name='World'">
+<my:greeter salutation="salutation" name="name"/>
+</div>
+</pre>
+
+
+to produce this DOM:
+
+
+<pre>
+<div ng:init="salutation='Hello'; name='World'">
+<my:greeter salutation="salutation" name="name"/>
+  <span class="salutation">Hello</span>
+  <span class="name">World</span>!
+</my:greeter>
+</div>
+</pre>
+
+
+That is, the new `<my:greeter/>` tag's `salutation` and `name` attributes should be transformed by
+the compiler such that two `<span>` tags display the values of the attributes, with CSS classes
+applied to the output.
+
+
+The following code snippet shows how to write a following widget definition that will be processed
+by the compiler. Note that you have to declare the {@link dev_guide.bootstrap namespace} `my` in
+the page:
+
+
+<pre>
+angular.widget('my:greeter', function(compileElement){
+var compiler = this;
+compileElement.css('display', 'block');
+var salutationExp = compileElement.attr('salutation');
+var nameExp = compileElement.attr('name');
+return function(linkElement){
+  var salutationSpan = angular.element('<span class="salutation"></span');
+  var nameSpan = angular.element('<span class="name"></span>');
+  linkElement.append(salutationSpan);
+  linkElement.append(compiler.text(' '));
+  linkElement.append(nameSpan);
+  linkElement.append(compiler.text('!'));
+  this.$watch(salutationExp, function(value){
+    salutationSpan.text(value);
+  });
+  this.$watch(nameExp, function(value){
+  nameSpan.text(value);
+  });
+};
+});
+</pre>
+
+
+Note: For more about widgets, see {@link dev_guide.compiler.widgets Understanding Angular Widgets}
+and the {@link api/angular.widget widget API reference page}.
+
+
+# Compilation process for `<my:greeter>`
+
+
+Here are the steps that the compiler takes in processing the page that contains the widget
+definition above:
+
+
+## Compile Phase
+
+
+1. Recursively traverse the DOM depth-first.
+2. Find the angular.widget definition.
+3. Find and execute the widget's compileElement function, which includes the following steps:
+   1. Add a style element with attribute display: block; to the template DOM so that the browser
+knows to treat the element as block element for rendering. (Note: because this style element was
+added on the template compileElement, this style is automatically applied to any clones of the
+template (i.e. any repeating elements)).
+   2. Extract the salutation and name HTML attributes as angular expressions.
+4. Return the aggregate link function, which includes just one link function in this example.
+
+
+## Link Phase
+
+
+1. Execute the aggregate link function, which includes the following steps:
+   1. Create a <span> element set to the salutation class
+   2. Create a <span> element set to the name class.
+2. Add the span elements to the linkElement. (Note: be careful not to add them to the
+compileElement, because that's the template.)
+3. Set up watches on the expressions. When an expression changes, copy the data to the
+corresponding spans.
+
+
+
+
+## Related Topics
+
+
+* {@link dev_guide.compiler Angular HTML Compiler}
+* {@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.compile angular.compile()}