From 0f8df7894705fca6127e3b0cdaa4d9db94d7e984 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Sat, 6 Aug 2016 12:15:51 -0700 Subject: [PATCH] docs(dart): decouple from TS .jade files temporarily Addresses #2043. --- .../docs/dart/latest/guide/architecture.jade | 2 +- .../latest/guide/attribute-directives.jade | 2 +- .../dart/latest/guide/component-styles.jade | 2 +- .../latest/guide/dependency-injection.jade | 2 +- .../dart/latest/guide/displaying-data.jade | 2 +- .../hierarchical-dependency-injection.jade | 2 +- .../dart/latest/guide/lifecycle-hooks.jade | 2 +- public/docs/dart/latest/guide/pipes.jade | 2 +- .../latest/guide/server-communication.jade | 2 +- .../latest/guide/structural-directives.jade | 2 +- .../dart/latest/guide/template-syntax.jade | 2 +- public/docs/dart/latest/quickstart.jade | 2 +- public/docs/dart/latest/tutorial/toh-pt6.jade | 2 +- public/docs/ts/_cache/_quickstart_repo.jade | 1 + public/docs/ts/_cache/_util-fns.jade | 1 + public/docs/ts/_cache/guide/architecture.jade | 597 +++++++ .../ts/_cache/guide/attribute-directives.jade | 372 ++++ .../ts/_cache/guide/component-styles.jade | 319 ++++ .../ts/_cache/guide/dependency-injection.jade | 897 ++++++++++ .../docs/ts/_cache/guide/displaying-data.jade | 283 ++++ .../hierarchical-dependency-injection.jade | 178 ++ .../docs/ts/_cache/guide/lifecycle-hooks.jade | 574 +++++++ public/docs/ts/_cache/guide/pipes.jade | 487 ++++++ public/docs/ts/_cache/guide/security.jade | 263 +++ .../ts/_cache/guide/server-communication.jade | 702 ++++++++ .../_cache/guide/structural-directives.jade | 336 ++++ .../docs/ts/_cache/guide/template-syntax.jade | 1502 +++++++++++++++++ public/docs/ts/_cache/quickstart.jade | 582 +++++++ public/docs/ts/_cache/tutorial/toh-pt6.jade | 632 +++++++ scripts/refresh-cache.sh | 44 + 30 files changed, 7783 insertions(+), 13 deletions(-) create mode 100644 public/docs/ts/_cache/_quickstart_repo.jade create mode 100644 public/docs/ts/_cache/_util-fns.jade create mode 100644 public/docs/ts/_cache/guide/architecture.jade create mode 100644 public/docs/ts/_cache/guide/attribute-directives.jade create mode 100644 public/docs/ts/_cache/guide/component-styles.jade create mode 100644 public/docs/ts/_cache/guide/dependency-injection.jade create mode 100644 public/docs/ts/_cache/guide/displaying-data.jade create mode 100644 public/docs/ts/_cache/guide/hierarchical-dependency-injection.jade create mode 100644 public/docs/ts/_cache/guide/lifecycle-hooks.jade create mode 100644 public/docs/ts/_cache/guide/pipes.jade create mode 100644 public/docs/ts/_cache/guide/security.jade create mode 100644 public/docs/ts/_cache/guide/server-communication.jade create mode 100644 public/docs/ts/_cache/guide/structural-directives.jade create mode 100644 public/docs/ts/_cache/guide/template-syntax.jade create mode 100644 public/docs/ts/_cache/quickstart.jade create mode 100644 public/docs/ts/_cache/tutorial/toh-pt6.jade create mode 100755 scripts/refresh-cache.sh diff --git a/public/docs/dart/latest/guide/architecture.jade b/public/docs/dart/latest/guide/architecture.jade index f5f63c07a8..9bf1256210 100644 --- a/public/docs/dart/latest/guide/architecture.jade +++ b/public/docs/dart/latest/guide/architecture.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/architecture.jade +extends ../../../ts/_cache/guide/architecture.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/attribute-directives.jade b/public/docs/dart/latest/guide/attribute-directives.jade index 350cd60b88..eda47d20f5 100644 --- a/public/docs/dart/latest/guide/attribute-directives.jade +++ b/public/docs/dart/latest/guide/attribute-directives.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/attribute-directives.jade +extends ../../../ts/_cache/guide/attribute-directives.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/component-styles.jade b/public/docs/dart/latest/guide/component-styles.jade index 967dc2d8b0..a101402e74 100644 --- a/public/docs/dart/latest/guide/component-styles.jade +++ b/public/docs/dart/latest/guide/component-styles.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/component-styles.jade +extends ../../../ts/_cache/guide/component-styles.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/dependency-injection.jade b/public/docs/dart/latest/guide/dependency-injection.jade index 7236d24c7d..c840601347 100644 --- a/public/docs/dart/latest/guide/dependency-injection.jade +++ b/public/docs/dart/latest/guide/dependency-injection.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/dependency-injection.jade +extends ../../../ts/_cache/guide/dependency-injection.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/displaying-data.jade b/public/docs/dart/latest/guide/displaying-data.jade index 9207073069..5a9a1cdffb 100644 --- a/public/docs/dart/latest/guide/displaying-data.jade +++ b/public/docs/dart/latest/guide/displaying-data.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/displaying-data.jade +extends ../../../ts/_cache/guide/displaying-data.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/hierarchical-dependency-injection.jade b/public/docs/dart/latest/guide/hierarchical-dependency-injection.jade index 153e3c8108..4214572991 100644 --- a/public/docs/dart/latest/guide/hierarchical-dependency-injection.jade +++ b/public/docs/dart/latest/guide/hierarchical-dependency-injection.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/hierarchical-dependency-injection.jade +extends ../../../ts/_cache/guide/hierarchical-dependency-injection.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/lifecycle-hooks.jade b/public/docs/dart/latest/guide/lifecycle-hooks.jade index 5a57169bbb..c67c1fa3f2 100644 --- a/public/docs/dart/latest/guide/lifecycle-hooks.jade +++ b/public/docs/dart/latest/guide/lifecycle-hooks.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/lifecycle-hooks.jade +extends ../../../ts/_cache/guide/lifecycle-hooks.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/pipes.jade b/public/docs/dart/latest/guide/pipes.jade index ae4e3aeead..e444a67771 100644 --- a/public/docs/dart/latest/guide/pipes.jade +++ b/public/docs/dart/latest/guide/pipes.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/pipes.jade +extends ../../../ts/_cache/guide/pipes.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/server-communication.jade b/public/docs/dart/latest/guide/server-communication.jade index 4064b7ec97..ef79633e6d 100644 --- a/public/docs/dart/latest/guide/server-communication.jade +++ b/public/docs/dart/latest/guide/server-communication.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/server-communication.jade +extends ../../../ts/_cache/guide/server-communication.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/structural-directives.jade b/public/docs/dart/latest/guide/structural-directives.jade index ecae8ac2ee..2637084cbd 100644 --- a/public/docs/dart/latest/guide/structural-directives.jade +++ b/public/docs/dart/latest/guide/structural-directives.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/structural-directives.jade +extends ../../../ts/_cache/guide/structural-directives.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/guide/template-syntax.jade b/public/docs/dart/latest/guide/template-syntax.jade index 71878e7b94..b754481889 100644 --- a/public/docs/dart/latest/guide/template-syntax.jade +++ b/public/docs/dart/latest/guide/template-syntax.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/guide/template-syntax.jade +extends ../../../ts/_cache/guide/template-syntax.jade block includes include ../_util-fns diff --git a/public/docs/dart/latest/quickstart.jade b/public/docs/dart/latest/quickstart.jade index f3d81db102..8126efc8dc 100644 --- a/public/docs/dart/latest/quickstart.jade +++ b/public/docs/dart/latest/quickstart.jade @@ -1,4 +1,4 @@ -extends ../../ts/latest/quickstart.jade +extends ../../ts/_cache/quickstart.jade block includes include _util-fns diff --git a/public/docs/dart/latest/tutorial/toh-pt6.jade b/public/docs/dart/latest/tutorial/toh-pt6.jade index bee08c95de..888bdb78bf 100644 --- a/public/docs/dart/latest/tutorial/toh-pt6.jade +++ b/public/docs/dart/latest/tutorial/toh-pt6.jade @@ -1,4 +1,4 @@ -extends ../../../ts/latest/tutorial/toh-pt6.jade +extends ../../../ts/_cache/tutorial/toh-pt6.jade block includes include ../_util-fns diff --git a/public/docs/ts/_cache/_quickstart_repo.jade b/public/docs/ts/_cache/_quickstart_repo.jade new file mode 100644 index 0000000000..c11222793b --- /dev/null +++ b/public/docs/ts/_cache/_quickstart_repo.jade @@ -0,0 +1 @@ +include ../latest/_quickstart_repo diff --git a/public/docs/ts/_cache/_util-fns.jade b/public/docs/ts/_cache/_util-fns.jade new file mode 100644 index 0000000000..b44b0e2959 --- /dev/null +++ b/public/docs/ts/_cache/_util-fns.jade @@ -0,0 +1 @@ +include ../latest/_util-fns diff --git a/public/docs/ts/_cache/guide/architecture.jade b/public/docs/ts/_cache/guide/architecture.jade new file mode 100644 index 0000000000..3510c864bb --- /dev/null +++ b/public/docs/ts/_cache/guide/architecture.jade @@ -0,0 +1,597 @@ +block includes + include ../_util-fns + - var _library_module = 'library module' + - var _at_angular = '@angular' + +:marked + Angular 2 is a framework to help us build client applications in HTML and + either JavaScript or a language (like Dart or TypeScript) that compiles to JavaScript. + +block angular-parts + :marked + The framework consists of several cooperating libraries, some of them core and some optional. + +:marked + With Angular, we write applications by composing HTML *templates* with Angularized-markup, + writing *component* classes to manage those templates, adding application logic in *services*, + and handing the top root component to Angular's *bootstrapper*. + + Angular takes over, presenting our application content in a browser and + responding to user interactions according to the instructions we provided. + + Of course there is more to it than this. + We'll learn the details when we dive into the guide chapters. + Let's get the big picture first. + +figure + img(src="/resources/images/devguide/architecture/overview2.png" alt="overview" style="margin-left:-40px;" width="700") + +:marked + The architecture diagram identifies the eight main building blocks of an Angular 2 application: + + 1. [Modules](#modules) + 1. [Components](#components) + 1. [Templates](#templates) + 1. [Metadata](#metadata) + 1. [Data binding](#data-binding) + 1. [Directives](#directives) + 1. [Services](#services) + 1. [Dependency injection](#dependency-injection) + + Learn these, and we're on our way. + +.l-sub-section + p The code referenced in this chapter is available as a #[+liveExampleLink2()]. + +.l-main-section +:marked + ## Modules +figure + img(src="/resources/images/devguide/architecture/module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" ) +:marked + Angular apps are modular. + + In general we assemble our application from many **modules**. + + A typical module is a cohesive block of code dedicated to a single purpose. + A module **exports** something of value in that code, typically one thing such as a class. +

