Skip to content

Commit 8f31d98

Browse files
jonasjabarijonasjabari
committed
added v3 migration guide
1 parent d65b680 commit 8f31d98

File tree

1 file changed

+211
-23
lines changed

1 file changed

+211
-23
lines changed

‎V3_MIGRATION.md

Lines changed: 211 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,45 @@
11
# Installation & setup changes
22

3+
## Core/Vuejs repo and gem split
4+
5+
- `matestack-ui-core` previously contained logic for
6+
- Ruby -> HTML conversion
7+
- Reactivity via prebuilt and custom Vue.js components
8+
- in order to have better seperation of concerns, we've moved the reactivity related things to its own repository/gem -> `matestack-ui-vue_js`
9+
- `matestack-ui-core` is now meant to be combined with any reactivity framework or none at all
10+
11+
If you've used reactivity features of `matestack-ui-core` 2.x you now have to install `matestack-ui-vue_js` (Ruby Gem & NPM Package) additionally:
12+
13+
`Gemfile`
14+
```ruby
15+
gem 'matestack-ui-core', '~> 3.0'
16+
gem 'matestack-ui-vue_js', '~> 3.0'
17+
```
18+
19+
**only for `matestack-ui-vue_js` users!**
20+
21+
`package.json`
22+
```json
23+
{
24+
"name": "my-app",
25+
"dependencies": {
26+
"matestack-ui-vue_js": "^3.0.0", // <-- new package name
27+
"..."
28+
}
29+
}
30+
31+
```
32+
333
## IE 11 support dropped
434

35+
**only for `matestack-ui-vue_js` users!**
36+
537
- vue3 dropped IE 11 support
638
- when using babel alongside webpacker, please adjust your package.json or .browserslistrc config in order to exclude IE 11 support:
739

840
```json
941
{
10-
"name": "my app",
42+
"name": "my-app",
1143
"...": { },
1244
"browserslist": [
1345
"defaults",
@@ -16,10 +48,12 @@
1648
}
1749
```
1850

19-
Otherwise you may encounter issues around `regeneratorRuntime`
51+
Otherwise you may encounter issues around `regeneratorRuntime` (especially when using Vuex)
2052

2153
## Setup via webpacker
2254

55+
**only for `matestack-ui-vue_js` users!**
56+
2357
`config/webpack/environment.js`
2458
```js
2559
const { environment } = require('@rails/webpacker')
@@ -44,6 +78,8 @@ environment.config.merge(customWebpackConfig)
4478
module.exports = environment
4579
```
4680

