From 6fd0a141ef6ab2227d870db4418dca8ea3c67648 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Wed, 14 Dec 2016 10:57:10 -0800 Subject: [PATCH] chore: drop ts/_cache (#2974) * chore: drop dart cache and link check scripts * chore: delete ts/_cache * chore(README): remove mention of ts/_cache * chore: ignore ts/_cache files --- .gitignore | 3 +- README.md | 2 - public/docs/ts/_cache/_quickstart_repo.jade | 3 - public/docs/ts/_cache/_util-fns.jade | 1 - public/docs/ts/_cache/glossary.jade | 758 -------- 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 | 280 --- .../hierarchical-dependency-injection.jade | 175 -- public/docs/ts/_cache/guide/index.jade | 92 - .../ts/_cache/guide/learning-angular.jade | 43 - .../docs/ts/_cache/guide/lifecycle-hooks.jade | 544 ------ public/docs/ts/_cache/guide/pipes.jade | 487 ------ public/docs/ts/_cache/guide/security.jade | 263 --- .../ts/_cache/guide/server-communication.jade | 703 -------- public/docs/ts/_cache/guide/setup.jade | 180 -- .../_cache/guide/structural-directives.jade | 336 ---- .../docs/ts/_cache/guide/template-syntax.jade | 1557 ----------------- public/docs/ts/_cache/quickstart.jade | 45 - public/docs/ts/_cache/tutorial/index.jade | 81 - public/docs/ts/_cache/tutorial/toh-pt5.jade | 966 ---------- public/docs/ts/_cache/tutorial/toh-pt6.jade | 643 ------- scripts/cache.sh | 95 - scripts/check-dart-api-links.sh | 43 - 26 files changed, 2 insertions(+), 9483 deletions(-) delete mode 100644 public/docs/ts/_cache/_quickstart_repo.jade delete mode 100644 public/docs/ts/_cache/_util-fns.jade delete mode 100644 public/docs/ts/_cache/glossary.jade delete mode 100644 public/docs/ts/_cache/guide/architecture.jade delete mode 100644 public/docs/ts/_cache/guide/attribute-directives.jade delete mode 100644 public/docs/ts/_cache/guide/component-styles.jade delete mode 100644 public/docs/ts/_cache/guide/dependency-injection.jade delete mode 100644 public/docs/ts/_cache/guide/displaying-data.jade delete mode 100644 public/docs/ts/_cache/guide/hierarchical-dependency-injection.jade delete mode 100644 public/docs/ts/_cache/guide/index.jade delete mode 100644 public/docs/ts/_cache/guide/learning-angular.jade delete mode 100644 public/docs/ts/_cache/guide/lifecycle-hooks.jade delete mode 100644 public/docs/ts/_cache/guide/pipes.jade delete mode 100644 public/docs/ts/_cache/guide/security.jade delete mode 100644 public/docs/ts/_cache/guide/server-communication.jade delete mode 100644 public/docs/ts/_cache/guide/setup.jade delete mode 100644 public/docs/ts/_cache/guide/structural-directives.jade delete mode 100644 public/docs/ts/_cache/guide/template-syntax.jade delete mode 100644 public/docs/ts/_cache/quickstart.jade delete mode 100644 public/docs/ts/_cache/tutorial/index.jade delete mode 100644 public/docs/ts/_cache/tutorial/toh-pt5.jade delete mode 100644 public/docs/ts/_cache/tutorial/toh-pt6.jade delete mode 100755 scripts/cache.sh delete mode 100755 scripts/check-dart-api-links.sh diff --git a/.gitignore b/.gitignore index 086a9a2f6d..f347aa50a6 100644 --- a/.gitignore +++ b/.gitignore @@ -33,4 +33,5 @@ protractor-results.txt link-checker-results.txt *a2docs.css /dist -/public/docs/dart \ No newline at end of file +/public/docs/dart +/public/docs/ts/_cache diff --git a/README.md b/README.md index fa39507356..0d46780d7e 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,6 @@ Filing issues is helpful but **pull requests** that improve the docs are even be Learn how to [contribute to Angular.io](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md). -> **IMPORTANT**: Do _NOT_ make changes to cached files under `public/docs/ts/_cache`. Cached files are updated through a separate workflow. - ## Development Setup This site relies heavily on node and npm. diff --git a/public/docs/ts/_cache/_quickstart_repo.jade b/public/docs/ts/_cache/_quickstart_repo.jade deleted file mode 100644 index e6a963a79d..0000000000 --- a/public/docs/ts/_cache/_quickstart_repo.jade +++ /dev/null @@ -1,3 +0,0 @@ -.l-sub-section - :marked - Alternatively, begin with a [download of the QuickStart source](!{_qsRepo}). diff --git a/public/docs/ts/_cache/_util-fns.jade b/public/docs/ts/_cache/_util-fns.jade deleted file mode 100644 index b44b0e2959..0000000000 --- a/public/docs/ts/_cache/_util-fns.jade +++ /dev/null @@ -1 +0,0 @@ -include ../latest/_util-fns diff --git a/public/docs/ts/_cache/glossary.jade b/public/docs/ts/_cache/glossary.jade deleted file mode 100644 index 59a8b8230f..0000000000 --- a/public/docs/ts/_cache/glossary.jade +++ /dev/null @@ -1,758 +0,0 @@ -block includes - include _util-fns - -//- current.path = ['docs', lang, 'latest', ...] -- var lang = current.path[1] -- var docsPath='/' + current.path[0] -- var docsLatest='/' + current.path.slice(0,3).join('/'); -- var _at = lang === 'js' ? '' : '@' -- var _decoratorLink = '' + _decorator + '' - -:marked - Angular has a vocabulary of its own. - Most Angular terms are everyday English words - with a specific meaning within the Angular system. - - This glossary lists the most prominent terms - and a few less familiar ones that have unusual or - unexpected definitions. - - [A](#A) [B](#B) [C](#C) [D](#D) [E](#E) [F](#F) [G](#G) [H](#H) [I](#I) - [J](#J) [K](#K) [L](#L) [M](#M) [N](#N) [O](#O) [P](#P) [Q](#Q) [R](#R) - [S](#S) [T](#T) [U](#U) [V](#V) [W](#W) [X](#X) [Y](#Y) [Z](#Z) - -.l-main-section#A - -a#aot -:marked - ## Ahead-of-time (AOT) compilation -.l-sub-section - :marked - You can compile Angular applications at build-time. - By compiling your application using the compiler-cli, `ngc`, you can bootstrap directly - to a module factory, meaning you don't need to include the Angular compiler in your JavaScript bundle. - Ahead-of-time compiled applications also benefit from decreased load time and increased performance. - -+ifDocsFor('ts') - :marked - ## Angular module - .l-sub-section - :marked - Helps you organize an application into cohesive blocks of functionality. - An Angular module identifies the components, directives, and pipes that the application uses along with the list of external Angular modules that the application needs, such as `FormsModule`. - - Every Angular application has an application root module class. By convention, the class is - called `AppModule` and resides in a file named `app.module.ts`. - - For details and examples, see the [Angular Module](!{docsLatest}/guide/ngmodule.html) page. - -+ifDocsFor('ts|dart') - :marked - ## Annotation - .l-sub-section - block annotation-defn - :marked - In practice, a synonym for [Decoration](#decorator). - -:marked - ## Attribute directive -.l-sub-section - :marked - A category of [directive](#directive) that can listen to and modify the behavior of - other HTML elements, attributes, properties, and components. They are usually represented - as HTML attributes, hence the name. - - A good example of an attribute directive is the `ngClass` directive for adding and removing CSS class names. - -.l-main-section#B - -+ifDocsFor('ts|js') - :marked - ## Barrel - .l-sub-section - :marked - A barrel is a way to *rollup exports* from several ES2015 modules into a single convenient ES2015 module. - The barrel itself is an ES2015 module file that re-exports *selected* exports of other ES2015 modules. - - Imagine three ES2015 modules in a `heroes` folder: - code-example. - // heroes/hero.component.ts - export class HeroComponent {} - - // heroes/hero.model.ts - export class Hero {} - - // heroes/hero.service.ts - export class HeroService {} - :marked - Without a barrel, a consumer would need three import statements: - code-example. - import { HeroComponent } from '../heroes/hero.component.ts'; - import { Hero } from '../heroes/hero.model.ts'; - import { HeroService } from '../heroes/hero.service.ts'; - :marked - You can add a barrel to the `heroes` folder (called `index`, by convention) that exports all of these items: - code-example. - export * from './hero.model.ts'; // re-export all of its exports - export * from './hero.service.ts'; // re-export all of its exports - export { HeroComponent } from './hero.component.ts'; // re-export the named thing - :marked - Now a consumer can import what it needs from the barrel. - code-example. - import { Hero, HeroService } from '../heroes'; // index is implied - :marked - The Angular [scoped packages](#scoped-package) each have a barrel named `index`. - - .alert.is-important - :marked - Note that you can often achieve this using [Angular modules](#angular-module) instead. - -:marked - ## Binding -.l-sub-section - :marked - Almost always refers to [Data Binding](#data-binding) and the act of - binding an HTML object property to a data object property. - - May refer to a [dependency injection](#dependency-injection) binding - between a "token", also referred to as a "key", and a dependency [provider](#provider). - This more rare usage should be clear in context. - -:marked - ## Bootstrap -.l-sub-section - block bootstrap-defn-top - :marked - You launch an Angular application by "bootstrapping" it using the application root Angular module (`AppModule`). Bootstrapping identifies an application's top level "root" [component](#component), which is the first component that is loaded for the application. - For more information, see the [Setup](!{docsLatest}/guide/setup.html) page. - :marked - You can bootstrap multiple apps in the same `index.html`, each with its own top level root. - -.l-main-section#C -:marked - ## camelCase -.l-sub-section - :marked - The practice of writing compound words or phrases such that each word or abbreviation begins with a capital letter - _except the first letter, which is lowercase_. - - Function, property, and method names are typically spelled in camelCase. Examples include: `square`, `firstName` and `getHeroes`. Notice that `square` is an example of how you write a single word in camelCase. - - This form is also known as **lower camel case**, to distinguish it from **upper camel case**, which is [PascalCase](#pascalcase). - When you see "camelCase" in this documentation it always means *lower camel case*. - -:marked - ## Component -.l-sub-section - :marked - An Angular class responsible for exposing data to a [view](#view) and handling most of the view’s display and user-interaction logic. - - The *component* is one of the most important building blocks in the Angular system. - It is, in fact, an Angular [directive](#directive) with a companion [template](#template). - - You apply the `!{_at}Component` !{_decoratorLink} to - the component class, thereby attaching to the class the essential component metadata - that Angular needs to create a component instance and render it with its template - as a view. - - Those familiar with "MVC" and "MVVM" patterns will recognize - the component in the role of "controller" or "view model". - -.l-main-section#D -:marked - ## dash-case -.l-sub-section - :marked - The practice of writing compound words or phrases such that each word is separated by a dash or hyphen (`-`). - This form is also known as [kebab-case](#kebab-case). - - [Directive](#directive) selectors (like `my-app`) and - the root of filenames (such as `hero-list.component.ts`) are often - spelled in dash-case. - -:marked - ## Data binding -.l-sub-section - :marked - Applications display data values to a user and respond to user - actions (clicks, touches, keystrokes). - - Instead of manually pushing application data values into HTML, attaching - event listeners, pulling changed values from the screen, and - updating application data values, you can use data binding by declaring the relationship between an HTML widget and data source and let the - framework handle the details. - - Angular has a rich data binding framework with a variety of data binding - operations and supporting declaration syntax. - - Read about the forms of binding in the [Template Syntax](!{docsLatest}/guide/template-syntax.html) page: - * [Interpolation](!{docsLatest}/guide/template-syntax.html#interpolation). - * [Property binding](!{docsLatest}/guide/template-syntax.html#property-binding). - * [Event binding](!{docsLatest}/guide/template-syntax.html#event-binding). - * [Attribute binding](!{docsLatest}/guide/template-syntax.html#attribute-binding). - * [Class binding](!{docsLatest}/guide/template-syntax.html#class-binding). - * [Style binding](!{docsLatest}/guide/template-syntax.html#style-binding). - * [Two-way data binding with ngModel](!{docsLatest}/guide/template-syntax.html#ngModel). - - -+ifDocsFor('ts|dart') - a#decorator - a#decoration - :marked - ## Decorator | decoration - .l-sub-section - block decorator-defn - :marked - A decorator is a **function** that adds metadata to a class, its members (properties, methods) and function arguments. - - Decorators are a JavaScript language [feature](https://github.com/wycats/javascript-decorators), implemented in TypeScript and proposed for ES2016 (AKA ES7). - - To apply a decorator, position it immediately above or to the left of the thing it decorates. - - Angular has its own set of decorators to help it interoperate with your application parts. - Here is an example of a `@Component` decorator that identifies a - class as an Angular [component](#component) and an `@Input` decorator applied to the `name` property - of that component. The elided object argument to the `@Component` decorator would contain the pertinent component metadata. - ``` - @Component({...}) - export class AppComponent { - constructor(@Inject('SpecialFoo') public foo:Foo) {} - @Input() name:string; - } - ``` - The scope of a decorator is limited to the language feature - that it decorates. None of the decorations shown here will "leak" to other - classes appearing below it in the file. - - .alert.is-important - :marked - Always include parentheses `()` when applying a decorator. - -:marked - ## Dependency injection -.l-sub-section - :marked - Dependency injection is both a design pattern and a mechanism - for creating and delivering parts of an application to other - parts of an application that request them. - - Angular developers prefer to build applications by defining many simple parts - that each do one thing well and then wiring them together at runtime. - - These parts often rely on other parts. An Angular [component](#component) - part might rely on a service part to get data or perform a calculation. When - part "A" relies on another part "B", you say that "A" depends on "B" and - that "B" is a dependency of "A". - - You can ask a "dependency injection system" to create "A" - for us and handle all the dependencies. - If "A" needs "B" and "B" needs "C", the system resolves that chain of dependencies - and returns a fully prepared instance of "A". - - Angular provides and relies upon its own sophisticated - [dependency injection](!{docsLatest}/guide/dependency-injection.html) system - to assemble and run applications by "injecting" application parts - into other application parts where and when needed. - - At the core there is an [`injector`](#injector) that returns dependency values on request. - The expression `injector.get(token)` returns the value associated with the given token. - - A token is an Angular type (`OpaqueToken`). You rarely deal with tokens directly; most - methods accept a class name (`Foo`) or a string ("foo") and Angular converts it - to a token. When you write `injector.get(Foo)`, the injector returns - the value associated with the token for the `Foo` class, typically an instance of `Foo` itself. - - During many of its operations, Angular makes similar requests internally, such as when it creates a [`component`](#component) for display. - - The `Injector` maintains an internal map of tokens to dependency values. - If the `Injector` can't find a value for a given token, it creates - a new value using a `Provider` for that token. - - A [provider](#provider) is a recipe for - creating new instances of a dependency value associated with a particular token. - - An injector can only create a value for a given token if it has - a `provider` for that token in its internal provider registry. - Registering providers is a critical preparatory step. - - Angular registers some of its own providers with every injector. - We can register our own providers. - - Read more in the [Dependency Injection](!{docsLatest}/guide/dependency-injection.html) page. -:marked - ## Directive -.l-sub-section - :marked - An Angular class responsible for creating, reshaping, and interacting with HTML elements - in the browser DOM. Directives are Angular's most fundamental feature. - - A Directive is almost always associated with an HTML element or attribute. - We often refer to such an element or attribute as the directive itself. - When Angular finds a directive in an HTML template, - it creates the matching directive class instance - and gives the instance control over that portion of the browser DOM. - - You can invent custom HTML markup (for example, ``) to - associate with your custom directives. You add this custom markup to HTML templates - as if you were writing native HTML. In this way, directives become extensions of - HTML itself. - - Directives fall into one of three categories: - - 1. [Components](#component) that combine application logic with an HTML template to - render application [views]. Components are usually represented as HTML elements. - They are the building blocks of an Angular application and the - developer can expect to write a lot of them. - - 1. [Attribute directives](#attribute-directive) that can listen to and modify the behavior of - other HTML elements, attributes, properties, and components. They are usually represented - as HTML attributes, hence the name. - - 1. [Structural directives](#structural-directive), a directive responsible for - shaping or reshaping HTML layout, typically by adding, removing, or manipulating - elements and their children. - -.l-main-section#E - -:marked - ## ECMAScript -.l-sub-section - :marked - The [official JavaScript language specification](https://en.wikipedia.org/wiki/ECMAScript). - - The latest approved version of JavaScript is - [ECMAScript 2016](http://www.ecma-international.org/ecma-262/7.0/) - (AKA "ES2016" or "ES7") and many Angular developers write their applications - either in this version of the language or a dialect that strives to be - compatible with it, such as [TypeScript](#typescript). - - Most modern browsers today only support the much older "ECMAScript 5" (AKA ES5) standard. - Applications written in ES2016, ES2015 or one of their dialects must be "[transpiled](#transpile)" - to ES5 JavaScript. - - Angular developers may choose to write in ES5 directly. - -:marked - ## ES2015 -.l-sub-section - :marked - Short hand for [ECMAScript](#ecmascript) 2015. -:marked - ## ES6 -.l-sub-section - :marked - Short hand for [ECMAScript](#ecmascript) 2015. -:marked - ## ES5 -.l-sub-section - :marked - Short hand for [ECMAScript](#ecmascript) 5, the version of JavaScript run by most modern browsers. - See [ECMAScript](#ecmascript). - -a#F -a#G -a#H -.l-main-section#I -:marked - ## Injector -.l-sub-section - :marked - An object in the Angular [dependency injection system](#dependency-injection) - that can find a named "dependency" in its cache or create such a thing - with a registered [provider](#provider). - -:marked - ## Input -.l-sub-section - :marked - A directive property that can be the ***target*** of a - [property binding](!{docsLatest}/guide/template-syntax.html#property-binding) (explained in detail in the [Template Syntax](!{docsLatest}/guide/template-syntax.html) page). - Data values flow *into* this property from the data source identified - in the template expression to the right of the equal sign. - - See the [Input and output properties](!{docsLatest}/guide/template-syntax.html#inputs-outputs) section of the [Template Syntax](!{docsLatest}/guide/template-syntax.html) page. - -:marked - ## Interpolation -.l-sub-section - :marked - A form of [property data binding](#data-binding) in which a - [template expression](#template-expression) between double-curly braces - renders as text. That text may be concatenated with neighboring text - before it is assigned to an element property - or displayed between element tags, as in this example. - - code-example(language="html" escape="html"). - - - :marked - Read more about [interpolation](!{docsLatest}/guide/template-syntax.html#interpolation) in the - [Template Syntax](!{docsLatest}/guide/template-syntax.html) page. - -.l-main-section#J - -a#jit -:marked - ## Just-in-time (JIT) compilation -.l-sub-section - :marked - With Angular _just-in-time_ bootstrapping you compile your components and modules in the browser - and launch the application dynamically. This is a good choice during development. - Consider using the [ahead-of-time](#aot) mode for production apps. - -.l-main-section#K -:marked - ## kebab-case -.l-sub-section - :marked - See [dash-case](#dash-case). - -.l-main-section#L -:marked - ## Lifecycle hooks -.l-sub-section - :marked - [Directives](#directive) and [components](#component) have a lifecycle - managed by Angular as it creates, updates, and destroys them. - - You can tap into key moments in that lifecycle by implementing - one or more of the lifecycle hook interfaces. - - Each interface has a single hook method whose name is the interface name prefixed with `ng`. - For example, the `OnInit` interface has a hook method named `ngOnInit`. - - Angular calls these hook methods in the following order: - * `ngOnChanges` - when an [input](#input)/[output](#output) binding value changes. - * `ngOnInit` - after the first `ngOnChanges`. - * `ngDoCheck` - developer's custom change detection. - * `ngAfterContentInit` - after component content initialized. - * `ngAfterContentChecked` - after every check of component content. - * `ngAfterViewInit` - after component's view(s) are initialized. - * `ngAfterViewChecked` - after every check of a component's view(s). - * `ngOnDestroy` - just before the directive is destroyed. - - Read more in the [Lifecycle Hooks](!{docsLatest}/guide/lifecycle-hooks.html) page. - -.l-main-section#M - -:marked - ## Module -.l-sub-section - block module-defn - .alert.is-important - :marked - In Angular, there are two types of modules: - - [Angular modules](#angular-module). - For details and examples, see the [Angular Modules](!{docsLatest}/guide/ngmodule.html) page. - - ES2015 modules, as described in this section. - - :marked - Angular apps are modular. - - In general, you assemble your application from many modules, both the ones you write and the ones you acquire from others. - - 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. - A module that needs that thing, **imports** it. - - The structure of Angular modules and the import/export syntax - is based on the [ES2015 module standard](http://www.2ality.com/2014/09/es6-modules-final.html). - - An application that adheres to this standard requires a module loader to - load modules on request, and resolve inter-module dependencies. - Angular does not ship with a module loader and does not have a preference - for any particular 3rd party library (although most examples use SystemJS). - You may pick any module library that conforms to the standard. - - Modules are typically named after the file in which the exported thing is defined. - The Angular [DatePipe](https://github.com/angular/angular/blob/master/modules/@angular/common/src/pipes/date_pipe.ts) - class belongs to a feature module named `date_pipe` in the file `date_pipe.ts`. - - You rarely access Angular feature modules directly. You usually import them from one of the Angular [scoped packages](#scoped-package) such as `@angular/core`. - -a#N -.l-main-section#O - -+ifDocsFor('ts|js') - :marked - ## Observable - .l-sub-section - :marked - You can think of an observable as an array whose items arrive asynchronously over time. - Observables help you manage asynchronous data, such as data coming from a backend service. - Observables are used within Angular itself, including Angular's event system and its http client service. - - To use observables, Angular uses a third-party library called Reactive Extensions (RxJS). - Observables are a proposed feature for ES 2016, the next version of JavaScript. - -:marked - ## Output -.l-sub-section - :marked - A directive property that can be the ***target*** of - [event binding](!{docsLatest}/guide/template-syntax.html#event-binding). - Events stream *out* of this property to the receiver identified - in the template expression to the right of the equal sign. - - See the [Input and output properties](!{docsLatest}/guide/template-syntax.html#inputs-outputs) section of the [Template Syntax](!{docsLatest}/guide/template-syntax.html) page. - -.l-main-section#P - -:marked - ## PascalCase -.l-sub-section - :marked - The practice of writing individual words, compound words, or phrases such that each word or abbreviation begins with a capital letter. Class names are typically spelled in PascalCase. Examples include: `Person` and `HeroDetailComponent`. - - This form is also known as **upper camel case** to distinguish it from **lower camel case**, which is simply called [camelCase](#camelcase). In this documentation, "PascalCase" means *upper camel case* and "camelCase" means *lower camel case*. - -:marked - ## Pipe -.l-sub-section - :marked - An Angular pipe is a function that transforms input values to output values for - display in a [view](#view). Use the `!{_at}Pipe` !{_decoratorLink} - to associate the pipe function with a name. You then use that - name in your HTML to declaratively transform values on screen. - - Here's an example that uses the built-in `currency` pipe to display - a numeric value in the local currency. - - code-example(language="html" escape="html"). - {{product.price | currency}} - :marked - Read more in the page on [pipes](!{docsLatest}/guide/pipes.html). - -:marked - ## Provider -.l-sub-section - :marked - A _provider_ creates a new instance of a dependency for the - [dependency injection](#dependency-injection) system. - It relates a lookup token to code—sometimes called a "recipe"—that can create a dependency value. - -a#Q -.l-main-section#R - -+ifDocsFor('ts|js') - :marked - ## Reactive forms - .l-sub-section - :marked - A technique for building Angular forms through code in a component. - The alternate technique is [Template-Driven Forms](#template-driven-forms). - - When building reactive forms: - - The "source of truth" is the component. The validation is defined using code in the component. - - Each control is explicitly created in the component class with `new FormControl()` or with `FormBuilder`. - - The template input elements do *not* use `ngModel`. - - The associated Angular directives are all prefixed with `Form` such as `FormGroup`, `FormControl`, and `FormControlName`. - - Reactive forms are powerful, flexible, and great for more complex data entry form scenarios such as dynamic generation of form controls. - -:marked - ## Router -.l-sub-section - :marked - Most applications consist of many screens or [views](#view). - The user navigates among them by clicking links and buttons, - and performing other similar actions that cause the application to - replace one view with another. - - The Angular [component router](!{docsLatest}/guide/router.html) is a richly featured mechanism for configuring and managing the entire view navigation process including the creation and destruction - of views. - +ifDocsFor('ts|js') - :marked - In most cases, components become attached to a [router](#router) by means - of a `RouterConfig` that defines routes to views. - - A [routing component's](#routing-component) template has a `RouterOutlet` element - where it can display views produced by the router. - - Other views in the application likely have anchor tags or buttons with `RouterLink` - directives that users can click to navigate. - - For more information, see the [Routing & Navigation](!{docsLatest}/guide/router.html) page. - -+ifDocsFor('ts|js') - :marked - ## Router module - .l-sub-section - :marked - A separate [Angular module](#angular-module) that provides the necessary service providers and directives for navigating through application views. - - For more information, see the [Routing & Navigation](!{docsLatest}/guide/router.html) page. - -:marked - ## Routing component -.l-sub-section - :marked - An Angular [component](#component) with a `RouterOutlet` that displays views based on router navigations. - - For more information, see the [Routing & Navigation](!{docsLatest}/guide/router.html) page. - -.l-main-section#S - -+ifDocsFor('ts|js') - :marked - ## Scoped package - .l-sub-section - :marked - Angular modules are delivered within *scoped packages* such as `@angular/core`, `@angular/common`, `@angular/platform-browser-dynamic`, - `@angular/http`, and `@angular/router`. - - A [*scoped package*](https://docs.npmjs.com/misc/scope) is a way to group related *npm* packages. - - You import a scoped package the same way that you'd import a *normal* package. - The only difference, from a consumer perspective, - is that the *scoped package* name begins with the Angular *scope name*, `@angular`. - - +makeExcerpt('architecture/ts/app/app.component.ts', 'import', '') - -a#snake-case -:marked - ## snake_case - -.l-sub-section - block snake-case-defn - :marked - The practice of writing compound words or phrases such that an - underscore (`_`) separates one word from the next. This form is also known as **underscore case**. - -:marked - ## Service -.l-sub-section - :marked - For data or logic that is not associated - with a specific view or that you want to share across components, build services. - - Applications often require services such as a hero data service or a logging service. - - A service is a class with a focused purpose. - We often create a service to implement features that are - independent from any specific view, - provide shared data or logic across components, or encapsulate external interactions. - - For more information, see the [Services](!{docsLatest}/tutorial/toh-pt4.html) page of the [Tour of Heroes](!{docsLatest}/tutorial/) tutorial. - -:marked - ## Structural directive -.l-sub-section - :marked - A category of [directive](#directive) that can - shape or reshape HTML layout, typically by adding, removing, or manipulating - elements and their children; for example, the `ngIf` "conditional element" directive and the `ngFor` "repeater" directive. - - Read more in the [Structural Directives](!{docsLatest}/guide/structural-directives.html) page. - -.l-main-section#T -:marked - ## Template -.l-sub-section - :marked - A template is a chunk of HTML that Angular uses to render a [view](#view) with - the support and continuing guidance of an Angular [directive](#directive), - most notably a [component](#component). - - -+ifDocsFor('ts|js') - :marked - ## Template-driven forms - .l-sub-section - :marked - A technique for building Angular forms using HTML forms and input elements in the view. - The alternate technique is [Reactive Forms](#reactive-forms). - - When building template-driven forms: - - The "source of truth" is the template. The validation is defined using attributes on the individual input elements. - - [Two-way binding](#data-binding) with `ngModel` keeps the component model in synchronization with the user's entry into the input elements. - - Behind the scenes, Angular creates a new control for each input element, provided you have set up a `name` attribute and two-way binding for each input. - - The associated Angular directives are all prefixed with `ng` such as `ngForm`, `ngModel`, and `ngModelGroup`. - - Template-driven forms are convenient, quick, and simple. They are a good choice for many basic data entry form scenarios. - - Read about how to build template-driven forms - in the [Forms](!{docsLatest}/guide/forms.html) page. - -:marked - ## Template expression -.l-sub-section - :marked - An expression is a !{_Lang}-like syntax that Angular evaluates within - a [data binding](#data-binding). - - Read about how to write template expressions - in the [Template Syntax](!{docsLatest}/guide/template-syntax.html#template-expressions) page. - -:marked - ## Transpile -.l-sub-section - :marked - The process of transforming code written in one form of JavaScript - (for example, TypeScript) into another form of JavaScript (for example, [ES5](#es5)). - - :marked - ## TypeScript -.l-sub-section - :marked - A version of JavaScript that supports most [ECMAScript 2015](#es2015) - language features such as [decorators](#decorator). - - TypeScript is also noteable for its optional typing system, which gives - us compile-time type checking and strong tooling support (for example, "intellisense", - code completion, refactoring, and intelligent search). Many code editors - and IDEs support TypeScript either natively or with plugins. - - TypeScript is the preferred language for Angular development although - you can use other JavaScript dialects such as [ES5](#es5). - - Read more about TypeScript at [typescript.org](http://www.typescriptlang.org/). - -a#U -.l-main-section#V - -:marked - ## View -.l-sub-section - :marked - A view is a portion of the screen that displays information and responds - to user actions such as clicks, mouse moves, and keystrokes. - - Angular renders a view under the control of one or more [directives](#directive), - especially [component](#component) directives and their companion [templates](#template). - The component plays such a prominent role that it's often - convenient to refer to a component as a view. - - Views often contain other views and any view might be loaded and unloaded - dynamically as the user navigates through the application, typically - under the control of a [router](#router). - -a#W -a#X -a#Y -.l-main-section#Z - -:marked - ## Zone -.l-sub-section - block zone-defn - :marked - Zones are a mechanism for encapsulating and intercepting - a JavaScript application's asynchronous activity. - - The browser DOM and JavaScript have a limited number - of asynchronous activities, activities such as DOM events (for example, clicks), - [promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise), and - [XHR](https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest) - calls to remote servers. - - Zones intercept all of these activities and give a "zone client" the opportunity - to take action before and after the async activity finishes. - - Angular runs your application in a zone where it can respond to - asynchronous events by checking for data changes, and updating - the information it displays via [data bindings](#data-binding). - - Learn more about zones in this - [Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). diff --git a/public/docs/ts/_cache/guide/architecture.jade b/public/docs/ts/_cache/guide/architecture.jade deleted file mode 100644 index 2303e4dace..0000000000 --- a/public/docs/ts/_cache/guide/architecture.jade +++ /dev/null @@ -1,597 +0,0 @@ -block includes - include ../_util-fns - - var _library_module = 'library module' - - var _at_angular = '@angular' - -:marked - Angular 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 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 . - -.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 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 deleted file mode 100644 index e6f0db9472..0000000000 --- a/public/docs/ts/_cache/guide/attribute-directives.jade +++ /dev/null @@ -1,372 +0,0 @@ -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 deleted file mode 100644 index 2ea8d2761a..0000000000 --- a/public/docs/ts/_cache/guide/component-styles.jade +++ /dev/null @@ -1,319 +0,0 @@ -block includes - include ../_util-fns - -:marked - Angular 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 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 `