From d9036c6cf37e761306ca19931132f5af6c0ac0ed Mon Sep 17 00:00:00 2001
From: Brian Ford <btford@umich.edu>
Date: Tue, 8 Sep 2015 21:42:23 -0700
Subject: [PATCH] feat(router): introduce new navigate method

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
---
 modules/angular2/src/router/router.ts          | 18 ++++++++++++++++++
 .../router/integration/router_link_spec.ts     |  6 +-----
 modules/angular2/test/router/router_spec.ts    | 15 +++++++++++++++
 3 files changed, 34 insertions(+), 5 deletions(-)

diff --git a/modules/angular2/src/router/router.ts b/modules/angular2/src/router/router.ts
index 5fbf2ebed6..27a11e2c27 100644
--- 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
index f5f0684af7..d815451be5 100644
--- 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
index 06301b9426..31b58d6c22 100644
--- 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();