81+
(don't forget to restart webpacker when changing this file!)
82+
4783
and then just use `import { whatever } from 'vue'` instead of `import { whatever } from 'vue/dist/vue.esm'`
4884

4985
**Optional: vue3 compat build usage**
@@ -76,31 +112,179 @@ environment.config.merge(customWebpackConfig)
76112
module.exports = environment
77113
```
78114

79-
# vue.js changes
115+
# Ruby related changes
116+
117+
## `Matestack::Ui::App` is now called `Matestack::Ui::Layout`
118+
119+
- `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
120+
- now `Matestack::Ui::App` is only a layout, that's why it should be named like that: `Matestack::Ui::Layout`
121+
122+
-> Search&Replace
123+
124+
## `matestack_app` method is renamed to `matestack_layout`
125+
126+
- following the above mentioned naming adjustment, the `matestack_app` method used on controller level is renamed to `matestack_layout`
127+
128+
`app/controllers/demo_controller.rb`
129+
```ruby
130+
class DemoController < ActionController::Base
131+
include Matestack::Ui::Core::Helper
132+
133+
layout "application" # root rails layout file
134+
135+
matestack_layout DemoApp::Layout # <-- renamed from matestack_app
136+
137+
def foo
138+
render DemoApp::Pages::Foo
139+
end
140+
141+
end
142+
```
143+
144+
# `Matestack::Ui::Layout` `Matestack::Ui::Page` wrapping DOM structures
145+
146+
- previously, `Matestack::Ui::App` added some wrapping DOM structure around the whole layout and around it's `yield`
147+
- this enabled dynamic page transition and loading state animations
148+
- `Matestack::Ui::Layout` now purely renders the layout and yields a page without anything in between
149+
- 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-vue_js` (see section below!)
150+
151+
`matestack/some/app/layout.rb`
152+
```ruby
153+
class Some::App::Layout < Matestack::Ui::Layout
154+
def response
155+
h1 "Demo App"
156+
main do
157+
yield
158+
end
159+
end
160+
end
161+
```
162+
163+
`matestack/some/app/pages/some_page.rb`
164+
```ruby
165+
class Some::App::Pages::SomePage < Matestack::Ui::Page
166+
def response
167+
h2 "Some Page"
168+
end
169+
end
170+
```
171+
172+
will just render:
173+
174+
```html
175+
<body> <!-- coming from rails layout if specified -->
176+
<!-- no wrapping DON structure around the layout -->
177+
<h1>Demo App</<h1>
178+
<main>
179+
<!-- page markup without any wrapping DOM structure -->
180+
<h2>Some Page</h2>
181+
<main>
182+
</body>
183+
```
184+
185+
## `Matestack::Ui::Layout` adjustments when using `matestack-ui-vue_js`
186+
187+
**only for `matestack-ui-vue_js` users!**
188+
189+
- `Matestack::Ui::Layout` classes are no longer automatically wrapped by a component tag meant to mount the matestack-ui-core-app component on it.
190+
- this has to be done manually via the `matestack_vue_js_app` component, which is more explicit and gives more flexibility
191+
- additionally, the `page_switch` component has to wrap the `yield` in order to support dynamic page transitions
192+
193+
`matestack/some/vue_js/app/layout.rb`
194+
```ruby
195+
class Some::VueJs::App::Layout < Matestack::Ui::Layout
196+
197+
def response
198+
h1 "Demo VueJs App"
199+
matestack_vue_js_app do # <-- this one
200+
main do
201+
page_switch do # <-- and this one
202+
yield
203+
end
204+
end
205+
end
206+
end
207+
208+
end
209+
```
210+
211+
- using these components will add the original wrapping DOM structres which enables loading state animations
212+
- new `<matestack-component-tempate>` will be rendered coming from these two new components
213+
214+
```html
215+
<body> <!-- coming from rails layout if specified -->
216+
<div id="matestack-ui"> <!-- coming from rails layout if specified -->
217+
<h1>Demo VueJs App</h1>
218+
<matestack-component-tempate> <!-- new tag rendered since 3.0, should not break anything -->
219+
<div class="matestack-app-wrapper">
220+
<main>
221+
<matestack-component-tempate> <!-- new tag rendered since 3.0, should not break anything -->
222+
<div class="matestack-page-container">
223+
<div class="matestack-page-wrapper">
224+
<div> <!--this div is necessary for conditonal switch to async template via v-if -->
225+
<div class="matestack-page-root">
226+
your page markup
227+
</div>
228+
</div>
229+
</div>
230+
</div>
231+
</matestack-component-tempate>
232+
</main>
233+
</div>
234+
</matestack-component-tempate>
235+
</div>
236+
</body>
237+
```
238+
239+
## `id="matestack-ui"` element can be removed from rails application layout when only using `matestack-ui-core`
240+
241+
**only for `matestack-ui-vue_js` users!**
242+
243+
- if you only use `matestack-ui-core`, you can remove the `id="matestack-ui"` element
244+
- if you use `matestack-ui-vue_js`, this is still required!
245+
246+
`app/views/layouts/application.html.erb`
247+
```html
248+
<body>
249+
<div id="matestack-ui"> <!-- you can remove this div with the matestack-ui ID when not using `matestack-ui-vue_js` -->
250+
<%= yield %>
251+
</div>
252+
</body>
253+
```
254+
255+
# Vuejs related changes in order to support vue3
256+
257+
**only for `matestack-ui-vue_js` users!**
258+
259+
## `MatestackUiCore` is now `MatestackUiVueJs`
260+
261+
- following the repo/gem split, the Vue.js related libary is now called `MatestackUiVueJs`
262+
263+
-> Search&Replace
80264

81265
## app definition and mount
82266

83267
`javascript/packs/application.js`
84268
```js
85269
import { createApp } from 'vue'
86-
import MatestackUiCore from 'matestack-ui-core'
270+
import MatestackUiVueJs from 'matestack-ui-vue_js'
87271

88272
const appInstance = createApp({})
89273

90274
document.addEventListener('DOMContentLoaded', () => {
91-
MatestackUiCore.mount(appInstance, '#matestack-ui') // use this mount method
275+
MatestackUiVueJs.mount(appInstance) // use this mount method
92276
})
93277
```
94278

95279
## custom component registration
96280

97281
`some/component/file.js`
98282
```js
99-
import MatestackUiCore from 'matestack-ui-core'
283+
import MatestackUiVueJs from 'matestack-ui-vue_js'
100284

101285
const myComponent = {
102-
mixins: [MatestackUiCore.componentMixin],
103-
template: MatestackUiCore.componentHelpers.inlineTemplate,
286+
mixins: [MatestackUiVueJs.componentMixin],
287+
template: MatestackUiVueJs.componentHelpers.inlineTemplate,
104288
data() {
105289
return {
106290
foo: "bar"
@@ -117,7 +301,7 @@ export default myComponent
117301
`javascript/packs/application.js`
118302
```js
119303
import { createApp } from 'vue'
120-
import MatestackUiCore from 'matestack-ui-core'
304+
import MatestackUiVueJs from 'matestack-ui-vue_js'
121305

122306
import myComponent from 'some/component/file.js' // import component definition from source
123307

@@ -126,21 +310,21 @@ const appInstance = createApp({})
126310
appInstance.component('my-component', myComponent) // register at appInstance
127311

128312
document.addEventListener('DOMContentLoaded', () => {
129-
MatestackUiCore.mount(appInstance, '#matestack-ui')
313+
MatestackUiVueJs.mount(appInstance)
130314
})
131315
```
132316

133317
## component template
134318

135-
- For application components, apply `template: MatestackUiCore.componentHelpers.inlineTemplate`
319+
- For application components, apply `template: MatestackUiVueJs.componentHelpers.inlineTemplate`
136320

137321
`some/component/file.js`
138322
```js
139-
import MatestackUiCore from 'matestack-ui-core'
323+
import MatestackUiVueJs from 'matestack-ui-vue_js'
140324

141325
const myComponent = {
142-
mixins: [MatestackUiCore.componentMixin],
143-
template: MatestackUiCore.componentHelpers.inlineTemplate, // this one!
326+
mixins: [MatestackUiVueJs.componentMixin],
327+
template: MatestackUiVueJs.componentHelpers.inlineTemplate, // this one!
144328
data() {
145329
return {
146330
foo: "bar"
@@ -160,15 +344,15 @@ export default myComponent
160344

161345
## component scope prefix
162346

163-
- use `vc.` or `vueComponent.` in order to prefix all properties references or method calls within your vue.js component `response`
347+
- use `vc.` (short for vue component) in order to prefix all properties references or method calls within your vue.js component `response`
164348

165349
`some/component/file.js`
166350
```js
167-
import MatestackUiCore from 'matestack-ui-core'
351+
import MatestackUiVueJs from 'matestack-ui-vue_js'
168352

169353
const myComponent = {
170-
mixins: [MatestackUiCore.componentMixin],
171-
template: MatestackUiCore.componentHelpers.inlineTemplate,
354+
mixins: [MatestackUiVueJs.componentMixin],
355+
template: MatestackUiVueJs.componentHelpers.inlineTemplate,
172356
data() {
173357
return {
174358
foo: "bar"
@@ -201,22 +385,26 @@ end
201385

202386
- use `this.getRefs()` instead of `this.$refs`
203387

388+
-> Search&Replace
389+
204390
## component $el
205391

206392
- use `this.getElement()` instead of `this.$el`
207393

394+
-> Search&Replace
395+
208396
## component beforeDestroy hook
209397

210398
- `beforeDestroy` was renamed to `beforeUnmount` within vue3
211-
- Search&Replace if your're using this hook in any of your vue components
399+
400+
-> Search&Replace
212401

213402
## $set, Vue.set
214403

215404
- `this.$set` and `Vue.set` are removed in vue3 as they are not longer required for proper reactivity binding
216405
- If you use these methods, use plain JavaScript mutations instead
217406

218-
# ruby changes
219-
220-
## matestack wrapper method
407+
## Vuex store dependency removed
221408

222-
- removed, app wrapping is done within the app class directly now
409+
- previously a Vuex store was required and by default available. Now it's optional
410+
- you can add a store manually following the official Vuex 4.x docs

0 commit comments

Comments
 (0)