[TASK] extend basic building blocks guide

Author: Nils Henning

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    matestack-ui-core (1.0.0.rc.1)
+    matestack-ui-core (1.0.0)
       cells-haml
       cells-rails
       haml
@@ -233,7 +233,7 @@ GEM
       activesupport (>= 4.2)
       rack-proxy (>= 0.6.1)
       railties (>= 4.2)
-    websocket-driver (0.7.2)
+    websocket-driver (0.7.3)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
     xpath (3.2.0)

docs/api/000-base/app.md renamed to docs/api/000-base/00-app.md

@@ -129,7 +129,7 @@ markup. See below, how you can pass in data to the VueJs JavaScript component.
 ### Same as component
 
 The basic VueJs Ruby component API is the same as described within the
-[component API documenation](/docs/api/000-base/component.md). The options below extend
+[component API documenation](/docs/api/000-base/20-component.md). The options below extend
 this API.
 
 ### Referencing the VueJs JavaScript component
@@ -216,9 +216,9 @@ class SomeComponent < Matestack::Ui::VueJsComponent
 end
 ```
 
-### Eventhub
+### Event Hub
 
-Matestack offers an eventhub, which can be used to communicate between components.
+Matestack offers an event hub, which can be used to communicate between components.
 
 #### Emitting events
 

docs/api/000-base/page.md renamed to docs/api/000-base/10-page.md

@@ -0,0 +1,47 @@
+### Event Hub
+
+Matestack offers an event hub, which can be used to communicate between components.
+
+#### Emitting events
+
+`app/matestack/components/some_component.js`
+
+```javascript
+MatestackUiCore.Vue.component('some-component', {
+  mixins: [MatestackUiCore.componentMixin],
+  data() {
+    return {}
+  },
+  mounted(){
+    MatestackUiCore.matestackEventHub.$emit("some-event", { some: "optional data" })
+  }
+})
+```
+
+Use `MatestackUiCore.matestackEventHub.$emit(EVENT_NAME, OPTIONAL PAYLOAD)`
+
+#### Receiving events
+
+`app/matestack/components/some_component.js`
+
+```javascript
+MatestackUiCore.Vue.component('some-component', {
+  mixins: [MatestackUiCore.componentMixin],
+  data() {
+    return {}
+  },
+  methods: {
+    reactToEvent(payload){
+      console.log(payload)
+    }
+  },
+  mounted(){
+    MatestackUiCore.matestackEventHub.$on("some-event", this.reactToEvent)
+  },
+  beforeDestroy: function() {
+    matestackEventHub.$off("some-event", this.reactToEvent)
+  }
+})
+```
+
+Make sure to cancel the event listener within the `beforeDestroy` hook!

docs/api/000-base/component.md renamed to docs/api/000-base/20-component.md

@@ -47,7 +47,7 @@ meant to be used for simple rendering of content and other components. Matestack
 will simply render the UI defined within the `response` method without any
 wrapping elements by default.
 
-[Read more](/docs/api/000-base/component.md)
+[Read more](/docs/api/000-base/20-component.md)
 
 #### VueJsComponent
 
@@ -59,7 +59,7 @@ Ruby component. The VueJs JavaScript component (defined in a separate JavaScript
 managed via Sprockets or Webpacker) will treat the response of the Ruby
 component as its template.
 
-[Read more](/docs/api/000-base/vue_js_component.md)
+[Read more](/docs/api/000-base/30-vue_js_component.md)
 
 #### IsolatedComponent
 
@@ -70,7 +70,7 @@ response defined in the Ruby component. Additionally, Matestack wraps the
 component's `response` with some DOM elements enabling asynchronous loading
 state animations.
 
-[Read more](/docs/api/000-base/isolated_component.md)
+[Read more](/docs/api/000-base/40-isolated_component.md)
 
 ### Core Components
 
@@ -101,7 +101,7 @@ A page is a special kind of `Matestack::Ui::VueJsComponent`. Matestack will
 therefore wrap the UI defined in the `response` method with some markup enabling
 dynamic UI behavior and CSS styling.
 
-Learn more about [pages](/docs/api/000-base/page.md)
+Learn more about [pages](/docs/api/000-base/10-page.md)
 
 ## Apps
 
@@ -116,4 +116,4 @@ The app ships a `Vuex store` and `Vue.js event hub`, which are used by core vuej
 components and can optionally be used by custom vuejs components in order to
 trigger events, manage client side date and communicate between components.
 
-Learn more about [apps](/docs/api/000-base/app.md)
+Learn more about [apps](/docs/api/000-base/10-app.md)