Skip to content

Commit 70e475e

Browse files
jonasjabarigitbook-bot
jonasjabari
authored and
gitbook-bot
committed
GitBook: [#7] Added importmap/cssbundling-rails install docs, restructuring JS install docs
1 parent 9087ff2 commit 70e475e

File tree

5 files changed

+276
-83
lines changed

5 files changed

+276
-83
lines changed

‎docs/SUMMARY.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,10 @@
66

77
## Getting Started
88

9-
* [Installation & Update](getting-started/installation-update.md)
9+
* [Installation & Update](getting-started/installation-update/README.md)
10+
* [JS via Webpacker](getting-started/installation-update/js-via-webpacker.md)
11+
* [JS via JSBundling-Rails](getting-started/installation-update/js-via-jsbundling-rails.md)
12+
* [JS via Importmap](getting-started/installation-update/js-via-importmap.md)
1013
* [Hello world](getting-started/hello-world.md)
1114

1215
## API

‎docs/getting-started/installation-update.md renamed to ‎docs/getting-started/installation-update/README.md

Lines changed: 80 additions & 82 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Make sure to install and get to know `matestack-ui-core` and `matestack-ui-vuejs
1010
Add 'matestack-ui-bootstrap' to your Gemfile
1111

1212
```ruby
13-
gem 'matestack-ui-bootstrap', "~> 3.0.0.rc2"
13+
gem 'matestack-ui-bootstrap', "~> 3.1.0"
1414
```
1515

1616
and run
@@ -72,99 +72,114 @@ Don't apply the "matestack-ui" id to the body tag.
7272

7373
#### Rails 7 importmap based installation
7474

75-
will be shipped in `matestack-ui-bootstrap` `3.1`
75+
{% content-ref url="js-via-importmap.md" %}
76+
[js-via-importmap.md](js-via-importmap.md)
77+
{% endcontent-ref %}
7678

7779
#### Webpacker > 5.x based JavaScript installation
7880

79-
Add 'matestack-ui-vuejs' to your `package.json` by adding:
81+
{% content-ref url="js-via-webpacker.md" %}
82+
[js-via-webpacker.md](js-via-webpacker.md)
83+
{% endcontent-ref %}
8084

81-
```
82-
{
83-
"name": "my-app",
84-
"dependencies": {
85-
"matestack-ui-bootstrap": "^3.0.0-rc2",
86-
"..."
87-
}
88-
}
89-
```
85+
#### JSBundling-Rails based installation
9086

91-
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`.
87+
{% content-ref url="js-via-jsbundling-rails.md" %}
88+
[js-via-jsbundling-rails.md](js-via-jsbundling-rails.md)
89+
{% endcontent-ref %}
9290

93-
**Note**:
91+
### Icons setup
9492

95-
* vue3 dropped IE 11 support
96-
* when using babel alongside webpacker, please adjust your package.json or .browserslistrc config in order to exclude IE 11 support:
93+
{% hint style="warning" %}
94+
Same approach for all below described Stylesheet setups. Will be optimized in a future release!
95+
{% endhint %}
9796

98-
```json
99-
{
100-
"name": "my-app",
101-
"...": { },
102-
"browserslist": [
103-
"defaults",
104-
"not IE 11" // <-- important!
105-
]
106-
}
97+
Download and import Bootstraps icons:
98+
99+
`app/assets/images/icons`
100+
101+
* download latest compatible icons: [https://github.com/twbs/icons/releases/tag/v1.8.1](https://github.com/twbs/icons/releases/tag/v1.8.1)
102+
* extract the bootstrap-icons.svg to this path: app/assets/images/icons (currently served via assets pipeline, we had issues not using the asset pipeline)
103+
104+
### Stylesheet Setup
105+
106+
#### Option 1: Via CDN (CSS only)
107+
108+
{% hint style="info" %}
109+
This option makes sense if you're using the importmap approach for the JS setup and are looking for a minimal setup in order to pull in the required styles. You cannot use SCSS features though.
110+
{% endhint %}
111+
112+
`app/views/layout.html.erb`
113+
114+
```markup
115+
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet">
116+
<link href="https://cdn.jsdelivr.net/npm/matestack-ui-bootstrap@3.1.0/dist/matestack-ui-bootstrap.css" rel="stylesheet" >
117+
118+
<%= javascript_importmap_tags %>
107119
```
108120

109-
Otherwise you may encounter issues around `regeneratorRuntime` (especially when using Vuex)
121+
Please adjust the version numbers to your needs. They should match the JavaScript package versions used in the importmap config.
110122

111-
Next, import and setup 'matestack-ui-vuejs' in your `app/javascript/packs/application.js`
123+
#### Option 2a : Importmap + CSSBundling-Rails
112124

113-
```javascript
114-
import { createApp } from 'vue'
115-
import MatestackUiVueJs from 'matestack-ui-vuejs'
125+
{% hint style="info" %}
126+
Use this option if you have installed the JavaScript packages via Importmap and want to use SCSS features like Bootstrap theming
127+
{% endhint %}
116128

117-
import MatestackUiBootstrap from 'matestack-ui-bootstrap' // add this
129+
**Install cssbundling-rails**
118130

119-
const appInstance = createApp({})
131+
Like documented here: [https://github.com/rails/cssbundling-rails](https://github.com/rails/cssbundling-rails)
120132

121-
MatestackUiBootstrap.registerComponents(appInstance) // add this
133+
```bash
134+
./bin/bundle add cssbundling-rails
135+
```
122136

123-
document.addEventListener('DOMContentLoaded', () => {
124-
MatestackUiVueJs.mount(appInstance)
125-
})
137+
```bash
138+
./bin/rails css:install:bootstrap
126139
```
127140

128-
and properly configure webpack:
141+
Afterwards make sure your package.json looks something like that:
129142

130-
`config/webpack/environment.js`
143+
`package.json`
131144

132-
```javascript
133-
const { environment } = require('@rails/webpacker')
134-
const webpack = require('webpack');
135-
136-
const customWebpackConfig = {
137-
resolve: {
138-
alias: {
139-
vue: 'vue/dist/vue.esm-bundler',
140-
}
145+
```json
146+
{
147+
"name": "your-app",
148+
"private": "true",
149+
"dependencies": {
150+
"@popperjs/core": "^2.11.5",
151+
"bootstrap": "^5.2.0-beta1",
152+
"bootstrap-icons": "^1.8.3",
153+
"sass": "^1.52.2"
141154
},
142-
plugins: [
143-
new webpack.DefinePlugin({
144-
__VUE_OPTIONS_API__: true,
145-
__VUE_PROD_DEVTOOLS__: false
146-
})
147-
]
155+
"scripts": {
156+
"build:css": "sass ./app/assets/stylesheets/application.bootstrap.scss ./app/assets/builds/application.css --no-source-map --load-path=node_modules"
157+
}
148158
}
149159

150-
environment.config.merge(customWebpackConfig)
151-
152-
module.exports = environment
153160
```
154161

155-
(don't forget to restart webpacker when changing this file!)
162+
Even if you use the importmap approach, this package.json will install the JavaScript packages into the node\_modules folder. They will not be used when following the importmap approach. Only the SCSS files will be used in this case.
156163

157-
and then finally compile the JavaScript code with webpack:
164+
And finally add the `matestack-ui-bootstrap.css` file to your layout via CDN. Alternatively you can download this file and let it be served via Sprockets.
158165

159-
```
160-
$ bin/webpack --watch
166+
`app/views/layout.html.erb`
167+
168+
```markup
169+
<link href="https://cdn.jsdelivr.net/npm/matestack-ui-bootstrap@3.1.0/dist/matestack-ui-bootstrap.css" rel="stylesheet" >
161170
```
162171

163-
{% hint style="warning" %}
164-
When you update the `matestack-ui-bootstrap` Ruby gem, make sure to update the npm package as well!
172+
#### Option 2b : JSBundling-Rails + CSSBundling-Rails
173+
174+
{% hint style="info" %}
175+
Use this option if you have installed the JavaScript packages via JSBundling-Rails and want to use SCSS features like Bootstrap theming
165176
{% endhint %}
166177

167-
### Stylesheet/Icon setup
178+
#### Option 3: Via Webpacker (SCSS)
179+
180+
{% hint style="info" %}
181+
Use this option if you have installed the JavaScript packages via Webpacker as well in order to be able to use SCSS features like Bootstrap theming
182+
{% endhint %}
168183

169184
Tell Webpack to import Bootstraps CSS:
170185

@@ -174,35 +189,18 @@ Tell Webpack to import Bootstraps CSS:
174189
@import "~bootstrap/scss/bootstrap.scss";
175190
```
176191

177-
Import the required JS libraries and mount MatestackUiCore and MatestackUiBootstrap properly. We recommend to remove Turbolinks, as it might interfere with some of the reactivity feature of Matestack:
178-
179192
`app/javascript/packs/application.js`
180193

181194
```javascript
182195
import "./stylesheets/application.scss"; // add this
183196

184197
import { createApp } from 'vue'
185198
import MatestackUiVueJs from 'matestack-ui-vuejs'
186-
187199
import MatestackUiBootstrap from 'matestack-ui-bootstrap'
188-
189-
const appInstance = createApp({})
190-
191-
MatestackUiBootstrap.registerComponents(appInstance)
192-
193-
document.addEventListener('DOMContentLoaded', () => {
194-
MatestackUiVueJs.mount(appInstance)
195-
})
200+
// ...
196201
```
197202

198-
Download and import Bootstraps icons:
199-
200-
`app/assets/images/icons`
201-
202-
* download latest compatible icons: [https://github.com/twbs/icons/releases/tag/v1.8.1](https://github.com/twbs/icons/releases/tag/v1.8.1)
203-
* 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)
204-
205-
and finally compile the code with webpack:
203+
and compile with:
206204

207205
```
208206
$ bin/webpack --watch

‎docs/getting-started/installation-update/js-via-importmap.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
---
2+
description: shipped in matestack-ui-bootstrap 3.1
3+
---
4+
5+
# JS via Importmap
6+
7+
Please follow the importmap install guide for `matestack-ui-vuejs` first: [https://docs.matestack.io/matestack-ui-vuejs/getting-started/installation-update/importmap-install-steps](https://docs.matestack.io/matestack-ui-vuejs/getting-started/installation-update/importmap-install-steps)
8+
9+
### Pins
10+
11+
Please add the pins manually:
12+
13+
`config/importmap.rb`
14+
15+
```ruby
16+
# pins for matestack-ui-vuejs
17+
pin "vue", to: "https://ga.jspm.io/npm:vue@3.2.31/dist/vue.esm-browser.js" if Rails.env.development?
18+
pin "vue", to: "https://ga.jspm.io/npm:vue@3.2.31/dist/vue.esm-browser.prod.js" if Rails.env.production?
19+
pin "matestack-ui-vuejs", to: "https://cdn.jsdelivr.net/npm/matestack-ui-vuejs@3.1.0/dist/matestack-ui-vuejs.esm.js"
20+
# below pins for matestack-ui-boostrap
21+
pin "@popperjs/core", to: "https://unpkg.com/@popperjs/core@2/dist/esm/popper.js"
22+
pin "bootstrap", to: "https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/js/bootstrap.esm.min.js"
23+
pin "matestack-ui-bootstrap", to: "https://cdn.jsdelivr.net/npm/matestack-ui-bootstrap@3.1.0/dist/matestack-ui-bootstrap.esm.js"
24+
```
25+
26+
### Usage
27+
28+
`app/javascript/packs/application.js`
29+
30+
```javascript
31+
import { createApp } from 'vue'
32+
import MatestackUiVueJs from 'matestack-ui-vuejs'
33+
import MatestackUiBootstrap from 'matestack-ui-bootstrap' // add this
34+
35+
const appInstance = createApp({})
36+
37+
MatestackUiBootstrap.registerComponents(appInstance) // add this
38+
39+
document.addEventListener('DOMContentLoaded', () => {
40+
MatestackUiVueJs.mount(appInstance)
41+
})
42+
43+
```
44+
45+
### (S)CSS setup
46+
47+
#### Without cssbundling-rails
48+
49+
`app/views/layout.html.erb`
50+
51+
```markup
52+
<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet">
53+
<link href="https://cdn.jsdelivr.net/npm/matestack-ui-bootstrap@3.1.0/dist/matestack-ui-bootstrap.css" rel="stylesheet" >
54+
55+
<%= javascript_importmap_tags %>
56+
```
57+
58+
Please adjust the version numbers to your needs. They should match the JavaScript package versions used in the importmap config.
59+
60+
#### With cssbundling-rails
61+
62+
\--> In order to use SCSS features e.g. for Bootstrap theming&#x20;
63+
64+
(without jsbundling-rails, using importmap approach for JavaScript assets instead in this guide)
65+
66+
**Install cssbundling-rails**
67+
68+
Like documented here: [https://github.com/rails/cssbundling-rails](https://github.com/rails/cssbundling-rails)
69+
70+
```bash
71+
./bin/bundle add cssbundling-rails
72+
```
73+
74+
```bash
75+
./bin/rails css:install:bootstrap
76+
```
77+
78+
Afterwards make sure your package.json looks something like that:
79+
80+
`package.json`
81+
82+
```json
83+
{
84+
"name": "your-app",
85+
"private": "true",
86+
"dependencies": {
87+
"@popperjs/core": "^2.11.5",
88+
"bootstrap": "^5.2.0-beta1",
89+
"bootstrap-icons": "^1.8.3",
90+
"sass": "^1.52.2"
91+
},
92+
"scripts": {
93+
"build:css": "sass ./app/assets/stylesheets/application.bootstrap.scss ./app/assets/builds/application.css --no-source-map --load-path=node_modules"
94+
}
95+
}
96+
97+
```
98+
99+
This package.json will install all the JavaScript packages pinned via importmap config into the node\_modules folder. We just use the scss parts of it. Alternativel to the `importmap` approach, you could use `jsbundling-rails`

‎docs/getting-started/installation-update/js-via-jsbundling-rails.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
# JS via JSBundling-Rails
2+

0 commit comments

Comments
 (0)