fixing broken links

1 files changed, 163 insertions, 0 deletions

diff --git a/docs/content/guide/compiler.ngdoc b/docs/content/guide/compiler.ngdoc
new file mode 100644
index 00000000..8896db43
--- /dev/null
+++ b/docs/content/guide/compiler.ngdoc
@@ -0,0 +1,163 @@
+@workInProgress
+@ngdoc overview
+@name Developer Guide: Compiler
+@description
+
+#Compiler
+
+While angular might look like just a cool way to build web applications, the core of angular is
+actually an HTML compiler. The default HTML transformations that this compiler provides are useful
+for building generic apps, but you can also use them to create a domain-specific language for
+building specific types of web applications.
+
+The compiler allows you to add behavior to existing HTML through widgets, directives, and text
+markup.
+
+All of this compilation happens in the web browser, meaning no server is involved.
+
+# The compilation process
+This section describes the steps that angular's HTML compiler goes through. If you use
+`ng:autobind` in your application, this compilation process happens automatically when the
+application is initialized (e.g. when the user loads the app in a browser). If you're an advanced
+user using manual bind mode, you can decide when and how often the compilation happens.
+
+First, a bit of background of what the compilation step is for. Every type of
+{@link angular.widget widget}, {@link angular.markup markup}, and
+{@link angular.directive directive} in angular is defined with a compile function, and that
+compile function returns an optional link function. Here is the relationship between the two:
+
+ * **compile function** - registers a listener for the widget, markup, or directive's expression.
+   This function is called exactly once.
+ * **link function** - sets up the listener. This function can be called multiple times, once per
+   cloned DOM element (e.g. repeating element).
+
+Note that angular's built-in widgets, markup, and directives have predefined compile and link
+functions that you don't need to modify. However, if you're writing your own widgets, markup, or
+directives, you write compile and link functions. Refer to the Compiler API for more information.
+
+When the HTML compiler compiles a page, it goes through 3 phases: Compile, Create Root Scope, and
+Link.
+
+## 1. Compile Phase
+
+ * Recursively traverse the DOM, depth-first.
+ * Look for a matching compile function of type widget, then markup, then directive.
+ * If a compile function is found then execute it.
+ * When the compile function completes, it should return a link function. Aggregate this link
+   function with all link functions returned previously by step 1c.
+ * Repeat steps 1c and 1d for all compile functions found. The result of the compilation step is
+   the aggregate link function, which comprises all of the individual link functions.
+
+## 2. Create Root Scope
+
+ * Inject all of the services into the root scope.
+
+## 3. Link Phase
+
+ * Execute the aggregate link function with the root scope. The aggregate link function calls all
+   the individual link functions that were generated in the compile phase.
+ * If there are any clones of the DOM caused by repeating elements, call the link function multiple
+   times, one for each repeating item.
+
+Note that while the compile function is executed exactly once, the link function can be executed
+multiple times: once for each iteration in a repeater.
+
+# Example
+
+The compilation process is best understood through example. Let's say that in your namespace my,
+you want to create a new DOM element <my:greeter/>, which should display a greeting.
+
+If 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>
+
+Write this widget definition (assuming you've already declared the my namespace 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 angular.widget Widget}.
+
+## Compilation process for this example
+
+Here are the steps that the compiler goes through for the page that contains this widget definition:
+
+### Compile Phase
+
+ * Recursively traverse the DOM depth-first.
+ * Find the angular.widget definition.
+ *  Find and execute the widget's compileElement function, which includes the following steps:
+   * 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)).
+   * Extract the salutation and name HTML attributes as angular expressions.
+ * Return the aggregate link function, which includes just one link function in this example.
+
+### Link Phase
+
+ * Execute the aggregate link function, which includes the following steps:
+   * Create a <span> element set to the salutation class
+   * Create a <span> element set to the name class.
+ * Add the span elements to the linkElement. (Note: be careful not to add them to the
+   compileElement, because that's the template.)
+ * Set up watches on the expressions. When an expression changes, copy the data to the
+   corresponding spans.
+
+
+## Compiler API
+
+If you define your own widgets, markup, or directives, you need to access the compiler API.
+This section describes the methods on the compiler that you can call.
+
+Note: As of 12 August 2010, these methods are subject to change.
+
+Recall that the compile function's this is a reference to the compiler.
+
+ * `compile(element)` - returns `linker` - Invoke new instance of 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  Get or set the current descend state. If true the
+    compiler will descend to children elements.
+ * `directives([set])` - returns `directive` - State Get or set the current directives processing
+   state. The compiler will process directives only when directives set to true.
+