docs(attribute-directive): new chapter + dev-guide chapter shuffle

closes #437

public/docs/_examples/attribute-directives/ts/.gitignore

@@ -0,0 +1 @@
+src/**/*.js

public/docs/_examples/attribute-directives/ts/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "angular2-attribute-directive",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "tsc": "tsc -p src -w",
+    "start": "live-server --open=src"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "angular2": "2.0.0-alpha.47",
+    "systemjs": "0.19.6"
+  },
+  "devDependencies": {
+    "live-server": "^0.8.2",
+    "typescript": "^1.6.2"
+  }
+}

public/docs/_examples/attribute-directives/ts/src/app/app.component.1.html

@@ -0,0 +1,4 @@
+<!-- #docregion -->
+<h1>My First Attribute Directive</h1>
+<span my-highlight>Highlight me!</span>
+<!-- #enddocregion -->

public/docs/_examples/attribute-directives/ts/src/app/app.component.html

@@ -0,0 +1,12 @@
+<!-- #docregion -->
+<h1>My First Attribute Directive</h1>
+<h4>Pick a highlight color</h4>
+<div>
+  <input type="radio" name="colors" (click)="color='lightgreen'">Green
+  <input type="radio" name="colors" (click)="color='yellow'">Yellow
+  <input type="radio" name="colors" (click)="color='cyan'">Cyan
+</div>
+<!-- #docregion span -->
+<p><span [my-highlight]="color">Highlight me!</span></p>
+<!-- #enddocregion span -->
+<!-- #enddocregion -->

public/docs/_examples/attribute-directives/ts/src/app/app.component.ts

@@ -0,0 +1,13 @@
+// #docregion
+import {Component} from 'angular2/angular2';
+import {Highlight} from './highlight.directive'
+
+@Component({
+  selector: 'my-app',
+  templateUrl: 'app/app.component.html',
+  directives: [Highlight]
+})
+
+export class AppComponent { }
+
+// #enddocregion

public/docs/_examples/attribute-directives/ts/src/app/boot.ts

@@ -0,0 +1,5 @@
+// #docregion
+import {bootstrap} from 'angular2/angular2';
+import {AppComponent} from './app.component';
+
+bootstrap(AppComponent);

public/docs/_examples/attribute-directives/ts/src/app/highlight.directive.1.ts

@@ -0,0 +1,14 @@
+// #docregion
+import {Directive, ElementRef, Renderer, Input} from 'angular2/angular2';
+
+@Directive({
+    selector: '[my-highlight]'
+})
+
+export class Highlight {
+    constructor(el: ElementRef, renderer: Renderer) {
+        //el.nativeElement.style.backgroundColor = 'yellow';
+       renderer.setElementStyle(el, 'background-color', 'yellow');
+    }
+}
+// #enddocregion

public/docs/_examples/attribute-directives/ts/src/app/highlight.directive.2.ts

@@ -0,0 +1,30 @@
+// #docregion
+import {Directive, ElementRef, Renderer, Input} from 'angular2/angular2';
+
+@Directive({
+  selector: '[my-highlight]',
+  // #docregion host
+  host: {
+    '(mouseenter)': 'onMouseEnter()',
+    '(mouseleave)': 'onMouseLeave()'
+  }
+  // #enddocregion host
+})
+
+export class Highlight {
+  // #docregion ctor
+  constructor(private el: ElementRef, private renderer: Renderer) {
+  }
+  // #enddocregion ctor
+
+  // #docregion mouse-methods
+  onMouseEnter() { this._highlight("yellow"); }
+  onMouseLeave() { this._highlight(null); }
+
+  private _highlight(color: string) {
+    this.renderer.setElementStyle(this.el, 'background-color', color);
+  }
+  // #enddocregion mouse-methods
+
+}
+// #enddocregion

public/docs/_examples/attribute-directives/ts/src/app/highlight.directive.ts

