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;
}

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

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)

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/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet">
<link href="https://cdn.jsdelivr.net/npm/matestack-ui-bootstrap@3.1.2/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!

PreviousMigrate to 3.0 NextJS via Webpacker

Last updated 2 years ago