From 8a2370750a7966b7bbdaf3a4ecc7c14cf212debb Mon Sep 17 00:00:00 2001 From: Brian Ford Date: Mon, 21 Sep 2015 17:17:25 -0700 Subject: [PATCH] docs(router): improve documentation for router bindings --- modules/angular2/router.ts | 116 ++++++++++++++++++++++++++++++++----- 1 file changed, 103 insertions(+), 13 deletions(-) diff --git a/modules/angular2/router.ts b/modules/angular2/router.ts index 21c7fcc882..641794b2da 100644 --- a/modules/angular2/router.ts +++ b/modules/angular2/router.ts @@ -31,33 +31,101 @@ import {Location} from './src/router/location'; import {bind, OpaqueToken, Binding} from './core'; import {CONST_EXPR, Type} from './src/core/facade/lang'; -export const ROUTER_PRIMARY_COMPONENT: OpaqueToken = - CONST_EXPR(new OpaqueToken('RouterPrimaryComponent')); - -export const ROUTER_DIRECTIVES: any[] = CONST_EXPR([RouterOutlet, RouterLink]); - /** - * A list of {@link Binding}. To use the router, you must add this to your application. + * Token used to bind the component with the top-level {@link RouteConfig}s for the + * application. * - * ## Example + * You can use the {@link routerBindings} function in your {@link bootstrap} bindings to + * simplify setting up these bindings. + * + * ## Example ([live demo](http://plnkr.co/edit/iRUP8B5OUbxCWQ3AcIDm)) + * + * ``` + * import {Component, View} from 'angular2/angular2'; + * import { + * ROUTER_DIRECTIVES, + * ROUTER_BINDINGS, + * ROUTER_PRIMARY_COMPONENT, + * RouteConfig + * } from 'angular2/router'; * - * ```typescript * @Component({...}) * @View({directives: [ROUTER_DIRECTIVES]}) * @RouteConfig([ - * new Route(...), + * {...}, * ]) * class AppCmp { - * constructor(router: Router, location: Location) { - * // ... - * } - * + * // ... * } * + * bootstrap(AppCmp, [ + * ROUTER_BINDINGS, + * bind(ROUTER_PRIMARY_COMPONENT).toValue(AppCmp) + * ]); + * ``` + */ +export const ROUTER_PRIMARY_COMPONENT: OpaqueToken = + CONST_EXPR(new OpaqueToken('RouterPrimaryComponent')); + +/** + * A list of directives. To use the router directives like {@link RouterOutlet} and + * {@link RouterLink}, add this to your `directives` array in the {@link View} decorator of your + * component. + * + * ## Example ([live demo](http://plnkr.co/edit/iRUP8B5OUbxCWQ3AcIDm)) + * + * ``` + * import {Component, View} from 'angular2/angular2'; + * import {ROUTER_DIRECTIVES, routerBindings, RouteConfig} from 'angular2/router'; + * + * @Component({...}) + * @View({directives: [ROUTER_DIRECTIVES]}) + * @RouteConfig([ + * {...}, + * ]) + * class AppCmp { + * // ... + * } * * bootstrap(AppCmp, [routerBindings(AppCmp)]); * ``` */ +export const ROUTER_DIRECTIVES: any[] = CONST_EXPR([RouterOutlet, RouterLink]); + +/** + * A list of {@link Binding}s. To use the router, you must add this to your application. + * + * Note that you also need to bind to {@link ROUTER_PRIMARY_COMPONENT}. + * + * You can use the {@link routerBindings} function in your {@link bootstrap} bindings to + * simplify setting up these bindings. + * + * ## Example ([live demo](http://plnkr.co/edit/iRUP8B5OUbxCWQ3AcIDm)) + * + * ``` + * import {Component, View} from 'angular2/angular2'; + * import { + * ROUTER_DIRECTIVES, + * ROUTER_BINDINGS, + * ROUTER_PRIMARY_COMPONENT, + * RouteConfig + * } from 'angular2/router'; + * + * @Component({...}) + * @View({directives: [ROUTER_DIRECTIVES]}) + * @RouteConfig([ + * {...}, + * ]) + * class AppCmp { + * // ... + * } + * + * bootstrap(AppCmp, [ + * ROUTER_BINDINGS, + * bind(ROUTER_PRIMARY_COMPONENT).toValue(AppCmp) + * ]); + * ``` + */ export const ROUTER_BINDINGS: any[] = CONST_EXPR([ RouteRegistry, CONST_EXPR(new Binding(LocationStrategy, {toClass: PathLocationStrategy})), @@ -74,6 +142,28 @@ function routerFactory(registry, location, primaryComponent) { return new RootRouter(registry, location, primaryComponent); } +/** + * A list of {@link Binding}s. To use the router, you must add these bindings to + * your application. + * + * ## Example ([live demo](http://plnkr.co/edit/iRUP8B5OUbxCWQ3AcIDm)) + * + * ``` + * import {Component, View} from 'angular2/angular2'; + * import {ROUTER_DIRECTIVES, routerBindings, RouteConfig} from 'angular2/router'; + * + * @Component({...}) + * @View({directives: [ROUTER_DIRECTIVES]}) + * @RouteConfig([ + * {...}, + * ]) + * class AppCmp { + * // ... + * } + * + * bootstrap(AppCmp, [routerBindings(AppCmp)]); + * ``` + */ export function routerBindings(primaryComponent: Type): Array { return [ROUTER_BINDINGS, bind(ROUTER_PRIMARY_COMPONENT).toValue(primaryComponent)]; }