@@ -0,0 +1,43 @@
+// #docplaster
+// #docregion full
+import {Directive, ElementRef, Renderer, Input} from 'angular2/angular2';
+
+@Directive({
+  selector: '[my-highlight]',
+  host: {
+    '(mouseenter)': 'onMouseEnter()',
+    '(mouseleave)': 'onMouseLeave()'
+  }
+})
+
+// #docregion class
+export class Highlight {
+// #enddocregion class
+// #enddocregion full
+  /*
+// #docregion highlight
+  @Input() myHighlight: string;
+// #enddocregion highlight
+  */
+// #docregion full
+// #docregion class
+// #docregion color
+  @Input('my-highlight') highlightColor: string;
+// #enddocregion color
+
+  private _defaultColor = 'red';
+
+  constructor(private el: ElementRef, private renderer: Renderer) { }
+
+// #docregion mouse-enter
+  onMouseEnter() { this._highlight(this.highlightColor || this._defaultColor); }
+// #enddocregion mouse-enter
+  onMouseLeave() { this._highlight(null); }
+
+  private _highlight(color:string) {
+    this.renderer.setElementStyle(this.el, 'background-color', color);
+  }
+
+}
+// #enddocregion class
+// #enddocregion full

public/docs/_examples/attribute-directives/ts/src/index.html

@@ -0,0 +1,21 @@
+<!-- #docregion -->
+<!DOCTYPE html>
+<html>
+
+<head>
+  <title>Attribute Directives</title>
+  <script src="../node_modules/systemjs/dist/system.src.js"></script>
+  <script src="../node_modules/angular2/bundles/angular2.dev.js"></script>
+  <script>
+    System.config({
+    packages: {'app': {defaultExtension: 'js'}}
+  });
+  System.import('app/boot');
+  </script>
+</head>
+
+<body>
+  <my-app>loading...</my-app>
+</body>
+
+</html>

public/docs/_examples/attribute-directives/ts/src/plnkr.json

@@ -0,0 +1,9 @@
+{
+  "description": "Attribute Directive",
+  "files":[
+    "!**/*.d.ts",
+    "!**/*.js",
+    "!app/*.[1,2].*"
+  ],
+  "tags": ["attribute", "directive"]
+}

public/docs/_examples/attribute-directives/ts/src/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES5",
+    "module": "commonjs",
+    "sourceMap": true,
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "removeComments": false,
+    "noImplicitAny": true,
+    "suppressImplicitAnyIndexErrors": true
+  }
+}

public/docs/ts/latest/guide/_data.json

@@ -23,26 +23,32 @@
     "title": "Forms",
     "intro": "A form creates a cohesive, effective, and compelling data entry experience. An Angular form coordinates a set of data-bound user controls, tracks changes, validates input, and presents errors."
   },