+ +block modules-in-dart + //- N/A + +block modules-are-optional + .l-sub-section + :marked + ### Modules are optional + We highly recommend modular design. TypeScript has great support for ES2015 module syntax and our chapters assume we're taking a modular + approach using that syntax. That's why we list *Module* among the basic building blocks. + + Angular itself doesn't require a modular approach nor this particular syntax. Don't use it if you don't want it. + Each chapter has plenty to offer after you steer clear of the `import` and `export` statements. + + Find setup and organization clues in the JavaScript track (select it from the combo-box at the top of this page) + which demonstrates Angular 2 development with plain old JavaScript and no module system. + +- var _app_comp_filename = _docsFor == 'dart' ? 'app_component.dart' : 'app.component.ts'; +:marked + Perhaps the first module we meet is a module that exports a *component* class. + The component is one of the basic Angular blocks, we write a lot of them, + and we'll talk about components in the next segment. For the moment it is enough to know that a + component class is the kind of thing we'd export from a module. + + Most applications have an `AppComponent`. By convention, we'll find it in a file named `!{_app_comp_filename}`. + Look inside such a file and we'll see a declaration such as this one. + ++makeExcerpt('app/app.component.ts ()', 'export') + +block export-qualifier + :marked + The `export` statement tells TypeScript that this is a module whose + `AppComponent` class is public and accessible to other modules of the application. + +:marked + When we need a reference to the `AppComponent`, we **import** it like this: + ++makeExcerpt('app/main.ts', 'import') + +block ts-import + :marked + The `import` statement tells the system it can get an `AppComponent` from a module named `app.component` + located in a neighboring file. + The **module name** (AKA module id) is often the same as the filename without its extension. + +:marked + ### Libraries + +figure + img(src="/resources/images/devguide/architecture/library-module.png" alt="Component" align="left" style="width:240px; margin-left:-40px;margin-right:10px" ) + +block angular-library-modules + :marked + Some modules are _libraries_ of other modules. + Angular itself ships as a collection of library modules within several npm packages. + Their names begin with the `!{_at_angular}` prefix. + + Each Angular library contains a [barrel](../glossary.html#barrel) module + that is actually a public façade over several logically-related private modules. + +:marked + `!{_at_angular}/core` is the primary Angular library from which we get most of what we need. +
+ + There are other important Angular libraries too, such as `!{_at_angular}/common`, + `!{_at_angular}/http` and `!{_at_angular}/router`. + We import what we need from an Angular !{_library_module}. + +block angular-imports + :marked + For example, we import the Angular **`Component` *function*** from `@angular/core` like this: + +makeExcerpt('app/app.component.ts', 'import') + :marked + Compare that syntax to our previous import of `AppComponent`. + +makeExcerpt('app/main.ts', 'import') + + :marked + Notice the difference? + In the first case, when importing from an Angular library module, + the import statement refers to the bare module name, `@angular/core`, *without a path prefix*. + + When we import from one of *our* own files, we prefix the module name with the file path. + In this example we specify a relative file path (`./`). That means the + source module is in the same folder (`./`) as the module importing it. + We could path up and around the application folder structure if the source module were somewhere else. + .l-sub-section + :marked + We import and export in the ECMAScript 2015 (ES2015) module syntax. + Learn more about that syntax [here](http://www.2ality.com/2014/09/es6-modules-final.html) + and many other places on the web. + + The infrastructure *behind* module loading and importing is an important subject. + But it's a subject outside the scope of this introduction to Angular. + While we're focused on our application, *import* and *export* + is about all we need to know. + +- var _export = _docsFor == 'dart' ? 'publicly declare' : 'export'; +- var _declare = _docsFor == 'dart' ? 'declare' : 'export'; +:marked + The key take-aways are: + * Angular apps are composed of modules. + * Modules !{_export} things — classes, function, values — that other modules import. + * We prefer to write our application as a collection of modules, each module exporting one thing. + + The first module we write will most likely !{_declare} a component. + +.l-main-section +:marked + ## Components +figure + img(src="/resources/images/devguide/architecture/hero-component.png" alt="Component" align="left" style="width:200px; margin-left:-40px;margin-right:10px" ) + +:marked + A **component** controls a patch of screen real estate that we could call a *view*. + The shell at the application root with navigation links, a list of heroes, a hero editor ... + they're all views controlled by components. + + We define a component's application logic — what it does to support the view — inside a class. + The class interacts with the view through an API of properties and methods. + + + A `HeroListComponent`, for example, might have a `heroes` property that returns !{_an} !{_array} of heroes + that it acquired from a service. + It might have a `selectHero()` method that sets a `selectedHero` property when the user clicks to choose a hero from that list. + The component might be a class like this: + ++makeExcerpt('app/hero-list.component.ts', 'class') +:marked + Angular creates, updates, and destroys components as the user moves through the application. + The developer can take action at each moment in this lifecycle through optional [lifecycle hooks](lifecycle-hooks.html), like `ngOnInit()` declared above. +.l-sub-section + :marked + We may wonder who is calling the component's constructor? Who provides the service parameter? + For the moment, have faith that Angular will call the constructor and deliver an + appropriate `HeroService` when we need it. + +.l-main-section +:marked + ## Templates +figure + img(src="/resources/images/devguide/architecture/template.png" alt="Template" align="left" style="width:200px; margin-left:-40px;margin-right:10px" ) +:marked + We define a component's view with its companion **template**. A template is a form of HTML + that tells Angular how to render the component. + + A template looks like regular HTML much of the time ... and then it gets a bit strange. Here is a + template for our `HeroListComponent`: + ++makeExample('app/hero-list.component.html') + +:marked + This template features typical HTML elements like `

` and `

`. + But what are `*ngFor`, `{{hero.name}}`, `(click)`, `[hero]`, and ``? + + These are examples of Angular's [template syntax](template-syntax.html). + We will grow accustomed to that syntax and may even learn to love it. + We'll begin to explain it in a moment. + + Before we do, focus attention on the last line. + The `` tag is a custom element representing the `HeroDetailComponent`. + + The `HeroDetailComponent` is a *different* component than the `HeroListComponent` we've been reviewing. + The `HeroDetailComponent` (code not shown) presents facts about a particular hero, the + hero that the user selects from the list presented by the `HeroListComponent`. + The `HeroDetailComponent` is a **child** of the `HeroListComponent`. + +figure + img(src="/resources/images/devguide/architecture/component-tree.png" alt="Metadata" align="left" style="width:300px; margin-left:-40px;margin-right:10px" ) +:marked + Notice how `` rests comfortably among native HTML elements. + We can and _will_ mix our custom components with native HTML in the same layouts. + + In this manner we'll compose complex component trees to build out our richly featured application. +
+ +.l-main-section +:marked + ## Metadata +figure + img(src="/resources/images/devguide/architecture/metadata.png" alt="Metadata" align="left" style="width:150px; margin-left:-40px;margin-right:10px" ) + +:marked +

Metadata tells Angular how to process a class.

+
+:marked + [Looking back at the code](#component-code) for `HeroListComponent`, we see that it's just a class. + There is no evidence of a framework, no "Angular" in it at all. + + In fact, it really is *just a class*. It's not a component until we *tell Angular about it*. + + We tell Angular that `HeroListComponent` is a component by attaching **metadata** to the class. + + In !{_Lang}, we attach metadata by using !{_a} **!{_decorator}**. + Here's some metadata for `HeroListComponent`: + ++makeExcerpt('app/hero-list.component.ts', 'metadata') + +:marked + Here we see the `@Component` !{_decorator} which (no surprise) identifies the class + immediately below it as a component class. + +block ts-decorator + :marked + A decorator is a function. Decorators often have a configuration parameter. + The `@Component` decorator takes a required configuration object with the + information Angular needs to create and present the component and its view. + + Here are a few of the possible `@Component` configuration options: + +:marked + - `selector`: CSS selector that tells Angular to create and insert an instance of this component + where it finds a `` tag in *parent* HTML. + For example, if an app's HTML contains ``, then + Angular inserts an instance of the `HeroListComponent` view between those tags. + + - `templateUrl`: address of this component's template, which we showed [above](#templates). + + - `directives`: !{_array} of the components or directives that *this* template requires. + We saw in the last line of our template that we expect Angular to insert a `HeroDetailComponent` + in the space indicated by `` tags. + Angular will do so only if we mention the `HeroDetailComponent` in this `directives` !{_array}. + + - `providers`: !{_array} of **dependency injection providers** for services that the component requires. + This is one way to tell Angular that our component's constructor requires a `HeroService` + so it can get the list of heroes to display. We'll get to dependency injection later. + +figure + img(src="/resources/images/devguide/architecture/template-metadata-component.png" alt="Metadata" align="left" style="height:200px; margin-left:-40px;margin-right:10px" ) + +:marked + Angular reads the metadata specified by the `@Component` + annotation. That's how Angular learns to do "the right thing". + + The template, metadata, and component together describe a view. + + We apply other metadata !{_decorator}s in a similar fashion to guide Angular behavior. + `@Injectable`, `@Input`, and `@Output` are a few of the more popular !{_decorator}s + we'll master as our Angular knowledge grows. +
+:marked + The architectural takeaway is that we must add metadata to our code + so that Angular knows what to do. + +.l-main-section +:marked + ## Data binding + Without a framework, we would be responsible for pushing data values into the HTML controls and turning user responses + into actions and value updates. Writing such push/pull logic by hand is tedious, error-prone, and a nightmare to + read as any experienced jQuery programmer can attest. +figure + img(src="/resources/images/devguide/architecture/databinding.png" alt="Data Binding" style="width:220px; float:left; margin-left:-40px;margin-right:20px" ) +:marked + Angular supports **data binding**, + a mechanism for coordinating parts of a template with parts of a component. + We add binding markup to the template HTML to tell Angular how to connect both sides. + + There are four forms of data binding syntax. Each form has a direction — to the DOM, from the DOM, or in both directions — + as indicated by the arrows in the diagram. +
+:marked + We saw three forms of data binding in our [example](#templates) template: + ++makeExcerpt('app/hero-list.component.1.html', 'binding') + +:marked + * The `{{hero.name}}` [*interpolation*](displaying-data.html#interpolation) + displays the component's `hero.name` property value within the `
  • ` tags. + + * The `[hero]` [*property binding*](template-syntax.html#property-binding) passes the value of `selectedHero` from + the parent `HeroListComponent` to the `hero` property of the child `HeroDetailComponent`. + + * The `(click)` [*event binding*](user-input.html#click) calls the component's `selectHero` method when the user clicks a hero's name. + + **Two-way data binding** is an important fourth form + that combines property and event binding in a single notation, using the `ngModel` directive. + We didn't have a two-way binding in the `HeroListComponent` template; + here's an example from the `HeroDetailComponent` template: + ++makeExcerpt('app/hero-detail.component.html', 'ngModel') + +:marked + In two-way binding, a data property value flows to the input box from the component as with property binding. + The user's changes also flow back to the component, resetting the property to the latest value, + as with event binding. + + Angular processes *all* data bindings once per JavaScript event cycle, + from the root of the application component tree down to the leaves. + +figure + img(src="/resources/images/devguide/architecture/component-databinding.png" alt="Data Binding" style="float:left; width:300px; margin-left:-40px;margin-right:10px" ) +:marked + We don't know all the details yet, + but it's clear from these examples that data binding plays an important role in communication + between a template and its component. +
    +figure + img(src="/resources/images/devguide/architecture/parent-child-binding.png" alt="Parent/Child binding" style="float:left; width:300px; margin-left:-40px;margin-right:10px" ) +:marked + Data binding is also important for communication between parent and child components. +
    + +.l-main-section +:marked + ## Directives +figure + img(src="/resources/images/devguide/architecture/directive.png" alt="Parent child" style="float:left; width:150px; margin-left:-40px;margin-right:10px" ) +:marked + Angular templates are *dynamic*. When Angular renders them, it transforms the DOM + according to the instructions given by **directives**. + + A directive is a class with directive metadata. In !{_Lang} we apply the `@Directive` !{_decorator} + to attach metadata to the class. +
    +:marked + We already met one form of directive: the component. A component is a *directive-with-a-template*; + a `@Component` !{_decorator} is actually a `@Directive` !{_decorator} extended with template-oriented features. + +.l-sub-section + :marked + While **a component is technically a directive**, + components are so distinctive and central to Angular applications that we chose + to separate components from directives in this architectural overview. +:marked + Two *other* kinds of directives exist: _structural_ and _attribute_ directives. + + They tend to appear within an element tag as attributes do, + sometimes by name but more often as the target of an assignment or a binding. + + **Structural** directives alter layout by adding, removing, and replacing elements in DOM. + + Our [example](#templates) template uses two built-in structural directives: + ++makeExcerpt('app/hero-list.component.1.html', 'structural') + +:marked + * [`*ngFor`](displaying-data.html#ngFor) tells Angular to stamp out one `
  • ` per hero in the `heroes` list. + * [`*ngIf`](displaying-data.html#ngIf) includes the `HeroDetail` component only if a selected hero exists. + +block dart-bool + //- N/A + +:marked + **Attribute** directives alter the appearance or behavior of an existing element. + In templates they look like regular HTML attributes, hence the name. + + The `ngModel` directive, which implements two-way data binding, is + an example of an attribute directive. `ngModel` modifies the behavior of + an existing element (typically an ``) + by setting its display value property and responding to change events. + ++makeExcerpt('app/hero-detail.component.html', 'ngModel') +:marked + Angular ships with a small number of other directives that either alter the layout structure + (for example, [ngSwitch](template-syntax.html#ngSwitch)) + or modify aspects of DOM elements and components + (for example, [ngStyle](template-syntax.html#ngStyle) and [ngClass](template-syntax.html#ngClass)). + + Of course, we can also write our own directives. Components such as + `HeroListComponent` are one kind of custom directive. + + +.l-main-section +:marked + ## Services +figure + img(src="/resources/images/devguide/architecture/service.png" alt="Service" style="float:left; margin-left:-40px;margin-right:10px" ) +:marked + _Service_ is a broad category encompassing any value, function, or feature that our application needs. + + Almost anything can be a service. + A service is typically a class with a narrow, well-defined purpose. It should do something specific and do it well. +
    +:marked + Examples include: + * logging service + * data service + * message bus + * tax calculator + * application configuration + + There is nothing specifically _Angular_ about services. Angular itself has no definition of a service. + There is no service base class, and no place to register a service. + + Yet services are fundamental to any Angular application. Our components are big consumers of services. + + Here's an example of a service class that logs to the browser console + ++makeExcerpt('app/logger.service.ts', 'class') + +:marked + Here's a `HeroService` that fetches heroes and returns them in a resolved !{_PromiseLinked}. + The `HeroService` depends on the `Logger` service and another `BackendService` that handles the server communication grunt work. + ++makeExcerpt('app/hero.service.ts', 'class') + +:marked + Services are everywhere. + + We prefer our component classes lean. Our components don't fetch data from the server, + they don't validate user input, and they don't log directly to the console. + They delegate such tasks to services. + + A component's job is to enable the user experience and nothing more. It mediates between the view (rendered by the template) + and the application logic (which often includes some notion of a _model_). + A good component presents properties and methods for data binding. + It delegates everything nontrivial to services. + + Angular doesn't *enforce* these principles. + It won't complain if we write a "kitchen sink" component with 3000 lines. + + Angular does help us *follow* these principles by making it easy to factor our + application logic into services and make those services available to components through *dependency injection*. + +.l-main-section +:marked + ## Dependency injection +figure + img(src="/resources/images/devguide/architecture/dependency-injection.png" alt="Service" style="float:left; width:200px; margin-left:-40px;margin-right:10px" ) +:marked + _Dependency injection_ is a way to supply a new instance of a class + with the fully-formed dependencies it requires. Most dependencies are services. + Angular uses dependency injection to provide new components with the services they need. +
    +:marked + Angular can tell which services a component needs by looking at the types of its constructor parameters. + For example, the constructor of our `HeroListComponent` needs a `HeroService`: + ++makeExcerpt('app/hero-list.component.ts (constructor)', 'ctor') + +:marked + When Angular creates a component, it first asks an **injector** for + the services that the component requires. + + An injector maintains a container of service instances that it has previously created. + If a requested service instance is not in the container, the injector makes one and adds it to the container + before returning the service to Angular. + When all requested services have been resolved and returned, + Angular can call the component's constructor with those services as arguments. + This is what we mean by *dependency injection*. + + The process of `HeroService` injection looks a bit like this: +figure + img(src="/resources/images/devguide/architecture/injector-injects.png" alt="Service" ) +:marked + If the injector doesn't have a `HeroService`, how does it know how to make one? + + In brief, we must have previously registered a **provider** of the `HeroService` with the injector. + A provider is something that can create or return a service, typically the service class itself. + + We can register providers at any level of the application component tree. + We often do so at the root when we bootstrap the application so that + the same instance of a service is available everywhere. + ++makeExcerpt('app/main.ts', 'bootstrap') + +:marked + Alternatively, we might register at a component level, in the providers property of the `@Component` metadata: + ++makeExcerpt('app/hero-list.component.ts', 'providers') + +:marked + Registering at a component level means we get a new instance of the + service with each new instance of that component. + + + + Points to remember about dependency injection: + + * Dependency injection is wired into the Angular framework and used everywhere. + + * The *injector* is the main mechanism. + * An injector maintains a *container* of service instances that it created. + * An injector can create a new service instance from a *provider*. + + * A *provider* is a recipe for creating a service. + + * We register *providers* with injectors. + +.l-main-section +:marked + ## Wrap up + + We've learned just a bit about the eight main building blocks of an Angular application: + + 1. [Modules](#modules) + 1. [Components](#components) + 1. [Templates](#templates) + 1. [Metadata](#metadata) + 1. [Data binding](#data-binding) + 1. [Directives](#directives) + 1. [Services](#services) + 1. [Dependency injection](#dependency-injection) + + That's a foundation for everything else in an Angular application, + and it's more than enough to get going. + But it doesn't include everything we'll need or want to know. + + Here is a brief, alphabetical list of other important Angular features and services. + Most of them are covered in this Developers Guide (or soon will be). + + > [**Animations**](animations.html): The animation library makes it easy for developers to animate component behavior + without deep knowledge of animation techniques or CSS. + + > **Bootstrap**: A method to configure and launch the root application component. + + > **Change detection**: Learn how Angular decides that a component property value has changed and + when to update the screen. + Learn how it uses **zones** to intercept asynchronous activity and run its change detection strategies. + + > **Component router**: With the component Router service, users can navigate a multi-screen application + in a familiar web browsing style using URLs. + + > **Events**: The DOM raises events. So can components and services. Angular offers mechanisms for + publishing and subscribing to events. + + > [**Forms**](forms.html): Support complex data entry scenarios with HTML-based validation and dirty checking. + + > [**HTTP**](server-communication.html): Communicate with a server to get data, save data, and invoke server-side actions with an HTTP client. + + > [**Lifecycle hooks**](lifecycle-hooks.html): We can tap into key moments in the lifetime of a component, from its creation to its destruction, + by implementing the lifecycle hook interfaces. + + > [**Pipes**](pipes.html): Services that transform values for display. + We can put pipes in our templates to improve the user experience. Consider + this `currency` pipe expression: +
    +code-example(). + price | currency:'USD':true +
    +:marked + > It displays a price of "42.33" as `$42.33`. + + > [**Router**](router.html): Navigate from page to page within the client + application and never leave the browser. + + > [**Testing**](testing.html): Angular provides a + [testing library](https://pub.dartlang.org/packages/angular2_testing) + to run unit tests on our application parts as they interact with the Angular framework. diff --git a/public/docs/ts/_cache/guide/attribute-directives.jade b/public/docs/ts/_cache/guide/attribute-directives.jade new file mode 100644 index 0000000000..e6f0db9472 --- /dev/null +++ b/public/docs/ts/_cache/guide/attribute-directives.jade @@ -0,0 +1,372 @@ +block includes + include ../_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](#write-directive) + * [apply the attribute directive to an element in a template](#apply-directive) + * [respond to user-initiated events](#respond-to-user) + * [pass values into the directive using data binding](#bindings) + + Try the . + + ## Directives overview + + There are three kinds of directives in Angular: + 1. Components + 1. Structural directives + 1. Attribute directives + + A *Component* is really a directive with a template. + It's the most common of the three directives and we tend to write lots of them as we build applications. + + [*Structural* directives](structural-directives.html) can change the DOM layout by adding and removing DOM elements. + [NgFor](template-syntax.html#ngFor) and [NgIf](template-syntax.html#ngIf) are two familiar examples. + + An *Attribute* directive can change the appearance or behavior of an element. + The built-in [NgStyle](template-syntax.html#ngStyle) 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: + + +makeExample('attribute-directives/ts/app/app.component.1.html','p-style-background') + + :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 +a#write-directive +:marked + ## Build a simple attribute directive + An attribute directive minimally requires building a controller class annotated with + `@Directive`, which 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. + +:marked + ### Our first draft + Create a new project folder (`attribute-directives`) and follow the steps in the [QuickStart](../quickstart.html). + +include ../_quickstart_repo +:marked + Create the following source file in the indicated folder with the given code: ++makeExample('app/highlight.directive.1.ts') + +block highlight-directive-1 + :marked + We begin by importing some symbols from the Angular `core`. + We need the `Directive` symbol for the `@Directive` decorator. + We need the `ElementRef` to [inject](dependency-injection.html) into the directive's constructor + so we can access the DOM element. + We don't need `Input` immediately 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. +:marked + `@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 `[myHighlight]`. + Angular will locate all elements in the template that have an attribute named `myHighlight`. +.l-sub-section + :marked + ### Why not call it "highlight"? + *highlight* is a nicer name than *myHighlight* and, technically, it would work if we called it that. + + However, we recommend picking a selector name with a prefix to ensure + that it cannot conflict with any standard HTML attribute, now or in the future. + There is also less risk of colliding with a third-party directive name when we give ours a prefix. + + We do **not** prefix our `highlight` directive name with **`ng`**. + That prefix belongs to Angular. + + We need a prefix of our own, preferably short, and `my` will do for now. +p + | After the #[code @Directive] metadata comes the directive's controller class, which contains the logic for the directive. + +ifDocsFor('ts') + | We export `HighlightDirective` to make it accessible to other components. +:marked + Angular creates a new instance of the directive's controller class for + each matching element, injecting an Angular `ElementRef` + into the constructor. + `ElementRef` is a service that grants us direct access to the DOM element + through its `nativeElement` property. + That's all we need to set the element's background color using the browser DOM API. + +.l-main-section +a#apply-directive +:marked + ## Apply the attribute directive + The `AppComponent` in this sample is a test harness for our `HighlightDirective`. + Let's give it a new template that + applies the directive as an attribute to a paragraph (`p`) element. + In Angular terms, the `

    ` element will be the attribute **host**. +p + | We'll put the template in its own + code #[+adjExPath('app.component.html')] + | file that looks like this: ++makeExample('attribute-directives/ts/app/app.component.1.html',null,'app/app.component.html')(format=".") +: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/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` component metadata so that Angular + will recognize our directive when it encounters `myHighlight` in the template. + + We run the app and see that our directive highlights the paragraph text. + +figure.image-display + img(src="/resources/images/devguide/attribute-directives/first-highlight.png" alt="First Highlight") +.l-sub-section + :marked + ### Your directive isn't working? + + Did you remember to set the `directives` attribute of `@Component`? It is easy to forget! + + Open the console in the browser tools and look for an error like this: + code-example(format="nocode"). + EXCEPTION: Template parse errors: + Can't bind to 'myHighlight' since it isn't a known native property + :marked + Angular detects that we're trying to bind to *something* but it doesn't know what. + We have to tell it by listing `HighlightDirective` in the `directives` metadata array. +:marked + Let's recap what happened. + + Angular found the `myHighlight` attribute on the `

    ` element. It created + an instance of the `HighlightDirective` class, + injecting a reference to the element into the constructor + where we set the `

    ` element's background style to yellow. + +.l-main-section +a#respond-to-user +: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 hovers over an element. + + We'll need to + 1. detect when the user hovers into and out of the element, + 2. respond to those actions by setting and clearing the highlight color, respectively. + + We apply the `@HostListener` !{_decorator} to methods which are called when an event is raised. + ++makeExample('attribute-directives/ts/app/highlight.directive.2.ts','host')(format=".") + +.l-sub-section + :marked + The `@HostListener` !{_decorator} refers to the DOM element that hosts our attribute directive, the `

    ` in our case. + + We could have attached event listeners by manipulating the host DOM element directly, but + there are at least three problems with such an 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 `@HostListener` !{_decorator}. +:marked + Now we implement the two mouse event handlers: ++makeExample('attribute-directives/ts/app/highlight.directive.2.ts','mouse-methods')(format=".") +:marked + Notice that they delegate to a helper method that sets the color via a private local variable, `#{_priv}el`. + We revise the constructor to capture the `ElementRef.nativeElement` in this variable. + ++makeExample('attribute-directives/ts/app/highlight.directive.2.ts','ctor')(format=".") +:marked + Here's the updated directive: ++makeExample('app/highlight.directive.2.ts') +:marked + We run the app and confirm that the background color appears as we move the mouse over the `p` and + disappears as we move out. +figure.image-display + img(src="/resources/images/devguide/attribute-directives/highlight-directive-anim.gif" alt="Second Highlight") +.l-main-section +a#bindings +:marked + ## Configure the directive with binding + + Currently the highlight color is hard-coded within the directive. That's inflexible. + We should set the color externally with a binding like this: ++makeExample('attribute-directives/ts/app/app.component.html','pHost') +: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: ++makeExcerpt('app/highlight.directive.ts', 'class') +a#input +:marked + The new `highlightColor` property is called an *input* property because data flows from the binding expression into our directive. + Notice the `@Input()` #{_decorator} applied to the property. ++makeExcerpt('app/highlight.directive.ts', 'color') +:marked + `@Input` adds metadata to the class that makes the `highlightColor` property available for + property binding under the `myHighlight` alias. + We must add this input metadata or Angular will reject the binding. + See the [appendix](#why-input) below to learn why. +.l-sub-section + :marked + ### @Input(_alias_) + The developer who uses this directive expects to bind to the attribute name, `myHighlight`. + The directive property name is `highlightColor`. That's a disconnect. + + We could resolve the discrepancy by renaming the property to `myHighlight` and define it as follows: + + +makeExcerpt('app/highlight.directive.ts', 'highlight', '') + :marked + Maybe we don't want that property name inside the directive perhaps because it + doesn't express our intention well. + We can **alias** the `highlightColor` property with the attribute name by + passing `myHighlight` into the `@Input` #{_decorator}: + +makeExcerpt('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 red as the default color to fallback on in case + the user neglects to bind with a color. ++makeExcerpt('attribute-directives/ts/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: ++makeExcerpt('attribute-directives/ts/app/app.component.html', 'v2', '') + +.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 second version of the directive in action. +figure.image-display + img(src="/resources/images/devguide/attribute-directives/highlight-directive-v2-anim.gif" alt="Highlight v.2") + +.l-main-section +:marked + ## Bind to a second property + Our directive only has a single, customizable property. What if we had ***two properties***? + + Let's allow the template developer to set the default color, the color that prevails until the user picks a highlight color. + We'll add a second **input** property to `HighlightDirective` called `defaultColor`: ++makeExample('attribute-directives/ts/app/highlight.directive.ts', 'defaultColor')(format=".") +:marked + The `defaultColor` property has a setter that overrides the hard-coded default color, "red". + We don't need a getter. + + How do we bind to it? We already "burned" the `myHighlight` attribute name as a binding target. + + Remember that a *component is a directive too*. + We can add as many component property bindings as we need by stringing them along in the template + as in this example that sets the `a`, `b`, `c` properties to the string literals 'a', 'b', and 'c'. +code-example(format="." ). + <my-component [a]="'a'" [b]="'b'" [c]="'c'"><my-component> +:marked + We do the same thing with an attribute directive. ++makeExample('attribute-directives/ts/app/app.component.html', 'defaultColor')(format=".") +:marked + Here we're binding the user's color choice to the `myHighlight` attribute as we did before. + We're *also* binding the literal string, 'violet', to the `defaultColor`. + + Here is the final version of the directive in action. +figure.image-display + img(src="/resources/images/devguide/attribute-directives/highlight-directive-final-anim.gif" alt="Final Highlight") + +.l-main-section +:marked + ## Summary + We now know how to + - [build a simple **attribute directive** to attach behavior to an HTML element](#write-directive), + - [use that directive in a template](#apply-directive), + - [respond to **events** to change behavior based on an event](#respond-to-user), + - and [use **binding** to pass values to the attribute directive](#bindings). + + The final source: + ++makeTabs( + `attribute-directives/ts/app/app.component.ts, + attribute-directives/ts/app/app.component.html, + attribute-directives/ts/app/highlight.directive.ts, + attribute-directives/ts/app/main.ts, + attribute-directives/ts/index.html + `, + ',,full', + `app.component.ts, + app.component.html, + highlight.directive.ts, + main.ts, + index.html + `) + + +a#why-input +.l-main-section +:marked + ### Appendix: Input properties + + Earlier we declared the `highlightColor` property to be an ***input*** property of our + `HighlightDirective` + + We've seen properties in bindings before. + We never had to declare them as anything. Why now? + + Angular makes a subtle but important distinction between binding **sources** and **targets**. + + In all previous bindings, the directive or component property was a binding ***source***. + A property is a *source* if it appears in the template expression to the ***right*** of the equals (=). + + A property is a *target* when it appears in **square brackets** ([ ]) to the **left** of the equals (=) ... + as it is does when we bind to the `myHighlight` property of the `HighlightDirective`, ++makeExample('attribute-directives/ts/app/app.component.html','pHost')(format=".") +:marked + The 'color' in `[myHighlight]="color"` is a binding ***source***. + A source property doesn't require a declaration. + + The 'myHighlight' in `[myHighlight]="color"` *is* a binding ***target***. + We must declare it as an *input* property. + Angular rejects the binding with a clear error if we don't. + + Angular treats a *target* property differently for a good reason. + A component or directive in target position needs protection. + + Imagine that our `HighlightDirective` did truly wonderous things. + We graciously made a gift of it to the world. + + To our surprise, some people — perhaps naively — + started binding to *every* property of our directive. + Not just the one or two properties we expected them to target. *Every* property. + That could really mess up our directive in ways we didn't anticipate and have no desire to support. + + The *input* declaration ensures that consumers of our directive can only bind to + the properties of our public API ... nothing else. diff --git a/public/docs/ts/_cache/guide/component-styles.jade b/public/docs/ts/_cache/guide/component-styles.jade new file mode 100644 index 0000000000..c87e746a8e --- /dev/null +++ b/public/docs/ts/_cache/guide/component-styles.jade @@ -0,0 +1,319 @@ +block includes + include ../_util-fns + +:marked + Angular 2 applications are styled with regular CSS. That means we can apply + everything we know about CSS stylesheets, selectors, rules, and media queries + to our Angular applications directly. + + On top of this, Angular has the ability to bundle *component styles* + with our components enabling a more modular design than regular stylesheets. + + In this chapter we learn how to load and apply these *component styles*. + + # Table Of Contents + + * [Using Component Styles](#using-component-styles) + * [Special selectors](#special-selectors) + * [Loading Styles into Components](#loading-styles) + * [Controlling View Encapsulation: Emulated, Native, and None](#view-encapsulation) + * [Appendix 1: Inspecting the generated runtime component styles](#inspect-generated-css) + * [Appendix 2: Loading Styles with Relative URLs](#relative-urls) + + Run the of the code shown in this chapter. + +.l-main-section +:marked + ## Using Component Styles + + For every Angular 2 component we write, we may define not only an HTML template, + but also the CSS styles that go with that template, + specifying any selectors, rules, and media queries that we need. + + One way to do this is to set the `styles` property in the component metadata. + The `styles` property takes #{_an} #{_array} of strings that contain CSS code. + Usually we give it one string as in this example: + ++makeExample('component-styles/ts/app/hero-app.component.ts')(format='.') + +:marked + Component styles differ from traditional, global styles in a couple of ways. + + Firstly, the selectors we put into a component's styles *only apply within the template + of that component*. The `h1` selector in the example above only applies to the `

    ` tag + in the template of `HeroAppComponent`. Any `

    ` elements elsewhere in + the application are unaffected. + + This is a big improvement in modularity compared to how CSS traditionally works: + + 1. We can use the CSS class names and selectors that make the most sense in the context of each component. + + 1. Class names and selectors are local to the component and won't collide with + classes and selectors used elsewhere in the application. + + 1. Our component's styles *cannot* be changed by changes to styles elsewhere in the application. + + 1. We can co-locate the CSS code of each component with the TypeScript and HTML code of the component, + which leads to a neat and tidy project structure. + + 1. We can change or remove component CSS code in the future without trawling through the + whole application to see where else it may have been used. We just look at the component we're in. + +a(id="special-selectors") +.l-main-section +:marked + ## Special selectors + + Component styles have a few special *selectors* from the world of + [shadow DOM style scoping](https://www.w3.org/TR/css-scoping-1): + + ### :host + + Use the `:host` pseudo-class selector to target styles in the element that *hosts* the component (as opposed to + targeting elements *inside* the component's template): + ++makeExample('component-styles/ts/app/hero-details.component.css', 'host')(format='.') + +:marked + This is the *only* way we can target the host element. We cannot reach + it from inside the component with other selectors, because it is not part of the + component's own template. It is in a parent component's template. + + Use the *function form* to apply host styles conditionally by + including another selector inside parentheses after `:host`. + + In the next example we target the host element again, but only when it also has the `active` CSS class. + ++makeExample('component-styles/ts/app/hero-details.component.css', 'hostfunction')(format=".") + +:marked + ### :host-context + + Sometimes it is useful to apply styles based on some condition *outside* a component's view. + For example, there may be a CSS theme class applied to the document `` element, and + we want to change how our component looks based on that. + + Use the `:host-context()` pseudo-class selector. It works just like the function + form of `:host()`. It looks for a CSS class in *any ancestor* of the component host element, all the way + up to the document root. It's useful when combined with another selector. + + In the following example, we apply a `background-color` style to all `

    ` elements *inside* the component, only + if some ancestor element has the CSS class `theme-light`. + ++makeExample('component-styles/ts/app/hero-details.component.css', 'hostcontext')(format='.') + +:marked + ### /deep/ + + Component styles normally apply only to the HTML in the component's own template. + + We can use the `/deep/` selector to force a style down through the child component tree into all the child component views. + The `/deep/` selector works to any depth of nested components, and it applies *both to the view + children and the content children* of the component. + + In this example, we target all `

    ` elements, from the host element down + through this component to all of its child elements in the DOM: ++makeExample('component-styles/ts/app/hero-details.component.css', 'deep')(format=".") + +:marked + The `/deep/` selector also has the alias `>>>`. We can use either of the two interchangeably. + +.alert.is-important + :marked + The `/deep/` and `>>>` selectors should only be used with **emulated** view encapsulation. + This is the default and it is what we use most of the time. See the + [Controlling View Encapsulation](#view-encapsulation) + section for more details. + +a(id='loading-styles') +.l-main-section +:marked + ## Loading Styles into Components + + We have several ways to add styles to a component: + * inline in the template HTML + * by setting `styles` or `styleUrls` metadata + * with CSS imports + + The scoping rules outlined above apply to each of these loading patterns. + + ### Styles in Metadata + + We can add a `styles` #{_array} property to the `@Component` #{_decorator}. + Each string in the #{_array} (usually just one string) defines the CSS. + ++makeExample('component-styles/ts/app/hero-app.component.ts') + +:marked + ### Template Inline Styles + + We can embed styles directly into the HTML template by putting them + inside `