Installation & Update

Installation

Make sure to install and get to know matestack-ui-core and matestack-ui-vuejs first!
Add 'matestack-ui-bootstrap' to your Gemfile
1
gem 'matestack-ui-bootstrap', "~> 3.0.0.rc2"
Copied!
and run
1
$ bundle install
Copied!

Matestack Ui Core/VueJs install steps (if not already happened)

Create a folder called 'matestack' in your app directory. All your Matestack apps, pages and components will be defined there.
1
$ mkdir app/matestack
Copied!
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:
app/controllers/application_controller.rb
1
class ApplicationController < ActionController::Base
2
include Matestack::Ui::Core::Helper
3
#...
4
end
Copied!
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!
For Example, your app/views/layouts/application.html.erb should look like this:
1
<!DOCTYPE html>
2
<html>
3
<head>
4
<title>My App</title>
5
<%= csrf_meta_tags %>
6
<%= csp_meta_tag %>
7
8
<%= stylesheet_link_tag 'application', media: 'all' %>
9
10
<!-- if you are using webpacker: -->
11
<%= javascript_pack_tag 'application' %>
12
</head>
13
14
<body>
15
<div id="matestack-ui">
16
<%= yield %>
17
</div>
18
</body>
19
</html>
Copied!
Don't apply the "matestack-ui" id to the body tag.

JavaScript installation

Rails 7 importmap based installation

will be shipped in matestack-ui-bootstrap 3.1

Webpacker > 5.x based JavaScript installation

Add 'matestack-ui-vuejs' to your package.json by adding:
1
{
2
"name": "my-app",
3
"dependencies": {
4
"matestack-ui-bootstrap": "^3.0.0-rc2",
5
"..."
6
}
7
}
Copied!
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.
Note:
  • 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:
1
{
2
"name": "my-app",
3
"...": { },
4
"browserslist": [
5
"defaults",
6
"not IE 11" // <-- important!
7
]
8
}
Copied!
Otherwise you may encounter issues around regeneratorRuntime (especially when using Vuex)
Next, import and setup 'matestack-ui-vuejs' in your app/javascript/packs/application.js
1
import { createApp } from 'vue'
2
import MatestackUiVueJs from 'matestack-ui-vuejs'
3
4
import MatestackUiBootstrap from 'matestack-ui-bootstrap' // add this
5
6
const appInstance = createApp({})
7
8
MatestackUiBootstrap.registerComponents(appInstance) // add this
9
10
document.addEventListener('DOMContentLoaded', () => {
11
MatestackUiVueJs.mount(appInstance)
12
})
Copied!
and properly configure webpack:
config/webpack/environment.js
1
const { environment } = require('@rails/webpacker')
2
const webpack = require('webpack');
3
4
const customWebpackConfig = {
5
resolve: {
6
alias: {
7
vue: 'vue/dist/vue.esm-bundler',
8
}
9
},
10
plugins: [
11
new webpack.DefinePlugin({
12
__VUE_OPTIONS_API__: true,
13
__VUE_PROD_DEVTOOLS__: false
14
})
15
]
16
}
17
18
environment.config.merge(customWebpackConfig)
19
20
module.exports = environment
Copied!
(don't forget to restart webpacker when changing this file!)
and then finally compile the JavaScript code with webpack:
1
$ bin/webpack --watch
Copied!
When you update the matestack-ui-bootstrap Ruby gem, make sure to update the npm package as well!

Stylesheet/Icon setup

Tell Webpack to import Bootstraps CSS:
app/javascript/packs/stylesheets/application.scss
1
@import "~bootstrap/scss/bootstrap.scss";
Copied!
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:
app/javascript/packs/application.js
1
import "./stylesheets/application.scss"; // add this
2
3
import { createApp } from 'vue'
4
import MatestackUiVueJs from 'matestack-ui-vuejs'
5
6
import MatestackUiBootstrap from 'matestack-ui-bootstrap'
7
8
const appInstance = createApp({})
9
10
MatestackUiBootstrap.registerComponents(appInstance)
11
12
document.addEventListener('DOMContentLoaded', () => {
13
MatestackUiVueJs.mount(appInstance)
14
})
Copied!
Download and import Bootstraps icons:
app/assets/images/icons
and finally compile the code with webpack:
1
$ bin/webpack --watch
Copied!

Update

When you update the matestack-ui-bootstrap Ruby gem, make sure to update the npm package as well!

Ruby Gem

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:
1
bundle update matestack-ui-bootstrap
Copied!
and then check the installed version:
1
bundle info matestack-ui-bootstrap
Copied!

JavaScript Package via Yarn

If you've installed the JavaScript dependecies via Yarn/Webpacker you need to update the JavaScript assets via yarn:
1
yarn update matestack-ui-bootstrap
Copied!
and finally check if the correct version is installed:
1
yarn list --pattern "matestack-ui-bootstrap"
Copied!
The Ruby gem version and the NPM package version should match!