Matestack enables you to implement reusable UI components in pure Ruby in order to efficiently build a maintainable UI implementation, utilizing Ruby's amazing language features. A Bootstrap card component may look like this:
class Components::Card < Matestack::Ui::Componentrequires :bodyoptional :titleoptional :imagedef responsediv class: "card shadow-sm border-0 bg-light" doimg path: image, class: "w-100" if image.present?div class: "card-body" doheading size: 5, text: title if title.present?paragraph class: "card-text", text: bodyendendendend
Such a component is defined within your application. We call them custom components. While implementing these, you use Matestack's core components in order to define your UI: Above we used methods like
div. These are all what we call core components provided trough a core component registry which is automatically loaded. These core components representing the corresponding HTML tags. Calling
div for example would result in
<div></div> after rendering. Matestack provides a always expanding wide set of w3c's specified HTML tags, enabling you to write UIs in pure Ruby. All available components are listed in our components api.
In order to use your custom component we need to register the component. We therefore need to create a component registry. We could place it anywhere we want, but we recommend placing it inside the components folder. It is possible to have multiple component registries, for example to keep shop components seperated from management components. Create a file called
module Components::RegistryMatestack::Ui::Core::Component::Registry.register_components(card: Components::Card)end
We register our card component as
card. One last thing remaining in order to use it with
card: We need to include the module in the controller, where we want to use it. Because we want to use the
card across the whole app, we include it in our application controller:
class ApplicationController < ActionController::Baseinclude Matestack::Ui::Core::ApplicationHelper # see installation guide for detailsinclude Components::Registryend
We can now use our components on our Rails views (and later on on Matestack pages and apps as well).
<%= @products.each do |product| %><%= matestack_component :card, title: product.title, body: product.description, image: product.gallery_image_url %><% end %>
card component can also be used on other registered custom components, skipping the
matestack_component helper call.
class Components::Products::Detail < Matestack::Ui::Componentrequires :productdef responsediv class: "row" dodiv class: "col" docard title: product.title, body: product.descriptionendendendend
In components you have access to your helpers and all Rails helpers. You don't have access to controller instance variables, because components should be reusable everywhere and therefore not depend on instance variables set in controller actions.
To access data inside components we can define required and/or optional properties which are passed to the component via hash and used with getter methods in the component. Our
card for example requires a body in order to show a minimal Bootstrap card.