cargdev/angular
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Revert "docs: test doc for decorator templates (#23902)"

Browse Source 
This reverts commit 3938a8be75240a9a59dae9f2c999e936b98de429.
This commit is contained in:
Jason Aden 2018-06-25 10:54:47 -07:00
parent 3938a8be75
commit 2056e1f05c
4 changed files with 456 additions and 552 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
packages/common/http/src/module.ts
View File

@ -19,13 +19,12 @@ import {BrowserXhr, HttpXhrBackend, XhrFactory} from './xhr';
import {HttpXsrfCookieExtractor, HttpXsrfInterceptor, HttpXsrfTokenExtractor, XSRF_COOKIE_NAME, XSRF_HEADER_NAME} from './xsrf'; import {HttpXsrfCookieExtractor, HttpXsrfInterceptor, HttpXsrfTokenExtractor, XSRF_COOKIE_NAME, XSRF_HEADER_NAME} from './xsrf';
/** /**
* An injectable `HttpHandler` that applies multiple interceptors * An `HttpHandler` that applies a bunch of `HttpInterceptor`s
* to a request before passing it to the given `HttpBackend`. * to a request before passing it to the given `HttpBackend`.
* *
* The interceptors are loaded lazily from the injector, to allow * The interceptors are loaded lazily from the injector, to allow
* interceptors to themselves inject classes depending indirectly * interceptors to themselves inject classes depending indirectly
* on `HttpInterceptingHandler` itself. * on `HttpInterceptingHandler` itself.
* @see `HttpInterceptor`
*/ */
@Injectable() @Injectable()
export class HttpInterceptingHandler implements HttpHandler { export class HttpInterceptingHandler implements HttpHandler {
@ -43,23 +42,6 @@ export class HttpInterceptingHandler implements HttpHandler {
} }
} }
/**
* Constructs an `HttpHandler` that applies interceptors
* to a request before passing it to the given `HttpBackend`.
*
* Use as a factory function within `HttpClientModule`.
*
*
*/
export function interceptingHandler(
backend: HttpBackend, interceptors: HttpInterceptor[] | null = []): HttpHandler {
if (!interceptors) {
return backend;
}
return interceptors.reduceRight(
(next, interceptor) => new HttpInterceptorHandler(next, interceptor), backend);
}
/** /**
* Factory function that determines where to store JSONP callbacks. * Factory function that determines where to store JSONP callbacks.
* *
@ -76,14 +58,14 @@ export function jsonpCallbackContext(): Object {
} }
/** /**
* An NgModule that adds XSRF protection support to outgoing requests. * `NgModule` which adds XSRF protection support to outgoing requests.
* *
* For a server that supports a cookie-based XSRF protection system, * Provided the server supports a cookie-based XSRF protection system, this
* use directly to configure XSRF protection with the correct * module can be used directly to configure XSRF protection with the correct
* cookie and header names. * cookie and header names.
* *
* If no names are supplied, the default cookie name is `XSRF-TOKEN` * If no such names are provided, the default is to use `X-XSRF-TOKEN` for
* and the default header name is `X-XSRF-TOKEN`. * the header name and `XSRF-TOKEN` for the cookie name.
* *
* *
*/ */
@ -110,12 +92,8 @@ export class HttpClientXsrfModule {
} }
/** /**
* Configure XSRF protection. * Configure XSRF protection to use the given cookie name or header name,
* @param options An object that can specify either or both * or the default names (as described above) if not provided.
* cookie name or header name.
* - Cookie name default is `XSRF-TOKEN`.
* - Header name default is `X-XSRF-TOKEN`.
*
*/ */
static withOptions(options: { static withOptions(options: {
cookieName?: string, cookieName?: string,
@ -132,7 +110,7 @@ export class HttpClientXsrfModule {
} }
/** /**
* An NgModule that provides the `HttpClient` and associated services. * `NgModule` which provides the `HttpClient` and associated services.
* *
* Interceptors can be added to the chain behind `HttpClient` by binding them * Interceptors can be added to the chain behind `HttpClient` by binding them
* to the multiprovider for `HTTP_INTERCEPTORS`. * to the multiprovider for `HTTP_INTERCEPTORS`.
@ -140,18 +118,12 @@ export class HttpClientXsrfModule {
* *
*/ */
@NgModule({ @NgModule({
/**
* Optional configuration for XSRF protection.
*/
imports: [ imports: [
HttpClientXsrfModule.withOptions({ HttpClientXsrfModule.withOptions({
cookieName: 'XSRF-TOKEN', cookieName: 'XSRF-TOKEN',
headerName: 'X-XSRF-TOKEN', headerName: 'X-XSRF-TOKEN',
}), }),
], ],
/**
* The module provides `HttpClient` itself, and supporting services.
*/
providers: [ providers: [
HttpClient, HttpClient,
{provide: HttpHandler, useClass: HttpInterceptingHandler}, {provide: HttpHandler, useClass: HttpInterceptingHandler},
@ -165,7 +137,7 @@ export class HttpClientModule {
} }
/** /**
* An NgModule that enables JSONP support in `HttpClient`. * `NgModule` which enables JSONP support in `HttpClient`.
* *
* Without this module, Jsonp requests will reach the backend * Without this module, Jsonp requests will reach the backend
* with method JSONP, where they'll be rejected. * with method JSONP, where they'll be rejected.

719
packages/core/src/metadata/directives.ts
View File

@ -137,6 +137,17 @@ export interface Directive {
* bankName: string; * bankName: string;
* id: string; * id: string;
* *
* // this property is not bound, and won't be automatically updated by Angular
* normalizedBankName: string;
* }
*
* @Component({
* selector: 'app',
* template: `
* <bank-account bankName="RBC" account-id="4747"></bank-account>
* `
* })
* class App {}
* ``` * ```
*/ */
inputs?: string[]; inputs?: string[];
@ -158,17 +169,29 @@ export interface Directive {
* *
* ```typescript * ```typescript
* @Directive({ * @Directive({
* selector: 'child-dir', * selector: 'interval-dir',
* exportAs: 'child' * outputs: ['everySecond', 'five5Secs: everyFiveSeconds']
* }) * })
* class ChildDir { * class IntervalDir {
* everySecond = new EventEmitter();
* five5Secs = new EventEmitter();
*
* constructor() {
* setInterval(() => this.everySecond.emit("event"), 1000);
* setInterval(() => this.five5Secs.emit("event"), 5000);
* }
* } * }
* *
* @Component({ * @Component({
* selector: 'main', * selector: 'app',
* template: `<child-dir #c="child"></child-dir>` * template: `
* <interval-dir (everySecond)="everySecond()" (everyFiveSeconds)="everyFiveSeconds()">
* </interval-dir>
* `
* }) * })
* class MainComponent { * class App {
* everySecond() { console.log('second'); }
* everyFiveSeconds() { console.log('five seconds'); }
* } * }
* ``` * ```
*/ */
@ -220,7 +243,6 @@ export interface Directive {
* }) * })
* class App {} * class App {}
* ``` * ```
* See [live demo](http://plnkr.co/edit/DlA5KU?p=preview)
* *
* ### Host Property Bindings * ### Host Property Bindings
* *
@ -254,7 +276,6 @@ export interface Directive {
* prop; * prop;
* } * }
* ``` * ```
* See [live demo](http://plnkr.co/edit/gNg0ED?p=preview).
* *
* ### Attributes * ### Attributes
* *
@ -273,18 +294,17 @@ export interface Directive {
* class MyButton { * class MyButton {
* } * }
* ``` * ```
* Attaching the `my-button` directive to the host `<div>` element */
* ensures that this element gets the "button" role. host?: {[key: string]: string};
*
* ```html /**
* <div my-button></div> * Defines the set of injectable objects that are visible to a Directive and its light DOM
* ``` * children.
* *
* @usageNotes * @usageNotes
* ### Simple Example * ### Simple Example
* *
* The following simple example shows how a class is injected, * Here is an example of a class that can be injected:
* using a provider specified in the directive metadata:
* *
* ``` * ```
* class Greeter { * class Greeter {
@ -344,7 +364,6 @@ export interface Directive {
* @usageNotes * @usageNotes
* ### Example * ### Example
* *
* The followoing example (shows what??)
* ``` * ```
* @Component({ * @Component({
* selector: 'someDir', * selector: 'someDir',
@ -367,8 +386,6 @@ export interface Directive {
* } * }
* } * }
* ``` * ```
*
* @Annotation
*/ */
queries?: {[key: string]: any}; queries?: {[key: string]: any};
} }
@ -378,148 +395,93 @@ export interface Directive {
* *
* @Annotation * @Annotation
*/ */
export interface Directive { export const Directive: DirectiveDecorator =
/** makeDecorator('Directive', (dir: Directive = {}) => dir);
* The CSS selector that identifies this directive in a template
* and triggers instantiation of the directive.
*
* Declare as one of the following:
*
* - `element-name`: Select by element name.
* - `.class`: Select by class name.
* - `[attribute]`: Select by attribute name.
* - `[attribute=value]`: Select by attribute name and value.
* - `:not(sub_selector)`: Select only if the element does not match the `sub_selector`.
* - `selector1, selector2`: Select if either `selector1` or `selector2` matches.
*
* Angular only allows directives to apply on CSS selectors that do not cross
* element boundaries.
*
* For the following template HTML, a directive with an `input[type=text]` selector,
* would be instantiated only on the `<input type="text">` element.
*
* ```html
* <form>
* <input type="text">
* <input type="radio">
* <form>
* ```
*
*/
selector?: string;
/** /**
* The set of event-bound output properties. * Type of the Component decorator / constructor function.
* When an output property emits an event, an event handler attached
* to that event in the template is invoked.
*
* Each output property maps a `directiveProperty` to a `bindingProperty`:
* - `directiveProperty` specifies the component property that emits events.
* - `bindingProperty` specifies the HTML attribute the event handler is attached to.
*
*/ */
outputs?: string[]; export interface ComponentDecorator {
/** /**
* Maps class properties to host element bindings for properties, * Marks a class as an Angular component and collects component configuration
* attributes, and events, using a set of key-value pairs. * metadata.
* *
* Angular automatically checks host property bindings during change detection. * Component decorator allows you to mark a class as an Angular component and provide additional
* If a binding changes, Angular updates the directive's host element. * metadata that determines how the component should be processed, instantiated and used at
* runtime.
* *
* When the key is a property of the host element, the property value is * Components are the most basic building block of an UI in an Angular application.
* the propagated to the specified DOM property. * An Angular application is a tree of Angular components.
* Angular components are a subset of directives. Unlike directives, components always have
* a template and only one component can be instantiated per an element in a template.
* *
* When the key is a static attribute in the DOM, the attribute value * A component must belong to an NgModule in order for it to be usable
* is propagated to the specified property in the host element. * by another component or application. To specify that a component is a member of an NgModule,
* you should list it in the `declarations` field of that NgModule.
* *
* For event handling: * In addition to the metadata configuration specified via the Component decorator,
* - The key is the DOM event that the directive listens to. * components can control their runtime behavior by implementing various Life-Cycle hooks.
* To listen to global events, add the target to the event name.
* The target can be `window`, `document` or `body`.
* - The value is the statement to execute when the event occurs. If the
* statement evalueates to `false`, then `preventDefault` is applied on the DOM
* event. A handler method can refer to the `$event` local variable.
* *
* **Metadata Properties:**
*
* * **animations** - list of animations of this component
* * **changeDetection** - change detection strategy used by this component
* * **encapsulation** - style encapsulation strategy used by this component
* * **entryComponents** - list of components that are dynamically inserted into the view of this
* component
* * **exportAs** - name under which the component instance is exported in a template
* * **host** - map of class property to host element bindings for events, properties and
* attributes
* * **inputs** - list of class property names to data-bind as component inputs
* * **interpolation** - custom interpolation markers used in this component's template
* * **moduleId** - ES/CommonJS module id of the file in which this component is defined
* * **outputs** - list of class property names that expose output events that others can
* subscribe to
* * **providers** - list of providers available to this component and its children
* * **queries** - configure queries that can be injected into the component
* * **selector** - css selector that identifies this component in a template
* * **styleUrls** - list of urls to stylesheets to be applied to this component's view
* * **styles** - inline-defined styles to be applied to this component's view
* * **template** - inline-defined template for the view
* * **templateUrl** - url to an external file containing a template for the view
* * **viewProviders** - list of providers available to this component and its view children
*
* @usageNotes
* ### Example
*
* {@example core/ts/metadata/metadata.ts region='component'}
*
* @Annotation
*/ */
host?: {[key: string]: string}; (obj: Component): TypeDecorator;
/** /**
* See the `Component` decorator. * See the `Component` decorator.
*/ */
providers?: Provider[]; new (obj: Component): Component;
/**
* The name or names that can be used in the template to assign this directive to a variable.
* For multiple names, use a comma-separated string.
*
*/
exportAs?: string;
/**
* Configures the queries that will be injected into the directive.
*
* Content queries are set before the `ngAfterContentInit` callback is called.
* View queries are set before the `ngAfterViewInit` callback is called.
*
*/
queries?: {[key: string]: any};
} }
/** /**
* Type of the Component metadata. * Type of the Component metadata.
*/ */
export const Directive: DirectiveDecorator = makeDecorator( export interface Component extends Directive {
'Directive', (dir: Directive = {}) => dir, undefined, undefined,
(type: Type<any>, meta: Directive) => (R3_COMPILE_DIRECTIVE || (() => {}))(type, meta));
/**
* Component decorator interface
*
*/
export interface ComponentDecorator {
/** /**
* Decorator that marks a class as an Angular component and provides configuration * Defines the used change detection strategy.
* metadata that determines how the component should be processed,
* instantiated, and used at runtime.
* *
* Components are the most basic UI building block of an Angular app. * When a component is instantiated, Angular creates a change detector, which is responsible for
* An Angular app contains a tree of Angular components. * propagating the component's bindings.
* *
* Angular components are a subset of directives, always associated with a template. * The `changeDetection` property defines, whether the change detection will be checked every time
* Unlike other directives, only one component can be instantiated per an element in a template. * or only when the component tells it to do so.
* */
* A component must belong to an NgModule in order for it to be available changeDetection?: ChangeDetectionStrategy;
* to another component or application. To make it a member of an NgModule,
* list it in the `declarations` field of the `@NgModule` metadata. /**
* * Defines the set of injectable objects that are visible to its view DOM children.
* Note that, in addition to these options for configuring a directive,
* you can control a component's runtime behavior by implementing
* life-cycle hooks. For more information, see the
* [Lifecycle Hooks](guide/lifecycle-hooks) guide.
* *
* @usageNotes * @usageNotes
* ### Simple Example
* *
* ### Setting component inputs * Here is an example of a class that can be injected:
*
* The following example creates a component with two data-bound properties,
* specified by the `inputs` value.
*
* <code-example path="core/ts/metadata/directives.ts" region="component-input">
* </code-example>
*
*
* ### Setting component outputs
*
* The following example shows two event emitters that emit on an interval. One
* emits an output every second, while the other emits every five seconds.
*
* {@example core/ts/metadata/directives.ts region='component-output-interval'}
*
* ### Injecting a class with a view provider
*
* The following simple example injects a class into a component
* using the view provider specified in component metadata:
* *
* ``` * ```
* class Greeter { * class Greeter {
@ -550,141 +512,88 @@ export interface ComponentDecorator {
* } * }
* *
* ``` * ```
*
*
* @Annotation
*/
(obj: Component): TypeDecorator;
/**
* See the `@Component` decorator.
*/
new (obj: Component): Component;
}
/**
* Supplies configuration metadata for an Angular component.
*/
export interface Component extends Directive {
/**
* The change-detection strategy to use for this component.
*
* When a component is instantiated, Angular creates a change detector,
* which is responsible for propagating the component's bindings.
* The strategy is one of:
* - `ChangeDetectionStrategy#OnPush` sets the strategy to `CheckOnce` (on demand).
* - `ChangeDetectionStrategy#Default` sets the strategy to `CheckAlways`.
*/
changeDetection?: ChangeDetectionStrategy;
/**
* Defines the set of injectable objects that are visible to its view DOM children.
* See [example](#injecting-a-class-with-a-view-provider).
*
*/ */
viewProviders?: Provider[]; viewProviders?: Provider[];
/** /**
* The module ID of the module that contains the component. * The module id of the module that contains the component.
* The component must be able to resolve relative URLs for templates and styles. * Needed to be able to resolve relative urls for templates and styles.
* SystemJS exposes the `__moduleName` variable within each module. * In CommonJS, this can always be set to `module.id`, similarly SystemJS exposes `__moduleName`
* In CommonJS, this can be set to `module.id`. * variable within each module.
* *
* @usageNotes
* ### Simple Example
*
* ```
* @Directive({
* selector: 'someDir',
* moduleId: module.id
* })
* class SomeDir {
* }
*
* ```
*/ */
moduleId?: string; moduleId?: string;
/** /**
* The URL of a template file for an Angular component. If provided, * Specifies a template URL for an Angular component.
* do not supply an inline template using `template`.
* *
* Only one of `templateUrl` or `template` can be defined per View.
*/ */
templateUrl?: string; templateUrl?: string;
/** /**
* An inline template for an Angular component. If provided, * Specifies an inline template for an Angular component.
* do not supply a template file using `templateUrl`.
* *
* Only one of `templateUrl` or `template` can be defined per Component.
*/ */
template?: string; template?: string;
/** /**
* One or more URLs for files containing CSS stylesheets to use * Specifies stylesheet URLs for an Angular component.
* in this component.
*/ */
styleUrls?: string[]; styleUrls?: string[];
/** /**
* One or more inline CSS stylesheets to use * Specifies inline stylesheets for an Angular component.
* in this component.
*/ */
styles?: string[]; styles?: string[];
/** /**
* One or more animation `trigger()` calls, containing * Animations are defined on components via an animation-like DSL. This DSL approach to describing
* `state()` and `transition()` definitions. * animations allows for a flexibility that both benefits developers and the framework.
* See the [Animations guide](/guide/animations) and animations API documentation.
* *
*/ * Animations work by listening on state changes that occur on an element within
animations?: any[]; * the template. When a state change occurs, Angular can then take advantage and animate the
* arc in between. This works similar to how CSS transitions work, however, by having a
/** * programmatic DSL, animations are not limited to environments that are DOM-specific.
* An encapsulation policy for the template and CSS styles. One of: * (Angular can also perform optimizations behind the scenes to make animations more performant.)
* - `ViewEncapsulation.Native`: Use shadow roots. This works
* only if natively available on the platform.
* - `ViewEncapsulation.Emulated`: Use shimmed CSS that
* emulates the native behavior.
* - `ViewEncapsulation.None`: Use global CSS without any
* encapsulation.
* *
* If not supplied, the value is taken from `CompilerOptions`. The default compiler option is * For animations to be available for use, animation state changes are placed within
* `ViewEncapsulation.Emulated`. * {@link trigger animation triggers} which are housed inside of the `animations` annotation
* * metadata. Within a trigger both `state` and `transition` entries
* If the policy is set to `ViewEncapsulation.Emulated` and the component has no `styles` * can be placed.
* or `styleUrls` specified, the policy is automatically switched to `ViewEncapsulation.None`.
*/
encapsulation?: ViewEncapsulation;
/**
* Overrides the default encapsulation start and end delimiters (`{{` and `}}`)
*/
interpolation?: [string, string];
/**
* A set of components that should be compiled along with
* this component. For each component listed here,
* Angular creates a {@link ComponentFactory} and stores it in the
* {@link ComponentFactoryResolver}.
*/
entryComponents?: Array<Type<any>|any[]>;
/**
* True to preserve or false to remove potentially superfluous whitespace characters
* from the compiled template. Whitespace characters are those matching the `\s`
* character class in JavaScript regular expressions. Default is false, unless
* overridden in compiler options.
*/
preserveWhitespaces?: boolean;
}
/**
* Component decorator and metadata.
* *
* @usageNotes * @usageNotes
* * ### Example
* ### Using animations
*
* The following snippet shows an animation trigger in a component's
* metadata. The trigger is attached to an element in the component's
* template, using "@_trigger_name_", and a state expression that is evaluated
* at run time to determine whether the animation should start.
* *
* ```typescript * ```typescript
* @Component({ * @Component({
* selector: 'animation-cmp', * selector: 'animation-cmp',
* templateUrl: 'animation-cmp.html', * templateUrl: 'animation-cmp.html',
* animations: [ * animations: [
* // this here is our animation trigger that
* // will contain our state change animations.
* trigger('myTriggerName', [ * trigger('myTriggerName', [
* // the styles defined for the `on` and `off`
* // states declared below are persisted on the
* // element once the animation completes.
* state('on', style({ opacity: 1 }), * state('on', style({ opacity: 1 }),
* state('off', style({ opacity: 0 }), * state('off', style({ opacity: 0 }),
*
* // this here is our animation that kicks off when
* // this state change jump is true
* transition('on => off', [ * transition('on => off', [
* animate("1s") * animate("1s")
* ]) * ])
@ -693,34 +602,94 @@ export interface Component extends Directive {
* }) * })
* ``` * ```
* *
* As depicted in the code above, a group of related animation states are all contained within
* an animation `trigger` (the code example above called the trigger `myTriggerName`).
* When a trigger is created then it can be bound onto an element within the component's
* template via a property prefixed by an `@` symbol followed by trigger name and an expression
* that
* is used to determine the state value for that trigger.
*
* ```html * ```html
* <!-- animation-cmp.html --> * <!-- animation-cmp.html -->
* <div @myTriggerName="expression">...</div> * <div @myTriggerName="expression">...</div>
* ``` * ```
* *
* ### Preserving whitespace * For state changes to be executed, the `expression` value must change value from its existing
* value
* to something that we have set an animation to animate on (in the example above we are listening
* to a change of state between `on` and `off`). The `expression` value attached to the trigger
* must be something that can be evaluated with the template/component context.
* *
* Removing whitespace can greatly reduce AOT-generated code size, and speed up view creation. * ### DSL Animation Functions
* As of Angular 6, default for `preserveWhitespaces` is false (whitespace is removed). *
* To change the default setting for all components in your application, set * Please visit each of the animation DSL functions listed below to gain a better understanding
* of how and why they are used for crafting animations in Angular:
*
* - `trigger()`
* - `state()`
* - `transition()`
* - `group()`
* - `sequence()`
* - `style()`
* - `animate()`
* - `keyframes()`
*/
animations?: any[];
/**
* Specifies how the template and the styles should be encapsulated:
* - `ViewEncapsulation.Native` to use shadow roots - only works if natively available on the
* platform,
* - `ViewEncapsulation.Emulated` to use shimmed CSS that emulates the native behavior,
* - `ViewEncapsulation.None` to use global CSS without any encapsulation.
*
* When no `encapsulation` is defined for the component, the default value from the
* `CompilerOptions` is used. The default is `ViewEncapsulation.Emulated`. Provide a new
* `CompilerOptions` to override this value.
*
* If the encapsulation is set to `ViewEncapsulation.Emulated` and the component has no `styles`
* nor `styleUrls` the encapsulation will automatically be switched to `ViewEncapsulation.None`.
*/
encapsulation?: ViewEncapsulation;
/**
* Overrides the default encapsulation start and end delimiters (respectively `{{` and `}}`)
*/
interpolation?: [string, string];
/**
* Defines the components that should be compiled as well when
* this component is defined. For each components listed here,
* Angular will create a `ComponentFactory` and store it in the
* `ComponentFactoryResolver`.
*/
entryComponents?: Array<Type<any>|any[]>;
/**
* If `Component.preserveWhitespaces` is set to `false`
* potentially superfluous whitespace characters (ones matching the `\s` character class in
* JavaScript regular expressions) will be removed from a compiled template. This can greatly
* reduce AOT-generated code size as well as speed up view creation.
*
* Current implementation works according to the following rules:
* - all whitespaces at the beginning and the end of a template are removed (trimmed);
* - text nodes consisting of whitespaces only are removed (ex.:
* `<button>Action 1</button> <button>Action 2</button>` will be converted to
* `<button>Action 1</button><button>Action 2</button>` (no whitespaces between buttons);
* - series of whitespaces in text nodes are replaced with one space (ex.:
* `<span>\n some text\n</span>` will be converted to `<span> some text </span>`);
* - text nodes are left as-is inside HTML tags where whitespaces are significant (ex. `<pre>`,
* `<textarea>`).
*
* Described transformations may (potentially) influence DOM nodes layout. However, the impact
* should so be minimal. That's why starting from Angular 6, the
* `preserveWhitespaces` option is `false` by default (whitespace removal).
* If you want to change the default setting for all components in your application you can use
* the `preserveWhitespaces` option of the AOT compiler. * the `preserveWhitespaces` option of the AOT compiler.
* *
* Current implementation removes whitespace characters as follows: * Even with the default behavior of whitespace removal, there are ways of preserving whitespaces
* - Trims all whitespaces at the beginning and the end of a template. * in certain fragments of a template. You can either exclude entire DOM sub-tree by using the
* - Removes whitespace-only text nodes. For example, * `ngPreserveWhitespaces` attribute, ex.:
* `<button>Action 1</button> <button>Action 2</button>` becomes
* `<button>Action 1</button><button>Action 2</button>`.
* - Replaces a series of whitespace characters in text nodes with a single space.
* For example, `<span>\n some text\n</span>` becomes `<span> some text </span>`.
* - Does NOT alter text nodes inside HTML tags such as `<pre>` or `<textarea>`,
* where whitespace characters are significant.
*
* Note that these transformations can influence DOM nodes layout, although impact
* should be minimal.
*
* You can override the default behavior to preserve whitespace characters
* in certain fragments of a template. For example, you can exclude an entire
* DOM sub-tree by using the `ngPreserveWhitespaces` attribute:
* *
* ```html * ```html
* <div ngPreserveWhitespaces> * <div ngPreserveWhitespaces>
@ -729,27 +698,44 @@ export interface Component extends Directive {
* </div> * </div>
* ``` * ```
* *
* You can force a single space to be preserved in a text node by using `&ngsp;`, * Alternatively you can force a space to be preserved in a text node by using the `&ngsp;`
* which is replaced with a space character by Angular's template * pseudo-entity. `&ngsp;` will be replaced with a space character by Angular's template
* compiler: * compiler, ex.:
* *
* ```html * ```html
* <a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a> * <a>Spaces</a>&ngsp;<a>between</a>&ngsp;<a>links.</a>
* <!-->compiled to be equivalent to:</> * ```
*
* will be compiled to the equivalent of:
*
* ```html
* <a>Spaces</a> <a>between</a> <a>links.</a> * <a>Spaces</a> <a>between</a> <a>links.</a>
* ``` * ```
* *
* Note that sequences of `&ngsp;` are still collapsed to just one space character when * Please note that sequences of `&ngsp;` are still collapsed to just one space character when
* the `preserveWhitespaces` option is set to `false`. * the `preserveWhitespaces` option is set to `false`. Ex.:
* *
* ```html * ```html
* <a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a> * <a>before</a>&ngsp;&ngsp;&ngsp;<a>after</a>
* <!-->compiled to be equivalent to:</>
* <a>Spaces</a> <a>between</a> <a>links.</a>
* ``` * ```
* *
* To preserve sequences of whitespace characters, use the * would be equivalent to:
* `ngPreserveWhitespaces` attribute. *
* ```html
* <a>before</a> <a>after</a>
* ```
*
* The `&ngsp;` pseudo-entity is useful for forcing presence of
* one space (a text node having `&ngsp;` pseudo-entities will never be removed), but it is not
* meant to mark sequences of whitespace characters. The previously described
* `ngPreserveWhitespaces` attribute is more useful for preserving sequences of whitespace
* characters.
*/
preserveWhitespaces?: boolean;
}
/**
* Component decorator and metadata.
* *
* @Annotation * @Annotation
*/ */
@ -762,8 +748,11 @@ export const Component: ComponentDecorator = makeDecorator(
*/ */
export interface PipeDecorator { export interface PipeDecorator {
/** /**
* Declares a reusable pipe function, and supplies configuration metadata. * Declare reusable pipe function.
* *
* A "pure" pipe is only re-evaluated when either the input or any of the arguments change.
*
* When not specified, pipes default to being pure.
*/ */
(obj: Pipe): TypeDecorator; (obj: Pipe): TypeDecorator;
@ -778,26 +767,34 @@ export interface PipeDecorator {
*/ */
export interface Pipe { export interface Pipe {
/** /**
* The pipe name to use in template bindings. * Name of the pipe.
* *
* The pipe name is used in template bindings. For example if a pipe is named
* `myPipe` then it would be used in the template binding expression like
* so: `{{ exp | myPipe }}`.
*/ */
name: string; name: string;
/** /**
* When true, the pipe is pure, meaning that the * If Pipe is pure (its output depends only on its input.)
* `transform()` method is invoked only when its input arguments
* change. Pipes are pure by default.
* *
* If the pipe has internal state (that is, the result * Normally pipe's `transform` method is only invoked when the inputs to pipe`s
* depends on state other than its arguments), set `pure` to false. * `transform` method change. If the pipe has internal state (it's result are
* In this case, the pipe is invoked on each change-detection cycle, * dependent on state other than its arguments) than set `pure` to `false` so
* even if the arguments have not changed. * that the pipe is invoked on each change-detection even if the arguments to the
* pipe do not change.
*/ */
pure?: boolean; pure?: boolean;
} }
/** /**
* Pipe decorator and metadata.
* *
* Use the `@Pipe` annotation to declare that a given class is a pipe. A pipe
* class must also implement `PipeTransform` interface.
*
* To use the pipe include a reference to the pipe class in
* `NgModule.declarations`.
* *
* @Annotation * @Annotation
*/ */
@ -805,51 +802,23 @@ export const Pipe: PipeDecorator = makeDecorator('Pipe', (p: Pipe) => ({pure: tr
/** /**
* Type of the Input decorator / constructor function.
*
* *
*/ */
export interface InputDecorator { export interface InputDecorator {
/** /**
* Decorator that marks a class as pipe and supplies configuration metadata. * Declares a data-bound input property.
* *
* A pipe class must implement the `PipeTransform` interface. * Angular automatically updates data-bound properties during change detection.
* For example, if the name is "myPipe", use a template binding expression
* such as the following:
* *
* ``` * `Input` takes an optional parameter that specifies the name
* {{ exp | myPipe }} * used when instantiating a component in the template. When not provided,
* ``` * the name of the decorated property is used.
* *
* The result of the expression is passed to the pipe's `transform()` method. * ### Example
* *
* A pipe must belong to an NgModule in order for it to be available * The following example creates a component with two input properties.
* to a template. To make it a member of an NgModule,
* list it in the `declarations` field of the `@NgModule` metadata.
*
*/
(bindingPropertyName?: string): any;
new (bindingPropertyName?: string): any;
}
/**
* Type of metadata for an `Input` property.
*
*
*/
export interface Input {
/**
* Decorator that marks a class field as an input property and supplies configuration metadata.
* Declares a data-bound input property, which Angular automatically updates
* during change detection.
*
* @usageNotes
*
* You can supply an optional name to use in templates when the
* component is instantiated, that maps to the
* name of the bound property. By default, the original
* name of the bound property is used for input binding.
*
* The following example creates a component with two input properties,
* one of which is given a special binding name.
* *
* ```typescript * ```typescript
* @Component({ * @Component({
@ -860,13 +829,10 @@ export interface Input {
* ` * `
* }) * })
* class BankAccount { * class BankAccount {
* // This property is bound using its original name.
* @Input() bankName: string; * @Input() bankName: string;
* // this property value is bound to a different property name
* // when this component is instantiated in a template.
* @Input('account-id') id: string; * @Input('account-id') id: string;
* *
* // this property is not bound, and is not automatically updated by Angular * // this property is not bound, and won't be automatically updated by Angular
* normalizedBankName: string; * normalizedBankName: string;
* } * }
* *
@ -880,10 +846,22 @@ export interface Input {
* class App {} * class App {}
* ``` * ```
*/ */
(bindingPropertyName?: string): any;
new (bindingPropertyName?: string): any;
}
/**
* Type of the Input metadata.
*/
export interface Input {
/**
* Name used when instantiating a component in the template.
*/
bindingPropertyName?: string; bindingPropertyName?: string;
} }
/** /**
* Input decorator and metadata.
* *
* @Annotation * @Annotation
*/ */
@ -895,18 +873,44 @@ export const Input: InputDecorator =
*/ */
export interface OutputDecorator { export interface OutputDecorator {
/** /**
* Decorator that marks a class field as an output property and supplies configuration metadata. * Declares an event-bound output property.
* Declares a data-bound output property, which Angular automatically updates *
* during change detection. * When an output property emits an event, an event handler attached to that event
* the template is invoked.
*
* `Output` takes an optional parameter that specifies the name
* used when instantiating a component in the template. When not provided,
* the name of the decorated property is used.
* *
* @usageNotes * @usageNotes
* ### Example
* *
* You can supply an optional name to use in templates when the * ```typescript
* component is instantiated, that maps to the * @Directive({
* name of the bound property. By default, the original * selector: 'interval-dir',
* name of the bound property is used for output binding. * })
* class IntervalDir {
* @Output() everySecond = new EventEmitter();
* @Output('everyFiveSeconds') five5Secs = new EventEmitter();
* *
* See `@Input` decorator for an example of providing a binding name. * constructor() {
* setInterval(() => this.everySecond.emit("event"), 1000);
* setInterval(() => this.five5Secs.emit("event"), 5000);
* }
* }
*
* @Component({
* selector: 'app',
* template: `
* <interval-dir (everySecond)="everySecond()" (everyFiveSeconds)="everyFiveSeconds()">
* </interval-dir>
* `
* })
* class App {
* everySecond() { console.log('second'); }
* everyFiveSeconds() { console.log('five seconds'); }
* }
* ```
* *
*/ */
(bindingPropertyName?: string): any; (bindingPropertyName?: string): any;
@ -919,6 +923,7 @@ export interface OutputDecorator {
export interface Output { bindingPropertyName?: string; } export interface Output { bindingPropertyName?: string; }
/** /**
* Output decorator and metadata.
* *
* @Annotation * @Annotation
*/ */
@ -931,20 +936,25 @@ export const Output: OutputDecorator =
*/ */
export interface HostBindingDecorator { export interface HostBindingDecorator {
/** /**
* Decorator that marks a DOM property as a host-binding property and supplies configuration * Declares a host property binding.
* metadata. *
* Angular automatically checks host property bindings during change detection, and * Angular automatically checks host property bindings during change detection.
* if a binding changes it updates the host element of the directive. * If a binding changes, it will update the host element of the directive.
*
* `HostBinding` takes an optional parameter that specifies the property
* name of the host element that will be updated. When not provided,
* the class property name is used.
* *
* @usageNotes * @usageNotes
* ### Example
* *
* The following example creates a directive that sets the `valid` and `invalid` * The following example creates a directive that sets the `valid` and `invalid` classes
* properties on the DOM element that has an `ngModel` directive on it. * on the DOM element that has ngModel directive on it.
* *
* ```typescript * ```typescript
* @Directive({selector: '[ngModel]'}) * @Directive({selector: '[ngModel]'})
* class NgModelStatus { * class NgModelStatus {
* constructor(public control: NgModel) {} * constructor(public control:NgModel) {}
* @HostBinding('class.valid') get valid() { return this.control.valid; } * @HostBinding('class.valid') get valid() { return this.control.valid; }
* @HostBinding('class.invalid') get invalid() { return this.control.invalid; } * @HostBinding('class.invalid') get invalid() { return this.control.invalid; }
* } * }
@ -964,11 +974,11 @@ export interface HostBindingDecorator {
/** /**
* Type of the HostBinding metadata. * Type of the HostBinding metadata.
*
*/ */
export interface HostBinding { hostPropertyName?: string; } export interface HostBinding { hostPropertyName?: string; }
/** /**
* HostBinding decorator and metadata.
* *
* @Annotation * @Annotation
*/ */
@ -980,36 +990,20 @@ export const HostBinding: HostBindingDecorator =
* Type of the HostListener decorator / constructor function. * Type of the HostListener decorator / constructor function.
*/ */
export interface HostListenerDecorator { export interface HostListenerDecorator {
(eventName: string, args?: string[]): any;
new (eventName: string, args?: string[]): any;
}
/**
* Type of the HostListener metadata.
*/
export interface HostListener {
/** /**
* The CSS event to listen for. * Declares a host listener.
*/ *
eventName?: string; * Angular will invoke the decorated method when the host element emits the specified event.
/** *
* A set of arguments to pass to the handler method when the event occurs. * If the decorated method returns `false`, then `preventDefault` is applied on the DOM event.
*/
args?: string[];
}
/**
* Binds a CSS event to a host listener and supplies configuration metadata.
* Angular invokes the supplied handler method when the host element emits the specified event,
* and updates the bound element with the result.
* If the handler method returns false, applies `preventDefault` on the bound element.
* *
* @usageNotes * @usageNotes
* ### Example
* *
* The following example declares a directive * The following example declares a directive that attaches a click listener to the button and
* that attaches a click listener to a button and counts clicks. * counts clicks.
* *
* ``` * ```typescript
* @Directive({selector: 'button[counting]'}) * @Directive({selector: 'button[counting]'})
* class CountClicks { * class CountClicks {
* numberOfClicks = 0; * numberOfClicks = 0;
@ -1029,5 +1023,22 @@ export interface HostListener {
* *
* @Annotation * @Annotation
*/ */
(eventName: string, args?: string[]): any;
new (eventName: string, args?: string[]): any;
}
/**
* Type of the HostListener metadata.
*/
export interface HostListener {
eventName?: string;
args?: string[];
}
/**
* HostListener decorator and metadata.
*
* @Annotation
*/
export const HostListener: HostListenerDecorator = export const HostListener: HostListenerDecorator =
makePropDecorator('HostListener', (eventName?: string, args?: string[]) => ({eventName, args})); makePropDecorator('HostListener', (eventName?: string, args?: string[]) => ({eventName, args}));

91
packages/core/src/metadata/ng_module.ts
View File

@ -14,7 +14,7 @@ import {TypeDecorator, makeDecorator} from '../util/decorators';
/** /**
* A wrapper around an NgModule that associates it with the providers. * A wrapper around a module that also includes the providers.
* *
* *
*/ */
@ -24,21 +24,17 @@ export interface ModuleWithProviders {
} }
/** /**
* A schema definition associated with an NgModule. * Interface for schema definitions in @NgModules.
*
* @see `@NgModule`, `CUSTOM_ELEMENTS_SCHEMA`, `NO_ERRORS_SCHEMA`
*
* @param name The name of a defined schema.
* *
* @experimental * @experimental
*/ */
export interface SchemaMetadata { name: string; } export interface SchemaMetadata { name: string; }
/** /**
* Defines a schema that allows an NgModule to contain the following: * Defines a schema that will allow:
* - Non-Angular elements named with dash case (`-`). * - any non-Angular elements with a `-` in their name,
* - Element properties named with dash case (`-`). * - any properties on elements with a `-` in their name which is the common rule for custom
* Dash case is the naming convention for custom elements. * elements.
* *
* *
*/ */
@ -47,7 +43,7 @@ export const CUSTOM_ELEMENTS_SCHEMA: SchemaMetadata = {
}; };
/** /**
* Defines a schema that allows any property on any element. * Defines a schema that will allow any property on any element.
* *
* @experimental * @experimental
*/ */
@ -63,7 +59,7 @@ export const NO_ERRORS_SCHEMA: SchemaMetadata = {
*/ */
export interface NgModuleDecorator { export interface NgModuleDecorator {
/** /**
* Marks a class as an NgModule and supplies configuration metadata. * Defines an NgModule.
*/ */
(obj?: NgModule): TypeDecorator; (obj?: NgModule): TypeDecorator;
new (obj?: NgModule): NgModule; new (obj?: NgModule): NgModule;
@ -76,13 +72,12 @@ export interface NgModuleDecorator {
*/ */
export interface NgModule { export interface NgModule {
/** /**
* The set of injectable objects that are available in the injector * Defines the set of injectable objects that are available in the injector
* of this module. * of this module.
* *
* @usageNotes * ## Simple Example
* *
* The following example defines a class that is injected in * Here is an example of a class that can be injected:
* the HelloWorld NgModule:
* *
* ``` * ```
* class Greeter { * class Greeter {
@ -108,12 +103,9 @@ export interface NgModule {
providers?: Provider[]; providers?: Provider[];
/** /**
* The set of directives and pipes that belong to this module. * Specifies a list of directives/pipes that belong to this module.
* *
* @usageNotes * ### Example
*
* The following example allows the CommonModule to use the `NgFor`
* directive.
* *
* ```javascript * ```javascript
* @NgModule({ * @NgModule({
@ -126,13 +118,11 @@ export interface NgModule {
declarations?: Array<Type<any>|any[]>; declarations?: Array<Type<any>|any[]>;
/** /**
* The set of NgModules, with or without providers, * Specifies a list of modules whose exported directives/pipes
* whose exported directives/pipes * should be available to templates in this module.
* are available to templates in this module. * This can also contain {@link ModuleWithProviders}.
* *
* @usageNotes * ### Example
*
* The following example allows MainModule to use CommonModule:
* *
* ```javascript * ```javascript
* @NgModule({ * @NgModule({
@ -141,18 +131,15 @@ export interface NgModule {
* class MainModule { * class MainModule {
* } * }
* ``` * ```
* @see {@link ModuleWithProviders}
*/ */
imports?: Array<Type<any>|ModuleWithProviders|any[]>; imports?: Array<Type<any>|ModuleWithProviders|any[]>;
/** /**
* The set of directives, pipe, and NgModules that can be used * Specifies a list of directives/pipes/modules that can be used within the template
* within the template of any component that is part of an * of any component that is part of an Angular module
* NgModule that imports this NgModule. * that imports this Angular module.
* *
* @usageNotes * ### Example
*
* The following example exports the `NgFor` directive from CommonModule.
* *
* ```javascript * ```javascript
* @NgModule({ * @NgModule({
@ -165,40 +152,45 @@ export interface NgModule {
exports?: Array<Type<any>|any[]>; exports?: Array<Type<any>|any[]>;
/** /**
* The set of components to compile when this NgModule is defined. * Specifies a list of components that should be compiled when this module is defined.
* For each component listed here, Angular creates a `ComponentFactory` * For each component listed here, Angular will create a {@link ComponentFactory}
* and stores it in the `ComponentFactoryResolver`. * and store it in the {@link ComponentFactoryResolver}.
*/ */
entryComponents?: Array<Type<any>|any[]>; entryComponents?: Array<Type<any>|any[]>;
/** /**
* The set of components that are bootstrapped when * Defines the components that should be bootstrapped when
* this module is bootstrapped. The components listed here * this module is bootstrapped. The components listed here
* are automatically added to `entryComponents`. * will automatically be added to `entryComponents`.
*/ */
bootstrap?: Array<Type<any>|any[]>; bootstrap?: Array<Type<any>|any[]>;
/** /**
* The set of schemas that declare elements to be allowed in the NgModule. * Elements and properties that are not Angular components nor directives have to be declared in
* Elements and properties that are neither Angular components nor directives * the schema.
* must be declared in a schema.
* *
* Allowed value are `NO_ERRORS_SCHEMA` and `CUSTOM_ELEMENTS_SCHEMA`. * Available schemas:
* - `NO_ERRORS_SCHEMA`: any elements and properties are allowed,
* - `CUSTOM_ELEMENTS_SCHEMA`: any custom elements (tag name has "-") with any properties are
* allowed.
* *
* @security When using one of `NO_ERRORS_SCHEMA` or `CUSTOM_ELEMENTS_SCHEMA` * @security When using one of `NO_ERRORS_SCHEMA` or `CUSTOM_ELEMENTS_SCHEMA` we're trusting that
* you must ensure that allowed elements and properties securely escape inputs. * allowed elements (and its properties) securely escape inputs.
*/ */
schemas?: Array<SchemaMetadata|any[]>; schemas?: Array<SchemaMetadata|any[]>;
/** /**
* A name or path that uniquely identifies this NgModule in `getModuleFactory`. * An opaque ID for this module, e.g. a name or a path. Used to identify modules in
* If left `undefined`, the NgModule is not registered with * `getModuleFactory`. If left `undefined`, the `NgModule` will not be registered with
* `getModuleFactory`. * `getModuleFactory`.
*/ */
id?: string; id?: string;
} }
/** /**
* NgModule decorator and metadata.
*
*
* @Annotation * @Annotation
*/ */
export const NgModule: NgModuleDecorator = makeDecorator( export const NgModule: NgModuleDecorator = makeDecorator(
@ -215,8 +207,3 @@ export const NgModule: NgModuleDecorator = makeDecorator(
imports: imports, imports: imports,
}); });
}); });
/**
* Decorator that marks the following class as an NgModule, and supplies
* configuration metadata for it.
*/
(type: Type<any>, meta: NgModule) => (R3_COMPILE_NGMODULE || preR3NgModuleCompile)(type, meta));

66
packages/examples/core/ts/metadata/directives.ts
View File

@ -1,66 +0,0 @@
/**
* @license
* Copyright Google Inc. All Rights Reserved.
*
* Use of this source code is governed by an MIT-style license that can be
* found in the LICENSE file at https://angular.io/license
*/
/* tslint:disable:no-console */
import {Component, Directive, EventEmitter} from '@angular/core';
// #docregion component-input
@Component({
selector: 'app-bank-account',
inputs: ['bankName', 'id: account-id'],
template: `
Bank Name: {{ bankName }}
Account Id: {{ id }}
`
})
export class BankAccountComponent {
bankName: string;
id: string;
// this property is not bound, and won't be automatically updated by Angular
normalizedBankName: string;
}
@Component({
selector: 'app-my-input',
template: `
<app-bank-account
bankName="RBC"
account-id="4747">
</app-bank-account>
`
})
export class MyInputComponent {
}
// #enddocregion component-input
// #docregion component-output-interval
@Directive({selector: 'app-interval-dir', outputs: ['everySecond', 'fiveSecs: everyFiveSeconds']})
export class IntervalDirComponent {
everySecond = new EventEmitter<string>();
fiveSecs = new EventEmitter<string>();
constructor() {
setInterval(() => this.everySecond.emit('event'), 1000);
setInterval(() => this.fiveSecs.emit('event'), 5000);
}
}
@Component({
selector: 'app-my-output',
template: `
<app-interval-dir
(everySecond)="onEverySecond()"
(everyFiveSeconds)="onEveryFiveSeconds()">
</app-interval-dir>
`
})
export class MyOutputComponent {
onEverySecond() { console.log('second'); }
onEveryFiveSeconds() { console.log('five seconds'); }
}
// #enddocregion component-output-interval