Install

Documentation

Install

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'

and run

$ bundle install

Javascript

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

Rails 6+ apps, by default, use webpacker, rails 5 apps, by default, use the asset pipeline.

Webpacker

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

$ yarn add https://github.com/matestack/matestack-ui-core#v0.7.4
$ yarn install

This adds the npm package that provides the javascript files corresponding to 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, in the future, you update the matestack-ui-core gem, make also sure to update the npm package as well.

Asset Pipeline

If you are not using webpacker but the asset pipeline, you don't need to install a separate npm package. All required javascript libraries including vuejs are provided by matestack-ui-core ready-to-use via the asset pipeline.

Require 'matestack-ui-core' in your app/assets/javascript/application.js

//= require matestack-ui-core

Require 'matestack-ui-core' in your app/assets/stylesheets/application.css

/*
 *= require matestack-ui-core
 */

At the moment, matestack-ui-core is not compatible with turbolinks. Please remove or deactive turbolinks for now. We are working on turbolinks support and will add it soon. (Issue #232)

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.

Adding Support for Custom Components

If you intend to write custom dynamic matestack components for your app, you need to make those accessible to the matestack-ui-core javscript code.

Webpack

When using webpack, make sure to import your custom components in app/javascript/packs/application.js:

import MatestackUiCore from 'matestack-ui-core'
import '../../../app/matestack/components/my_custom_component'

Asset Pipeline

When using the asset pipeline, add the matestack folder to the asset paths:

# config/initializers/assets.rb
Rails.application.config.assets.paths << Rails.root.join('app/matestack/components')

Websocket Integration

If you want to use websockets, please read this guide

That's it!

That's all you need to setup matestack!

For your next steps in learning matestack we recommend you check out the basics concepts and follow the hello world guide which shows you how to create your first matestack app!