docs(router): improve docs for Instruction and related classes

Closes #4303
This commit is contained in:
Brian Ford 2015-09-21 19:06:53 -07:00
parent 3d6e3c2551
commit ec68074e69
1 changed files with 80 additions and 4 deletions

View File

@ -11,6 +11,37 @@ import {Promise} from 'angular2/src/core/facade/async';
import {PathRecognizer} from './path_recognizer'; import {PathRecognizer} from './path_recognizer';
import {Url} from './url_parser'; import {Url} from './url_parser';
/**
* `RouteParams` is an immutable map of parameters for the given route
* based on the url matcher and optional parameters for that route.
*
* You can inject `RouteParams` into the constructor of a component to use it.
*
* ## Example
*
* ```
* import {bootstrap, Component, View} from 'angular2/angular2';
* import {Router, ROUTER_DIRECTIVES, routerBindings, RouteConfig} from 'angular2/router';
*
* @Component({...})
* @View({directives: [ROUTER_DIRECTIVES]})
* @RouteConfig([
* {path: '/user/:id', component: UserCmp, as: 'UserCmp'},
* ])
* class AppCmp {}
*
* @Component({...})
* @View({ template: 'user: {{id}}' })
* class UserCmp {
* string: id;
* constructor(params: RouteParams) {
* this.id = params.get('id');
* }
* }
*
* bootstrap(AppCmp, routerBindings(AppCmp));
* ```
*/
export class RouteParams { export class RouteParams {
constructor(public params: StringMap<string, string>) {} constructor(public params: StringMap<string, string>) {}
@ -18,15 +49,41 @@ export class RouteParams {
} }
/** /**
* `Instruction` is a tree of `ComponentInstructions`, with all the information needed * `Instruction` is a tree of {@link ComponentInstruction}s with all the information needed
* to transition each component in the app to a given route, including all auxiliary routes. * to transition each component in the app to a given route, including all auxiliary routes.
* *
* This is a public API. * `Instruction`s can be created using {@link Router#generate}, and can be used to
* perform route changes with {@link Router#navigateByInstruction}.
*
* ## Example
*
* ```
* import {bootstrap, Component, View} from 'angular2/angular2';
* import {Router, ROUTER_DIRECTIVES, routerBindings, RouteConfig} from 'angular2/router';
*
* @Component({...})
* @View({directives: [ROUTER_DIRECTIVES]})
* @RouteConfig([
* {...},
* ])
* class AppCmp {
* constructor(router: Router) {
* var instruction = router.generate(['/MyRoute']);
* router.navigateByInstruction(instruction);
* }
* }
*
* bootstrap(AppCmp, routerBindings(AppCmp));
* ```
*/ */
export class Instruction { export class Instruction {
constructor(public component: ComponentInstruction, public child: Instruction, constructor(public component: ComponentInstruction, public child: Instruction,
public auxInstruction: StringMap<string, Instruction>) {} public auxInstruction: StringMap<string, Instruction>) {}
/**
* Returns a new instruction that shares the state of the existing instruction, but with
* the given child {@link Instruction} replacing the existing child.
*/
replaceChild(child: Instruction): Instruction { replaceChild(child: Instruction): Instruction {
return new Instruction(this.component, child, this.auxInstruction); return new Instruction(this.component, child, this.auxInstruction);
} }
@ -85,8 +142,7 @@ function stringifyAux(instruction: Instruction): string {
* *
* `ComponentInstruction`s are [https://en.wikipedia.org/wiki/Hash_consing](hash consed). You should * `ComponentInstruction`s are [https://en.wikipedia.org/wiki/Hash_consing](hash consed). You should
* never construct one yourself with "new." Instead, rely on {@link Router/PathRecognizer} to * never construct one yourself with "new." Instead, rely on {@link Router/PathRecognizer} to
* construct * construct `ComponentInstruction`s.
* `ComponentInstruction`s.
* *
* You should not modify this object. It should be treated as immutable. * You should not modify this object. It should be treated as immutable.
*/ */
@ -99,13 +155,33 @@ export class ComponentInstruction {
constructor(public urlPath: string, public urlParams: string[], constructor(public urlPath: string, public urlParams: string[],
private _recognizer: PathRecognizer, public params: StringMap<string, any> = null) {} private _recognizer: PathRecognizer, public params: StringMap<string, any> = null) {}
/**
* Returns the component type of the represented route, or `null` if this instruction
* hasn't been resolved.
*/
get componentType() { return this._recognizer.handler.componentType; } get componentType() { return this._recognizer.handler.componentType; }
/**
* Returns a promise that will resolve to component type of the represented route.
* If this instruction references an {@link AsyncRoute}, the `loader` function of that route
* will run.
*/
resolveComponentType(): Promise<Type> { return this._recognizer.handler.resolveComponentType(); } resolveComponentType(): Promise<Type> { return this._recognizer.handler.resolveComponentType(); }
/**
* Returns the specificity of the route associated with this `Instruction`.
*/
get specificity() { return this._recognizer.specificity; } get specificity() { return this._recognizer.specificity; }
/**
* Returns `true` if the component type of this instruction has no child {@link RouteConfig},
* or `false` if it does.
*/
get terminal() { return this._recognizer.terminal; } get terminal() { return this._recognizer.terminal; }
/**
* Returns the route data of the given route that was specified in the {@link RouteDefinition},
* or `null` if no route data was specified.
*/
routeData(): Object { return this._recognizer.handler.data; } routeData(): Object { return this._recognizer.handler.data; }
} }