Update documentation, add another test

Author: pascalwengerter

docs/concepts/component.md

@@ -2,7 +2,7 @@
 
 Show [specs](/spec/usage/base/component_spec.rb).
 
-Components are used to define reusable UI elements. The `matestack-ui-core` contains a number of generic, so-called `core components`, but anyone can extend them and write `custom components` that live within a his or her application and cater a specific or unique need.
+Components are used to define reusable UI elements. The `matestack-ui-core` contains a number of generic, so-called `core components`, but anyone can extend them and write `custom components` that live within his or her application and cater a specific or unique need.
 
 This document aims to give a brief introducing to the different kinds of components (with links to further sources) and serves as a manual on [how to configure your components](#component-configuration).
 
@@ -18,7 +18,7 @@ To extend the available core components, just fork [the repo](https://github.com
 
 ## Custom Components
 
-By definition, `custom components` only live within your application. In Rails applications, they are put into the `app/matestack/components/` directory. To use them on your `apps` and `pages`, you need to add a *prefixed 'custom_'*. This clearly differentiates them from the vanilla `core components`.
+By definition, `custom components` only live within your application. In Rails applications, they are put into the `app/matestack/components/` directory. To use them on your `apps` and `pages`, you need to add a *prefixed 'custom_'*. This way, one can clearly differentiate between `custom components` and `core components`.
 
 ### Static Components
 

docs/extend/README.md

@@ -4,8 +4,9 @@ Matestack provides you with a lot of functionality out of the box. But at certai
 
 ## Custom Components
 
-See below for a list of guides on how to create your own project-specific custom components:
+The different component concepts are explained [here](/docs/concepts/component.md). See below for a list of guides on how to create your own project-specific custom components:
 
 1. [Custom static components](/docs/extend/custom_static_components.md)
+  - [Custom static actionview components](/docs/extend/custom_actionview_components.md)
 2. [Custom dynamic components](/docs/extend/custom_dynamic_components.md)
-3. [Custom actionview components](/docs/extend/custom_actionview_components.md)
+  - [Custom dynamic actionview components](/docs/extend/custom_actionview_components.md)

docs/extend/custom_dynamic_components.md

@@ -1,13 +1,58 @@
 # Custom dynamic components
 
-To create dynamic behavior, you got to choose: Either you wrap a bunch of `core components` and/or `custom components` inside an `dynamic core component`, or you go the whole way and create a `custom dynamic component` with a corresponding Vue.js counterpart.
+To create dynamic behavior, you got either:
+
+- use a bunch of `dynamic core components` (like async, emit ...) inside a `custom static component` ([examp below](#dynamic-core-components-inside-a-custom-static_component))
+- wrap a `custom static component` in a `dynamic core component` ([example below](#async-wrapper-around-static-components))
+- create a custom dynamic component with a corresponding Vue.js counterpart ([example below](#dynamic-components-with-custom-))
+
+
+## Dynamic core components inside a custom static component
+
+Create a `custom static component` in `app/matestack/components/some/component.rb`
+
+```ruby
+class Components::Some::Component < Matestack::Ui::StaticComponent
+
+  def response
+    components {
+      div id: "my-component" do
+        async rerender_on: "my_event" do
+          plain DateTime.now.strftime('%Q')
+        end
+      end
+    }
+  end
+
+end
+```
+
+and add it to the Example Page.
+
+Since we've put a `dynamic core component` inside our `custom static component`, the timestamp inside our custom component gets updated whenever *\"my_event\"* happens - for example by an `onclick` component, as shown below:
+
+```ruby
+class Pages::ExamplePage < Matestack::Ui::Page
+
+  def response
+    components {
+      div id: "div-on-page" do
+        custom_some_component
+
+        onclick emit "my_event"
+      end
+    }
+  end
+
+end
+```
 
 ## Async wrapper around static components
 
-Create a `custom static component` in `app/matestack/components/static/component.rb`
+Create a `custom static component` in `app/matestack/components/some/component.rb`
 
 ```ruby
-class Components::Static::Component < Matestack::Ui::StaticComponent
+class Components::Some::Component < Matestack::Ui::StaticComponent
 
   def response
     components {
@@ -50,7 +95,7 @@ To create a custom dynamic component (we will call our example one *FancyCompone
 While `custom static components` inherit from `Matestack::Ui::StaticComponent`, `custom dynamic component` inherit from *a different class*, namely `Matestack::Ui::DynamicComponent`:
 
 ```ruby
-class Fancy::Component < Matestack::Ui::DynamicComponent
+class Components::Fancy::Component < Matestack::Ui::DynamicComponent
 
   def response
     components {

docs/extend/custom_static_components.md

@@ -113,7 +113,7 @@ The output looks like this:
 
 ## Camelcased module or class names
 
-Components named in camelcase  are referenced to with their downcased counterpart!
+Components named in camelcase  are referenced with their downcased counterpart!
 As an example, define the camelcased component in `app/matestack/components/my_component.rb`
 
 ```ruby

spec/usage/extend/custom_component_spec.rb

@@ -29,7 +29,7 @@ def my_action
 
   end
 
-  it 'by orchestrating existing core components' do
+  it 'by orchestrating existing static core components' do
 
     module Components end
 
@@ -61,6 +61,75 @@ def response
 
     expect(page).to have_xpath('//div[@id="div-on-page"]/div[@id="my-component-1" and contains(.,"I\'m a static component!")]')
 
+  end
+
+  it 'by orchestrating existing dynamic core components' do
+
+    module Components end
+
+    class Components::Demo < Matestack::Ui::DynamicComponent
+
+      def response
+        components {
+          div id: 'my-component-1' do
+            plain "{{dynamic_value}}"
+          end
+        }
+      end
+
+    end
+
+    component_definition = <<~javascript
+
+      MatestackUiCore.Vue.component('custom-demo', {
+        mixins: [MatestackUiCore.componentMixin],
+        data: function data() {
+          return {
+            dynamic_value: "Show on pageview"
+          };
+        },
+        mounted(){
+          const self = this
+          setTimeout(function () {
+            self.dynamic_value = "Show after 300ms"
+          }, 300);
+        }
+      });
+
+    javascript
+
+    class Pages::ExamplePage < Matestack::Ui::Page
+
+      def response
+        components {
+          div id: 'div-on-page' do
+            # The async rerender is only used in this test
+            # because we add the Vue.js component definition
+            # during runtime and therefore need to
+            # re-initialize this DOM-part to trigger
+            # Vue.js to mount the component properly.
+            async rerender_on: "refresh" do
+              custom_demo
+            end
+          end
+        }
+      end
+
+    end
+
+    visit '/custom_component_test'
+
+    page.execute_script(component_definition)
+
+    # refresh script only needed in tests, see explanation on page definition above
+    page.execute_script('MatestackUiCore.matestackEventHub.$emit("refresh")')
+
+    expect(page).to have_content('Show on pageview')
+    sleep 0.5
+    expect(page).to have_content('Show after 300ms')
+
+
+
   end
 
   it 'by extending actionview components - static' do
@@ -107,7 +176,7 @@ def response
     module Components end
 
     class Components::TimeClick < Matestack::Ui::DynamicActionviewComponent
-      # class Components::TimeClick < Matestack::Ui::Core::Actionview::Dynamic # without alias
+    # class Components::TimeClick < Matestack::Ui::Core::Actionview::Dynamic # without alias
 
       def prepare
         @start_time = Time.now
@@ -147,6 +216,11 @@ class Pages::ExamplePage < Matestack::Ui::Page
       def response
         components {
           div id: 'div-on-page' do
+            # The async rerender is only used in this test
+            # because we add the Vue.js component definition
+            # during runtime and therefore need to
+            # re-initialize this DOM-part to trigger
+            # Vue.js to mount the component properly.
             async rerender_on: "refresh" do
               custom_timeClick
             end
@@ -159,6 +233,8 @@ def response
     visit '/custom_component_test'
 
     page.execute_script(component_definition)
+
+    # refresh script only needed in tests, see explanation on page definition above
     page.execute_script('MatestackUiCore.matestackEventHub.$emit("refresh")')
 
     expect(page).to have_content('Now I show: less than 5 seconds')