feat(router): introduce new navigate method

btford · btford · commit d9036c6cf37e · 2015-09-11T17:20:13.000-07:00
Previously, `router.navigate` took a string representing the URL. Now, it accepts an array that mirrors the link DSL. Closes #4040 BREAKING CHANGE The old method has been renamed to `router.navigateByUrl`. Either change your navigation calls to use the DSL (preferred) or call `router.navigateByUrl` instead. Closes #4074
diff --git a/modules/angular2/src/router/router.ts b/modules/angular2/src/router/router.ts
@@ -152,9 +152,27 @@ export class Router {
     return this.renavigate();
   }
 
+  /**
+   * Navigate based on the provided Route Link DSL. It's preferred to navigate with this method
+   * over `navigateByUrl`.
+   *
+   * # Usage
+   *
+   * This method takes an array representing the Route Link DSL:
+   * ```
+   * ['./MyCmp', {param: 3}]
+   * ```
+   * See the {@link RouterLink} directive for more.
+   */
+  navigate(linkParams: any[]): Promise<any> {
+    var instruction = this.generate(linkParams);
+    return this.navigateByInstruction(instruction, false);
+  }
+
 
   /**
    * Navigate to a URL. Returns a promise that resolves when navigation is complete.
+   * It's preferred to navigate with `navigate` instead of this method, since URLs are more brittle.
    *
    * If the given URL begins with a `/`, router will navigate absolutely.
    * If the given URL does not begin with `/`, the router will navigate relative to this component.
diff --git a/modules/angular2/test/router/integration/router_link_spec.ts b/modules/angular2/test/router/integration/router_link_spec.ts
@@ -139,11 +139,7 @@ export function main() {
                  as: 'child-with-grandchild'
                })
              ]))
-             .then((_) => {
-               // TODO: refactor when https://github.com/angular/angular/pull/4074 lands
-               var instruction = router.generate(['/child-with-grandchild']);
-               return router.navigateInstruction(instruction);
-             })
+             .then((_) => router.navigate(['/child-with-grandchild']))
              .then((_) => {
                rootTC.detectChanges();
                expect(DOM.getAttribute(
diff --git a/modules/angular2/test/router/router_spec.ts b/modules/angular2/test/router/router_spec.ts
@@ -76,6 +76,21 @@ export function main() {
              });
        }));
 
+    it('should activate viewports and update URL when navigating via DSL',
+       inject([AsyncTestCompleter], (async) => {
+         var outlet = makeDummyOutlet();
+
+         router.registerPrimaryOutlet(outlet)
+             .then((_) =>
+                       router.config([new Route({path: '/a', component: DummyComponent, as: 'A'})]))
+             .then((_) => router.navigate(['/A']))
+             .then((_) => {
+               expect(outlet.spy('activate')).toHaveBeenCalled();
+               expect(location.urlChanges).toEqual(['/a']);
+               async.done();
+             });
+       }));
+
     it('should not push a history change on when navigate is called with skipUrlChange',
        inject([AsyncTestCompleter], (async) => {
          var outlet = makeDummyOutlet();
