Essential Guide 1: Setup
Demo: Matestack Demo Github Repo: Matestack Demo Application
Welcome to the first part of our tutorial about building a web application with matestack.
Introduction
In this guide, we will
create a new Rails application
install
matestack-ui-core
create and render our first 'Hello world' page
add a simple matestack app, wrap our page and add another one
Prerequisites
To follow along, make sure you have successfully installed
Ruby (Version > 2.6, view installation details)
RubyOnRails (Version >6.0, view installation details)
Getting started
In the terminal, create a new Rails app by running
We skip turbolinks, because matestack has it's own loading api which makes turbolinks unnecessary. Using turbolinks in a matestack application can result in unwanted behavior and errors.
Remove turbolinks if installed We encourage you to remove turbolinks if it's installed. To do so remove the line gem 'turbolinks', '~> 5'
from your Gemfile and remove require("turbolinks").start()
from the app/javascript/packs/application.js
file. To clean things up remove the two "data-turbolinks-track": "reload"
key/value pairs from your app/views/application.html.erb
. </details>
Switch into the newly created project via
Need to create database first
To make sure things work as expected, you can run
to start the application. Now visit localhost:3000 and you should see the canonical Yay! You're on Rails! screen!
Install Matestack
To install matestack, run gem install matestack-ui-core
or add gem 'matestack-ui-core'
to your Gemfile and run bundle install
.
For a complete setup with Webpacker, you also need to run yarn add https://github.com/matestack/matestack-ui-core#v1.3.2
followed by yarn install
.
Then, add
to the app/javascripts/packs/application.js
and run
to compile your JavaScript code.
In order to use matestack complete the setup by including the Matestack::Ui::Core::ApplicationHelper
in your ApplicationController
. Your app/controllers/application_controller.rb
should look like this:
And add an element with the id matestack_ui
to your layout, by changing your app/views/layouts/application.html.erb
. It should look like this:
By including the Matestack::Ui::Core::ApplicationHelper
and defining a div with the matestack-ui
id you can now use matestacks render method in your controller actions. Based on the id matestack apps and pages can be rendered and pages can be replaced without a full reload of the browser page.
Create our first page
Apps, Pages and Components will live in a Matestack directory inside your app
directory. So lets create a directory called matestack
inside app
.
Now lets create our first page featuring the well known "Hello World!" greeting.
Before creating our page we add a root route which calls the first_page
action of our DemoController
. Change your config/routes.rb
and add the following route.
Accordingly to our route we create a new controller called demo_controller.rb
within app/controllers/
.
Now its time to create our first page. Create a file called first_page.rb
in app/matestack/
and add the following content. We will take a closer look at what is happening down below.
A page needs to inherit from Matestack::Ui::Page
. Each page must have a response
method. The response method should contain your html (written in ruby) which will be displayed when this page gets rendered.
In our FirstPage
we define the response method and inside call div
with a block and heading
with text and size inside this block. div
and heading
are two of many Matestack::Ui::Components
which you can use to create UI's in Ruby. As you might can imagine the div
call will render a <div></div>
and the given block will be rendered inside this div. heading
renders a html headline tag with the given size, in this case a h1 tag. So this response message would look like this in HTML:
Okay, so now lets render this page and take a look at it in the browser.
To render a page matestack provides a render
helper through the module you included earlier in the ApplicationController
.
Rendering the page is as simple as calling render FirstPage
. Change your DemoController
to look like this.
We successfully rendered our first page displaying "Hello World" without writing any HTML code.
Create our first app
Lets say we want to add a header with navigation links to our first page and upcoming pages. In Rails we would implement this navigation inside our layout, so we don't repeat ourselfs by adding the navigation in every single view. With Matestack we have so called apps which replace the concept of Rails layouts. In order to add a navigation around our page similiar to a rails layout we will create an app called Demo::App
. But where to put this app. We recommend you structure your apps and pages as follows:
In our example we want to have a demo app and pages rendered inside this app. That means that Demo
is our namespace for those. Therefore we put our app and pages inside a folder called demo
. We move our first page inside this demo folder because it should belong to the demo app. Since we can have many different pages we put all pages in a subfolder called pages
.
Because we moved our first page inside demo/pages
we need to update the class name accordingly, matching the Rails naming conventions. Update the class name of your first page to Demo::Pages::FirstPage
.
Now we create the demo app by creating a file called app.rb
inside app/matestack/demo
and add the following content. We will take a closer look at what is happening down below.
What is happening here. An app needs to inherit from Matestack::Ui::App
and define a response method like a page. header, heading, main
are all matestack component helper like div
which we used in our first page. The yield_page
call tells the app where the page content should be rendered. In this case inside a main
tag beneath the header
tag.
The last thing we need to do in order to render our app around our page is to tell the controller to use the app as a layout. We do this by adding matestack_app Demo::App
inside our controller, which should now look like this:
If we visit localhost:3000 now, we can see that our app is rendered around our first page and the "Hello world!" is shown below the heading "Demo App".
Create a second page
In order to better unterstand which advantages and features apps provide, let's create a second page.
First we add a route to our routes.rb
file.
Afterwards we create the second page under app/matestack/demo/pages
as second_page.rb
and add some page content.
To view our second page we need to add the corresponding controller action second_page
.
Visit localhost:3000/second_page to view our second page.
Understanding matestack apps
Now we have two pages which we can only visit via typing in the url. Let's add a navigation above our header to our app in order to navigate between these two pages. We do this like we would normally do it, by adding two links into a nav html tag using matestacks link
helper. In this step we also add a footer for better understanding of whats happening later.
As you might guess right now, all the method calls like nav, footer, hr, small
are calls of matestack helpers representing the equivalent html tags.
If we visit localhost:3000 now, we see our page with the 'Hello World!' content wrapped by our navigation, header and footer. Clicking the link to the second page, the whole browser page is rerendered and we see our second page. Nothing special here, but matestack provides us with a transition
helper. Let's take a look at what it does by changing our links to transitions.
Again visit localhost:3000. Okay now pay close attention to the navigation, header and footer from our app. When you click one of the links generated by the transition
helper, you should notice that only the page content, in this case the 'Hello World!' gets replaced by the contents of our second page.
matestack transitions
asynchronously fetch the requested page without the app layout and only replaces the page. Providing a more app like or SPA like behavior. And all you needed to do was creating an app for your pages.
Commiting the status quo
Let's save the progress so far using Git. In the repo root, run
to do that.
Recap & outlook
We now have a working Rails app using matestack
.
In this guide we learned how matestack pages work, how we can use matestacks components to create html and how we can use an app as a layout for pages and what benefits we get through using an app.
After taking a well deserved rest, make sure to continue exploring the features matestack
offers you by checking out the next part of the series.
Last updated