GitBook: [#5] No subject

Author: jonasjabari

docs/SUMMARY.md

@@ -31,11 +31,9 @@
   * [Cable Component API](built-in-reactivity/partial-ui-updates/cable-component-api.md)
   * [Isolated Component API](built-in-reactivity/partial-ui-updates/isolated-component-api.md)
 * [Page Transitions](built-in-reactivity/page-transitions/README.md)
-  * [Overview](built-in-reactivity/page-transitions/overview.md)
   * [Transition Component API](built-in-reactivity/page-transitions/transition-component-api.md)
 * [Reactive Collections](built-in-reactivity/reactive-collections/README.md)
-  * [Overview](built-in-reactivity/reactive-collections/overview.md)
-  * [Collection Component API \[WIP\]](built-in-reactivity/reactive-collections/collection-component-api.md)
+  * [Overview & API](built-in-reactivity/reactive-collections/overview.md)
 
 ## Custom Reactivity implemented in Vue.js <a href="#custom-reactivity" id="custom-reactivity"></a>
 

docs/built-in-reactivity/page-transitions/overview.md

@@ -1,6 +1,45 @@
 # Transition Component API
 
-Performing dynamic page transitions without full page reload.
+Matestack's `transition` component enables switching between pages without a full website reload. It works similar to links, but instead of reloading the complete website, including the layout like Rails usually does, it only asynchronously reloads the page without the layout and replaces it dynamically.
+
+{% hint style="info" %}
+Since `3.0.0` transitions require a wrapping `matestack_vue_js_app` component and a `page_switch` component as seen below
+{% endhint %}
+
+```ruby
+class Shop::Layout < Matestack::Ui::Layout
+
+  def response
+    matestack_vue_js_app do # required to wrap transitions and page_switch
+      nav do
+        transition 'Matestack Shop', path: root_path
+        transition 'Products', path: products_path
+      end
+      page_switch do # required to wrap the yield
+        yield
+      end
+    end
+  end
+
+end
+```
+
+Let's add the products page which simply lists all products and adds a transition to their show page for each one.
+
+```ruby
+class Shop::Pages::Products::Index < Matestack::Ui::Page
+
+  def response
+    Products.all.each do |product|
+      div do
+        paragraph product.name
+        transition 'Details', path: product_path(product)
+      end
+    end
+  end
+
+end
+```
 
 ## Parameters
 
@@ -50,28 +89,122 @@ When a sub page of a parent `transition` component is currently active, the pare
 
 Parent target: `/some_page`
 
-Currently active: `/some_page/child_page` --&gt; Parent gets `child-active`
+Currently active: `/some_page/child_page` --> Parent gets `child-active`
 
 Query params do not interfere with this behavior.
 
 ## Events
 
 The `transition` component automatically emits events on:
 
-* transition triggered by user action -&gt; "page\_loading\_triggered"
+* transition triggered by user action -> "page\_loading\_triggered"
 * _optional client side delay via `delay` attribute_
-* start to get new page from server -&gt; "page\_loading"
+* start to get new page from server -> "page\_loading"
 * _server side/network delay_
-* successfully received new page from server -&gt; "page\_loaded"
-* failed to receive new page from server -&gt; "page\_loading\_error"
+* successfully received new page from server -> "page\_loaded"
+* failed to receive new page from server -> "page\_loading\_error"
+
+## DOM structure and loading state element
+
+`app/matestack/example_app/layout.rb`
+
+```ruby
+class ExampleApp::Layout < Matestack::Ui::Layout
+
+  def response
+    #...
+    main do
+      page_switch do
+        yield
+      end
+    end
+    #...
+  end
+
+  def my_loading_state_slot
+    span class: "some-loading-spinner" do
+      plain "loading..."
+    end
+  end
+
+end
+```
+
+which will render:
+
+```markup
+<main>
+  <div class="matestack-page-container">
+    <div class="loading-state-element-wrapper">
+      <span class="some-loading-spinner">
+        loading...
+      </span>
+    </div>
+    <div class="matestack-page-wrapper">
+      <div><!--this div is necessary for conditonal switch to async template via v-if -->
+        <div class="matestack-page-root">
+          your page markup
+        </div>
+      </div>
+    </div>
+  </div>
+</end>
+```
+
+and during async page request triggered via transition:
+
+```markup
+<main>
+  <div class="matestack-page-container loading">
+    <div class="loading-state-element-wrapper loading">
+      <span class="some-loading-spinner">
+        loading...
+      </span>
+    </div>
+    <div class="matestack-page-wrapper loading">
+      <div><!--this div is necessary for conditonal switch to async template via v-if -->
+        <div class="matestack-page-root">
+          your page markup
+        </div>
+      </div>
+    </div>
+  </div>
+</end>
+```
+
+You can use the `loading` class and your loading state element to implement CSS based loading state effects. It may look like this (scss):
+
+```css
+.matestack-page-container{
+
+  .matestack-page-wrapper {
+    opacity: 1;
+    transition: opacity 0.2s ease-in-out;
+
+    &.loading {
+      opacity: 0;
+    }
+  }
+
+  .loading-state-element-wrapper{
+    opacity: 0;
+    transition: opacity 0.3s ease-in-out;
+
+    &.loading {
+      opacity: 1;
+    }
+  }
+
+}
+```
 
 ## Examples
 
 The transition core component renders the HTML `<a>` tag and performs a page transition
 
 ### Perform transition from one page to another without full page reload
 
-First, we define our routes \(`config/routes.rb`\) and the corresponding endpoints in our example controller:
+First, we define our routes (`config/routes.rb`) and the corresponding endpoints in our example controller:
 
 ```ruby
 get 'my_example_app/page1', to: 'example_app_pages#page1', as: 'page1'
@@ -156,8 +289,8 @@ class ExampleApp::Pages::SecondExamplePage < Matestack::Ui::Page
 end
 ```
 
-Now, we can visit our first example page via `localhost:3000/my_example_app/page1` and see our two buttons \(`Page 1` and `Page 2`\) and the content of page 1 \(`My Example App Layout` and `This is Page 1`\).
+Now, we can visit our first example page via `localhost:3000/my_example_app/page1` and see our two buttons (`Page 1` and `Page 2`) and the content of page 1 (`My Example App Layout` and `This is Page 1`).
 
-After clicking on the `Page 2`-button, we get transferred to our second page \(`This is Page 2`\) without re-loading the whole page.
+After clicking on the `Page 2`-button, we get transferred to our second page (`This is Page 2`) without re-loading the whole page.
 
-If we then click the other button available \(`Back to Page 1`\), we get transferred back to the first page, again without re-loading the whole page. This behavior can save quite some request payload \(and therefore loading time\) as only the relevant content on a page gets replaced!
+If we then click the other button available (`Back to Page 1`), we get transferred back to the first page, again without re-loading the whole page. This behavior can save quite some request payload (and therefore loading time) as only the relevant content on a page gets replaced!