# Installation & Update ## Installation Add 'matestack-ui-core' to your Gemfile ```ruby gem 'matestack-ui-core' ``` and run ``` $ bundle install ``` ### Matestack folder Create a folder called 'matestack' in your app directory. All your Matestack apps, pages and components will be defined there. ``` $ mkdir app/matestack ``` ### Controller setup 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::ApplicationHelper #... end ``` Now, you are able to create UI components in pure Ruby and use them in your Rails views. Additionally you can substitute Rails views and layouts with Matestack pages and apps. If you want to use Matestack's optional reactivity features in pure Ruby (through dynamic Vue.js components such as `form` and `async` or dynamic page transitions), please perform the next steps to set up the JavaScript parts via AssetPipeline or Webpacker. {% hint style="info" %} Matestack's JavaScript is only required if you want to use reactive features. It's totally valid to just use the "static" features of Matestack, namely implement UI components, pages and apps in pure Ruby. {% endhint %} ### Webpacker Add 'matestack-ui-core' to your `package.json` by running: ``` $ yarn add matestack-ui-core ``` This adds the npm package that provides the JavaScript corresponding to the matestack-ui-core 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-core`. Next, import 'matestack-ui-core' in your `app/javascript/packs/application.js` ```javascript import MatestackUiCore from 'matestack-ui-core' ``` and compile the JavaScript code with webpack: ``` $ bin/webpack --watch ``` {% hint style="warning" %} When you update the `matestack-ui-core` Ruby gem, make sure to update the npm package as well! {% endhint %} ### Asset Pipeline If you are using the asset pipeline, you don't need to install the separate npm package. All required JavaScript libraries are provided by the `matestack-ui-core` gem. Require `matestack-ui-core` in your `app/assets/javascript/application.js` ```javascript //= require matestack-ui-core ``` ### Turbolinks We recommend to (remove/deactivate)() turbolinks, as there is no reason to use it alongside matestack-ui-core and there might appear some strange side effects. If you encounter strange page-transition/form-submit/action-submit behavior and have turbolinks activated, try to deactivate it first. ### Application layout adjustments 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' %> <%= javascript_include_tag 'application' %>
<%= yield %>
``` {% hint style="warning" %} Don't apply the "matestack-ui" id to the body tag. {% endhint %} ### ActionCable Integration Some of Matestack's reactive core components may be used with or require ActionCable. If you want to use ActionCable, please read the action cable guide: {% content-ref url="../integrations/action-cable" %} [action-cable](https://docs.matestack.io/matestack-ui-core/1.5.0/integrations/action-cable) {% endcontent-ref %} ## Update ### 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-core ``` and then check the installed version: ```bash bundle info matestack-ui-core ``` ### JavaScript via AssetPipeline/Sprockets If you've installed the JavaScript dependecies via AssetPipeline/Sprockets, updating the Ruby gem is enough! Nothing to do here! ### JavaScript 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-core ``` and finally check if the correct version is installed: ```bash yarn list --pattern "matestack-ui-core" ``` {% hint style="warning" %} The Ruby gem version and the npm package version should match! {% endhint %}