Migrating from 2.x to 3.0

Core/VueJs repo and gem split

  • matestack-ui-core previously contained logic for

    • Ruby -> HTML conversion

    • Reactivity via prebuilt and custom Vue.js components

  • in order to have better seperation of concerns, we've moved the reactivity related things to its own repository/gem -> matestack-ui-vuejs

  • matestack-ui-core is now meant to be combined with any reactivity framework or none at all

Please follow the migration guide within the docs of matestack-ui-vuejs when using reactivity features of matestack-ui-core 2.x


Add the latest version to your Gemfile

gem 'matestack-ui-core', '~> 3.0.0.rc2'

and run

$ bundle update matestack-ui-core

Remove matestack-ui-core JavaScript package

  • matestack-ui-core does not ship a JavaScript package anymore

  • please remove the package from your application and switch to matestack-ui-vuejs for the VueJs driven reactivity if required

yarn remove matestack-ui-core

Matestack::Ui::App is now called Matestack::Ui::Layout

  • Matestack::Ui::App was always meant to be a layout wrapping pages, but was supercharged with some vuejs logic before splitting the core and vuejs repos

  • now Matestack::Ui::App is only a layout, that's why it should be named like that: Matestack::Ui::Layout

-> Search&Replace

matestack_app method is renamed to matestack_layout

  • following the above mentioned naming adjustment, the matestack_app method used on controller level is renamed to matestack_layout


class DemoController < ActionController::Base
  include Matestack::Ui::Core::Helper

  layout "application" # root rails layout file

  matestack_layout DemoApp::Layout # <-- renamed from matestack_app

  def foo
    render DemoApp::Pages::Foo


-> Search&Replace

Matestack::Ui::Layout Matestack::Ui::Page wrapping DOM structures

  • previously, Matestack::Ui::App added some wrapping DOM structure around the whole layout and around it's yield

  • this enabled dynamic page transition and loading state animations

  • Matestack::Ui::Layout now purely renders the layout and yields a page without anything in between

  • the wrapping DOM structres required for dynamic page transitions and loading state animations needs to be added via two new components if you want to use these features via matestack-ui-vue_js (see section below!)


class Some::App::Layout < Matestack::Ui::Layout
  def response
    h1 "Demo App"
    main do


class Some::App::Pages::SomePage < Matestack::Ui::Page
  def response
    h2 "Some Page"

will just render:

<body> <!-- coming from rails layout if specified -->
  <!-- no wrapping DON structure around the layout -->
  <h1>Demo App</<h1>
    <!-- page markup without any wrapping DOM structure -->
    <h2>Some Page</h2>

-> Adjust CSS if you have created any rules targeting the wrapping DOM structure which now only is applied when using components from matestack-ui-vuejs explicitly

Last updated