added option for form transitions

Author: jonasjabari

app/concepts/matestack/ui/core/form/form.js

@@ -104,9 +104,27 @@ const componentDef = {
         if (self.componentConfig["success"] != undefined && self.componentConfig["success"]["emit"] != undefined) {
           matestackEventHub.$emit(self.componentConfig["success"]["emit"], response.data);
         }
-        if (self.componentConfig["success"] != undefined && self.componentConfig["success"]["transition"] != undefined && self.$store != undefined) {
+        if (self.componentConfig["success"] != undefined
+          && self.componentConfig["success"]["transition"] != undefined
+          && (
+            self.componentConfig["success"]["transition"]["follow_response"] == undefined
+            ||
+            self.componentConfig["success"]["transition"]["follow_response"] === false
+          )
+          && self.$store != undefined
+        ) {
           let path = self.componentConfig["success"]["transition"]["path"]
           self.$store.dispatch('navigateTo', {url: path, backwards: false})
+          return;
+        }
+        if (self.componentConfig["success"] != undefined
+          && self.componentConfig["success"]["transition"] != undefined
+          && self.componentConfig["success"]["transition"]["follow_response"] === true
+          && self.$store != undefined
+        ) {
+          let path = response.data["transition_to"]
+          self.$store.dispatch('navigateTo', {url: path, backwards: false})
+          return;
         }
         self.setProps(self.data, null);
         self.initValues()

docs/components/form.md

@@ -275,6 +275,49 @@ We then get displayed our nice success message (`server says: form submitted suc
 
 If we fill in the the input field there and hit the submit button, we not only see the failure messages (`server says: form had errors` and `'foo': [ 'seems to be invalid' ]`), we also get transferred back to the first page, just the way we specified this behavior in the page definition above!
 
+### Example 3.1: Async submit request with success transition - dynamically determined by server
+
+In the example shown above, the `success` `transition` is statically defined. Sometimes the `transition` needs to be dynamically controlled within the server action.
+Imagine creating a new Active Record instance with a `form`. If you want to show the fresh instance on another page and therefore want to define a `transition` after successful form submission, you would need to know the ID of the fresh instance! That is not possible, as the ID is auto-generated and depends on the current environment/state. Therefore you can tell the `form` component to follow a transition, which the server action defines after creating the new instance (and now knowing the ID):
+
+On the `page`:
+```ruby
+#...
+
+def form_config
+  return {
+    for: :my_object,
+    method: :post,
+    path: :success_form_test_path,
+    success: {
+      emit: 'my_form_success',
+      transition: {
+        follow_response: true # follow the serverside transition
+      }
+    }
+  }
+end
+```
+On the `controller` `action`:
+
+```ruby
+#...
+def model_submit
+  @test_model = TestModel.create(model_params)
+  if @test_model.errors.any?
+    render json: {
+      message: 'server says: something went wrong!',
+      errors: @test_model.errors
+    }, status: :unproccessable_entity
+  else
+    render json: {
+      message: 'server says: form submitted successfully!',
+      transition_to: some_other_path(id: @test_model.id) #tell the form component where to transition to with the id, which was not available before
+    }, status: :ok
+  end
+end
+```
+
 ### Example 4: Multiple input fields of different types
 
 Of course, our input core component accepts not only 'text', but very different input types: In this example, we will introduce 'password', 'number', 'email', 'textarea' types!

spec/usage/components/form_spec.rb

@@ -24,6 +24,13 @@ def success_submit
         render json: { message: "server says: form submitted successfully" }, status: 200
       end
 
+      def success_submit_with_transition
+        render json: {
+          message: "server says: form submitted successfully",
+          transition_to: form_test_page_4_path(id: 42)
+        }, status: 200
+      end
+
       def failure_submit
         render json: {
           message: "server says: form had errors",
@@ -35,6 +42,7 @@ def failure_submit
 
     Rails.application.routes.append do
       post '/success_form_test/:id', to: 'form_test#success_submit', as: 'success_form_test'
+      post '/success_form_test_with_transition/:id', to: 'form_test#success_submit_with_transition', as: 'success_form_test_with_transition'
       post '/failure_form_test/:id', to: 'form_test#failure_submit', as: 'failure_form_test'
     end
     Rails.application.reload_routes!
@@ -376,6 +384,108 @@ def page2
 
   end
 
+  it "Example 5 - Async submit request with success transition determined by server response" do
+    class Apps::ExampleApp < Matestack::Ui::App
+
+      def response
+        components {
+          heading size: 1, text: "My Example App Layout"
+          main do
+            page_content
+          end
+          async show_on: "my_form_success", hide_after: 300 do
+            plain "{{event.data.message}}"
+          end
+          async show_on: "my_form_failure", hide_after: 300 do
+            plain "{{event.data.message}}"
+            plain "{{event.data.errors}}"
+          end
+        }
+      end
+
+    end
+
+    module Pages::ExampleApp
+
+    end
+
+    class Pages::ExampleApp::ExamplePage3 < Matestack::Ui::Page
+
+      def response
+        components {
+          heading size: 2, text: "This is Page 3"
+          form form_config, :include do
+            form_input id: "my-test-input-on-page-3", key: :foo, type: :text
+            form_submit do
+              button text: "Submit me!"
+            end
+          end
+        }
+      end
+
+      def form_config
+        return {
+          for: :my_object,
+          method: :post,
+          path: :success_form_test_with_transition_path,
+          params: {
+            id: 42
+          },
+          success: {
+            emit: "my_form_success",
+            transition: {
+              follow_response: true
+            }
+          }
+        }
+      end
+
+    end
+
+    class Pages::ExampleApp::ExamplePage4 < Matestack::Ui::Page
+
+      def response
+        components {
+          heading size: 2, text: "This is Page 4"
+        }
+      end
+
+    end
+
+    class ExampleAppPagesController < ExampleController
+      include Matestack::Ui::Core::ApplicationHelper
+
+      def page3
+        responder_for(Pages::ExampleApp::ExamplePage3)
+      end
+
+      def page4
+        responder_for(Pages::ExampleApp::ExamplePage4)
+      end
+
+    end
+
+    Rails.application.routes.append do
+      scope :form_test do
+        get 'page3', to: 'example_app_pages#page3', as: 'form_test_page_3'
+        get 'page4/:id', to: 'example_app_pages#page4', as: 'form_test_page_4'
+      end
+    end
+    Rails.application.reload_routes!
+
+    visit "form_test/page3"
+
+    expect(page).to have_content("This is Page 3")
+
+    fill_in "my-test-input-on-page-3", with: "bar"
+    click_button "Submit me!"
+
+    expect(page).to have_content("server says: form submitted successfully")
+
+    expect(page).to have_content("This is Page 4")
+
+  end
+
   describe "Form Input Component" do
 
     it "Example 1 - Supports 'text', 'password', 'number', 'email', 'textarea' type" do