# Directives Directives are classes which get instantiated as a response to a particular DOM structure. By controlling the DOM structure, what directives are imported, and their selectors, the developer can use the [composition pattern](http://en.wikipedia.org/wiki/Object_composition) to get a desirable application behavior. Directives are the cornerstone of an Angular application. We use Directives to break complex problems into smaller more reusable components. Directives allow the developer to turn HTML into a DSL and then control the application assembly process. Angular applications do not have a main method. Instead they have a root Component. Dependency Injection then assembles the directives into a working Angular application. There are three different kinds of directives (described in more detail in later sections). 1. *Decorators*: can be placed on any DOM element and can be combined with other directives. 2. *Components*: Components have an encapsulated view and can configure injectors. 3. *Viewport*: is responsible for adding or removing child views in a parent view. (i.e. foreach, if) ## CSS Selectors Decorators are instantiated whenever the decorator CSS selector matches the DOM structure. Angular supports these CSS selector constructs: * Element name: `name` * Attribute: `[attribute]` * Attribute has value: `[attribute=value]` * Attribute contains value: `[attribute*=value]` * Class: `.class` * AND operation: `name[attribute]` * OR operation: `name,.class` Angular does not support these (and any CSS selector which crosses element boundaries): * Descendant: `body div` * Direct descendant: `body > div` * Adjacent: `div + table` * Sibling: `div ~ table` * Wildcard: `*` * ID: `#id` * Pseudo selectors: `:pseudo` Given this DOM: `````` These CSS selectors will match: * `input`: Triggers whenever element name is `input`. * `[required]`: Triggers whenever element contains a required attribute. * `[type=text]`: Triggers whenever element contains attribute `type` whose value is `text`. * `.primary`: Triggers whenever element class contains `primary`. CSS Selectors can be combined: * `input[type=text]`: Triggers on element name `input` which is of `type` `text`. * `input[type=text], textarea`: triggers on element name `input` which is of `type` `text` or element name `textarea` ## Decorators The simplest kind of directive is a decorator. Directives are usefull for encapsulating behavior. * Multiple decorators can be placed on a single element. * Decorators do not introduce new evaluation context. * Decorators are registered through the `@Decorator` meta-data annotation. Here is a trivial example of a tooltip decorator. The directive will log a tooltip into the console on every time mouse enters a region: ``` @Decorator({ selector: '[tooltip]', // CSS Selector which triggers the decorator bind: { // List which properties need to be bound text: 'tooltip' // - DOM element tooltip property should be }, // mapped to the directive text property. event: { // List which events need to be mapped. mouseover: 'show' // - Invoke the show() method every time } // the mouseover event is fired. }) class Form { // Directive controller class, instantiated // when CSS matches. text:string; // text property on the Decorator Controller. show(event) { // Show method which implements the show action. console.log(this.text); } } ``` Example of usage: ```Some text here.``` The developer of an application can now freely use the `tooltip` attribute wherever the behavior is needed. The code above has taught the browser a new reusable and declarative behavior. Notice that data binding will work with this decorator with no further effort as shown below. ```Some text here.``` ## Components Component is a directive which uses shadow DOM to create encapsulate visual behavior. Components are typically used to create UI widgets or to break up the application into smaller components. * Only one component can be present per DOM element. * Component's CSS selectors usually trigger on element names. (Best practice) * Component has its own shadow view which is attached to the element as a Shadow DOM. * Shadow view context is the component instance. (i.e. template expressions are evaluated against the component instance.) >> TODO(misko): Configuring the injector Example of a component: ``` @Component({ | Component annotation selector: 'pane', | CSS selector on element bind: { | List which property need to be bound 'title': 'title', | - title mapped to component title 'open': 'open' | - open attribute mapped to component's open property }, | }) | @Template({ | Template annotation url: 'pane.html' | - URL of template HTML }) | class Pane { | Component controller class title:string; | - title property open:boolean; constructor() { this.title = ''; this.open = true; } // Public API toggle() => this.open = !this.open; open() => this.open = true; close() => this.open = false; } ``` `pane.html`: ```

{{title}}

``` `pane.css`: ``` .outer, .inner { border: 1px solid blue;} .h1 {background-color: blue;} ``` Example of usage: ``` Some text to wrap. ``` ## Viewport Viewport is a directive which can control instantiation of child views which are then inserted into the DOM. (Examples are `if` and `foreach`.) * Viewports can only be placed on `