Merge pull request #809 from infinitered/feature/replace-nav-stack

Add ability to replace the nav stack while pushing a new screen onto the nav stack.

docs/Reference/ProMotion Screen.md

@@ -493,7 +493,13 @@ class MyNavigationController < PM::NavigationController; end
 open HomeScreen.new(nav_bar: true, nav_controller: MyNavigationController), close_all: true
 
 # Opens a screen with a navigation controller but with the navigation bar hidden
-open HomeScreen.new(nav_bar: true, hide_nav_bar: true) # Edge feature
+open HomeScreen.new(nav_bar: true, hide_nav_bar: true)
+
+# Sometimes you need to push a new screen onto the nav stack and remove the previous screens (disable the back button). This is similar to setting a new root screen, while keeping the existing navigation controller.
+open OtherScreen, replace_nav_stack: true
+
+# ...or update the current nav stack:
+replace_nav_stack([PreviousScreen.new, TopScreen.new], animated: false)
 ```
 
 ##### Setting screen accessors

lib/ProMotion/screen/screen_module.rb

@@ -187,7 +187,7 @@ def add_nav_bar_buttons
     end
 
     def apply_properties(args)
-      reserved_args = [ :nav_bar, :nav_controller, :hide_nav_bar, :hide_tab_bar, :animated, :close_all, :in_tab, :in_detail, :in_master, :to_screen, :toolbar ]
+      reserved_args = [ :nav_bar, :nav_controller, :hide_nav_bar, :hide_tab_bar, :animated, :close_all, :replace_nav_stack, :in_tab, :in_detail, :in_master, :to_screen, :toolbar ]
       set_attributes self, args.dup.delete_if { |k,v| reserved_args.include?(k) }
     end
 

lib/ProMotion/screen/screen_navigation.rb

@@ -10,11 +10,12 @@ def open_screen(screen, args = {})
       ensure_wrapper_controller_in_place(screen, args)
 
       opened ||= open_in_split_screen(screen, args) if self.split_screen
-      opened ||= open_root_screen(screen) if args[:close_all]
+      opened ||= open_root_screen(screen, args) if args[:close_all]
+      opened ||= replace_nav_stack([screen], args) if args[:replace_nav_stack]
       opened ||= present_modal_view_controller(screen, args) if args[:modal]
       opened ||= open_in_tab(screen, args[:in_tab]) if args[:in_tab]
       opened ||= push_view_controller(screen, self.navigationController, !!args[:animated]) if self.navigationController
-      opened ||= open_root_screen(screen.navigationController || screen)
+      opened ||= open_root_screen(screen.navigationController || screen, args)
       screen
     end
     alias :open :open_screen
@@ -25,8 +26,8 @@ def open_in_split_screen(screen, args)
       args[:in_detail] || args[:in_master]
     end
 
-    def open_root_screen(screen)
-      app_delegate.open_root_screen(screen)
+    def open_root_screen(screen, args = {})
+      app_delegate.open_root_screen(screen, args)
     end
 
     def open_modal(screen, args = {})
@@ -75,6 +76,11 @@ def push_view_controller(vc, nav_controller=nil, animated=true)
       nav_controller.pushViewController(vc, animated: animated)
     end
 
+    def replace_nav_stack(screens, args = {})
+      args[:animated] ||= true
+      navigationController.setViewControllers(screens, animated: !!args[:animated])
+    end
+
   protected
 
     def set_up_screen_for_open(screen, args={})

spec/unit/screen_helpers_spec.rb

@@ -155,7 +155,7 @@
       end
 
       it "should open a root screen if :close_all is provided" do
-        @screen.mock!(:open_root_screen) { |screen| screen.should.be.instance_of BasicScreen }
+        @screen.mock!(:open_root_screen) { |screen, args| screen.should.be.instance_of BasicScreen }
         screen = @screen.open BasicScreen, close_all: true
         screen.should.be.kind_of BasicScreen
       end
@@ -218,7 +218,7 @@
       it "should open the provided view controller as root view if no other conditions are met" do
         parent_screen = HomeScreen.new
         new_screen = BasicScreen.new
-        parent_screen.mock!(:open_root_screen) { |vc| vc.should.be == new_screen }
+        parent_screen.mock!(:open_root_screen) { |vc, args| vc.should.be == new_screen }
         screen = parent_screen.open_screen new_screen
         screen.should == new_screen
       end