GitBook: [#8] No subject

Author: jonasjabari

docs/migrate-to-3.0.md

@@ -1,22 +1,26 @@
-# Installation & setup changes
+# Migrating to 3.0
 
-## Core/Vuejs repo and gem split
+## Installation & setup changes
 
-- `matestack-ui-core` previously contained logic for
-  - Ruby -> HTML conversion
-  - Reactivity via prebuilt and custom Vue.js components
-- in order to have better seperation of concerns, we've moved the reactivity related things to its own repository/gem -> `matestack-ui-vuejs`
-- `matestack-ui-core` is now meant to be combined with any reactivity framework or none at all
+### Core/Vuejs repo and gem split
+
+* `matestack-ui-core` previously contained logic for
+  * Ruby -> HTML conversion
+  * Reactivity via prebuilt and custom Vue.js components
+* in order to have better seperation of concerns, we've moved the reactivity related things to its own repository/gem -> `matestack-ui-vuejs`
+* `matestack-ui-core` is now meant to be combined with any reactivity framework or none at all
 
 If you've used reactivity features of `matestack-ui-core` 2.x you now have to install `matestack-ui-vuejs` (Ruby Gem & NPM Package) additionally:
 
 `Gemfile`
+
 ```ruby
 gem 'matestack-ui-core', '~> 3.0'
 gem 'matestack-ui-vuejs', '~> 3.0'
 ```
 
 `package.json`
+
 ```json
 {
   "name": "my-app",
@@ -25,14 +29,12 @@ gem 'matestack-ui-vuejs', '~> 3.0'
     "..."
   }
 }
-
 ```
 
-## IE 11 support dropped
-
+### IE 11 support dropped
 
-- vue3 dropped IE 11 support
-- when using babel alongside webpacker, please adjust your package.json or .browserslistrc config in order to exclude IE 11 support:
+* vue3 dropped IE 11 support
+* when using babel alongside webpacker, please adjust your package.json or .browserslistrc config in order to exclude IE 11 support:
 
 ```json
 {
@@ -47,11 +49,11 @@ gem 'matestack-ui-vuejs', '~> 3.0'
 
 Otherwise you may encounter issues around `regeneratorRuntime` (especially when using Vuex)
 
-## Setup via webpacker
-
+### Setup via webpacker
 
 `config/webpack/environment.js`
-```js
+
+```javascript
 const { environment } = require('@rails/webpacker')
 const webpack = require('webpack');
 
@@ -80,12 +82,13 @@ and then just use `import { whatever } from 'vue'` instead of `import { whatever
 
 **Optional: vue3 compat build usage**
 
-- if you're using any vue2 APIs (or one of the libraries you're using), you can use the vue3 compat build
-- this enables you to use both vue2 and vue3 APIs and migrate step by step
-- usage via webpack config when using webpacker 5.x and up:
+* if you're using any vue2 APIs (or one of the libraries you're using), you can use the vue3 compat build
+* this enables you to use both vue2 and vue3 APIs and migrate step by step
+* usage via webpack config when using webpacker 5.x and up:
 
 `config/webpack/environment.js`
-```js
+
+```javascript
 const { environment } = require('@rails/webpacker')
 const webpack = require('webpack')
 
@@ -108,20 +111,21 @@ environment.config.merge(customWebpackConfig)
 module.exports = environment
 ```
 
-# Ruby related changes
+## Ruby related changes
 
-## `Matestack::Ui::App` is now called `Matestack::Ui::Layout`
+### `Matestack::Ui::App` is now called `Matestack::Ui::Layout`
 
-- `Matestack::Ui::App` was always meant to be a layout wrapping pages, but was supercharged with some vuejs logic before splitting the `core` and `vuejs` repos
-- now `Matestack::Ui::App` is only a layout, that's why it should be named like that: `Matestack::Ui::Layout`
+* `Matestack::Ui::App` was always meant to be a layout wrapping pages, but was supercharged with some vuejs logic before splitting the `core` and `vuejs` repos
+* now `Matestack::Ui::App` is only a layout, that's why it should be named like that: `Matestack::Ui::Layout`
 
--> Search&Replace
+\-> Search\&Replace
 
-## `matestack_app` method is renamed to `matestack_layout`
+### `matestack_app` method is renamed to `matestack_layout`
 
-- following the above mentioned naming adjustment, the `matestack_app` method used on controller level is renamed to `matestack_layout`
+* following the above mentioned naming adjustment, the `matestack_app` method used on controller level is renamed to `matestack_layout`
 
 `app/controllers/demo_controller.rb`
+
 ```ruby
 class DemoController < ActionController::Base
   include Matestack::Ui::Core::Helper
