Installation & Update

Installation

Add 'matestack-ui-core' to your Gemfile
1
gem 'matestack-ui-core'
Copied!
and run
1
$ bundle install
Copied!

Matestack folder

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!

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
1
class ApplicationController < ActionController::Base
2
include Matestack::Ui::Core::Helper
3
#...
4
end
Copied!
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 Webpacker.
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.

Webpacker

Add 'matestack-ui-core' to your package.json by running:
1
$ yarn add matestack-ui-core
Copied!
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 and setup 'matestack-ui-core' in your app/javascript/packs/application.js
1
import Vue from 'vue/dist/vue.esm'
2
import Vuex from 'vuex'
3
4
import MatestackUiCore from 'matestack-ui-core'
5
6
let matestackUiApp = undefined
7
8
document.addEventListener('DOMContentLoaded', () => {
9
matestackUiApp = new Vue({
10
el: "#matestack-ui",
11
store: MatestackUiCore.store
12
})
13
})
Copied!
and compile the JavaScript code with webpack:
1
$ bin/webpack --watch
Copied!
When you update the matestack-ui-core Ruby gem, make sure to update the npm package as well!
If you want to use matestack-ui-core alongside with Turbolinks or Turbo, please add:
1
yarn add vue-turbolinks
Copied!
And use following snippet instead:
1
import Vue from 'vue/dist/vue.esm'
2
import Vuex from 'vuex'
3
4
import MatestackUiCore from 'matestack-ui-core'
5
6
import TurbolinksAdapter from 'vue-turbolinks'; // import vue-turbolinks
7
Vue.use(TurbolinksAdapter); // tell Vue to use it
8
9
let matestackUiApp = undefined
10
11
// change the trigger event
12
document.addEventListener('turbolinks:load', () => {
13
matestackUiApp = new Vue({
14
el: "#matestack-ui",
15
store: MatestackUiCore.store
16
})
17
})
18
Copied!

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:
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
13
<!-- if you are using the asset pipeline: -->
14
<%= javascript_include_tag 'application' %>
15
</head>
16
17
<body>
18
<div id="matestack-ui">
19
<%= yield %>
20
</div>
21
</body>
22
</html>
Copied!
Don't apply the "matestack-ui" id to the body tag.

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:

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:
1
bundle update matestack-ui-core
Copied!
and then check the installed version:
1
bundle info matestack-ui-core
Copied!
If you've installed the JavaScript dependecies via Yarn/Webpacker you need to update the JavaScript assets via yarn:
1
yarn update matestack-ui-core
Copied!
and finally check if the correct version is installed:
1
yarn list --pattern "matestack-ui-core"
Copied!
The Ruby gem version and the npm package version should match!
Last modified 4mo ago