Merge branch '20200914_improve-and-extend-documentation'

Author: Nils Henning

CHANGELOG.md

@@ -121,6 +121,7 @@ app/matestack/
 and your corresponding controllers could look like this:
 
 `app/controllers/admin_controller.rb`
+
 ```ruby
 class AdminController < ApplicationController
   include Matestack::Ui::Core::ApplicationHelper
@@ -137,6 +138,7 @@ end
 ```
 
 `app/controllers/website_controller.rb`
+
 ```ruby
 class WebsiteController < ApplicationController
   include Matestack::Ui::Core::ApplicationHelper
@@ -181,6 +183,7 @@ This auto resolving is being completely removed in the `1.0.0` release. All comp
 *Core components*
 
 `CORE_ROOT/lib/matestack/ui/core/components.rb`
+
 ```ruby
 module Matestack::Ui::Core::Components
   #...
@@ -202,6 +205,7 @@ The registered DSL method `some_new_component` does not have to match the compon
 Create a registry module like:
 
 `APP_ROOT/app/matestack/components/registry.rb`
+
 ```ruby
 module Components::Registry
 
@@ -573,7 +577,7 @@ We reworked the form components quite a bit:
 - options passed as hashes in to `form_select`, `form_radio` and `form_checkbox` are now expected to be { label_value: input_value } and thus the other way around. Until 0.7.6 it was { input_value: label_value }
 - and added a lot of new features, such as customizing the error rendering.
 
-We invested a lot of time to improve the `form` API docs found [here](/docs/api/components/form.md).
+We invested a lot of time to improve the `form` API docs found [here](/docs/api/100-components/form.md).
 
 - [ ] Please make sure to read through the docs and migrate your forms accordingly!
 
@@ -708,6 +712,7 @@ To render existing rails views inside your components or pages, use the new `rai
 You can render existing partials and views with this helper anywhere in your app. For further information read the `rails_view` documentation.
 
 Let's say you have an old view file in `app/views/example/partial.html.erb`
+
 ```html
 <p>An example text in a Rails view</p>
 ```
@@ -1075,13 +1080,15 @@ none
 ***OLD:***
 
 `app/matestack/app/example_app.rb`
+
 ```ruby
 class Apps::ExampleApp < App::Cell::App end
 ```
 
 ***NEW:***
 
 `app/matestack/app/example_app.rb`
+
 ```ruby
 class Apps::ExampleApp < Matestack::Ui::App end
 ```
@@ -1091,13 +1098,15 @@ class Apps::ExampleApp < Matestack::Ui::App end
 ***OLD:***
 
 `app/matestack/pages/example_app/example_page.rb`
+
 ```ruby
 class Pages::ExampleApp::ExamplePage < Page::Cell::Page end
 ```
 
 ***NEW:***
 
 `app/matestack/pages/example_app/example_page.rb`
+
 ```ruby
 class Pages::ExampleApp::ExamplePage < Matestack::Ui::Page end
 ```
@@ -1107,13 +1116,15 @@ class Pages::ExampleApp::ExamplePage < Matestack::Ui::Page end
 ***OLD:***
 
 `app/matestack/components/card/cell/card.rb`
+
 ```ruby
 class Components::Card::Cell::Card < Component::Cell::Static end
 ```
 
 ***NEW:***
 
 `app/matestack/components/card.rb`
+
 ```ruby
 class Components::Card < Matestack::Ui::StaticComponent end
 ```
@@ -1123,23 +1134,27 @@ class Components::Card < Matestack::Ui::StaticComponent end
 ***OLD:***
 
 `app/matestack/components/card/cell/card.rb`
+
 ```ruby
 class Components::Card::Cell::Card < Component::Cell::Dynamic end
 ```
 
 `app/matestack/components/card/cell/card.js`
+
 ```javascript
 MatestackUiCore.Vue.component('custom-card-cell', { ... });
 ```
 
 ***NEW:***
 
 `app/matestack/components/card.rb`
+
 ```ruby
 class Components::Card < Matestack::Ui::DynamicComponent end
 ```
 
 `app/matestack/components/card.js`
+
 ```javascript
 MatestackUiCore.Vue.component('custom-card', { ... }); //no -cell postfix
 ```
@@ -1149,6 +1164,7 @@ MatestackUiCore.Vue.component('custom-card', { ... }); //no -cell postfix
 ***OLD:***
 
 `app/matestack/pages/example_app/example_page.rb`
+
 ```ruby
 class Pages::ExampleApp::ExamplePage < Matestack::Ui::Page
 
@@ -1166,6 +1182,7 @@ end
 ***NEW:***
 
 `app/matestack/pages/example_app/example_page.rb`
+
 ```ruby
 class Pages::ExampleApp::ExamplePage < Matestack::Ui::Page
 
@@ -1197,6 +1214,7 @@ app/concepts/matestack/ui/core
 ```
 
 `app/concepts/matestack/ui/core/div/div.rb`
+
 ```ruby
 module Matestack::Ui::Core::Div
   class Div < Matestack::Ui::Core::Component::Static
@@ -1213,6 +1231,7 @@ We also removed the `Cell` module (`cell` folder) and the separate `js` and `vie
 Last module name and class name of CORE components have to be the same. That doesn't apply for CUSTOM components:
 
 `app/matestack/pages/example_app/example_page.rb`
+
 ```ruby
 class Pages::ExampleApp::ExamplePage < Matestack::Ui::Page
 
