From 3105660200fd09197f58d289d9eb3287ecac6e69 Mon Sep 17 00:00:00 2001 From: Ward Bell Date: Fri, 16 Oct 2015 14:51:15 -0700 Subject: [PATCH] (docs) Wrote and added glossary --- public/docs/ts/latest/guide/_data.json | 5 + public/docs/ts/latest/guide/glossary.jade | 445 ++++++++++++++++++++++ 2 files changed, 450 insertions(+) create mode 100644 public/docs/ts/latest/guide/glossary.jade diff --git a/public/docs/ts/latest/guide/_data.json b/public/docs/ts/latest/guide/_data.json index 39b399ba82..8205cd7070 100644 --- a/public/docs/ts/latest/guide/_data.json +++ b/public/docs/ts/latest/guide/_data.json @@ -13,5 +13,10 @@ "user-input": { "title": "User Input", "intro": "DOM events drive user input in Angular. You can use the native events like click, mouseover, and keyup. Angular uses a special syntax to register events to DOM elements. This section covers all the ins and outs of using the event syntax." + }, + + "glossary": { + "title": "Glossary", + "intro": "Brief definitions of the most important words in the Angular 2 vocabulary" } } \ No newline at end of file diff --git a/public/docs/ts/latest/guide/glossary.jade b/public/docs/ts/latest/guide/glossary.jade new file mode 100644 index 0000000000..d9ed0552e5 --- /dev/null +++ b/public/docs/ts/latest/guide/glossary.jade @@ -0,0 +1,445 @@ +:markdown + # Angular 2 Glossary +#sg-tables.showcase.shadow-1 + header.showcase-header + p. + The difference between the right word + and the almost right word is the difference between + lightening and a lightening bug. - Mark Twain + +:markdown + Angular 2 has a vocabulary of its own. + Most Angular 2 terms are everyday English words + with a specific meaning within the Angular system. + + We have gathered here the most prominent terms + and a few less familiar ones that have unusual or + unexpected definitions. + +.l-main-section +:markdown + ## Annotation +.l-sub-section + :markdown + In practice a synonym for [Decoration](#decoration). + + :markdown + ## Attribute Directive +.l-sub-section + :markdown + 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. + + The `ng-class` directive for adding and removing CSS class names is a good example of + an Attribute Directive. + +.l-main-section +:markdown + ## Binding +.l-sub-section + :markdown + 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" or "key" and a dependency [provider](#provider). + This more rare usage should be clear in context. + +:markdown + ## Bootstrap +.l-sub-section + :markdown + We launch an Angular application by "bootstrapping" it with the `bootstrap` method. + The `bootstrap` method identifies the application's' top level "root" [Component](#component) + and optionally registers service [providers](#provider) with the + [dependency injection system](#dependency-injection). + + +.l-main-section +:markdown + ## Component +.l-sub-section + :markdown + 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). + + The developer applies the `@Component` [decorator](decorator) 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 +:markdown + ## Data Binding +.l-sub-section + :markdown + Applications display data values to a user and respond to user + actions (clicks, touches, keystrokes). + + We could push application data values into HTML, attach + event listeners, pull changed values from the screen, and + update application data values ... all by hand. + + Or we could declare the relationship between an HTML widget + and an application data source ... and let a data binding + framework handle the details. + + Data Binding is that second approach. Angular has a rich + data binding framework with a variety of data binding + operations and supporting declaration syntax. + + The many forms of binding include: + * [Interpolation](./template-syntax.html#interpolation) + * [Property Binding](./template-syntax.html#property-binding) + * [Event Binding](./template-syntax.html#event-binding) + * [Attribute Binding](./template-syntax.html#aattribute-binding) + * [Class Binding](./template-syntax.html#class-binding) + * [Style Binding](./template-syntax.html#style-binding) + * [Two-way data binding with ng-model](./template-syntax.html#ng-model) + + Learn more about data binding in the + [Template Syntax](./template-syntax.html#data-binding) chapter. + +:markdown + ## Decoration +.l-sub-section + :markdown + A feature of TypeScript and ES2015. + + A Decoration is a function that adds Angular metadata to a class, + constructor parameter, or a property. + + We apply a decoration by positioning it + immediately above or to the left of the thing it decorates + as seen here. + ``` + @Component({...}) + export class AppComponent { + constructor(@Inject('SpecialFoo') public foo:Foo) {} + @Input() + name:string; + } + ``` + The scope of a decoration 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. + + :markdown + ## Dependency Injection +.l-sub-section + :markdown + 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 wire them together at runtime. + + These parts often rely on one another. An Angular [Component](#component) + part might rely on a service part to get data or perform a calculation. When a + part "A" relies on another part "B", we say that "A" depends on "B" and + that "B" is a dependency of "A". + + We developers have a choice. We can teach "A" to find or create "B" all by itself. + Or we can ask a "Dependency Injection System"" to find or create "B" and deliver + it to part "A" when "A" needs it. + + These choices and their relative merits are the subject of + much discussion under the rubric. "Dependency Injection". + We can read about that in many places including + [on the web here](https://en.wikipedia.org/wiki/Dependency_injection) + + Angular strongly favors the Dependency Injection approach + and relies on its own sophisticated + [Dependency Injection System](./dependency-injection.html) system + to assemble and run applications by "injecting" application parts + where and when needed. + + These parts (often called "dependencies") are created by [providers](#provider) + that we register with an [injector](#injector) at the appropriate time. + + Quite often the best time to register a provider is when + we [bootstrap](#bootstrap) the application + but there are other opportunities to register as well. + + Learn more by reading the [Dependency Injection System](./dependency-injection.html) chapter. + + :markdown + ## Directive +.l-sub-section + :markdown + An Angular class responsible for creating, re-shaping, 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 that instance control over that portion of the browser DOM. + + Developers can invent custom HTML markup (e.g., ``) to + associate with their custom directives. They add this custom markup to HTML templates + as if they 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 re-shaping HTML layout, typically by adding, removing, or manipulating + elements and their children. + +.l-main-section +:markdown + ## ECMAScript +.l-sub-section + :markdown + The [official JavaScript language specification](https://en.wikipedia.org/wiki/ECMAScript). + + The lastest released version of JavaScript is + [ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/) + (AKA "ES2015" or "ES6") and many Angular 2 developers will write their applications + either in this version of the language or a dialect that strives to be + compatible with it such as [TypeScript](#typesScript). + + Most modern browsers today only support the prior "ECMAScript 5" (AKA ES5) standard. + Applications written in ES2015 or one of its dialects must be "[transpiled](transpile)" + to ES5 JavaScript. + + Angular 2 developers may choose to write in ES5 directly. +:markdown + ## ECMAScript 2015 +.l-sub-section + :markdown + The lastest released version of JavaScript, + [ECMAScript 2015](http://www.ecma-international.org/ecma-262/6.0/) + (AKA "ES2015" or "ES6") +:markdown + ## ES2015 +.l-sub-section + :markdown + Short hand for "[ECMAScript 2015](#ecmascript=2015)". +:markdown + ## ES6 +.l-sub-section + :markdown + Short hand for "[ECMAScript 2015](#ecmascript=2015)". +:markdown + ## ES5 +.l-sub-section + :markdown + Short hand for "ECMAScript 5", the version of JavaScript run by most modern browsers. + See [ECMAScript](#ecmascript). + +.l-main-section +:markdown + ## Injector +.l-sub-section + :markdown + 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). + +:markdown + ## Input +.l-sub-section + :markdown + A directive property that can be the ***target*** of a + [Property Binding](./template-syntax.html#property-binding). + Data values flow *into* this property from the data source identified + in the template expression to the right of the equal sign. + + See the [Template Syntax](./template-syntax.html#inputs-outputs) chapter. + +:markdown + ## Interpolation +.l-sub-section + :markdown + A form of [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"). + + + :markdown + Learn more about interpolation in the + [Template Syntax](./template-syntax.html#interpolation) chapter. + +.l-main-section +:markdown + ## Output +.l-sub-section + :markdown + A directive property that can be the ***target*** of an + [Event Binding](./template-syntax.html#property-binding). + Events stream *out* of this property to the receiver identified + in the template expression to the right of the equal sign. + + See the [Template Syntax](./template-syntax.html#inputs-outputs) chapter. + +.l-main-section +:markdown + ## Pipe +.l-sub-section + :markdown + An Angular pipe is a function that transforms input values to output values for + display in a [view](#view). We use the `@Pipe` [decorator](decorator) + to associate the pipe function with a name. We then can use that + name in our 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}} + :markdown + Learn more in the chapter on [pipes](./pipes.html) . + +:markdown + ## Provider +.l-sub-section + :markdown + Angular relies on [dependency injection](#dependency-injection) to create and deliver + pieces of functionality to the application parts that need them. Those pieces are + often called "dependencies". + + Angular can't find or create these dependencies by itself. Something has to "provide" them. + That something is called a "Provider". A provider can be almost anything that can produce + the dependency although it is most often a class that we register with the + [dependency injector](injector). + + We typically register our application providers when we [bootstrap](#bootstrap) the application + but there are other opportunities to do that as well. + See the [Dependency Injection[(./dependency-injection.html)] chapter for details. + +.l-main-section +:markdown + ## Router +.l-sub-section + :markdown + Most applications consist of many screens or [views](#view). + The user navigates among them by clicking links and buttons + and taking other similar actions that cause the application to + replace one view with another. + + The [Angular router](./router.html) is a richly featured mechanism for configuring + and managing the entire navigation process including the creation and destruction + of views. + +.l-main-section +:markdown + ## Structural Directive +.l-sub-section + :markdown + A category of [Directive](#directive) that can + shape or re-shape HTML layout, typically by adding, removing, or manipulating + elements and their children. + + The `ng-if` "conditional element" directive and the `ng-for` "repeater" directive are + good examples in this category. + +.l-main-section +:markdown + ## Template +.l-sub-section + :markdown + 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). + + We write templates in a special [Template Syntax](./template-syntax.html). + +:markdown + ## Template Expresion +.l-sub-section + :markdown + An expression in a JavaScript-like syntax that Angular evaluates within + a [data binding](#data-binding). Learn how to write template expressions + in the [Template Syntax](./template-syntax.html#template-expressions) chapter. + +:markdown + ## Transpile +.l-sub-section + :markdown + The process of transforming code written in one form of JavaScript + (e.g., TypeScript) into another form of JavaScript (e.g., [ES5](#es5)). + + :markdown + ## TypeScript +.l-sub-section + :markdown + A version of JavaScript that supports most [ECMAScript 2015](#ecmascript=2015) + language features and many features that may arrive in future versions + of JavaScript such as [Decorations](#decoration). + + TypeScript is also noteable for its optional typing system which gives + us compile-time type-checking and strong tooling support (e.g. "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 2 development although + we are welcome to write in other JavaScript dialects such as [ES5](#es5). + + Angular 2 itself is written in TypeScript. + + Learn more about TypeScript on its [website](http://www.typescriptlang.org/). + +.l-main-section +:markdown + ## View +.l-sub-section + :markdown + 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 we often + find it 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](#rounter). + +.l-main-section +:markdown + ## Zone +.l-sub-section + :markdown + 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 (e.g., clicks), + [promises](#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 asynch activity completes. + + Angular runs our application in a zone where it can respond to + asynchronous events by checking for data changes and updating + the information it displays via [data binding(#data-binding). + + Learn more about zones in this + [Brian Ford video](https://www.youtube.com/watch?v=3IqtmUscE_U). \ No newline at end of file