1 | declare namespace angular {
|
2 | /**
|
3 | * `Instruction` is a tree of {@link ComponentInstruction}s with all the information needed
|
4 | * to transition each component in the app to a given route, including all auxiliary routes.
|
5 | *
|
6 | * `Instruction`s can be created using {@link Router#generate}, and can be used to
|
7 | * perform route changes with {@link Router#navigateByInstruction}.
|
8 | *
|
9 | * ### Example
|
10 | *
|
11 | * ```
|
12 | * import { Component } from 'angular2/core';
|
13 | * import {bootstrap} from 'angular2/platform/browser';
|
14 | * import {Router, ROUTER_DIRECTIVES, ROUTER_PROVIDERS, RouteConfig} from 'angular2/router';
|
15 | *
|
16 | * @Component({directives: [ROUTER_DIRECTIVES]})
|
17 | * @RouteConfig([
|
18 | * {...},
|
19 | * ])
|
20 | * class AppCmp {
|
21 | * constructor(router: Router) {
|
22 | * var instruction = router.generate(['/MyRoute']);
|
23 | * router.navigateByInstruction(instruction);
|
24 | * }
|
25 | * }
|
26 | *
|
27 | * bootstrap(AppCmp, ROUTER_PROVIDERS);
|
28 | * ```
|
29 | */
|
30 | interface Instruction {
|
31 | component: ComponentInstruction;
|
32 | child: Instruction;
|
33 | auxInstruction: { [key: string]: Instruction };
|
34 |
|
35 | urlPath(): string;
|
36 |
|
37 | urlParams(): string[];
|
38 |
|
39 | specificity(): number;
|
40 |
|
41 | resolveComponent(): IPromise<ComponentInstruction>;
|
42 |
|
43 | /**
|
44 | * converts the instruction into a URL string
|
45 | */
|
46 | toRootUrl(): string;
|
47 |
|
48 | toUrlQuery(): string;
|
49 |
|
50 | /**
|
51 | * Returns a new instruction that shares the state of the existing instruction, but with
|
52 | * the given child {@link Instruction} replacing the existing child.
|
53 | */
|
54 | replaceChild(child: Instruction): Instruction;
|
55 |
|
56 | /**
|
57 | * If the final URL for the instruction is ``
|
58 | */
|
59 | toUrlPath(): string;
|
60 |
|
61 | /**
|
62 | * default instructions override these
|
63 | */
|
64 | toLinkUrl(): string;
|
65 | }
|
66 |
|
67 | /**
|
68 | * A router outlet is a placeholder that Angular dynamically fills based on the application's route.
|
69 | *
|
70 | * ## Use
|
71 | *
|
72 | * ```
|
73 | * <router-outlet></router-outlet>
|
74 | * ```
|
75 | */
|
76 | interface RouterOutlet {
|
77 | name: string;
|
78 |
|
79 | /**
|
80 | * Called by the Router to instantiate a new component during the commit phase of a navigation.
|
81 | * This method in turn is responsible for calling the `routerOnActivate` hook of its child.
|
82 | */
|
83 | activate(nextInstruction: ComponentInstruction): IPromise<any>;
|
84 |
|
85 | /**
|
86 | * Called by the {@link Router} during the commit phase of a navigation when an outlet
|
87 | * reuses a component between different routes.
|
88 | * This method in turn is responsible for calling the `routerOnReuse` hook of its child.
|
89 | */
|
90 | reuse(nextInstruction: ComponentInstruction): IPromise<any>;
|
91 |
|
92 | /**
|
93 | * Called by the {@link Router} when an outlet disposes of a component's contents.
|
94 | * This method in turn is responsible for calling the `routerOnDeactivate` hook of its child.
|
95 | */
|
96 | deactivate(nextInstruction: ComponentInstruction): IPromise<any>;
|
97 |
|
98 | /**
|
99 | * Called by the {@link Router} during recognition phase of a navigation.
|
100 | *
|
101 | * If this resolves to `false`, the given navigation is cancelled.
|
102 | *
|
103 | * This method delegates to the child component's `routerCanDeactivate` hook if it exists,
|
104 | * and otherwise resolves to true.
|
105 | */
|
106 | routerCanDeactivate(nextInstruction: ComponentInstruction): IPromise<boolean>;
|
107 |
|
108 | /**
|
109 | * Called by the {@link Router} during recognition phase of a navigation.
|
110 | *
|
111 | * If the new child component has a different Type than the existing child component,
|
112 | * this will resolve to `false`. You can't reuse an old component when the new component
|
113 | * is of a different Type.
|
114 | *
|
115 | * Otherwise, this method delegates to the child component's `routerCanReuse` hook if it exists,
|
116 | * or resolves to true if the hook is not present.
|
117 | */
|
118 | routerCanReuse(nextInstruction: ComponentInstruction): IPromise<boolean>;
|
119 | }
|
120 |
|
121 | interface RouteRegistry {
|
122 | /**
|
123 | * Given a component and a configuration object, add the route to this registry
|
124 | */
|
125 | config(parentComponent: any, config: RouteDefinition): void;
|
126 |
|
127 | /**
|
128 | * Reads the annotations of a component and configures the registry based on them
|
129 | */
|
130 | configFromComponent(component: any): void;
|
131 |
|
132 | /**
|
133 | * Given a URL and a parent component, return the most specific instruction for navigating
|
134 | * the application into the state specified by the url
|
135 | */
|
136 | recognize(url: string, ancestorInstructions: Instruction[]): IPromise<Instruction>;
|
137 |
|
138 | /**
|
139 | * Given a normalized list with component names and params like: `['user', {id: 3 }]`
|
140 | * generates a url with a leading slash relative to the provided `parentComponent`.
|
141 | *
|
142 | * If the optional param `_aux` is `true`, then we generate starting at an auxiliary
|
143 | * route boundary.
|
144 | */
|
145 | generate(linkParams: any[], ancestorInstructions: Instruction[], _aux?: boolean): Instruction;
|
146 |
|
147 | hasRoute(name: string, parentComponent: any): boolean;
|
148 |
|
149 | generateDefault(componentCursor: any): Instruction;
|
150 | }
|
151 |
|
152 | /**
|
153 | * The `Router` is responsible for mapping URLs to components.
|
154 | *
|
155 | * You can see the state of the router by inspecting the read-only field `router.navigating`.
|
156 | * This may be useful for showing a spinner, for instance.
|
157 | *
|
158 | * ## Concepts
|
159 | *
|
160 | * Routers and component instances have a 1:1 correspondence.
|
161 | *
|
162 | * The router holds reference to a number of {@link RouterOutlet}.
|
163 | * An outlet is a placeholder that the router dynamically fills in depending on the current URL.
|
164 | *
|
165 | * When the router navigates from a URL, it must first recognize it and serialize it into an
|
166 | * `Instruction`.
|
167 | * The router uses the `RouteRegistry` to get an `Instruction`.
|
168 | */
|
169 | interface Router {
|
170 | navigating: boolean;
|
171 | lastNavigationAttempt: string;
|
172 | registry: RouteRegistry;
|
173 | parent: Router;
|
174 | hostComponent: any;
|
175 | currentInstruction: Instruction;
|
176 |
|
177 | /**
|
178 | * Constructs a child router. You probably don't need to use this unless you're writing a reusable
|
179 | * component.
|
180 | */
|
181 | childRouter(hostComponent: any): Router;
|
182 |
|
183 | /**
|
184 | * Constructs a child router. You probably don't need to use this unless you're writing a reusable
|
185 | * component.
|
186 | */
|
187 | auxRouter(hostComponent: any): Router;
|
188 |
|
189 | /**
|
190 | * Register an outlet to be notified of primary route changes.
|
191 | *
|
192 | * You probably don't need to use this unless you're writing a reusable component.
|
193 | */
|
194 | registerPrimaryOutlet(outlet: RouterOutlet): IPromise<boolean>;
|
195 |
|
196 | /**
|
197 | * Register an outlet to notified of auxiliary route changes.
|
198 | *
|
199 | * You probably don't need to use this unless you're writing a reusable component.
|
200 | */
|
201 | registerAuxOutlet(outlet: RouterOutlet): IPromise<boolean>;
|
202 |
|
203 | /**
|
204 | * Given an instruction, returns `true` if the instruction is currently active,
|
205 | * otherwise `false`.
|
206 | */
|
207 | isRouteActive(instruction: Instruction): boolean;
|
208 |
|
209 | /**
|
210 | * Dynamically update the routing configuration and trigger a navigation.
|
211 | *
|
212 | * ### Usage
|
213 | *
|
214 | * ```
|
215 | * router.config([
|
216 | * { 'path': '/', 'component': IndexComp },
|
217 | * { 'path': '/user/:id', 'component': UserComp },
|
218 | * ]);
|
219 | * ```
|
220 | */
|
221 | config(definitions: RouteDefinition[]): IPromise<any>;
|
222 |
|
223 | /**
|
224 | * Navigate based on the provided Route Link DSL. It's preferred to navigate with this method
|
225 | * over `navigateByUrl`.
|
226 | *
|
227 | * ### Usage
|
228 | *
|
229 | * This method takes an array representing the Route Link DSL:
|
230 | * ```
|
231 | * ['./MyCmp', {param: 3}]
|
232 | * ```
|
233 | * See the {@link RouterLink} directive for more.
|
234 | */
|
235 | navigate(linkParams: any[]): IPromise<any>;
|
236 |
|
237 | /**
|
238 | * Navigate to a URL. Returns a promise that resolves when navigation is complete.
|
239 | * It's preferred to navigate with `navigate` instead of this method, since URLs are more brittle.
|
240 | *
|
241 | * If the given URL begins with a `/`, router will navigate absolutely.
|
242 | * If the given URL does not begin with `/`, the router will navigate relative to this component.
|
243 | */
|
244 | navigateByUrl(url: string, _skipLocationChange?: boolean): IPromise<any>;
|
245 |
|
246 | /**
|
247 | * Navigate via the provided instruction. Returns a promise that resolves when navigation is
|
248 | * complete.
|
249 | */
|
250 | navigateByInstruction(instruction: Instruction, _skipLocationChange?: boolean): IPromise<any>;
|
251 |
|
252 | /**
|
253 | * Updates this router and all descendant routers according to the given instruction
|
254 | */
|
255 | commit(instruction: Instruction, _skipLocationChange?: boolean): IPromise<any>;
|
256 |
|
257 | /**
|
258 | * Subscribe to URL updates from the router
|
259 | */
|
260 | subscribe(onNext: (value: any) => void): {};
|
261 |
|
262 | /**
|
263 | * Removes the contents of this router's outlet and all descendant outlets
|
264 | */
|
265 | deactivate(instruction: Instruction): IPromise<any>;
|
266 |
|
267 | /**
|
268 | * Given a URL, returns an instruction representing the component graph
|
269 | */
|
270 | recognize(url: string): IPromise<Instruction>;
|
271 |
|
272 | /**
|
273 | * Navigates to either the last URL successfully navigated to, or the last URL requested if the
|
274 | * router has yet to successfully navigate.
|
275 | */
|
276 | renavigate(): IPromise<any>;
|
277 |
|
278 | /**
|
279 | * Generate an `Instruction` based on the provided Route Link DSL.
|
280 | */
|
281 | generate(linkParams: any[]): Instruction;
|
282 | }
|
283 |
|
284 | /**
|
285 | * RouteData is an immutable map of additional data you can configure in your Route.
|
286 | * You can inject RouteData into the constructor of a component to use it.
|
287 | */
|
288 | interface RouteData {
|
289 | data: { [key: string]: any };
|
290 | get(key: string): any;
|
291 | }
|
292 |
|
293 | /**
|
294 | * A `ComponentInstruction` represents the route state for a single component. An `Instruction` is
|
295 | * composed of a tree of these `ComponentInstruction`s.
|
296 | *
|
297 | * `ComponentInstructions` is a public API. Instances of `ComponentInstruction` are passed
|
298 | * to route lifecycle hooks, like {@link CanActivate}.
|
299 | *
|
300 | * `ComponentInstruction`s are [https://en.wikipedia.org/wiki/Hash_consing](hash consed). You should
|
301 | * never construct one yourself with "new." Instead, rely on {@link Router/RouteRecognizer} to
|
302 | * construct `ComponentInstruction`s.
|
303 | *
|
304 | * You should not modify this object. It should be treated as immutable.
|
305 | */
|
306 | interface ComponentInstruction {
|
307 | reuse: boolean;
|
308 | routeData: RouteData;
|
309 | urlPath: string;
|
310 | urlParams: string[];
|
311 | data: RouteData;
|
312 | componentType: any;
|
313 | terminal: boolean;
|
314 | specificity: number;
|
315 | params: { [key: string]: any };
|
316 | }
|
317 |
|
318 | /**
|
319 | * Defines route lifecycle method `routerOnActivate`, which is called by the router at the end of a
|
320 | * successful route navigation.
|
321 | *
|
322 | * For a single component's navigation, only one of either {@link OnActivate} or {@link OnReuse}
|
323 | * will be called depending on the result of {@link CanReuse}.
|
324 | *
|
325 | * The `routerOnActivate` hook is called with two {@link ComponentInstruction}s as parameters, the
|
326 | * first
|
327 | * representing the current route being navigated to, and the second parameter representing the
|
328 | * previous route or `null`.
|
329 | *
|
330 | * If `routerOnActivate` returns a promise, the route change will wait until the promise settles to
|
331 | * instantiate and activate child components.
|
332 | *
|
333 | * ### Example
|
334 | * {@example router/ts/on_activate/on_activate_example.ts region='routerOnActivate'}
|
335 | */
|
336 | interface OnActivate {
|
337 | $routerOnActivate(next?: angular.ComponentInstruction, prev?: angular.ComponentInstruction): any;
|
338 | }
|
339 |
|
340 | /**
|
341 | * Defines route lifecycle method `routerCanDeactivate`, which is called by the router to determine
|
342 | * if a component can be removed as part of a navigation.
|
343 | *
|
344 | * The `routerCanDeactivate` hook is called with two {@link ComponentInstruction}s as parameters,
|
345 | * the
|
346 | * first representing the current route being navigated to, and the second parameter
|
347 | * representing the previous route.
|
348 | *
|
349 | * If `routerCanDeactivate` returns or resolves to `false`, the navigation is cancelled. If it
|
350 | * returns or
|
351 | * resolves to `true`, then the navigation continues, and the component will be deactivated
|
352 | * (the {@link OnDeactivate} hook will be run) and removed.
|
353 | *
|
354 | * If `routerCanDeactivate` throws or rejects, the navigation is also cancelled.
|
355 | *
|
356 | * ### Example
|
357 | * {@example router/ts/can_deactivate/can_deactivate_example.ts region='routerCanDeactivate'}
|
358 | */
|
359 | interface CanDeactivate {
|
360 | $routerCanDeactivate(next?: ComponentInstruction, prev?: ComponentInstruction): boolean | IPromise<boolean>;
|
361 | }
|
362 |
|
363 | /**
|
364 | * Defines route lifecycle method `routerOnDeactivate`, which is called by the router before
|
365 | * destroying
|
366 | * a component as part of a route change.
|
367 | *
|
368 | * The `routerOnDeactivate` hook is called with two {@link ComponentInstruction}s as parameters, the
|
369 | * first
|
370 | * representing the current route being navigated to, and the second parameter representing the
|
371 | * previous route.
|
372 | *
|
373 | * If `routerOnDeactivate` returns a promise, the route change will wait until the promise settles.
|
374 | *
|
375 | * ### Example
|
376 | * {@example router/ts/on_deactivate/on_deactivate_example.ts region='routerOnDeactivate'}
|
377 | */
|
378 | interface OnDeactivate {
|
379 | $routerOnDeactivate(next?: angular.ComponentInstruction, prev?: angular.ComponentInstruction): any;
|
380 | }
|
381 |
|
382 | /**
|
383 | * Defines route lifecycle method `routerCanReuse`, which is called by the router to determine
|
384 | * whether a
|
385 | * component should be reused across routes, or whether to destroy and instantiate a new component.
|
386 | *
|
387 | * The `routerCanReuse` hook is called with two {@link ComponentInstruction}s as parameters, the
|
388 | * first
|
389 | * representing the current route being navigated to, and the second parameter representing the
|
390 | * previous route.
|
391 | *
|
392 | * If `routerCanReuse` returns or resolves to `true`, the component instance will be reused and the
|
393 | * {@link OnDeactivate} hook will be run. If `routerCanReuse` returns or resolves to `false`, a new
|
394 | * component will be instantiated, and the existing component will be deactivated and removed as
|
395 | * part of the navigation.
|
396 | *
|
397 | * If `routerCanReuse` throws or rejects, the navigation will be cancelled.
|
398 | *
|
399 | * ### Example
|
400 | * {@example router/ts/reuse/reuse_example.ts region='reuseCmp'}
|
401 | */
|
402 | interface CanReuse {
|
403 | $routerCanReuse(
|
404 | next?: angular.ComponentInstruction,
|
405 | prev?: angular.ComponentInstruction,
|
406 | ): boolean | IPromise<boolean>;
|
407 | }
|
408 |
|
409 | /**
|
410 | * Defines route lifecycle method `routerOnReuse`, which is called by the router at the end of a
|
411 | * successful route navigation when {@link CanReuse} is implemented and returns or resolves to true.
|
412 | *
|
413 | * For a single component's navigation, only one of either {@link OnActivate} or {@link OnReuse}
|
414 | * will be called, depending on the result of {@link CanReuse}.
|
415 | *
|
416 | * The `routerOnReuse` hook is called with two {@link ComponentInstruction}s as parameters, the
|
417 | * first
|
418 | * representing the current route being navigated to, and the second parameter representing the
|
419 | * previous route or `null`.
|
420 | *
|
421 | * ### Example
|
422 | * {@example router/ts/reuse/reuse_example.ts region='reuseCmp'}
|
423 | */
|
424 | interface OnReuse {
|
425 | $routerOnReuse(next?: angular.ComponentInstruction, prev?: angular.ComponentInstruction): any;
|
426 | }
|
427 |
|
428 | /**
|
429 | * Runtime representation a type that a Component or other object is instances of.
|
430 | *
|
431 | * An example of a `Type` is `MyCustomComponent` class, which in JavaScript is be represented by
|
432 | * the `MyCustomComponent` constructor function.
|
433 | */
|
434 | interface Type extends Function {
|
435 | }
|
436 |
|
437 | /**
|
438 | * `RouteDefinition` defines a route within a {@link RouteConfig} decorator.
|
439 | *
|
440 | * Supported keys:
|
441 | * - `path` or `aux` (requires exactly one of these)
|
442 | * - `component`, `loader`, `redirectTo` (requires exactly one of these)
|
443 | * - `name` or `as` (optional) (requires exactly one of these)
|
444 | * - `data` (optional)
|
445 | *
|
446 | * See also {@link Route}, {@link AsyncRoute}, {@link AuxRoute}, and {@link Redirect}.
|
447 | */
|
448 | interface RouteDefinition {
|
449 | path?: string;
|
450 | aux?: string;
|
451 | component?: Type | ComponentDefinition | string;
|
452 | loader?: Function;
|
453 | redirectTo?: any[];
|
454 | as?: string;
|
455 | name?: string;
|
456 | data?: any;
|
457 | useAsDefault?: boolean;
|
458 | }
|
459 |
|
460 | /**
|
461 | * Represents either a component type (`type` is `component`) or a loader function
|
462 | * (`type` is `loader`).
|
463 | *
|
464 | * See also {@link RouteDefinition}.
|
465 | */
|
466 | interface ComponentDefinition {
|
467 | type: string;
|
468 | loader?: Function;
|
469 | component?: Type;
|
470 | }
|
471 |
|
472 | // Supplement IComponentOptions from angular.d.ts with router-specific
|
473 | // fields.
|
474 | interface IComponentOptions {
|
475 | $canActivate?: (...args: any[]) => boolean | angular.IPromise<boolean>;
|
476 | $routeConfig?: RouteDefinition[];
|
477 | }
|
478 | }
|