Skip to content

Commit 3613f53

Browse files
jonasjabarijonasjabari
committed
fixed docs feature walk-trhough
1 parent cb5c9c2 commit 3613f53

File tree

1 file changed

+3
-348
lines changed

1 file changed

+3
-348
lines changed

‎docs/README.md

Lines changed: 3 additions & 348 deletions
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ Start right away and install `matestack-ui-core` on top of your Rails app, or re
4848

4949
## Feature walk-through
5050

51-
#### 1. Create UI components in pure Ruby
51+
### 1. Create UI components in pure Ruby
5252

5353
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.
5454

@@ -308,7 +308,7 @@ class Components::CardBody < Matestack::Ui::Component
308308
end
309309
```
310310

311-
#### 2. Substitute Rails Views with Matestack Pages
311+
### 2. Substitute Rails Views with Matestack Pages
312312

313313
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:
314314

@@ -349,352 +349,7 @@ end
349349

350350
The page response - in this case - will be yielded into the Rails layout if not specified differently.
351351

352-
#### 3. Wrap Matestack Pages in Matestack Layouts
353-
354-
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.
355-
356-
{% code title="app/matestack/some_app/some_layout.rb" %}
357-
```ruby
358-
class SomeApp::SomeLayout < Matestack::Ui::Layout
359-
360-
def response
361-
h1 "Some App"
362-
main do
363-
yield
364-
end
365-
end
366-
367-
end
368-
```
369-
{% endcode %}
370-
371-
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.
372-
373-
{% hint style="info" %}
374-
A Matestack layout itself will be yielded into the Rails layout, unless the Rails layout is disabled in the controller via:`layout false`
375-
{% endhint %}
376-
377-
Usually 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:
378-
379-
```bash
380-
app/matestack/
381-
|
382-
└───some_app/
383-
│ │ some_layout.rb
384-
│ └───pages/
385-
│ │ │ page1.rb
386-
│ │ │ page2.rb
387-
│ │ │ page3.rb
388-
```
389-
390-
and then used in a controller like this:
391-
392-
393-
394-
### Feature walk-through
395-
396-
#### 1. Create UI components in pure Ruby
397-
398-
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.
399-
400-
**Implement UI components in pure Ruby**
401-
402-
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").
403-
404-
`app/matestack/components/card.rb`
405-
406-
```ruby
407-
class Components::Card < Matestack::Ui::Component
408-
409-
required :body
410-
optional :title
411-
optional :image
412-
413-
def response
414-
div class: "card shadow-sm border-0 bg-light" do
415-
img path: context.image, class: "w-100" if context.image.present?
416-
div class: "card-body" do
417-
h5 context.title if context.title.present?
418-
paragraph context.body, class: "card-text"
419-
end
420-
end
421-
end
422-
423-
end
424-
```
425-
426-
**Use your Ruby UI components on your existing Rails views**
427-
428-
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.
429-
430-
`app/views/your_view.html.erb`
431-
432-
```erb
433-
<!-- some other erb markup -->
434-
<%= Components::Card.call(title: "hello", body: "world") %>
435-
<!-- some other erb markup -->
436-
```
437-
438-
**Use Ruby methods as partials**
439-
440-
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.
441-
442-
`app/matestack/components/card.rb`
443-
444-
```ruby
445-
class Components::Card < Matestack::Ui::Component
446-
447-
required :body
448-
optional :title
449-
optional :image
450-
optional :footer
451-
452-
def response
453-
div class: "card shadow-sm border-0 bg-light" do
454-
img path: context.image, class: "w-100" if context.image.present?
455-
card_content
456-
card_footer if context.footer.present?
457-
end
458-
end
459-
460-
def card_content
461-
div class: "card-body" do
462-
h5 context.title if context.title.present?
463-
paragraph context.body, class: "card-body"
464-
end
465-
end
466-
467-
def card_footer
468-
div class: "card-footer text-muted" do
469-
plain footer
470-
end
471-
end
472-
473-
end
474-
```
475-
476-
`app/views/your_view.html.erb`
477-
478-
```erb
479-
<!-- some other erb markup -->
480-
<%= Components::Card.call(title: "hello", body: "world", footer: "foo") %>
481-
<!-- some other erb markup -->
482-
```
483-
484-
**Use class inheritance**
485-
486-
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.
487-
488-
`app/matestack/components/blue_card.rb`
489-
490-
```ruby
491-
class Components::BlueCard < Components::Card
492-
493-
def response
494-
div class: "card shadow-sm border-0 bg-primary text-white" do
495-
img path: context.image, class: "w-100" if context.image.present?
496-
card_content #defined in parent class
497-
card_footer if context.footer.present? #defined in parent class
498-
end
499-
end
500-
501-
end
502-
```
503-
504-
`app/views/your_view.html.erb`
505-
506-
```erb
507-
<!-- some other erb markup -->
508-
<%= Components::BlueCard.call(title: "hello", body: "world") %>
509-
<!-- some other erb markup -->
510-
```
511-
512-
**Use components within components**
513-
514-
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!
515-
516-
`app/matestack/components/card.rb`
517-
518-
```ruby
519-
class Components::Card < Matestack::Ui::Component
520-
521-
required :body
522-
optional :title
523-
optional :image
524-
525-
def response
526-
div class: "card shadow-sm border-0 bg-light" do
527-
img path: context.image, class: "w-100" if context.image.present?
528-
# calling the CardBody component rather than using Ruby method partials
529-
Components::CardBody.call(title: context.title, body: context.body)
530-
end
531-
end
532-
533-
end
534-
```
535-
536-
`app/matestack/components/card_body.rb`
537-
538-
```ruby
539-
class Components::CardBody < Matestack::Ui::Component
540-
541-
required :body
542-
optional :title
543-
544-
def response
545-
# Just an example. Would make more sense, if this component had
546-
# a more complex structure
547-
div class: "card-body" do
548-
h5 context.title if context.title.present?
549-
paragraph context.body, class: "card-body"
550-
end
551-
end
552-
553-
end
554-
```
555-
556-
**Yield components into components**
557-
558-
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.
559-
560-
`app/matestack/components/card.rb`
561-
562-
```ruby
563-
class Components::Card < Matestack::Ui::Component
564-
565-
required :body
566-
optional :title
567-
optional :image
568-
569-
def response
570-
div class: "card shadow-sm border-0 bg-light" do
571-
img path: context.image, class: "w-100" if context.image.present?
572-
Components::CardBody.call() do
573-
# yielding a block into the card_body component
574-
h5 context.title if context.title.present?
575-
paragraph context.body, class: "card-body"
576-
end
577-
end
578-
end
579-
580-
end
581-
```
582-
583-
`app/matestack/components/card_body.rb`
584-
585-
```ruby
586-
class Components::CardBody < Matestack::Ui::Component
587-
588-
def response
589-
# Just an example. Would make more sense, if this component had
590-
# a more complex structure
591-
div class: "card-body" do
592-
yield if block_given?
593-
end
594-
end
595-
596-
end
597-
```
598-
599-
**Use named slots for advanced content injection**
600-
601-
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!
602-
603-
`app/matestack/components/card.rb`
604-
605-
```ruby
606-
class Components::Card < Matestack::Ui::Component
607-
608-
required :body
609-
optional :title
610-
optional :image
611-
612-
def response
613-
div class: "card shadow-sm border-0 bg-light" do
614-
img path: context.image, class: "w-100" if context.image.present?
615-
Components::CardBody.call(slots: {
616-
heading: method(:heading_slot),
617-
body: method(:body_slot)
618-
})
619-
end
620-
end
621-
622-
def heading_slot
623-
h5 context.title if context.title.present?
624-
end
625-
626-
def body_slot
627-
paragraph context.body, class: "card-body"
628-
end
629-
630-
end
631-
```
632-
633-
`app/matestack/components/card_body.rb`
634-
635-
```ruby
636-
class Components::CardBody < Matestack::Ui::Component
637-
638-
required :slots
639-
640-
def response
641-
# Just an example. Would make more sense, if this component had
642-
# a more complex structure
643-
div class: "card-body" do
644-
div class: "heading-section" do
645-
slot :heading
646-
end
647-
div class: "body-section" do
648-
slot :body
649-
end
650-
end
651-
end
652-
653-
end
654-
```
655-
656-
#### 2. Substitute Rails Views with Matestack Pages
657-
658-
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:
659-
660-
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.
661-
662-
{% code title="app/matestack/pages/some_page.rb" %}
663-
```ruby
664-
class Pages::SomePage < Matestack::Ui::Page
665-
666-
def response
667-
div class: "container" do
668-
span id: "hello" do
669-
plain "hello world!"
670-
end
671-
Components::Card.call(title: "foo", body: "bar")
672-
end
673-
end
674-
675-
end
676-
```
677-
{% endcode %}
678-
679-
Pages are used as Rails view substitutes and therefore called in a Rails controller action:
680-
681-
{% code title="app/controllers/some_controller.rb" %}
682-
```ruby
683-
class SomeController < ApplicationController
684-
685-
include Matestack::Ui::Core::Helper
686-
687-
def overview
688-
render Pages::SomePage
689-
end
690-
691-
end
692-
```
693-
{% endcode %}
694-
695-
The page response - in this case - will be yielded into the Rails layout if not specified differently.
696-
697-
#### 3. Wrap Matestack Pages in Matestack Layouts
352+
### 3. Wrap Matestack Pages in Matestack Layouts
698353

699354
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.
700355

0 commit comments

Comments
 (0)