Merge pull request #1357 from NativeScript/cankov/go-back-to-backstack-entry

Frame.goBack can now accept an entry to navigate back to

apps/tests/navigation-tests.ts

@@ -1,6 +1,7 @@
 import TKUnit = require("./TKUnit");
 import pageModule = require("ui/page");
 import frame = require("ui/frame");
+import { Page } from "ui/page";
 
 export var test_backstackVisible = function() {
     var pageFactory = function(): pageModule.Page {
@@ -31,6 +32,46 @@ export var test_backstackVisible = function() {
     TKUnit.waitUntilReady(() => { return frame.topmost().currentPage === mainTestPage; });
 }
 
+export var test_backToEntry = function() {
+    let page = (tag) => () => {
+        var p = new Page();
+        p["tag"] = tag;
+        return p;
+    }
+    let topmost = frame.topmost();
+    let wait = tag => TKUnit.waitUntilReady(() => topmost.currentPage["tag"] === tag, 1);
+    let navigate = tag => {
+        topmost.navigate({ create: page(tag) });
+        wait(tag)
+    }
+    let back = pages => {
+        topmost.goBack(topmost.backStack[topmost.backStack.length - pages]);
+    }
+    let currentPageMustBe = tag => {
+        wait(tag); // TODO: Add a timeout...
+        TKUnit.assert(topmost.currentPage["tag"] === tag, "Expected current page to be " + tag + " it was " + topmost.currentPage["tag"] + " instead."); 
+    }
+
+    navigate("page1");
+    navigate("page2");
+    navigate("page3");
+    navigate("page4");
+
+    currentPageMustBe("page4");
+    back(2);
+    currentPageMustBe("page2");
+    back(1);
+    currentPageMustBe("page1");
+    navigate("page1.1");
+    navigate("page1.2");
+    currentPageMustBe("page1.2");
+    back(1);
+    currentPageMustBe("page1.1");
+    back(1);
+    currentPageMustBe("page1");
+    back(1);
+}
+
 // Clearing the history messes up the tests app.
 export var test_ClearHistory = function () {
     var pageFactory = function(): pageModule.Page {

ui/frame/frame-common.ts

@@ -152,14 +152,27 @@ export class Frame extends CustomLayoutView implements definition.Frame {
         return this._backStack.length > 0;
     }
 
-    public goBack() {
+    /**
+     * Navigates to the previous entry (if any) in the back stack.
+     * @param to The backstack entry to navigate back to.
+     */
+    public goBack(backstackEntry?: definition.BackstackEntry) {
         trace.write(this._getTraceId() + ".goBack();", trace.categories.Navigation);
         if (!this.canGoBack()) {
             // TODO: Do we need to throw an error?
             return;
         }
 
-        var backstackEntry = this._backStack.pop();
+        if (!backstackEntry) {
+            backstackEntry = this._backStack.pop();
+        } else {
+            let backIndex = this._backStack.indexOf(backstackEntry);
+            if (backIndex < 0) {
+                return;
+            }
+            this._backStack.splice(backIndex);
+        }
+
         var navigationContext: NavigationContext = {
             entry: backstackEntry,
             isBackNavigation: true

ui/frame/frame.d.ts

@@ -19,8 +19,9 @@ declare module "ui/frame" {
 
         /**
          * Navigates to the previous entry (if any) in the back stack.
+         * @param to The backstack entry to navigate back to.
          */
-        goBack();
+        goBack(to?: BackstackEntry);
 
         /**
          * Checks whether the goBack operation is available.