Installation

This guide shows you how to add matestack-ui-core to an existing rails application.

Gemfile

Add 'matestack-ui-core' to your Gemfile

gem 'matestack-ui-core', '~> 1.0.0'

and run

$ bundle install

JavaScript

Matestack uses JavaScript and, in particular, vuejs. To include these into your existing rails app, matestack supports both, webpack(er) and the asset pipeline.

Rails 6+ apps use webpacker by default. Rails 5 and below apps use the asset pipeline by default.

Webpacker

Add 'matestack-ui-core' to your package.json by running:

$ yarn add https://github.com/matestack/matestack-ui-core#v1.0.0
$ yarn install

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

import MatestackUiCore from 'matestack-ui-core'

and compile the JavaScript code with webpack:

$ bin/webpack

When you update the matestack-ui-core gem, make sure to update the npm package as well.

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

//= require matestack-ui-core

We recommend to (remove/deactivate)(https://stackoverflow.com/a/38649595) 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.

Matestack Folder

Create a folder called 'matestack' in your app directory. All your matestack apps, pages and components will be defined there.

Include Helper

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::ApplicationHelper
  #...
end

Application Layout

You need to add the ID "matestack-ui" to some part of your application layout (or any layout you use)

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' %>

    <!-- if you are using the asset pipeline: -->
    <%= javascript_include_tag 'application' %>
  </head>

  <body>
    <div id="matestack-ui">
      <%= yield %>
    </div>
  </body>
</html>

Don't apply the "matestack-ui" id to the body tag.

Websocket Integration

If you want to use websockets, please read our action cable guide.

That's it!

That's all you need to setup matestack!

For further reading check out the basic building blocks or get started with the tutorial and create your first matestack app.