@@ -1254,6 +1273,7 @@ Scoping all core components within `Matestack::Ui::Core` is reflected in differe
 Example: `async` core component
 
 `app/concepts/matestack/ui/core/async`
+
 ```javascript
 //old
 Vue.component('async-cell', componentDef)
@@ -1278,6 +1298,7 @@ ADDON_ENGINE_ROOT/app/concepts/matestack/ui/materialize
 ```
 
 `ADDON_ENGINE_ROOT/app/concepts/matestack/ui/materialize/row/row.rb`
+
 ```ruby
 module Matestack::Ui::Materialize::Row
   class Row < Matestack::Ui::Core::Component::Static
@@ -1296,6 +1317,7 @@ end
 Usage:
 
 `app/matestack/pages/example_app/example_page.rb`
+
 ```ruby
 class Pages::ExampleApp::ExamplePage < Matestack::Ui::Page
 

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/1-base/app.md renamed to docs/api/000-base/00-app.md

@@ -155,4 +155,4 @@ and during async page request triggered via transition:
 
 You can use the `loading` class and your loading state element to implement CSS based loading state effects.
 
-For more informations on transitions, visit [transitions](/docs/api/2-components/transition.md)
+For more informations on transitions, visit [transitions](/docs/api/100-components/transition.md)

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

@@ -15,6 +15,7 @@ components and custom components are registered slightly different:
 Create a registry module like:
 
 `APP_ROOT/app/matestack/components/registry.rb`
+
 ```ruby
 module Components::Registry
 
@@ -52,6 +53,7 @@ will be available without having to restart the server.
 ### Core component registry
 
 `CORE_ROOT/lib/matestack/ui/core/components.rb`
+
 ```ruby
 module Matestack::Ui::Core::Components
   #...

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

@@ -17,6 +17,7 @@ A VueJs component is defined by two files. A Ruby file and a JavaScript file:
 Within the Ruby file, the Ruby class inherits from `Matestack::Ui::VueJsComponent`:
 
 `app/matestack/components/some_component.rb`
+
 ```ruby
 class SomeComponent < Matestack::Ui::VueJsComponent
 
@@ -37,6 +38,7 @@ one root element! Disregarding this rule will lead to Vue.js errors in the brows
 This Ruby class has to be registered like all other components:
 
 `app/matestack/components/registry.rb`
+
 ```ruby
 module Components::Registry
   Matestack::Ui::Core::Component::Registry.register_components(
@@ -51,6 +53,7 @@ end
 The VueJs JavaScript component is defined in a separate JavaScript file:
 
 `app/matestack/components/some_component.js`
+
 ```javascript
 MatestackUiCore.Vue.component('some-component', {
   mixins: [MatestackUiCore.componentMixin],
@@ -126,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/1-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
@@ -135,6 +138,7 @@ As seen above, the VueJs JavaScript component name has to be referenced in the V
 Ruby component using the `vue_js_component_name` class method
 
 `app/matestack/components/some_component.rb`
+
 ```ruby
 class SomeComponent < Matestack::Ui::VueJsComponent
 
@@ -151,6 +155,7 @@ the component tag. In order to fill in some date there, you should use the `setu
 method like this:
 
 `app/matestack/components/some_component.rb`
+
 ```ruby
 class SomeComponent < Matestack::Ui::VueJsComponent
 
@@ -176,6 +181,7 @@ within the VueJs JavaScript component.
 ### Component mixin
 
 `app/matestack/components/some_component.js`
+
 ```javascript
 MatestackUiCore.Vue.component('some-component', {
   mixins: [MatestackUiCore.componentMixin],
@@ -197,6 +203,7 @@ this.componentConfig["some_serverside_data"]
 if implemented like
 
 `app/matestack/components/some_component.rb`
+
 ```ruby
 class SomeComponent < Matestack::Ui::VueJsComponent
 
@@ -209,13 +216,14 @@ 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
 
 `app/matestack/components/some_component.js`
+
 ```javascript
 MatestackUiCore.Vue.component('some-component', {
   mixins: [MatestackUiCore.componentMixin],
@@ -233,6 +241,7 @@ 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],

docs/api/1-base/vue_js_component.md renamed to docs/api/000-base/30-vue_js_component.md

@@ -61,7 +61,7 @@ Furthermore isolated components have to be authorized independently. See below.
 
 ## Differences to the `async` component
 
-The [`async` component](docs/api/2-components/core/async.md) offers pretty similar
+The [`async` component](docs/api/100-components/core/async.md) offers pretty similar
 functionalities enabling you to define asynchronous rendering. The important difference
 is that rerendering an `async` component requires resolving the whole page on the serverside,
 which can be performance critical on complex pages. An isolated component bypasses
@@ -112,13 +112,13 @@ rendered within a secured context.
 That's why we enforce the usage of the `authorized?` method to make sure, all isolated
 components take care of their authorization themselves.
 
-If `authorized?` return `true`, the component will be rendered. If it returns `false`,
+If `authorized?` returns `true`, the component will be rendered. If it returns `false`,
 the component will not be rendered.
 
 A public isolated component therefore needs an `authorized?` method simply returning `true`.
 
 You can create your own isolated base components with their `authorized` methods
-for your use cases and thus keep your code DRY
+for your use cases and thus keep your code DRY.
 
 ### Options
 

docs/api/1-base/isolated_component.md renamed to docs/api/000-base/40-isolated_component.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!