My App

# 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 ```ruby 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` ```ruby 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: ```markup My App <%= csrf_meta_tags %> <%= csp_meta_tag %> <%= stylesheet_link_tag 'application', media: 'all' %> <%= javascript_pack_tag 'application' %>

<%= yield %>

``` {% hint style="warning" %} Don't apply the "matestack-ui" id to the body tag. {% endhint %} {% hint style="success" %} `v-cloak` is used to avoid to hide un-compiled Vuejs templates until they are ready when using a CSS rule like: ```css [v-cloak] { display: none; } ``` This is optional but highly recommended for a better UI experience. More info here: {% endhint %} ### JavaScript installation #### Webpacker > 5.x based JavaScript installation {% content-ref url="/pages/MHMf6pYRbHieuLYIVrGC" %} [JS via Webpacker](/matestack-ui-bootstrap/getting-started/installation-update/js-via-webpacker.md) {% endcontent-ref %} #### Rails 7 importmap based installation {% content-ref url="/pages/3EkwLRPcFO6BmUZ7sZVv" %} [JS via Importmap](/matestack-ui-bootstrap/getting-started/installation-update/js-via-importmap.md) {% endcontent-ref %} #### JSBundling-Rails based installation {% content-ref url="/pages/FjEf090MVO5G5jP2nKdc" %} [JS via JSBundling-Rails](/matestack-ui-bootstrap/getting-started/installation-update/js-via-jsbundling-rails.md) {% endcontent-ref %} ### Icons setup {% hint style="warning" %} Same approach for all below described Stylesheet setups. Will be optimized in a future release! {% endhint %} Download and import Bootstraps icons: `app/assets/images/icons` * download latest compatible 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) {% hint style="info" %} 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. {% endhint %} `app/views/layout.html.erb` ```markup <%= 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) {% hint style="info" %} 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. {% endhint %} Install the `bootstrap gem` ```bash bundle add bootstrap ``` Add the asset path to `config/initializers/assets.rb` ```ruby 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` ```scss @import "bootstrap"; @import "matestack-ui-bootstrap"; ``` #### Option 2b : Importmap + CSSBundling-Rails {% hint style="info" %} Use this option if you have installed the JavaScript packages via Importmap and want to use SCSS features like Bootstrap theming {% endhint %} **Install cssbundling-rails** Like documented here: ```bash ./bin/bundle add cssbundling-rails ``` ```bash ./bin/rails css:install:bootstrap ``` And then add `matestack-ui-bootstrap`: ```bash yarn add matestack-ui-bootstrap ``` Afterwards make sure your package.json looks something like that: `package.json` ```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: ```scss @import 'bootstrap/scss/bootstrap'; @import 'matestack-ui-bootstrap/dist/stylesheets/matestack-ui-bootstrap'; ``` and run your server and css builder with ```bash ./bin/dev ``` #### Option 2c : JSBundling-Rails + CSSBundling-Rails {% hint style="info" %} Use this option if you have installed the JavaScript packages via JSBundling-Rails and want to use SCSS features like Bootstrap theming {% endhint %} not tested yet #### Option 3: Via Webpacker (SCSS) {% hint style="info" %} 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 {% endhint %} Tell Webpack to import Bootstraps CSS: `app/javascript/packs/stylesheets/application.scss` ```css @import "~bootstrap/scss/bootstrap.scss"; ``` `app/javascript/packs/application.js` ```javascript 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 {% hint style="warning" %} When you update the `matestack-ui-bootstrap` Ruby gem, make sure to update the npm package as well! {% endhint %} ### 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: ```bash bundle update matestack-ui-bootstrap ``` and then check the installed version: ```bash 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: ```bash yarn update matestack-ui-bootstrap ``` and finally check if the correct version is installed: ```bash yarn list --pattern "matestack-ui-bootstrap" ``` {% hint style="warning" %} The Ruby gem version and the NPM package version should match! {% endhint %} --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.matestack.io/matestack-ui-bootstrap/getting-started/installation-update.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.