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
gem 'matestack-ui-bootstrap', "~> 3.1.0"
and run
$ bundle install

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.
$ mkdir app/matestack
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
class ApplicationController < ActionController::Base
include Matestack::Ui::Core::Helper
#...
end
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:
<!DOCTYPE html>
<html>
<head>
<title>My App</title>
<%= csrf_meta_tags %>
<%= csp_meta_tag %>
<%= stylesheet_link_tag 'application', media: 'all' %>
<!-- if you are using webpacker: -->
<%= javascript_pack_tag 'application' %>
</head>
<body>
<div id="matestack-ui" v-cloak>
<%= yield %>
</div>
</body>
</html>
Don't apply the "matestack-ui" id to the body tag.
v-cloak is used to avoid to hide un-compiled Vuejs templates until they are ready when using a CSS rule like:
[v-cloak] {
display: none;
}
This is optional but highly recommended for a better UI experience. More info here: https://vuejs.org/api/built-in-directives.html#v-cloak

JavaScript installation

Webpacker > 5.x based JavaScript installation

Rails 7 importmap based installation

JSBundling-Rails based installation

Icons setup

Same approach for all below described Stylesheet setups. Will be optimized in a future release!
Download and import Bootstraps icons:
app/assets/images/icons

Stylesheet Setup

Option 1: Via CDN (CSS only)

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.
app/views/layout.html.erb
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/stylesheets/matestack-ui-bootstrap.css" rel="stylesheet" >
<%= javascript_importmap_tags %>
Please adjust the version numbers to your needs. They should match the JavaScript package versions used in the importmap config.

Option 2a : Importmap + Sprockets/SassC (SCSS without node and yarn)

This option makes sense if you're using the importmap approach for the JS setup and are looking for a minimal setup without node and yarn involved in order to pull in the required styles and use SCSS features.
Install the bootstrap gem
bundle add bootstrap
Add the asset path to config/initializers/assets.rb
Rails.application.config.assets.paths << Rails.root.join("app/matestack")
Rails.application.config.assets.paths << File.join(Gem::Specification.find_by_name("matestack-ui-bootstrap").gem_dir, 'dist/stylesheets')
Import the scss files in your app/assets/stylesheets/application.scss
@import "bootstrap";
@import "matestack-ui-bootstrap";

Option 2b : Importmap + CSSBundling-Rails

Use this option if you have installed the JavaScript packages via Importmap and want to use SCSS features like Bootstrap theming
Install cssbundling-rails
./bin/bundle add cssbundling-rails
./bin/rails css:install:bootstrap
And then add matestack-ui-bootstrap:
yarn add matestack-ui-bootstrap
Afterwards make sure your package.json looks something like that:
package.json
{
"name": "your-app",
"private": "true",
"dependencies": {
"@popperjs/core": "^2.11.5",
"bootstrap": "^5.2.0-beta1",
"bootstrap-icons": "^1.8.3",
"sass": "^1.52.2",
"matestack-ui-bootstrap": "^3.1.0"
},
"scripts": {
"build:css": "sass ./app/assets/stylesheets/application.bootstrap.scss ./app/assets/builds/application.css --no-source-map --load-path=node_modules"
}
}
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 (S)CSS files will be used in this case.
And finally adjust the app/assets/stylesheets/application.bootstrap.scss to look like:
@import 'bootstrap/scss/bootstrap';
@import 'matestack-ui-bootstrap/dist/stylesheets/matestack-ui-bootstrap';
and run your server and css builder with
./bin/dev

Option 2c : JSBundling-Rails + CSSBundling-Rails

Use this option if you have installed the JavaScript packages via JSBundling-Rails and want to use SCSS features like Bootstrap theming
not tested yet

Option 3: Via Webpacker (SCSS)

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
Tell Webpack to import Bootstraps CSS:
app/javascript/packs/stylesheets/application.scss
@import "~bootstrap/scss/bootstrap.scss";
app/javascript/packs/application.js
import "./stylesheets/application.scss"; // add this
import { createApp } from 'vue'
import MatestackUiVueJs from 'matestack-ui-vuejs'
import MatestackUiBootstrap from 'matestack-ui-bootstrap'
// ...
and compile with:
$ bin/webpack --watch

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

JavaScript Package via Yarn

If you've installed the JavaScript dependecies via Yarn/Webpacker you need to update the JavaScript assets via yarn:
yarn update matestack-ui-bootstrap
and finally check if the correct version is installed:
yarn list --pattern "matestack-ui-bootstrap"
The Ruby gem version and the NPM package version should match!
Copy link
Outline
Installation
Matestack Ui Core/VueJs install steps (if not already happened)
JavaScript installation
Icons setup
Stylesheet Setup
Update
Ruby Gem
JavaScript Package via Yarn