@@ -137,14 +141,15 @@ class DemoController < ActionController::Base
 end
 ```
 
-# `Matestack::Ui::Layout` `Matestack::Ui::Page` wrapping DOM structures
+## `Matestack::Ui::Layout` `Matestack::Ui::Page` wrapping DOM structures
 
-- previously, `Matestack::Ui::App` added some wrapping DOM structure around the whole layout and around it's `yield`
-- this enabled dynamic page transition and loading state animations
-- `Matestack::Ui::Layout` now purely renders the layout and yields a page without anything in between
-- the wrapping DOM structres required for dynamic page transitions and loading state animations needs to be added via two new components if you want to use these features via `matestack-ui-vuejs` (see section below!)
+* previously, `Matestack::Ui::App` added some wrapping DOM structure around the whole layout and around it's `yield`
+* this enabled dynamic page transition and loading state animations
+* `Matestack::Ui::Layout` now purely renders the layout and yields a page without anything in between
+* the wrapping DOM structres required for dynamic page transitions and loading state animations needs to be added via two new components if you want to use these features via `matestack-ui-vuejs` (see section below!)
 
 `matestack/some/app/layout.rb`
+
 ```ruby
 class Some::App::Layout < Matestack::Ui::Layout
   def response
@@ -157,6 +162,7 @@ end
 ```
 
 `matestack/some/app/pages/some_page.rb`
+
 ```ruby
 class Some::App::Pages::SomePage < Matestack::Ui::Page
   def response
@@ -178,14 +184,14 @@ will just render:
 </body>
 ```
 
-## `Matestack::Ui::Layout` adjustments when using `matestack-ui-vuejs`
-
+### `Matestack::Ui::Layout` adjustments when using `matestack-ui-vuejs`
 
-- `Matestack::Ui::Layout` classes are no longer automatically wrapped by a component tag meant to mount the matestack-ui-core-app component on it.
-- this has to be done manually via the `matestack_vue_js_app` component, which is more explicit and gives more flexibility
-- additionally, the `page_switch` component has to wrap the `yield` in order to support dynamic page transitions
+* `Matestack::Ui::Layout` classes are no longer automatically wrapped by a component tag meant to mount the matestack-ui-core-app component on it.
+* this has to be done manually via the `matestack_vue_js_app` component, which is more explicit and gives more flexibility
+* additionally, the `page_switch` component has to wrap the `yield` in order to support dynamic page transitions
 
 `matestack/some/vue_js/app/layout.rb`
+
 ```ruby
 class Some::VueJs::App::Layout < Matestack::Ui::Layout
 
@@ -203,8 +209,8 @@ class Some::VueJs::App::Layout < Matestack::Ui::Layout
 end
 ```
 
-- using these components will add the original wrapping DOM structres which enables loading state animations
-- new `<matestack-component-tempate>` will be rendered coming from these two new components
+* using these components will add the original wrapping DOM structres which enables loading state animations
+* new `<matestack-component-tempate>` will be rendered coming from these two new components
 
 ```html
 <body> <!-- coming from rails layout if specified -->
