GitBook: [#4] No subject

Author: jonasjabari

docs/SUMMARY.md

@@ -40,9 +40,9 @@
 ## Custom Reactivity implemented in Vue.js <a href="#custom-reactivity" id="custom-reactivity"></a>
 
 * [Custom Vue.js Components](custom-reactivity/custom-vue-js-components.md)
-* [Third party Vue.js Components \[WIP\]](custom-reactivity/third-party-vue.js-components.md)
-* [Matestack's Vue.js APIs \[WIP\]](custom-reactivity/matestacks-vue-js-apis.md)
-* [Matestack's Vuex API \[WIP\]](custom-reactivity/matestacks-vuex-api.md)
+* [Third party Vue.js Components \[WIP\]](custom-reactivity/third-party-vue.js-components-wip.md)
+* [Matestack's Vue.js APIs \[WIP\]](custom-reactivity/matestacks-vue.js-apis-wip.md)
+* [Matestack's Vuex API \[WIP\]](custom-reactivity/matestacks-vuex-api-wip.md)
 
 ## Integrations
 

docs/built-in-reactivity/partial-ui-updates/async-component-api.md

@@ -8,7 +8,7 @@ Please be aware that, if not configured otherwise, the `async` core component do
 
 The `async` core component accepts the following parameters:
 
-### ID  - required
+### ID - required
 
 The `async` component needs an ID in order to resolve the correct content on an async HTTP request
 
@@ -32,13 +32,13 @@ end
 
 **Note:** The `rerender_on` option lets you rerender parts of your UI asynchronously. But please consider that, if not configured differently, it
 
-a\) is **not** _lazily loaded_ and
+a) is **not** _lazily loaded_ and
 
-b\) and does get displayed on initial pageload
+b) and does get displayed on initial pageload
 
 by default.
 
-Lazy \(or defered\) loading can be configured like shown [here](async-component-api.md#defer).
+Lazy (or defered) loading can be configured like shown [here](async-component-api.md#defer).
 
 You can pass in multiple, comma-separated events on which the component should rerender.
 
@@ -127,43 +127,43 @@ During async rendering a `loading` class will automatically be applied, which ca
 
 ## Examples
 
-See some common use cases below:
+### Deferring content
 
-### Rerender on event
-
-On our example page, we wrap a simple timestamp in an async component and tell it to rerender when the event `my_event` gets triggered.
+You can either configure an `async` component to request its content directly after the page load or to delay the request for a given amount of time after the page load. `:defer` expects either a boolean or a integer representing the delay time in milliseconds. If `:defer` is set to `false` the `async` component will be rendered on page load and not deferred. If set to `true` it will request its content directly after the page load.
 
 ```ruby
-class ExamplePage < Matestack::Ui::Page
-
-  def response
-    async rerender_on: 'my_event', id: "some-unique-id" do
-      div id: 'my-div' do
-        plain "#{DateTime.now.strftime('%Q')}"
-      end
-    end
+def response
+  async id: 'deferred-async', defer: true do
+    plain 'Some content rendered after page is loaded.'
   end
+end
+```
 
+The above `async` component will be rendered asynchronously after page load.
+
+```ruby
+def response
+  async id: 'delayed-deferred-async', defer: 500 do
+    plain 'Some delayed deferred content'
+  end
 end
 ```
 
-Not surprisingly, the timestamp gets updated after our event was fired!
+Specifying `defer: 500` will delay the asynchronous request after page load of the `async` component for 300ms and render the content afterwards.
 
-### Deferred loading
+### Rerendering content
 
-On our example page, we wrap our `async` event around a placeholder for the event message.
+The `async` leverages the event hub and can react to emitted events. If it receives one or more of the with `:rerender_on` specified events it will asynchronously request a rerender of its content. The response will only include the rerendered html of the `async` component which then replaces the current content of the `async`. If you specify multiple events in `:rerender_on` they need to be seperated by a comma.
 
 ```ruby
-class ExamplePage < Matestack::Ui::Page
-
-  def response 
-    async defer: true, id: "some-unique-id" do 
-      div id: 'my-div' do 
-        plain 'I will be requested within a separate GET request right after initial page load is done' 
-      end 
-    end 
+def response
+  async id: 'rerendering-async', rerender_on: 'update-time' do
+    paragraph DateTime.now
+  end
+  onclick emit: 'update-time' do
+    button text: 'Update time'
   end
-
 end
 ```
 
+The above snippet renders a paragraph with the current time and a button "Update time" on page load. If the button is clicked a _update-time_ event is emitted. The `async` component wrapping the paragraph receives the event and reacts to it by requesting its rerendered content from the server and replacing its content with the received html. In this case it will rerender after button click and show the updated time.

docs/built-in-reactivity/partial-ui-updates/cable-component-api.md

@@ -185,3 +185,238 @@ ActionCable.server.broadcast("matestack_ui_core", {
 
 `data` can also be an Array of ID-strings.
 
+## Examples
+
+
+
+###
+
+Imagine a list of Todo Items and a above that list a form to create new Todos, implemented like this:
+
+```ruby
+class MyPage < Matestack::Ui::Page
+
+  def response
+    matestack_form method: :post, path: create_action_rails_route_path do
+      form_input key: :title, type: :text
+      button "submit"
+    end
+
+    Todo.all.each do |instance|
+      TodoComponent.call(todo: instance)
+    end
+  end
+
+end
+```
+
+```ruby
+class TodoComponent < Matestack::Ui::Component
+
+  required :todo
+
+  def response
+    div id: "todo-#{context.todo.id}", class: "row" do
+      div class: "col" do
+        plain context.todo.title
+      end
+    end
+  end
+
+end
+```
+
+After form submission, the form resets itself dynamically, but the list will not get updated with the new todo instance. You can now decide, if you want to use `async` or `cable` in order to implement that reactivity. `async` could react to an event emitted by the `form` and simply rerender the whole list without any further implementation. Wrapping the list in a correctly configured `async` component would be enough!
+
+But in this case, we do not want to rerender the whole list every time we submitted the form, because - let's say - the list will be quite long and rerendering the whole list would be getting slow. We only want to add new items to the current DOM without touching the rest of the list. The `cable` component enables you to do exactly this. The principle behind it: After form submission the new component is rendered on the serverside and than pushed to the clientside via ActionCable. The `cable` component receives this event and will than - depending on your configuration - append or prepend the current list on the UI. Implementation would look like this:
+
+
+
+### Appending elements
+
+_adding elements on the bottom of the list_
+
+```ruby
+class MyPage < Matestack::Ui::Page
+
+  def response
+    matestack_form method: :post, path: create_action_rails_route_path do
+      form_input key: :title, type: :text
+      button "submit"
+    end
+
+    cable id: "my-cable-list", append_on: "new_todo_created" do
+      Todo.all.each do |instance|
+        TodoComponent.call(todo: instance)
+      end
+    end
+  end
+
+end
+```
+
+and on your controller:
+
+```ruby
+def create
+  @todo = Todo.create(todo_params)
+
+  unless @todo.errors.any?
+    ActionCable.server.broadcast("matestack_ui_core", {
+      event: "new_todo_created",
+      data: TodoComponent.call(todo: @todo)
+    })
+    # respond to the form POST request (needs to be last)
+    render json: { }, status: :created
+  end
+end
+```
+
+Please notice that we recommend to use a component for each list item. With a component for each item it is possible to easily render a new list item within the `create` action and push it to the client. But it is possible to also use another component or a html string. Any given html will be appended to the list.
+
+### Prepending elements
+
+_adding elements on the top of the list_
+
+Prepending works pretty much the same as appending element, just configure your `cable` component like this:
+
+```ruby
+cable id: "my-cable-list", prepend_on: "new_todo_created" do
+  Todo.all.each do |instance|
+    TodoComponent.call(todo: instance)
+  end
+end
+```
+
+### Updating elements
+
+_updating existing elements within the list_
+
+Now imagine you want to update elements in your list without browser reload because somewhere else the title of a todo instance was changed. You could use `async` for this as well. Esspecially because `async` can react to serverside events pushed via ActionCable as well. But again: `async` would rerender the whole list... and in our usecase we do not want to this. We only want to update a specific element of the list. Luckily the implementation for this features does not differ from the above explained ones!
+
+Imagine somewhere else the specific todo was updated via a form targeting the following controller action:
+
+```ruby
+def update
+  @todo = Todo.find(params[:id])
+  @todo.update(todo_params)
+
+  unless @todo.errors.any?
+    ActionCable.server.broadcast("matestack_ui_core", {
+      event: "todo_updated",
+      data: TodoComponent.call(todo: @todo)
+    })
+    # respond to the form PUT request (needs to be last)
+    render json: { }, status: :ok
+  end
+end
+```
+
+Again, the controller action renders a new version of the component and pushes that to the clientside. Nothing changed here! We only need to tell the `cable` component to react properly to that event:
+
+```ruby
+cable id: "my-cable-list", update_on: "todo_updated" do
+  Todo.all.each do |instance|
+    TodoComponent.call(todo: instance)
+  end
+end
+```
+
+Please notice that it is mandatory to have a unique ID on the root element of each list item. The `cable` component will use the ID found in the root element of the pushed component in order to figure out, which element of the current list should be updated. In our example above we used `div id: "todo-#{todo.id}"` as the root element of our `todo_component` used for each element in the list.
+
+### Removing elements
+
+_removing existing elements within the list_
+
+Well, of course we want to be able to remove elements from that list without rerendering the whole list, as `async` would do. The good thing: We can tell the `cable` component to delete elements by ID:
+
+```ruby
+cable id: "my-cable-list", delete_on: "todo_deleted" do
+  Todo.all.each do |instance|
+    TodoComponent.call(todo: instance)
+  end
+end
+```
+
+Imagine somewhere else the following destroy controller action was targeted:
+
+```ruby
+def destroy
+  @todo = Todo.find(params[:id])
+
+  if @todo.destroy
+    ActionCable.server.broadcast("matestack_ui_core", {
+      event: "todo_deleted",
+      data: "todo-#{params[:id]}"
+    })
+    # respond to the DELETE request (needs to be last)
+    render json: { }, status: :deleted
+  end
+end
+```
+
+After deleting the todo instance, the controller action pushes an event via ActionCable, now including just the ID of the element which should be removed. Notice that this ID have to match the ID used on the root element of the component. In our example above we used `div id: "todo-#{todo.id}"` as the root element of our `todo_component` used for each element in the list.
+
+### Replacing the whole component body
+
+Now imagine a context in which the whole `cable` component body should be updated rather than just adding/updating/deleting specific elements of a list. In an online shop app this could be the shopping cart component rendered on the top right. When adding a product to the cart, you might want to update the shopping cart component in order to display the new amount of already included products.
+
+The component may look like this:
+
+```ruby
+class ShoppingCart < Matestack::Ui::Component
+
+  def response
+    div id: "shopping-cart", class: "some-fancy-styling" do
+      icon "some-shopping-cart-icon"
+      span count, class: "some-badge"
+      transition path: shopping_cart_path do
+        button "to my cart"
+      end
+    end
+  end
+
+  def count
+    # some logic returning the amount of products in the users cart (saved on serverside)
+    current_user.cart.products_count
+  end
+
+end
+```
+
+Imagine somewhere else the following controller action was targeted when adding a product to the cart:
+
+```ruby
+def add_to_cart
+  @product = Product.find(params[:id])
+  current_user.cart.add(@product) #some logic adding the product to the users cart (saved on serverside)
+
+  ActionCable.server.broadcast("matestack_ui_core", {
+    event: "shopping_cart_updated",
+    data: ShoppingCart.call()
+  })
+  render json: { }, status: :ok
+end
+```
+
+and on your UI class (probably your app class):
+
+```ruby
+cable id: "shopping-cart", replace_on: "shopping_cart_updated" do
+  ShoppingCart.call()
+end
+```
+
+### Event data as Array
+
+All above shown examples demonstrated how to push a single component or ID to the `cable` component. In all usecases it's also possble to provide an Array of components/ID-strings, e.g.:
+
+```ruby
+ActionCable.server.broadcast("matestack_ui_core", {
+  event: "todo_updated",
+  data: [
+    ShoppingCart.call(todo: @todo1),
+    ShoppingCart.call(todo: @todo2)
+  ]
+})
+```