491 lines
17 KiB
Plaintext
491 lines
17 KiB
Plaintext
include ../../../../_includes/_util-fns
|
|
|
|
:marked
|
|
Everything that we can do in Angular in TypeScript, we can also do
|
|
in JavaScript. Translating from one language to the other is mostly a
|
|
matter of changing the way we organize our code and the way we access
|
|
Angular APIs.
|
|
|
|
Since TypeScript is a popular language option in Angular, many of the
|
|
code examples you see on the Internet as well as on this site are written
|
|
in TypeScript. This cookbook contains recipes for translating these kinds of
|
|
code examples to ES5, so that they can be applied to Angular JavaScript
|
|
applications.
|
|
|
|
<a id="toc"></a>
|
|
:marked
|
|
## Table of contents
|
|
|
|
[From TS to ES6 to ES5](#from-ts)
|
|
|
|
[Modularity: imports and exports](#modularity)
|
|
|
|
[Classes and Class Metadata](#class-metadata)
|
|
|
|
[Input and Output Metadata](#property-metadata)
|
|
|
|
[Dependency Injection](#dependency-injection)
|
|
|
|
[Host and Query Metadata](#host-query-metadata)
|
|
|
|
**Run and compare the live <live-example name="cb-ts-to-js">TypeScript</live-example> and <live-example name="cb-ts-to-js" lang="js">JavaScript</live-example>
|
|
code shown in this cookbook.**
|
|
|
|
a(id="from-ts")
|
|
.l-main-section
|
|
:marked
|
|
## From TS to ES6 to ES5
|
|
|
|
Since TypeScript is a superset of ES6 JavaScript, and ES6 itself is a superset of ES5, the
|
|
transformation of Typescript code all the way to ES5 javascript can be seen as "shedding"
|
|
features.
|
|
|
|
When going from TypeScript to ES6 with decorators, we mostly remove
|
|
[type annotations](https://www.typescriptlang.org/docs/handbook/basic-types.html)
|
|
, such as `string` or `boolean`, and
|
|
[class property modifiers](http://www.typescriptlang.org/docs/handbook/classes.html#public-private-and-protected-modifiers)
|
|
such as `public` and `private`.
|
|
The exception is type annotations used for dependency injection, which can be kept.
|
|
|
|
Going from ES6 with decorators to plain ES6 JavaScript we lose all
|
|
[decorators](https://www.typescriptlang.org/docs/handbook/decorators.html)
|
|
and the remaining type annotations.
|
|
We also lose class properties, which now have to be declared in the class constructor.
|
|
|
|
Finally, in the transition from ES6 to ES5 JavaScript the main missing features are `import`
|
|
statements and `class` declarations.
|
|
|
|
For ES6 transpilation we recommend using a similar setup as our TypeScript quickstart,
|
|
replacing TypeScript with [Babel](https://babeljs.io/) using the `es2015` preset.
|
|
To use decorators and annotations with Babel, install the
|
|
[`angular2`](https://github.com/shuhei/babel-plugin-angular2-annotations) preset as well.
|
|
|
|
a(id="modularity")
|
|
.l-main-section
|
|
:marked
|
|
## Importing and Exporting
|
|
|
|
### Importing Angular Code
|
|
|
|
In TypeScript and ES6 JavaScript, Angular classes, functions, and other members are imported
|
|
with ES6 `import` statements.
|
|
|
|
In ES5 JavaScript code, when using [the Angular packages](../glossary.html#!#scoped-package),
|
|
we can access Angular code through the global `ng` object. In the nested members of this
|
|
object we'll find everything we would import from `@angular` in TypeScript:
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/main.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/main.es6,
|
|
cb-ts-to-js/js-es6/app/main.es6,
|
|
cb-ts-to-js/js/app/main.js
|
|
`,`
|
|
ng2import,
|
|
ng2import,
|
|
ng2import,
|
|
ng2import
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
|
|
:marked
|
|
### Importing and Exporting Application Code
|
|
|
|
Each file in an Angular TypeScript or ES6 JavaScript application constitutes a ES6 module.
|
|
When we want to make something from a module available to other modules, we `export` it.
|
|
|
|
In an Angular ES5 JavaScript application, we load each file to the page using a `<script>` tag.
|
|
Each file can make things available to other files via the shared global `window` scope.
|
|
|
|
We often introduce an application namespace object (such as `app`) onto `window` and attach
|
|
everything we need to share to that namespace object.
|
|
We also wrap our code in an
|
|
[Immediately Invoked Function Expression (IIFE)](https://en.wikipedia.org/wiki/Immediately-invoked_function_expression).
|
|
These practices together prevent our code from polluting the global scope.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/hero.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/hero.component.es6,
|
|
cb-ts-to-js/js-es6/app/hero.component.es6,
|
|
cb-ts-to-js/js/app/hero.component.js
|
|
`,`
|
|
appexport,
|
|
appexport,
|
|
appexport,
|
|
appexport
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
|
|
:marked
|
|
Using Typescript or ES6 JavaScript, in other modules we can then `import` things that have been exported
|
|
elsewhere.
|
|
|
|
In ES5 JavaScript we can access anything using the shared namespace in other files.
|
|
Note that the order of `<script>` tags on the page is significant.
|
|
We must load a file that defines a shared member before a file that uses that member.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/main.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/main.es6,
|
|
cb-ts-to-js/js-es6/app/main.es6,
|
|
cb-ts-to-js/js/app/main.js
|
|
`,`
|
|
appimport,
|
|
appimport,
|
|
appimport,
|
|
appimport
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
|
|
.alert.is-helpful
|
|
:marked
|
|
Alternatively, we can use a module loader such as Webpack or
|
|
Browserify in an Angular JavaScript project. In such a project, we would
|
|
use CommonJS modules and the `require` function to load Angular framework code.
|
|
We would then use `module.exports` and `require` to export and import application
|
|
code.
|
|
|
|
|
|
a(id="class-metadata")
|
|
.l-main-section
|
|
:marked
|
|
## Classes and Class Metadata
|
|
|
|
### Classes
|
|
|
|
We put most of our Angular TypeScript or ES6 JavaScript code into classes. ES6 without decorators
|
|
also does not have support for class properties, so they must be assigned inside the constructor.
|
|
|
|
ES5 JavaScript has no classes. We use the constructor pattern instead which works with
|
|
Angular as well as classes do.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/hero.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/hero.component.es6,
|
|
cb-ts-to-js/js-es6/app/hero.component.es6,
|
|
cb-ts-to-js/js/app/hero.component.js
|
|
`,`
|
|
class,
|
|
class,
|
|
class,
|
|
constructorproto
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
|
|
:marked
|
|
### Metadata
|
|
|
|
Using Typescript or ES6 with decorators, we have access to *decorators*.
|
|
Most Angular classes have one or more *decorators* attached to provide configuration
|
|
and metadata.
|
|
For example, a component must have a
|
|
[`@Component`](../api/core/index/Component-decorator.html) decorator.
|
|
|
|
In ES5/6 JavaScript we can instead attach an `annotations` array to a class/constructor
|
|
to provide metadata.
|
|
Each item in the array corresponds to a decorator.
|
|
|
|
The pattern of creating a constructor and decorating it with metadata is so common that Angular
|
|
provides an alternative ES5 convenience class API for it for ES5 JavaScript.
|
|
This API lets us define everything in a single expression.
|
|
|
|
With this API we first call the `ng.core.Component` function, followed by a chained `Class`
|
|
method call.
|
|
The argument to `Class` is an object that defines the constructor and the instance methods
|
|
of the component.
|
|
Similar APIs are also available for other decorators. You can define a directive with
|
|
`ng.core.Directive` or a pipe with `ng.core.Pipe`.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/hero.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/hero.component.es6,
|
|
cb-ts-to-js/js-es6/app/hero.component.es6,
|
|
cb-ts-to-js/js/app/hero.component.js,
|
|
cb-ts-to-js/js/app/hero-dsl.component.js
|
|
`,`
|
|
metadata,
|
|
metadata,
|
|
metadata,
|
|
metadata,
|
|
component
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript,
|
|
ES5 JavaScript with Class API
|
|
`)
|
|
|
|
:marked
|
|
### Interfaces
|
|
|
|
When defining classes that need to implement a certain method, it is common to use TypeScript
|
|
interfaces that enforce that the method signature is correct.
|
|
Component lifecycle methods like `ngOnInit` are one example of this pattern.
|
|
`ngOnInit` is defined in the `OnInit` interface.
|
|
|
|
TypeScript interfaces are purely for developer convenience and are not used by Angular at runtime.
|
|
This means that in ES5/6 JavaScript code we don't need to substitute anything for interfaces.
|
|
We can just implement the methods.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/hero-lifecycle.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/hero-lifecycle.component.es6,
|
|
cb-ts-to-js/js-es6/app/hero-lifecycle.component.es6,
|
|
cb-ts-to-js/js/app/hero-lifecycle.component.js
|
|
`,`
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
|
|
a(id="property-metadata")
|
|
.l-main-section
|
|
:marked
|
|
## Input and Output Metadata
|
|
|
|
### Input and Output Decorators
|
|
|
|
In TypeScript and ES6 with decorators, property decorators are often used to provide additional
|
|
metadata for components and directives.
|
|
For [inputs and outputs](../guide/template-syntax.html#inputs-outputs), we use `@Input` and
|
|
`@Output` property decorators.
|
|
They may optionally specify input and output binding names if we want them to be different
|
|
from the class property names.
|
|
|
|
There is no equivalent of a property decorator in ES5/6 JavaScript.
|
|
Instead, we add comparable information to the `Component` (or `Directive`) metadata.
|
|
|
|
In this example, we add `inputs` and `outputs` array attributes containing the input and
|
|
output property names.
|
|
If we need a binding name that is different from the property itself, we use the
|
|
`propertyName: bindingName` syntax.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/hero-io.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/hero-io.component.es6,
|
|
cb-ts-to-js/js-es6/app/hero-io.component.es6,
|
|
cb-ts-to-js/js/app/hero-io.component.js
|
|
`,`
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
|
|
.l-main-section
|
|
:marked
|
|
## Dependency Injection
|
|
|
|
### Injection by Type
|
|
|
|
Angular can often use TypeScript type information to determine what needs to be injected.
|
|
ES6 with decorators can also make use of type information.
|
|
|
|
Since no type information is available in ES5/6 JavaScript, we must identify "injectables" in
|
|
some other way.
|
|
|
|
We attach a `parameters` array to the constructor function.
|
|
Each array item is the dependency injection token that identifies the thing to be injected.
|
|
Often the token is the constructor function for the class-like dependency.
|
|
|
|
In ES6 the decorators need to be inside a nested array.
|
|
When using the ES5 class convenience API, we can also supply the parameter tokens by wrapping
|
|
the constructor in an array.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/hero-di.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/hero-di.component.es6,
|
|
cb-ts-to-js/js-es6/app/hero-di.component.es6,
|
|
cb-ts-to-js/js/app/hero-di.component.js,
|
|
cb-ts-to-js/js/app/hero-di-inline.component.js
|
|
`,`
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript,
|
|
ES5 JavaScript with Class API
|
|
`)
|
|
|
|
:marked
|
|
### Injection with the @Inject decorator
|
|
|
|
When the thing being injected doesn't correspond directly to a type, we use the
|
|
`@Inject()` decorator to supply the injection token.
|
|
In this example, we're injecting a string identified by the "heroName" token.
|
|
|
|
In ES5/6 JavaScript we add the token string to the injection parameters array.
|
|
Alternatively, when using the ES5 convenience class API we can create a token with the
|
|
`Inject` method and add that to the constructor array in the annotations.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/hero-di-inject.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/hero-di-inject.component.es6,
|
|
cb-ts-to-js/js-es6/app/hero-di-inject.component.es6,
|
|
cb-ts-to-js/js/app/hero-di-inject.component.js,
|
|
cb-ts-to-js/js/app/hero-di-inject.component.js
|
|
`,`
|
|
,
|
|
,
|
|
,
|
|
parameters,
|
|
ctor
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript,
|
|
ES5 JavaScript with Class API
|
|
`)
|
|
|
|
:marked
|
|
### Additional Injection Decorators
|
|
|
|
We can attach additional decorators to constructor parameters to qualify the injection behavior.
|
|
We can mark optional dependencies with the [`@Optional`](../api/core/index/Optional-decorator.html),
|
|
inject host element attributes with [`@Attribute`](../api/core/index/Attribute-interface.html),
|
|
inject content child queries with [`@ContentChild`](../api/core/index/ContentChild-decorator.html)
|
|
and inject view child queries with [`@ViewChild`](../api/core/index/ViewChild-decorator.html)).
|
|
|
|
In ES6 JavaScript we just add the extra decorators to the nested injection parameters array.
|
|
|
|
To achieve the same effect in ES5 JavaScript, use a nested array with the constructor
|
|
array notation in which the injection information precedes the constructor function itself.
|
|
|
|
We can apply other additional parameter decorators such as
|
|
[`@Host`](../api/core/index/Host-decorator.html) and
|
|
[`@SkipSelf`](../api/core/index/SkipSelf-decorator.html) in the same way -
|
|
by adding `new ng.core.Host()` or `ng.core.SkipSelf()` in the
|
|
parameters array.
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/hero-di-inject-additional.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/hero-di-inject-additional.component.es6,
|
|
cb-ts-to-js/js-es6/app/hero-di-inject-additional.component.es6,
|
|
cb-ts-to-js/js/app/hero-di-inject-additional.component.js
|
|
`,`
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
|
|
a(id="host-query-metadata")
|
|
.l-main-section
|
|
:marked
|
|
## Host and Query Metadata
|
|
|
|
### Host Decorators
|
|
|
|
In Typescript and ES6 with decorators we can use host property decorators to bind a host
|
|
element to a component or directive.
|
|
The [`@HostBinding`](../api/core/index/HostBinding-interface.html) decorator
|
|
binds host element properties to component data properties.
|
|
The [`@HostListener`](../api/core/index/HostListener-interface.html) decorator binds
|
|
host element events to component event handlers.
|
|
|
|
When using ES5/6 we add a `host` attribute to the component metadata to achieve the
|
|
same effect as `@HostBinding` and `@HostListener`.
|
|
|
|
The `host` value is an object whose properties are host property and listener bindings:
|
|
|
|
* Each key follows regular Angular binding syntax: `[property]` for host bindings
|
|
or `(event)` for host listeners.
|
|
* Each value identifies the corresponding component property or method.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/heroes-bindings.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/heroes-bindings.component.es6,
|
|
cb-ts-to-js/js-es6/app/heroes-bindings.component.es6,
|
|
cb-ts-to-js/js/app/heroes-bindings.component.js
|
|
`,`
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
.alert.is-helpful
|
|
:marked
|
|
In TypeScript and ES6 with decorators we can also use the `queries` metadata
|
|
instead of the `@ViewChild` and `@ContentChild` property decorators.
|
|
|
|
:marked
|
|
### Query Decorators
|
|
|
|
There are several property decorators for querying the descendants of
|
|
a component or directive.
|
|
|
|
The [`@ViewChild`](../api/core/index/ViewChild-decorator.html) and
|
|
[`@ViewChildren`](../api/core/index/ViewChildren-decorator.html) property decorators
|
|
allow a component to query instances of other components that are used in
|
|
its view.
|
|
|
|
In ES5/6 JavaScript we access a component's view children by adding a `queries` attribute to
|
|
the component metadata. It should be an object where:
|
|
|
|
* Each key is the name of a component property that will hold the view children
|
|
* Each value is an instance of either `ViewChild` or `ViewChildren`.
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/heroes-queries.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/heroes-queries.component.es6,
|
|
cb-ts-to-js/js-es6/app/heroes-queries.component.es6,
|
|
cb-ts-to-js/js/app/heroes-queries.component.js
|
|
`,`
|
|
view,
|
|
view,
|
|
view,
|
|
view
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|
|
|
|
:marked
|
|
The [`@ContentChild`](../api/core/index/ContentChild-decorator.html) and
|
|
[`@ContentChildren`](../api/core/index/ContentChildren-decorator.html) property decorators
|
|
allow a component to query instances of other components that have been projected
|
|
into its view from elsewhere.
|
|
|
|
They can be added in the same way as [`@ViewChild`](../api/core/index/ViewChild-decorator.html) and
|
|
[`@ViewChildren`](../api/core/index/ViewChildren-decorator.html).
|
|
|
|
+makeTabs(`
|
|
cb-ts-to-js/ts/app/heroes-queries.component.ts,
|
|
cb-ts-to-js/js-es6-decorators/app/heroes-queries.component.es6,
|
|
cb-ts-to-js/js-es6/app/heroes-queries.component.es6,
|
|
cb-ts-to-js/js/app/heroes-queries.component.js
|
|
`,`
|
|
content,
|
|
content,
|
|
content,
|
|
content
|
|
`,`
|
|
Typescript,
|
|
ES6 JavaScript with decorators,
|
|
ES6 JavaScript,
|
|
ES5 JavaScript
|
|
`)
|