3.0
Getting started
HTML Rendering
Components
Hello World
1. Create UI components in pure Ruby
Craft your UI based on your components written in pure Ruby. Utilizing Ruby's amazing language features, you're able to create a cleaner and more maintainable UI implementation.
Implement UI components in pure Ruby
Create Ruby classes within your Rails project and call Matestack's core components through a Ruby DSL in order to craft your UIs. The Ruby method "div" for example calls one of the static core components, responsible for rendering HTML tags. A component can take Strings, Integers Symbols, Arrays or Hashes (...) as optional properties (e.g. "title") or require them (e.g. "body").
app/matestack/components/card.rb1
class Components::Card < Matestack::Ui::Component
2
​
3
required :body
4
optional :title
5
optional :image
6
​
7
def response
8
div class: "card shadow-sm border-0 bg-light" do
9
img path: context.image, class: "w-100" if context.image.present?
10
div class: "card-body" do
11
h5 context.title if context.title.present?
12
paragraph context.body, class: "card-text"
13
end
14
end
15
end
16
​
17
end
Copied!
Use your Ruby UI components on your existing Rails views
Components can be then called on Rails views (not only! see below), enabling you to create a reusable card components, abstracting UI complexity in your own components.
app/views/your_view.html.erb1
<!-- some other erb markup -->
2
<%= Components::Card.call(title: "hello", body: "world") %>
3
<!-- some other erb markup -->
Copied!
Learn more:
Use Ruby methods as partials
Split your UI implementation into multiple small chunks helping others (and yourself) to better understand your implementation. Using this approach helps you to create a clean, readable and maintainable codebase.
app/matestack/components/card.rb1
class Components::Card < Matestack::Ui::Component
2
​
3
required :body
4
optional :title
5
optional :image
6
optional :footer
7
​
8
def response
9
div class: "card shadow-sm border-0 bg-light" do
10
img path: context.image, class: "w-100" if context.image.present?
11
card_content
12
card_footer if context.footer.present?
13
end
14
end
15
​
16
def card_content
17
div class: "card-body" do
18
h5 context.title if context.title.present?
19
paragraph context.body, class: "card-body"
20
end
21
end
22
​
23
def card_footer
24
div class: "card-footer text-muted" do
25
plain context.footer
26
end
27
end
28
​
29
end
Copied!
app/views/your_view.html.erb1
<!-- some other erb markup -->
2
<%= Components::Card.call(title: "hello", body: "world", footer: "foo") %>
3
<!-- some other erb markup -->
Copied!
Use class inheritance
Because it's just a Ruby class, you can use class inheritance in order to further improve the quality of your UI implementation. Class inheritance can be used to easily create variants of UI components but still reuse parts of the implementation.
app/matestack/components/blue_card.rb1
class Components::BlueCard < Components::Card
2
​
3
def response
4
div class: "card shadow-sm border-0 bg-primary text-white" do
5
img path: context.image, class: "w-100" if context.image.present?
6
card_content #defined in parent class
7
card_footer if context.footer.present? #defined in parent class
8
end
9
end
10
​
11
end
Copied!
app/views/your_view.html.erb1
<!-- some other erb markup -->
2
<%= Components::BlueCard.call(title: "hello", body: "world") %>
3
<!-- some other erb markup -->
Copied!
Use components within components
Just like you used Matestack's core components on your own UI component, you can use your own UI components within other custom UI components. You decide when using a Ruby method partial should be replaced by another self contained UI component!
app/matestack/components/card.rb1
class Components::Card < Matestack::Ui::Component
2
​
3
required :body
4
optional :title
5
optional :image
6
​
7
def response
8
div class: "card shadow-sm border-0 bg-light" do
9
img path: context.image, class: "w-100" if context.image.present?
10
# calling the CardBody component rather than using Ruby method partials
11
Components::CardBody.call(title: context.title, body: context.body)
12
end
13
end
14
​
15
end
Copied!
app/matestack/components/card_body.rb1
class Components::CardBody < Matestack::Ui::Component
2
​
3
required :body
4
optional :title
5
​
6
def response
7
# Just an example. Would make more sense, if this component had
8
# a more complex structure
9
div class: "card-body" do
10
h5 context.title if context.title.present?
11
paragraph context.body, class: "card-body"
12
end
13
end
14
​
15
end
Copied!
Yield components into components
Sometimes it's not enough to just pass simple data into a component. No worries! You can just yield a block into your components! Using this approach gives you more flexibility when using your UI components. Ofcourse yielding can be used alongside passing in simple params.
app/matestack/components/card.rb1
class Components::Card < Matestack::Ui::Component
2
​
3
required :body
4
optional :title
5
optional :image
6
​
7
def response
8
div class: "card shadow-sm border-0 bg-light" do
9
img path: context.image, class: "w-100" if context.image.present?
10
Components::CardBody.call() do
11
# yielding a block into the card_body component
12
h5 context.title if context.title.present?
13
paragraph context.body, class: "card-body"
14
end
15
end
16
end
17
​
18
end
Copied!
app/matestack/components/card_body.rb1
class Components::CardBody < Matestack::Ui::Component
2
​
3
def response
4
# Just an example. Would make more sense, if this component had
5
# a more complex structure
6
div class: "card-body" do
7
yield if block_given?
8
end
9
end
10
​
11
end
Copied!
Use named slots for advanced content injection
If you need to inject multiple blocks into your UI component, you can use "slots"! Slots help you to build complex UI components with multiple named content placeholders for highest implementation flexibility!
app/matestack/components/card.rb1
class Components::Card < Matestack::Ui::Component
2
​
3
required :body
4
optional :title
5
optional :image
6
​
7
def response
8
div class: "card shadow-sm border-0 bg-light" do
9
img path: context.image, class: "w-100" if context.image.present?
10
Components::CardBody.call(slots: {
11
heading: method(:heading_slot),
12
body: method(:body_slot)
13
})
14
end
15
end
16
​
17
def heading_slot
18
h5 context.title if context.title.present?
19
end
20
​
21
def body_slot
22
paragraph context.body, class: "card-body"
23
end
24
​
25
end
Copied!
app/matestack/components/card_body.rb1
class Components::CardBody < Matestack::Ui::Component
2
​
3
required :slots
4
​
5
def response
6
# Just an example. Would make more sense, if this component had
7
# a more complex structure
8
div class: "card-body" do
9
div class: "heading-section" do
10
slot :heading
11
end
12
div class: "body-section" do
13
slot :body
14
end
15
end
16
end
17
​
18
end
Copied!
2. Substitute Rails Views with Matestack Pages
Until here we used Matestack components on Rails views. If desired you can go one step further and use Matestack components on something called a Matestack Page:
A Matestack page can be compared to a Rails view and might be yielded within a layout provided by an associated Matestack layout class (see below). The page itself uses Matestack's HTML rendering mechanism in a
response method and may additionally call other components in order to define a specific UI.app/matestack/pages/some_page.rb
1
class Pages::SomePage < Matestack::Ui::Page
2
​
3
def response
4
div class: "container" do
5
span id: "hello" do
6
plain "hello world!"
7
end
8
Components::Card.call(title: "foo", body: "bar")
9
end
10
end
11
​
12
end
Copied!
Pages are used as Rails view substitutes and therefore called in a Rails controller action:
app/controllers/some_controller.rb
1
class SomeController < ApplicationController
2
​
3
include Matestack::Ui::Core::Helper
4
​
5
def overview
6
render Pages::SomePage
7
end
8
​
9
end
Copied!
The page response - in this case - will be yielded into the Rails layout if not specified differently.
Learn more:
3. Wrap Matestack Pages in Matestack Layouts
Just like a Rails layout would yield a Rails view, a Matestack layout yields a Matestack page. The layout uses Matestack's HTML rendering mechanism in a
response method and may additionally call other components in order to define a specific UI.app/matestack/some_app/some_layout.rb
1
class SomeApp::SomeLayout < Matestack::Ui::Layout
2
​
3
def response
4
h1 "Some App"
5
main do
6
yield
7
end
8
end
9
​
10
end
Copied!
In this basic example the layout is using the methods
h1 and main in order to create the markup as well as a yield in order to yield a page on a specific position.A Matestack layout itself will be yielded into the Rails layout, unless the Rails layout is disabled in the controler via:
layout falseUsually a layout implies a specific context of your application. Multiple pages are then scoped within that context, which could lead to a file structure like:
1
app/matestack/
2
|
3
└───some_app/
4
│ │ some_layout.rb
5
│ └───pages/
6
│ │ │ page1.rb
7
│ │ │ page2.rb
8
│ │ │ page3.rb
Copied!
and then used in a controller like this:
app/controllers/some_controller.rb
1
class SomeController < ApplicationController
2
​
3
include Matestack::Ui::Core::Helper
4
​
5
matestack_layout SomeApp::SomeLayout
6
​
7
def page_1
8
render SomeApp::Pages::Page1
9
end
10
​
11
def page_2
12
render SomeApp::Pages::Page2
13
end
14
​
15
def page_3
16
render SomeApp::Pages::Page3, matestack_layout: false # skip app layout on this page
17
end
18
​
19
end
Copied!
Learn more: