Skip to content

Commit c404f9e

Browse files
jonasjabarijonasjabari
committed
adjusted install and migration guides, updated component integration guides
1 parent 67684da commit c404f9e

File tree

8 files changed

+338
-93
lines changed

8 files changed

+338
-93
lines changed

‎docs/SUMMARY.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@
66
## Getting Started
77

88
* [Installation & Update](getting-started/installation-update.md)
9-
* [Quick Start \[WIP\]](getting-started/quick-start.md)
9+
* [Hello world](getting-started/hello-world.md)
1010

1111
## API
1212

‎docs/getting-started/hello-world.md‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
# Hello world \[WIP\]
2+
3+
{% hint style="info" %}
4+
We're about to add much more content to this guide. Stay tuned!
5+
6+
Until we have more content in place here, it might be a good idea to review the source code of the [dummy app](https://dummy.matestack.io), which can be found here: [https://github.com/matestack/matestack-ui-bootstrap/tree/main/spec/dummy](https://github.com/matestack/matestack-ui-bootstrap/tree/main/spec/dummy)
7+
8+
That should already give you a good idea how to use `matestack-ui-bootstrap`
9+
{% endhint %}
10+
11+
## Usage
12+
13+
Create Matestack layouts, pages and components as described in the docs of `matestack-ui-core` and `matestack-ui-vuejs` and utilize the components described in the following docs sections in order to create your UI.

‎docs/getting-started/installation-update.md‎

Lines changed: 152 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -2,30 +2,63 @@
22

33
## Installation
44

5-
Make sure to install and get to know `matestack-ui-core` first! [https://docs.matestack.io/matestack-ui-core](https://docs.matestack.io/matestack-ui-core)
5+
Make sure to install and get to know `matestack-ui-core` and `matestack-ui-vuejs` first!
66

7-
Add the Ruby gem and NPM package:
7+
- [https://docs.matestack.io/matestack-ui-core](https://docs.matestack.io/matestack-ui-core)
8+
- [https://docs.matestack.io/matestack-ui-vuejs](https://docs.matestack.io/matestack-ui-vuejs)
89

9-
```text
10-
bundle add 'matestack-ui-bootstrap'
11-
yarn add 'matestack-ui-bootstrap'
10+
## Installation
11+
12+
Add 'matestack-ui-bootstrap' to your Gemfile
13+
14+
```ruby
15+
gem 'matestack-ui-bootstrap', "~> 3.0.0.rc1"
1216
```
1317

14-
Adjust the relevant application layout and add a div with the ID `matestack-ui`
18+
and run
1519

16-
`app/views/layouts/application.html.erb`
20+
```
21+
$ bundle install
22+
```
1723

18-
```text
24+
### Matestack Ui Core/VueJs install steps (if not already happened)
25+
26+
Create a folder called 'matestack' in your app directory. All your Matestack apps, pages and components will be defined there.
27+
28+
```
29+
$ mkdir app/matestack
30+
```
31+
32+
Add the Matestack helper to your controllers. If you want to make the helpers available in all controllers, add it to your 'ApplicationController' this way:
33+
34+
`app/controllers/application_controller.rb`
35+
36+
```ruby
37+
class ApplicationController < ActionController::Base
38+
include Matestack::Ui::Core::Helper
39+
#...
40+
end
41+
```
42+
43+
You need to add the ID "matestack-ui" to some part of your application layout (or any layout you use). That's required for Matestack's Vue.js to work properly!
44+
45+
For Example, your `app/views/layouts/application.html.erb` should look like this:
46+
47+
```markup
1948
<!DOCTYPE html>
2049
<html>
2150
<head>
22-
<title>Your App</title>
23-
<meta name="viewport" content="width=device-width,initial-scale=1">
51+
<title>My App</title>
2452
<%= csrf_meta_tags %>
2553
<%= csp_meta_tag %>
2654
27-
<%= stylesheet_link_tag 'application', media: 'all'%>
28-
<%= javascript_pack_tag 'application'%>
55+
<%= stylesheet_link_tag 'application', media: 'all' %>
56+
57+
<!-- if you are using webpacker: -->
58+
<%= javascript_pack_tag 'application' %>
59+
60+
<!-- if you are using the asset pipeline: -->
61+
<%= javascript_include_tag 'application' %>
2962
</head>
3063
3164
<body>
@@ -36,6 +69,102 @@ Adjust the relevant application layout and add a div with the ID `matestack-ui`
3669
</html>
3770
```
3871

72+
{% hint style="warning" %}
73+
Don't apply the "matestack-ui" id to the body tag.
74+
{% endhint %}
75+
76+
### JavaScript installation
77+
78+
#### Rails 7 importmap based installation
79+
80+
will be shipped in `matestack-ui-bootstrap` `3.1`
81+
82+
#### Webpacker > 5.x based JavaScript installation
83+
84+
Add 'matestack-ui-vuejs' to your `package.json` by running:
85+
86+
```
87+
$ yarn add [email protected]
88+
```
89+
90+
This adds the npm package that provides the JavaScript corresponding to the matestack-ui-bootstrap Ruby gem. Make sure that the npm package version matches the gem version. To find out what gem version you are using, you may use `bundle info matestack-ui-bootstrap`.
91+
92+
**Note**:
93+
94+
* vue3 dropped IE 11 support
95+
* when using babel alongside webpacker, please adjust your package.json or .browserslistrc config in order to exclude IE 11 support:
96+
97+
```json
98+
{
99+
"name": "my-app",
100+
"...": { },
101+
"browserslist": [
102+
"defaults",
103+
"not IE 11" // <-- important!
104+
]
105+
}
106+
```
107+
108+
Otherwise you may encounter issues around `regeneratorRuntime` (especially when using Vuex)
109+
110+
Next, import and setup 'matestack-ui-vuejs' in your `app/javascript/packs/application.js`
111+
112+
```javascript
113+
import { createApp } from 'vue'
114+
import MatestackUiVueJs from 'matestack-ui-vuejs'
115+
116+
import MatestackUiBootstrap from 'matestack-ui-bootstrap' // add this
117+
118+
const appInstance = createApp({})
119+
120+
MatestackUiBootstrap.registerComponents(appInstance) // add this
121+
122+
document.addEventListener('DOMContentLoaded', () => {
123+
MatestackUiVueJs.mount(appInstance)
124+
})
125+
```
126+
127+
and properly configure webpack:
128+
129+
`config/webpack/environment.js`
130+
131+
```javascript
132+
const { environment } = require('@rails/webpacker')
133+
const webpack = require('webpack');
134+
135+
const customWebpackConfig = {
136+
resolve: {
137+
alias: {
138+
vue: 'vue/dist/vue.esm-bundler',
139+
}
140+
},
141+
plugins: [
142+
new webpack.DefinePlugin({
143+
__VUE_OPTIONS_API__: true,
144+
__VUE_PROD_DEVTOOLS__: false
145+
})
146+
]
147+
}
148+
149+
environment.config.merge(customWebpackConfig)
150+
151+
module.exports = environment
152+
```
153+
154+
(don't forget to restart webpacker when changing this file!)
155+
156+
and then finally compile the JavaScript code with webpack:
157+
158+
```
159+
$ bin/webpack --watch
160+
```
161+
162+
{% hint style="warning" %}
163+
When you update the `matestack-ui-bootstrap` Ruby gem, make sure to update the npm package as well!
164+
{% endhint %}
165+
166+
### Stylesheet/Icon setup
167+
39168
Tell Webpack to import Bootstraps CSS:
40169

41170
`app/javascript/packs/stylesheets/application.scss`
@@ -49,38 +178,27 @@ Import the required JS libraries and mount MatestackUiCore and MatestackUiBootst
49178
`app/javascript/packs/application.js`
50179

51180
```javascript
52-
import Rails from "@rails/ujs"
53-
// import Turbolinks from "turbolinks"
54-
import * as ActiveStorage from "@rails/activestorage"
55-
import "channels"
181+
import "./stylesheets/application.scss"; // add this
56182

57-
import "./stylesheets/application.scss";
183+
import { createApp } from 'vue'
184+
import MatestackUiVueJs from 'matestack-ui-vuejs'
58185

59-
import Vue from 'vue/dist/vue.esm'
60-
import Vuex from 'vuex'
186+
import MatestackUiBootstrap from 'matestack-ui-bootstrap'
61187

62-
import MatestackUiCore from 'matestack-ui-core'
63-
import MatestackUiBootstrap from "matestack-ui-bootstrap"
188+
const appInstance = createApp({})
64189

65-
let matestackUiApp = undefined
190+
MatestackUiBootstrap.registerComponents(appInstance)
66191

67192
document.addEventListener('DOMContentLoaded', () => {
68-
matestackUiApp = new Vue({
69-
el: "#matestack-ui",
70-
store: MatestackUiCore.store
71-
})
193+
MatestackUiVueJs.mount(appInstance)
72194
})
73-
74-
Rails.start()
75-
// Turbolinks.start()
76-
ActiveStorage.start()
77195
```
78196

79197
Download and import Bootstraps icons:
80198

81199
`app/assets/images/icons`
82200

83-
* download latest compatible icons: [https://github.com/twbs/icons/releases/tag/v1.3.0](https://github.com/twbs/icons/releases/tag/v1.3.0)
201+
* download latest compatible icons: [https://github.com/twbs/icons/releases/tag/v1.8.1](https://github.com/twbs/icons/releases/tag/v1.8.1)
84202
* extract the bootstrap-icons.svg to this path: app/assets/images/icons \(currently served via assets pipeline, we had issues serving the icons via Webpack\)
85203

86204
and finally compile the code with webpack:
@@ -89,12 +207,12 @@ and finally compile the code with webpack:
89207
$ bin/webpack --watch
90208
```
91209

210+
## Update
211+
92212
{% hint style="warning" %}
93213
When you update the `matestack-ui-bootstrap` Ruby gem, make sure to update the npm package as well!
94214
{% endhint %}
95215

96-
## Update
97-
98216
### Ruby Gem
99217

100218
Depending on the entry in your Gemfile, you might need to adjust the allowed version ranges in order to update the Gem. After checked and adjusted the version ranges, run:
@@ -109,7 +227,7 @@ and then check the installed version:
109227
bundle info matestack-ui-bootstrap
110228
```
111229

112-
### JavaScript Package
230+
### JavaScript Package via Yarn
113231

114232
If you've installed the JavaScript dependecies via Yarn/Webpacker you need to update the JavaScript assets via yarn:
115233

@@ -126,4 +244,3 @@ yarn list --pattern "matestack-ui-bootstrap"
126244
{% hint style="warning" %}
127245
The Ruby gem version and the NPM package version should match!
128246
{% endhint %}
129-

‎docs/getting-started/quick-start.md‎

Lines changed: 0 additions & 36 deletions
This file was deleted.

0 commit comments

Comments
 (0)