@@ -231,19 +237,19 @@ end
 </body>
 ```
 
-# Vuejs related changes in order to support vue3
+## VueJs related changes in order to support vue3
 
+### `MatestackUiCore` is now `MatestackUiVueJs`
 
-## `MatestackUiCore` is now `MatestackUiVueJs`
+* following the repo/gem split, the Vue.js related libary is now called `MatestackUiVueJs`
 
-- following the repo/gem split, the Vue.js related libary is now called `MatestackUiVueJs`
+\-> Search\&Replace
 
--> Search&Replace
-
-## app definition and mount
+### app definition and mount
 
 `javascript/packs/application.js`
-```js
+
+```javascript
 import { createApp } from 'vue'
 import MatestackUiVueJs from 'matestack-ui-vuejs'
 
@@ -254,10 +260,11 @@ document.addEventListener('DOMContentLoaded', () => {
 })
 ```
 
-## custom component registration
+### custom component registration
 
 `some/component/file.js`
-```js
+
+```javascript
 import MatestackUiVueJs from 'matestack-ui-vuejs'
 
 const myComponent = {
@@ -277,7 +284,8 @@ export default myComponent
 ```
 
 `javascript/packs/application.js`
-```js
+
+```javascript
 import { createApp } from 'vue'
 import MatestackUiVueJs from 'matestack-ui-vuejs'
 
@@ -292,12 +300,13 @@ document.addEventListener('DOMContentLoaded', () => {
 })
 ```
 
-## component template
+### component template
 
-- For application components, apply `template: MatestackUiVueJs.componentHelpers.inlineTemplate`
+* For application components, apply `template: MatestackUiVueJs.componentHelpers.inlineTemplate`
 
 `some/component/file.js`
-```js
+
+```javascript
 import MatestackUiVueJs from 'matestack-ui-vuejs'
 
 const myComponent = {
@@ -316,16 +325,17 @@ const myComponent = {
 export default myComponent
 ```
 
-- Only for core components
-  - add import `import componentHelpers from 'some/relative/path/to/helpers'`
-  - and then apply `template: componentHelpers.inlineTemplate`
+* Only for core components
+  * add import `import componentHelpers from 'some/relative/path/to/helpers'`
+  * and then apply `template: componentHelpers.inlineTemplate`
 
-## component scope prefix
+### component scope prefix
 
-- use `vc.` (short for vue component) in order to prefix all properties references or method calls within your vue.js component `response`
+* use `vc.` (short for vue component) in order to prefix all properties references or method calls within your vue.js component `response`
 
 `some/component/file.js`
-```js
+
+```javascript
 import MatestackUiVueJs from 'matestack-ui-vuejs'
 
 const myComponent = {
@@ -359,30 +369,30 @@ class Components::MyComponent < Matestack::Ui::VueJsComponent
 end
 ```
 
-## component $refs
+### component $refs
 
-- use `this.getRefs()` instead of `this.$refs`
+* use `this.getRefs()` instead of `this.$refs`
 
--> Search&Replace
+\-> Search\&Replace
 
-## component $el
+### component $el
 
-- use `this.getElement()` instead of `this.$el`
+* use `this.getElement()` instead of `this.$el`
 
--> Search&Replace
+\-> Search\&Replace
 
-## component beforeDestroy hook
+### component beforeDestroy hook
 
-- `beforeDestroy` was renamed to `beforeUnmount` within vue3
+* `beforeDestroy` was renamed to `beforeUnmount` within vue3
 
--> Search&Replace
+\-> Search\&Replace
 
-## $set, Vue.set
+### $set, Vue.set
 
-- `this.$set` and `Vue.set` are removed in vue3 as they are not longer required for proper reactivity binding
-- If you use these methods, use plain JavaScript mutations instead
+* `this.$set` and `Vue.set` are removed in vue3 as they are not longer required for proper reactivity binding
+* If you use these methods, use plain JavaScript mutations instead
 
-## Vuex store dependency removed
+### Vuex store dependency removed
 
-- previously a Vuex store was required and by default available. Now it's optional
-- you can add a store manually following the official Vuex 4.x docs
+* previously a Vuex store was required and by default available. Now it's optional
+* you can add a store manually following the official Vuex 4.x docs