-    
-  "pipes": {
-    "title": "Pipes",
-    "intro": "Pipes transform displayed values within a template"
+  
+  "dependency-injection": {
+    "title": "Dependency Injection",
+    "intro": "Angular's dependency injection system creates and delivers dependent services \"just-in-time\"."
   },
  
   "template-syntax": {
     "title": "Template Syntax",
     "intro": "How to write templates that display data and consume user events with the help of data binding."
   },
-
-  "dependency-injection": {
-    "title": "Dependency Injection",
-    "intro": "Angular's dependency injection system creates and delivers dependent services \"just-in-time\"."
+    
+  "pipes": {
+    "title": "Pipes",
+    "intro": "Pipes transform displayed values within a template"
+  },
+  
+  "attribute-directives": {
+    "title": "Attribute Directives",
+    "intro": "Attribute directives attach behavior to elements."
   },
   
   "hierarchical-dependency-injection": {
     "title": "Hierarchical Injectors",
     "intro": "Angular's hierarchical dependency injection system supports nested injectors in parallel with the component tree."
   },
+  
   "glossary": {
     "title": "Glossary",
     "intro": "Brief definitions of the most important words in the Angular 2 vocabulary"

public/docs/ts/latest/guide/attribute-directives.jade

@@ -0,0 +1,314 @@
+include ../../../../_includes/_util-fns
+
+:marked
+  An **Attribute** directive changes the appearance or behavior of a DOM element.
+
+:marked
+  In this chapter we will
+  * write an attribute directive to change the background color
+  * apply the attribute directive to an element in a template
+  * respond to user-initiated events
+  * pass a value into the directive using data binding
+
+  [Live Example](/resources/live-examples/attribute-directives/ts/src/plnkr.html)
+
+  ## Directives overview
+  
+  There are three kinds of directives in Angular:
+  1. Components
+  1. Structural directives  
+  1. Attribute directives
+
+  The *Component* is really a directive with a template. 
+  It's the most common of the three directives and we write lots of them as we build our application.
+
+  The *Structural* directive changes the DOM layout by adding and removing DOM elements. 
+  [NgFor](template-syntax.html#ng-for) and [NgIf](template-syntax.html#ng-if) are two familiar examples.
+  
+  The *Attribute* directive changes the appearance or behavior of an element.
+  The built-in [NgStyle](template-syntax.html#ng-style) directive, for example,
+  can change several element styles at the same time.
+  
+  We are going to write our own attribute directive to set an element's background color
+  when the user hovers over that element.
+.l-sub-section
+  :marked
+    We don't need *any* directive to simply set the background color.
+    We can set it with the special [Style Binding](template-syntax.html#style-binding) like this:
+  code-example.
+    <p [style.background]="'lime'">I am green with envy!</p>
+  <br>
+  :marked
+    That wouldn't be nearly as much fun as creating our own directive.
+    
+    Besides, we're not just *setting* the color; we'll be *changing* the color
+    in response to a user action, a mouse hover.
+
+.l-main-section
+:marked
+  ## Build a simple attribute directive
+  An attribute directive minimally requires building a controller class annotated with a 
+  `Directive` decorator. The `Directive` decorator specifies the selector identifying
+  the attribute associated with the directive. 
+  The controller class implements the desired directive behavior.
+
+  Let's build a small illustrative example together.
+
+  ### Setup
+  Create a new project folder (`attribute-directives`) and follow the steps in the [QuickStart](../quickstart.html).
+  
+  As in the [tutorial](/docs/ts/latest/tutorial/), we'll rename `app.ts` to `app.component.ts`
+  and relocate the call to `bootstrap` to a separate `boot.ts` file.
++makeExample('attribute-directives/ts/src/app/boot.ts', null, 'app/boot.ts')
+:marked
+  A clean `app.component.ts` without bootstrapping is much easer to test.
+  
+  Finally, we remember to update `index.html` to load `boot.ts`
+  
+code-example.
+  System.import('app/boot');
+:marked
+  ### Write the directive
+  Add a new file to the `app` folder called `highlight.directive.ts` and add the following code:
++makeExample('attribute-directives/ts/src/app/highlight.directive.1.ts', null, 'app/highlight.directive.ts')
+
+:marked
+  We begin by importing some symbols from the Angular library.
+  We need the `Directive` symbol for the `@Directive` decorator.
+  We need symbols for the *Element Reference* and the *Renderer* service that
+  we will [inject](dependency-injection.html) into the directive's constructor.
+  We don't need `Input` now but we will need it later in the chapter.
+  
+  Then we define the directive metadata in a configuration object passed
+  as an argument to the `@Directive` decorator function. 
+  A `@Directive` decorator for an attribute directive requires a css selector to identify
+  the HTML in the template that is associated with our directive.
+  The [css selector for an attribute](https://developer.mozilla.org/en-US/docs/Web/CSS/Attribute_selectors)
+  is the attribute name in square brackets.
+  
+  Our directive's selector is `[my-highlight]`. 
+  Angular will locate all elements in the template that have an attribute named `my-highlight`. 
+.l-sub-section
+  :marked
+    ### Why not call it "highlight"?
+    *highlight* is a nicer name than *my-highlight* and, technically, it would work if we called it that.
+    However, the good folks at Angular strongly prefer hyphenated directive selector names. 
+    The HTML standards body will never name one of its attributes with a hyphen and there is
+    less risk of colliding with a third-party directive name when we give ours a prefix.
+    The `ng-` prefix belongs to Angular. 
+    We need a prefix of our own, preferably short, and `my-` will do for now.
+:marked
+  After the `@Component` metadata comes the directive's controller class which we are exporting
+  to make it accessible to other components. 
+  The directive's controller class contains the logic for our directive.
+  
+  Angular creates a new instance of the directive's controller class for
+  each matching element, injecting  an *Element Reference* and 
+  the *Renderer* service as arguments to our constructor. 
+  We'll need them to set the element's background color.
+    
+  Our code shows two ways to do that.
+  
+  We could access the `nativeElement` property of the element reference 
+  and set the element's background using the browser DOM API. We don't need
+  the `Renderer` for this technique. But we commented it out.
+
+  We chose the second way, the preferred way, that relies on the `Renderer` service
+  to set the element properties.
+
+.l-sub-section
+  :marked
+    ### Why prefer the Renderer?
+    Manipulating the DOM directly is a practice we should *avoid* because it chains us
+    to the browser DOM API.
+    
+    The  `Renderer` insulates our code from the browser's API. 
+    That gives us options.
+    The rendering phase could be offloaded to a Web Worker for faster performance.
+    Our directive might work when we ran the application outside the browser,
+    perhaps on the server in a pre-render phase. 
+    Server-side rendering can make our application load faster and
+    is often friendlier to Search Engine Optimizations (SEO).
+
+:marked
+.l-main-section
+:marked
+  ## Apply the attribute directive
+  The `AppComponent` will be the test harness for our `highlight` directive.
+  Let's give it a new template that 
+  applies the directive as an attribute to a `span` element.
+  In Angular terms, the `<span>` element will be the attribute **host**.
+  
+  We'll put the template in its own `app.component.html` file that looks like this:
++makeExample('attribute-directives/ts/src/app/app.component.1.html',null,'app/app.component.html')
+:marked
+  A separate template file is clearly overkill for a 2-line template. 
+  Hang in there; we're going to expand it later.
+  Meanwhile, we'll revise the `AppComponent` to reference this template.
++makeExample('attribute-directives/ts/src/app/app.component.ts',null,'app/app.component.ts')
+:marked
+  We've added an `import` statement to fetch the 'Highlight' directive and 
+  added that class to a `directives` array in the component metadata so that Angular 
+  will recognize our directive when it encounters `my-highlight` in the template. 
+  Angular would simply ignore the `my-highlight` attribute without it.
+  
+  We run the app and see that our directive highlights the span text.
+  
+figure.image-display
+  img(src="/resources/images/devguide/attribute-directives/first-highlight.png" alt="First Highlight")
+:marked
+  Let's recap what happened.
+  
+  Angular found the `my-highlight` attribute on the `<span>` element. It created
+  an instance of the `Highlight` directive class, 
+  injecting both a reference to the element and the `Renderer` service into the constructor.
+  The constructor told the `Renderer` to set the `<span>` element's background style to yellow.
+
+.l-main-section
+:marked
+  ## Respond to user action
+
+  We are not satisfied to simply set an element color.
+  Our directive should set the color in response to a user action.
+  Specifically, we want to set the color when the user mouses over the element.
+  
+  We'll need to
+  1. detect when the user mouses into and out of the element
+  1. respond to those actions by setting and clearing the highlight color.
+  
+  Start with event detection. 
+  We add a `host` property to the directive metadata and give it a configuration object
+  that specifies two mouse events and the directive methods to call when they are raised.
++makeExample('attribute-directives/ts/src/app/highlight.directive.2.ts','host')
+:marked
+.l-sub-section
+  :marked
+    The `host` property refers to the DOM element that hosts our attribute directive, the `<span>` in our case.
+     
+    We could have attached an event listener to the native element (`el.nativeElement`) with 
+    plain old JavaScript. 
+    There are at least three problems with that approach:
+    
+    1. We have to write the listeners correctly.
+    1. We must *detach* our listener when the directive is destroyed to avoid memory leaks.
+    1. We'd be talking to DOM API directly which, we learned, is something to avoid.
+
+    Let's roll with the `host` property. 
+:marked
+  Now we implement those two mouse event handlers:
++makeExample('attribute-directives/ts/src/app/highlight.directive.2.ts','mouse-methods')
+:marked
+  Notice that they delegate to a helper method that calls the `Renderer` service
+  as we used to do in the constructor.
+  
+  We no longer need the constructor body but 
+  we still want the injected `ElementRef` and `Renderer` service.
+  We revise the constructor signature to capture the injectables in private variables
+  and clear the body.
++makeExample('attribute-directives/ts/src/app/highlight.directive.2.ts','ctor')
+:marked
+  Here's the updated directive:
++makeExample('attribute-directives/ts/src/app/highlight.directive.2.ts',null, 'app/highlight.directive.ts')
+:marked
+  We run the app and confirm that the background color appears as we move the mouse over the `span` and
+  disappears as we move out.
+figure.image-display
+  img(src="/resources/images/devguide/attribute-directives/highlight-directive-anim.gif" alt="Second Highlight")
+:marked
+.l-main-section
+:marked
+  ## Configure the directive with binding
+
+  Currently the highlight color is hard-coded within the directive. That's inflexible.
+  We should set the highlight color externally with a binding like this:
++makeExample('attribute-directives/ts/src/app/app.component.html','span')
+:marked
+  We'll extend our directive class with a bindable **input** `highlightColor` property and use it when we highlight text.
+
+  Here is the final version of the class:
+  
++makeExample('attribute-directives/ts/src/app/highlight.directive.ts', 'class', 'app/highlight.directive.ts (class only)')
+:marked
+  The new `highlightColor` property is called an "input" property because data flows from the binding expression into our directive.
+  Notice that we call the `@Input()` decorator function while defining the property.
++makeExample('attribute-directives/ts/src/app/highlight.directive.ts', 'color')
+:marked
+  This `@Input` decorator adds metadata to the class that makes the `highlightColor` property  available for property binding
+  under the `my-highlight` alias. 
+  We must add this input metadata. Angular will give us an error if we try to bind 
+  to a property without declaring it as an input.
+.l-sub-section
+  :marked
+    The developer who uses our directive expects to bind to the attribute name, `my-highlight`.
+    The directive property name is `highlightColor`. That's a disconnect.
+    
+    We can resolve the discrepancy by renaming the property to `myHighlight` and define it as follows:
+
+  +makeExample('attribute-directives/ts/src/app/highlight.directive.ts', 'highlight')
+  <br>
+  :marked
+    We don't like that property name. 
+    We prefer, in this case, to **alias** the `highlightColor` property with the attribute name by
+    passing `my-highlight` into the `@Input` decorator:
+  +makeExample('attribute-directives/ts/src/app/highlight.directive.ts', 'color')
+:marked
+  Now that we're getting the highlight color as an input, we modify the `onMouseEnter()` method to use
+  it instead of the hard-coded color name.
+  We also define a red default color as a fallback in case
+  the user neglects to bind with a color.
++makeExample('attribute-directives/ts/src/app/highlight.directive.ts', 'mouse-enter')
+:marked
+  Now we'll update our `AppComponent` template to let 
+  users pick the highlight color and bind their choice to our directive.
+  
+  Here is the updated template:
+
++makeExample('attribute-directives/ts/src/app/app.component.html')
+
+.l-sub-section
+  :marked
+    ### Where is the templated *color* property?
+    
+    The eagle-eyed may notice that the radio button click handlers in the template set a `color` property
+    and we are binding that `color` to the directive. 
+    We should expect to find a `color` on the host `AppComponent`.
+    
+    **We never defined a color property for the host *AppComponent***!
+    And yet this code works. Where is the template `color` value going?
+    
+    Browser debugging reveals that Angular dynamically added a `color` property 
+    to the runtime instance of the `AppComponent`.
+    
+    This is *convenient* behavior but it is also *implicit* behavior that could be confusing. 
+    While it's cool that this technique works, we recommend adding the `color` property to the `AppComponent`.
+
+:marked
+  Here is our final app in action.
+figure.image-display
+  img(src="/resources/images/devguide/attribute-directives/highlight-directive-final-anim.gif" alt="Final Highlight")
+:marked
+.l-main-section
+:marked
+  ## Summary
+  Now we know how to
+  - build a simple **attribute directive** to attach behavior to an HTML element,
+  - use that directive in a template,
+  - respond to **events** to change behavior based on an event,
+  - and use **binding** to pass a value to the attribute directive.
+
+  The final source:
+
++makeTabs(
+  `attribute-directives/ts/src/app/app.component.ts,
+   attribute-directives/ts/src/app/app.component.html, 
+   attribute-directives/ts/src/app/highlight.directive.ts,
+   attribute-directives/ts/src/app/boot.ts,
+   attribute-directives/ts/src/index.html
+  `,
+  ',,full',
+  `app.component.ts,
+   app.component.html,
+   highlight.directive.ts,
+   boot.ts,
+   index.html
+  `)

public/docs/ts/latest/guide/dependency-injection.jade

@@ -559,8 +559,8 @@ include ../../../../_includes/_util-fns
 
   The Angular Dependency Injection is more capable than we've described.
   We can learn more about its advanced features, beginning with its support for
-  a hierarchy of nested injectors in the next
-  [Dependency Injection chapter](./hierarchical-dependency-injection.html)
+  nested injectors, in the 
+  [Hierarchical Dependency Injection](./hierarchical-dependency-injection.html) chapter.
 
 .l-main-section
 <a name="forward-ref"></a>