UNPKG

ng-metadata-baden-fix1

Version:

Angular 2 decorators and utils for Angular 1.x

986 lines 31.2 kB
"use strict"; var __extends = (this && this.__extends) || function (d, b) { for (var p in b) if (b.hasOwnProperty(p)) d[p] = b[p]; function __() { this.constructor = d; } d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __()); }; var metadata_1 = require("../di/metadata"); /** * Directives allow you to attach behavior to elements in the DOM. * * {@link DirectiveMetadata}s with an embedded view are called {@link ComponentMetadata}s. * * A directive consists of a single directive annotation and a controller class. When the * directive's `selector` matches * elements in the DOM, the following steps occur: * * 1. For each directive, the `ElementInjector` attempts to resolve the directive's constructor * arguments. * 2. Angular instantiates directives for each matched element using `ElementInjector` in a * depth-first order, * as declared in the HTML. * * ## Understanding How Injection Works * * There are three stages of injection resolution. * - *Pre-existing Injectors*: * - The terminal {@link Injector} cannot resolve dependencies. It either throws an error or, if * the dependency was * specified as `@Optional`, returns `null`. * - The platform injector resolves browser singleton resources, such as: cookies, title, * location, and others. * - *Component Injectors*: Each component instance has its own {@link Injector}, and they follow * the same parent-child hierarchy * as the component instances in the DOM. * - *Element Injectors*: Each component instance has a Shadow DOM. Within the Shadow DOM each * element has an `ElementInjector` * which follow the same parent-child hierarchy as the DOM elements themselves. * * When a template is instantiated, it also must instantiate the corresponding directives in a * depth-first order. The * current `ElementInjector` resolves the constructor dependencies for each directive. * * Angular then resolves dependencies as follows, according to the order in which they appear in the * {@link ViewMetadata}: * * 1. Dependencies on the current element * 2. Dependencies on element injectors and their parents until it encounters a Shadow DOM boundary * 3. Dependencies on component injectors and their parents until it encounters the root component * 4. Dependencies on pre-existing injectors * * * The `ElementInjector` can inject other directives, element-specific special objects, or it can * delegate to the parent * injector. * * To inject other directives, declare the constructor parameter as: * - `directive:DirectiveType`: a directive on the current element only * - `@Host() directive:DirectiveType`: any directive that matches the type between the current * element and the * Shadow DOM root. * - `@Query(DirectiveType) query:QueryList<DirectiveType>`: A live collection of direct child * directives. * - `@QueryDescendants(DirectiveType) query:QueryList<DirectiveType>`: A live collection of any * child directives. * * To inject element-specific special objects, declare the constructor parameter as: * - `element: ElementRef` to obtain a reference to logical element in the view. * - `viewContainer: ViewContainerRef` to control child template instantiation, for * {@link DirectiveMetadata} directives only * - `bindingPropagation: BindingPropagation` to control change detection in a more granular way. * * ### Example * * The following example demonstrates how dependency injection resolves constructor arguments in * practice. * * * Assume this HTML template: * * ``` * <div dependency="1"> * <div dependency="2"> * <div dependency="3" my-directive> * <div dependency="4"> * <div dependency="5"></div> * </div> * <div dependency="6"></div> * </div> * </div> * </div> * ``` * * With the following `dependency` decorator and `SomeService` injectable class. * * ``` * @Injectable() * class SomeService { * } * * @Directive({ * selector: '[dependency]', * inputs: [ * 'id: dependency' * ] * }) * class Dependency { * id:string; * } * ``` * * Let's step through the different ways in which `MyDirective` could be declared... * * * ### No injection * * Here the constructor is declared with no arguments, therefore nothing is injected into * `MyDirective`. * * ``` * @Directive({ selector: '[my-directive]' }) * class MyDirective { * constructor() { * } * } * ``` * * This directive would be instantiated with no dependencies. * * * ### Component-level injection * * Directives can inject any injectable instance from the closest component injector or any of its * parents. * * Here, the constructor declares a parameter, `someService`, and injects the `SomeService` type * from the parent * component's injector. * ``` * @Directive({ selector: '[my-directive]' }) * class MyDirective { * constructor(someService: SomeService) { * } * } * ``` * * This directive would be instantiated with a dependency on `SomeService`. * * * ### Injecting a directive from the current element * * Directives can inject other directives declared on the current element. * * ``` * @Directive({ selector: '[my-directive]' }) * class MyDirective { * constructor(dependency: Dependency) { * expect(dependency.id).toEqual(3); * } * } * ``` * This directive would be instantiated with `Dependency` declared at the same element, in this case * `dependency="3"`. * * ### Injecting a directive from any ancestor elements * * Directives can inject other directives declared on any ancestor element (in the current Shadow * DOM), i.e. on the current element, the * parent element, or its parents. * ``` * @Directive({ selector: '[my-directive]' }) * class MyDirective { * constructor(@Host() dependency: Dependency) { * expect(dependency.id).toEqual(2); * } * } * ``` * * `@Host` checks the current element, the parent, as well as its parents recursively. If * `dependency="2"` didn't * exist on the direct parent, this injection would * have returned * `dependency="1"`. * * * ### Injecting a live collection of direct child directives * * * A directive can also query for other child directives. Since parent directives are instantiated * before child directives, a directive can't simply inject the list of child directives. Instead, * the directive injects a {@link QueryList}, which updates its contents as children are added, * removed, or moved by a directive that uses a {@link ViewContainerRef} such as a `ngFor`, an * `ngIf`, or an `ngSwitch`. * * ``` * @Directive({ selector: '[my-directive]' }) * class MyDirective { * constructor(@Query(Dependency) dependencies:QueryList<Dependency>) { * } * } * ``` * * This directive would be instantiated with a {@link QueryList} which contains `Dependency` 4 and * `Dependency` 6. Here, `Dependency` 5 would not be included, because it is not a direct child. * * ### Injecting a live collection of descendant directives * * By passing the descendant flag to `@Query` above, we can include the children of the child * elements. * * ``` * @Directive({ selector: '[my-directive]' }) * class MyDirective { * constructor(@Query(Dependency, {descendants: true}) dependencies:QueryList<Dependency>) { * } * } * ``` * * This directive would be instantiated with a Query which would contain `Dependency` 4, 5 and 6. * * ### Optional injection * * The normal behavior of directives is to return an error when a specified dependency cannot be * resolved. If you * would like to inject `null` on unresolved dependency instead, you can annotate that dependency * with `@Optional()`. * This explicitly permits the author of a template to treat some of the surrounding directives as * optional. * * ``` * @Directive({ selector: '[my-directive]' }) * class MyDirective { * constructor(@Optional() dependency:Dependency) { * } * } * ``` * * This directive would be instantiated with a `Dependency` directive found on the current element. * If none can be * found, the injector supplies `null` instead of throwing an error. * * ### Example * * Here we use a decorator directive to simply define basic tool-tip behavior. * * ``` * @Directive({ * selector: '[tooltip]', * inputs: [ * 'text: tooltip' * ], * host: { * '(mouseenter)': 'onMouseEnter()', * '(mouseleave)': 'onMouseLeave()' * } * }) * class Tooltip{ * text:string; * overlay:Overlay; // NOT YET IMPLEMENTED * overlayManager:OverlayManager; // NOT YET IMPLEMENTED * * constructor(overlayManager:OverlayManager) { * this.overlay = overlay; * } * * onMouseEnter() { * // exact signature to be determined * this.overlay = this.overlayManager.open(text, ...); * } * * onMouseLeave() { * this.overlay.close(); * this.overlay = null; * } * } * ``` * In our HTML template, we can then add this behavior to a `<div>` or any other element with the * `tooltip` selector, * like so: * * ``` * <div tooltip="some text here"></div> * ``` * * Directives can also control the instantiation, destruction, and positioning of inline template * elements: * * A directive uses a {@link ViewContainerRef} to instantiate, insert, move, and destroy views at * runtime. * The {@link ViewContainerRef} is created as a result of `<template>` element, and represents a * location in the current view * where these actions are performed. * * Views are always created as children of the current {@link ViewMetadata}, and as siblings of the * `<template>` element. Thus a * directive in a child view cannot inject the directive that created it. * * Since directives that create views via ViewContainers are common in Angular, and using the full * `<template>` element syntax is wordy, Angular * also supports a shorthand notation: `<li *foo="bar">` and `<li template="foo: bar">` are * equivalent. * * Thus, * * ``` * <ul> * <li *foo="bar" title="text"></li> * </ul> * ``` * * Expands in use to: * * ``` * <ul> * <template [foo]="bar"> * <li title="text"></li> * </template> * </ul> * ``` * * Notice that although the shorthand places `*foo="bar"` within the `<li>` element, the binding for * the directive * controller is correctly instantiated on the `<template>` element rather than the `<li>` element. * * ## Lifecycle hooks * * When the directive class implements some {@link angular2/lifecycle_hooks} the callbacks are * called by the change detection at defined points in time during the life of the directive. * * ### Example * * Let's suppose we want to implement the `unless` behavior, to conditionally include a template. * * Here is a simple directive that triggers on an `unless` selector: * * ``` * @Directive({ * selector: '[unless]', * inputs: ['unless'] * }) * export class Unless { * viewContainer: ViewContainerRef; * templateRef: TemplateRef; * prevCondition: boolean; * * constructor(viewContainer: ViewContainerRef, templateRef: TemplateRef) { * this.viewContainer = viewContainer; * this.templateRef = templateRef; * this.prevCondition = null; * } * * set unless(newCondition) { * if (newCondition && (isBlank(this.prevCondition) || !this.prevCondition)) { * this.prevCondition = true; * this.viewContainer.clear(); * } else if (!newCondition && (isBlank(this.prevCondition) || this.prevCondition)) { * this.prevCondition = false; * this.viewContainer.create(this.templateRef); * } * } * } * ``` * * We can then use this `unless` selector in a template: * ``` * <ul> * <li *unless="expr"></li> * </ul> * ``` * * Once the directive instantiates the child view, the shorthand notation for the template expands * and the result is: * * ``` * <ul> * <template [unless]="exp"> * <li></li> * </template> * <li></li> * </ul> * ``` * * Note also that although the `<li></li>` template still exists inside the `<template></template>`, * the instantiated * view occurs on the second `<li></li>` which is a sibling to the `<template>` element. */ var DirectiveMetadata = (function (_super) { __extends(DirectiveMetadata, _super); function DirectiveMetadata(_a) { var _b = _a === void 0 ? {} : _a, selector = _b.selector, inputs = _b.inputs, attrs = _b.attrs, outputs = _b.outputs, host = _b.host, providers = _b.providers, exportAs = _b.exportAs, queries = _b.queries, legacy = _b.legacy; var _this = _super.call(this) || this; _this.selector = selector; _this._inputs = inputs; _this._attrs = attrs; _this._outputs = outputs; _this.host = host; _this.exportAs = exportAs; _this.queries = queries; _this._providers = providers; _this.legacy = legacy; return _this; } Object.defineProperty(DirectiveMetadata.prototype, "inputs", { /** * Enumerates the set of data-bound input properties for a directive * * Angular automatically updates input properties during change detection. * * The `inputs` property defines a set of `directiveProperty` to `bindingProperty` * configuration: * * - `directiveProperty` specifies the component property where the value is written. * - `bindingProperty` specifies the DOM property where the value is read from. * * When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`. * * ### Example ([live demo](http://plnkr.co/edit/ivhfXY?p=preview)) * * The following example creates a component with two data-bound properties. * * ```typescript * @Component({ * selector: 'bank-account', * inputs: ['bankName', 'id: account-id'], * template: ` * Bank Name: {{bankName}} * Account Id: {{id}} * ` * }) * class BankAccount { * bankName: string; * id: string; * * // this property is not bound, and won't be automatically updated by Angular * normalizedBankName: string; * } * * @Component({ * selector: 'app', * template: ` * <bank-account bank-name="RBC" account-id="4747"></bank-account> * `, * directives: [BankAccount] * }) * class App {} * * bootstrap(App); * ``` * */ get: function () { return this._inputs; }, enumerable: true, configurable: true }); Object.defineProperty(DirectiveMetadata.prototype, "attrs", { /** * Enumerates the set of attribute-bound input properties for a directive * * Angular automatically updates input properties during change detection. * * The `attrs` property defines a set of `directiveProperty` to `bindingProperty` * configuration: * * - `directiveProperty` specifies the component property where the value is written. * - `bindingProperty` specifies the DOM property where the value is read from. * * When `bindingProperty` is not provided, it is assumed to be equal to `directiveProperty`. * * #### Behind the scenes: * This is just Angular 1 `@` binding on `bindToController` object. * * So this `attrs: ['bankName', 'id: account-id']` * is equal to: `bindToController{bankName:'@',id:'@accountId'}` * * * The following example creates a component with two attribute-bound properties. * * ```typescript * @Component({ * selector: 'bank-account', * attrs: ['bankName', 'id: accountId'], * template: ` * Bank Name: {{ctrl.bankName}} * Account Id: {{ctrl.id}} * ` * }) * class BankAccount { * bankName: string; * id: string; * * // this property is not bound, and won't be automatically updated by Angular * normalizedBankName: string; * } * * @Component({ * selector: 'app', * template: ` * <bank-account bank-name="RBC" account-id="4747"></bank-account> * ` * }) * class App {} * * ``` * * Will output: * ```html * <bank-account bank-name="RBC" account-id="4747"> * Bank Name: RBC * Account Id: 4747 * </bank-account> * ``` * */ get: function () { return this._attrs; }, enumerable: true, configurable: true }); Object.defineProperty(DirectiveMetadata.prototype, "outputs", { /** * Enumerates the set of event-bound output properties. * * When an output property emits an event, an event handler attached to that event * the template is invoked. * * The `outputs` property defines a set of `directiveProperty` to `bindingProperty` * configuration: * * - `directiveProperty` specifies the component property that emits events. * - `bindingProperty` specifies the DOM property the event handler is attached to. * * ### Example ([live demo](http://plnkr.co/edit/d5CNq7?p=preview)) * * ```typescript * @Directive({ * selector: 'interval-dir', * outputs: ['everySecond', 'five5Secs: everyFiveSeconds'] * }) * class IntervalDir { * everySecond = new EventEmitter(); * five5Secs = new EventEmitter(); * * constructor() { * setInterval(() => this.everySecond.emit("event"), 1000); * setInterval(() => this.five5Secs.emit("event"), 5000); * } * } * * @Component({ * selector: 'app', * template: ` * <interval-dir (every-second)="everySecond()" (every-five-seconds)="everyFiveSeconds()"> * </interval-dir> * `, * directives: [IntervalDir] * }) * class App { * everySecond() { console.log('second'); } * everyFiveSeconds() { console.log('five seconds'); } * } * bootstrap(App); * ``` * */ get: function () { return this._outputs; }, enumerable: true, configurable: true }); Object.defineProperty(DirectiveMetadata.prototype, "providers", { /** * Defines the set of injectable objects that are visible to a Directive and its light DOM * children. * * ## Simple Example * * Here is an example of a class that can be injected: * * ``` * class Greeter { * greet(name:string) { * return 'Hello ' + name + '!'; * } * } * * @Directive({ * selector: 'greet', * bindings: [ * Greeter * ] * }) * class HelloWorld { * greeter:Greeter; * * constructor(greeter:Greeter) { * this.greeter = greeter; * } * } * ``` */ get: function () { return this._providers; }, enumerable: true, configurable: true }); return DirectiveMetadata; }(metadata_1.InjectableMetadata)); exports.DirectiveMetadata = DirectiveMetadata; /** * Declare reusable UI building blocks for an application. * * Each Angular component requires a single `@Component` annotation. The * `@Component` * annotation specifies when a component is instantiated, and which properties and hostListeners it * binds to. * * When a component is instantiated, Angular * - creates a shadow DOM for the component. * - loads the selected template into the shadow DOM. * - creates all the injectable objects configured with `providers` and `viewProviders`. * * All template expressions and statements are then evaluated against the component instance. * * ## Lifecycle hooks * * When the component class implements some {@link angular2/lifecycle_hooks} the callbacks are * called by the change detection at defined points in time during the life of the component. * * ### Example * * {@example core/ts/metadata/metadata.ts region='component'} */ var ComponentMetadata = (function (_super) { __extends(ComponentMetadata, _super); function ComponentMetadata(_a) { var _b = _a === void 0 ? {} : _a, selector = _b.selector, inputs = _b.inputs, attrs = _b.attrs, outputs = _b.outputs, host = _b.host, exportAs = _b.exportAs, moduleId = _b.moduleId, providers = _b.providers, viewProviders = _b.viewProviders, _c = _b.changeDetection, changeDetection = _c === void 0 ? 1 /* Default */ : _c, queries = _b.queries, templateUrl = _b.templateUrl, template = _b.template, styleUrls = _b.styleUrls, styles = _b.styles, legacy = _b.legacy; var _this = _super.call(this, { selector: selector, inputs: inputs, attrs: attrs, outputs: outputs, host: host, exportAs: exportAs, providers: providers, queries: queries, legacy: legacy }) || this; _this.changeDetection = changeDetection; _this._viewProviders = viewProviders; _this.templateUrl = templateUrl; _this.template = template; _this.styleUrls = styleUrls; _this.styles = styles; _this.moduleId = moduleId; return _this; } Object.defineProperty(ComponentMetadata.prototype, "viewProviders", { /** * Defines the set of injectable objects that are visible to its view DOM children. * * ## Simple Example * * Here is an example of a class that can be injected: * * ``` * class Greeter { * greet(name:string) { * return 'Hello ' + name + '!'; * } * } * * @Directive({ * selector: 'needs-greeter' * }) * class NeedsGreeter { * greeter:Greeter; * * constructor(greeter:Greeter) { * this.greeter = greeter; * } * } * * @Component({ * selector: 'greet', * viewProviders: [ * Greeter * ], * template: `<needs-greeter></needs-greeter>`, * directives: [NeedsGreeter] * }) * class HelloWorld { * } * * ``` */ get: function () { return this._viewProviders; }, enumerable: true, configurable: true }); return ComponentMetadata; }(DirectiveMetadata)); exports.ComponentMetadata = ComponentMetadata; /** * Declares a data-bound input property. * * Angular automatically updates data-bound properties during change detection. * * `InputMetadata` 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. * * ### Example * * The following example creates a component with two input properties. * * ```typescript * @Component({ * selector: 'bank-account', * template: ` * Bank Name: {{bankName}} * Account Id: {{id}} * ` * }) * class BankAccount { * @Input() bankName: string; * @Input('account-id') id: string; * * // this property is not bound, and won't be automatically updated by Angular * normalizedBankName: string; * } * * @Component({ * selector: 'app', * template: ` * <bank-account bank-name="RBC" account-id="4747"></bank-account> * `, * directives: [BankAccount] * }) * class App {} * * bootstrap(App); * ``` */ var InputMetadata = (function () { /** * * @param {string?} bindingPropertyName Name used when instantiating a component in the template. */ function InputMetadata(bindingPropertyName) { this.bindingPropertyName = bindingPropertyName; } return InputMetadata; }()); exports.InputMetadata = InputMetadata; /** * Declares a data-bound attribute property. * * Angular automatically updates data-bound properties during change detection. * * `AttrMetadata` 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. * * * #### Behind the scenes: * This is just Angular 1 `@` binding on `bindToController` object. * * So this `attrs: ['bankName', 'id: account-id']` * is equal to: `bindToController{bankName:'@',id:'@accountId'}` * * ### Example * * The following example creates a component with two attribute-bound properties. * * ```typescript * @Component({ * selector: 'bank-account', * template: ` * Bank Name: {{ctrl.bankName}} * Account Id: {{ctrl.id}} * ` * }) * class BankAccount { * @Attr() bankName: string; * @Attr('accountId') id: string; * * // this property is not bound, and won't be automatically updated by Angular * normalizedBankName: string; * } * * @Component({ * selector: 'app', * template: ` * <bank-account bank-name="RBC" account-id="4747"></bank-account> * ` * }) * class App {} * ``` * * Will output: * ```html * <bank-account bank-name="RBC" account-id="4747"> * Bank Name: RBC * Account Id: 4747 * </bank-account> * ``` * */ var AttrMetadata = (function () { /** * * @param {string?} bindingPropertyName Name used when instantiating a component in the template. */ function AttrMetadata(bindingPropertyName) { this.bindingPropertyName = bindingPropertyName; } return AttrMetadata; }()); exports.AttrMetadata = AttrMetadata; /** * Declares an event-bound output property. * * When an output property emits an event, an event handler attached to that event * the template is invoked. * * `OutputMetadata` 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. * * ### Example * * ```typescript * @Directive({ * selector: 'interval-dir', * }) * class IntervalDir { * @Output() everySecond = new EventEmitter(); * @Output('everyFiveSeconds') five5Secs = new EventEmitter(); * * constructor() { * setInterval(() => this.everySecond.emit("event"), 1000); * setInterval(() => this.five5Secs.emit("event"), 5000); * } * } * * @Component({ * selector: 'app', * template: ` * <interval-dir (every-second)="everySecond()" (every-five-seconds)="everyFiveSeconds()"> * </interval-dir> * `, * directives: [IntervalDir] * }) * class App { * everySecond() { console.log('second'); } * everyFiveSeconds() { console.log('five seconds'); } * } * bootstrap(App); * ``` */ var OutputMetadata = (function () { /** * * @param {string?} bindingPropertyName Name used when instantiating a component in the template. */ function OutputMetadata(bindingPropertyName) { this.bindingPropertyName = bindingPropertyName; } return OutputMetadata; }()); exports.OutputMetadata = OutputMetadata; /** * Declares a host property binding. * * Angular automatically checks host property bindings during change detection. * If a binding changes, it will update the host element of the directive. * * `HostBindingMetadata` 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. * * ### Example * * The following example creates a directive that sets the `valid` and `invalid` classes * on the DOM element that has ngModel directive on it. * * ```typescript * @Directive({selector: '[ngModel]'}) * class NgModelStatus { * constructor(public control:NgModel) {} * @HostBinding('[class.valid]') get valid { return this.control.valid; } * @HostBinding('[class.invalid]') get invalid { return this.control.invalid; } * } * * @Component({ * selector: 'app', * template: `<input [(ngModel)]="prop">`, * directives: [FORM_DIRECTIVES, NgModelStatus] * }) * class App { * prop; * } * * bootstrap(App); * ``` */ var HostBindingMetadata = (function () { function HostBindingMetadata(hostPropertyName) { this.hostPropertyName = hostPropertyName; } return HostBindingMetadata; }()); exports.HostBindingMetadata = HostBindingMetadata; /** * Declares a host listener. * * Angular will invoke the decorated method when the host element emits the specified event. * * If the decorated method returns `false`, then `preventDefault` is applied on the DOM * event. * * ### Example * * The following example declares a directive that attaches a click listener to the button and * counts clicks. * * ```typescript * @Directive({selector: 'button[counting]'}) * class CountClicks { * numberOfClicks = 0; * * @HostListener('click', ['$event.target']) * onClick(btn) { * console.log("button", btn, "number of clicks:", this.numberOfClicks++); * } * } * * @Component({ * selector: 'app', * template: `<button counting>Increment</button>`, * directives: [CountClicks] * }) * class App {} * * bootstrap(App); * ``` */ var HostListenerMetadata = (function () { function HostListenerMetadata(eventName, args) { this.eventName = eventName; this.args = args; } return HostListenerMetadata; }()); exports.HostListenerMetadata = HostListenerMetadata; /** * Declares an Angular Module. */ var NgModuleMetadata = (function (_super) { __extends(NgModuleMetadata, _super); function NgModuleMetadata(options) { if (options === void 0) { options = {}; } var _this = // We cannot use destructuring of the constructor argument because `exports` is a // protected symbol in CommonJS and closure tries to aggressively optimize it away. _super.call(this) || this; _this._providers = options.providers; _this.declarations = options.declarations; _this.imports = options.imports; return _this; } Object.defineProperty(NgModuleMetadata.prototype, "providers", { get: function () { return this._providers; }, enumerable: true, configurable: true }); return NgModuleMetadata; }(metadata_1.InjectableMetadata)); exports.NgModuleMetadata = NgModuleMetadata; //# sourceMappingURL=metadata_directives.js.map