Skip to content

Commit bcac875

Browse files
jonasjabarijonasjabari
committed
refactored and restructured docs
1 parent 23354e5 commit bcac875

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

117 files changed

+3183
-3126
lines changed

‎docs/api/README.md

Lines changed: 2 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,4 @@
11
# API Reference
22

3-
Explain how things work
4-
5-
Contains examples
6-
7-
But guides are more detailed and praxis-oriented
8-
9-
1. [Concepts](/base/)
10-
3. [Core Components](/components)
3+
1. [Base](/base)
4+
2. [Core Components](/components)

‎docs/api/base/README.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# Base API
2+
3+
matestack's UI concept consists of three major building blocks: `component`, `page` and `app`.
4+
A component is a reusable UI-Element. A `page` contains multiple `components`
5+
and represents the main content on a specific view. Multiple
6+
`pages` can be wrapped in an `app`, sharing a layout for example.
7+
8+
If you think of an UI, a small `component` may be a simple button. A bigger `component` may
9+
use three other components, including an image-component, a text-component and this
10+
button-component to display a product-image, -description and a "more details" button.
11+
12+
A `component` is the smallest UI-Element and can consist of other components. matestack
13+
provides a wide set of core components, which enables you to easily build your UI.
14+
You can build your own components as well!
15+
16+
20 of these product-components should be displayed on a specific `page` of your Web-App.
17+
A `page` therefore defines, that 20 product-components should be used and how they should
18+
be aligned to each other.
19+
20+
A `page` composes multiple components in order to display the main content.
21+
22+
Usually a `page` should be wrapped in a layout. A layout may define a navigation-menu,
23+
header and footer for example. In matestack, a layout is defined in an `app`. Multiple
24+
`pages` belong to one matestack `app`, which can perform dynamic transitions
25+
between its `pages`. A Rails application may host multiple matestack `apps`: One could
26+
be the Online-Shop-App, displaying products on multiple `pages`. The other could be
27+
an Backoffice-App managing all kind of data and processes.
28+
29+
A matestack `app` manages multiple `pages` in order to fullfill one specific purpose of your organization.
30+
31+
## Components
32+
33+
### Types of components
34+
35+
Matestack uses three different types of components:
36+
37+
* Component
38+
* VueJsComponent
39+
* IsolatedComponent
40+
41+
All components define their UI within a `response` method, written in Ruby.
42+
43+
#### Component
44+
45+
The simplest type of a component inherits from `Matestack::Ui::Component` and is
46+
meant to be used for simple rendering of content and other components. Matestack
47+
will simply render the UI defined within the `response` method without any
48+
wrapping elements by default.
49+
50+
[Read more](/docs/api/base/component.md)
51+
52+
#### VueJsComponent
53+
54+
In order to equip a Ruby component with some JavaScript, we associate
55+
the Ruby component with a VueJs JavaScript component. The Ruby component therefore needs to inherit
56+
from `Matestack::Ui::VueJsComponent`. Matestack will then render a HTML component
57+
tag with some special attributes and props around the response defined in the
58+
Ruby component. The VueJs JavaScript component (defined in a separate JavaScript file and
59+
managed via Sprockets or Webpacker) will treat the response of the Ruby
60+
component as its template.
61+
62+
[Read more](/docs/api/base/vue_js_component.md)
63+
64+
#### IsolatedComponent
65+
66+
Components inheriting from `Matestack::Ui::IsolatedComponent` are designed for
67+
isolated, asynchronous rendering. Like seen at VueJsComponents, Matestack will
68+
render a HTML component tag with some special attributes and props around the
69+
response defined in the Ruby component. Additionally, Matestack wraps the
70+
component's `response` with some DOM elements enabling asynchronous loading
71+
state animations.
72+
73+
[Read more](/docs/api/base/isolated_component.md)
74+
75+
### Core Components
76+
77+
Matestack ships a lot of core components. A lot of them are simple `Matestack::Ui::Component`s
78+
and representing HTML tags in order to enable the developer to create html markup
79+
with pure Ruby. Some other core components are `Matestack::Ui::VueJsComponent`s shipping
80+
predefined dynamic UI behavior.
81+
82+
See [here](/docs/api/components/core/README.md) for a list of available `core components`.
83+
84+
### Custom Components
85+
86+
By definition, custom components only live within your application.
87+
To use them on your `apps` and `pages`, you need to register them in a component
88+
registry file. Custom components can inherit from `Matestack::Ui::Component`,
89+
`Matestack::Ui::VueJsComponent` or `Matestack::Ui::IsolatedComponent` depending on
90+
the specific usecase.
91+
92+
[Read more](/docs/api/components/custom/README.md)
93+
94+
## Pages
95+
96+
A page orchestrates components within its response method. A Rails controller
97+
action references a page (and its corresponding app) in its render call. Thus a
98+
matestack page substitutes a typical Rails view.
99+
100+
A page is a special kind of `Matestack::Ui::VueJsComponent`. Matestack will
101+
therefore wrap the UI defined in the `response` method with some markup enabling
102+
dynamic UI behavior and CSS styling.
103+
104+
Learn more about [pages](/docs/api/base/page.md)
105+
106+
## Apps
107+
108+
An app defines a layout within its `response` method and uses the `yield_page`
109+
method to yield the content of a page in its layout.
110+
111+
An app is a special kind of `Matestack::Ui::VueJsComponent`. Matestack will
112+
therefore wrap the UI defined in the `response` method with some markup enabling
113+
dynamic UI behavior and CSS styling.
114+
115+
The app ships a `Vuex store` and `Vue.js event hub`, which are used by core vuejs
116+
components and can optionally be used by custom vuejs components in order to
117+
trigger events, manage client side date and communicate between components.
118+
119+
Learn more about [apps](/docs/api/base/app.md)

‎docs/api/base/app.md

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# App
2+
3+
An app defines a layout within its `response` method and uses the `yield_page`
4+
method to yield the content of a page in its layout.
5+
6+
An app is a special kind of `Matestack::Ui::VueJsComponent`. Matestack will
7+
therefore wrap the UI defined in the `response` method with some markup enabling
8+
dynamic UI behavior and CSS styling.
9+
10+
The app ships a `Vuex store` and `Vue.js event hub`, which are used by core vuejs
11+
components and can optionally be used by custom vuejs components in order to
12+
trigger events, manage client side date and communicate between components.
13+
14+
## An App can wrap pages with a layout
15+
16+
`app/matestack/example_app/app.rb`
17+
18+
```ruby
19+
class ExampleApp::App < Matestack::Ui::App
20+
21+
def response
22+
heading size: 1, text: "My Example App Layout"
23+
main do
24+
#yield_page is a core method which yields the page and enables dynamic transitions
25+
#it can be placed anywhere in your layout
26+
yield_page
27+
end
28+
end
29+
30+
end
31+
```
32+
33+
`app/matestack/example_app/pages/example_page.rb`
34+
35+
```ruby
36+
class ExampleApp::Pages::ExamplePage < Matestack::Ui::Page
37+
38+
def response
39+
div id: "my-div-on-page-1" do
40+
heading size: 2, text: "This is Page 1"
41+
end
42+
end
43+
44+
end
45+
```
46+
47+
`app/matestack/pages/example_app/second_example_page.rb`
48+
49+
```ruby
50+
class ExampleApp::Pages::SecondExamplePage < Matestack::Ui::Page
51+
52+
def response
53+
div id: "my-div-on-page-2" do
54+
heading size: 2, text: "This is Page 2"
55+
end
56+
end
57+
58+
end
59+
```
60+
61+
## An App enables transitions between pages without page reload
62+
63+
`app/matestack/example_app/app.rb`
64+
65+
```ruby
66+
class ExampleApp::App < Matestack::Ui::App
67+
68+
def response
69+
heading size: 1, text: "My Example App Layout"
70+
nav do
71+
transition path: :app_specs_page1_path do
72+
button text: "Page 1"
73+
end
74+
transition path: :app_specs_page2_path do
75+
button text: "Page 2"
76+
end
77+
end
78+
main do
79+
yield_page
80+
end
81+
end
82+
83+
end
84+
```
85+
86+
The `transition` components will trigger async HTTP requests and exchange the page content without a page reload.
87+
88+
## An App enables transitions between pages without page reload with loading element
89+
90+
`app/matestack/example_app/app.rb`
91+
92+
```ruby
93+
class ExampleApp::App < Matestack::Ui::App
94+
95+
def response
96+
#...
97+
main do
98+
yield_page slots: { loading_state: my_loading_state_slot }
99+
end
100+
#...
101+
end
102+
103+
def my_loading_state_slot
104+
slot do
105+
span class: "some-loading-spinner" do
106+
plain "loading..."
107+
end
108+
end
109+
end
110+
111+
end
112+
```
113+
114+
which will render:
115+
116+
```html
117+
<main>
118+
<div class="matestack-page-container">
119+
<div class="loading-state-element-wrapper">
120+
<span class="some-loading-spinner">
121+
loading...
122+
</span>
123+
</div>
124+
<div class="matestack-page-wrapper">
125+
<div><!--this div is necessary for conditonal switch to async template via v-if -->
126+
<div class="matestack-page-root">
127+
your page markup
128+
</div>
129+
</div>
130+
</div>
131+
</div>
132+
</end>
133+
```
134+
135+
and during async page request triggered via transition:
136+
137+
```html
138+
<main>
139+
<div class="matestack-page-container loading">
140+
<div class="loading-state-element-wrapper loading">
141+
<span class="some-loading-spinner">
142+
loading...
143+
</span>
144+
</div>
145+
<div class="matestack-page-wrapper loading">
146+
<div><!--this div is necessary for conditonal switch to async template via v-if -->
147+
<div class="matestack-page-root">
148+
your page markup
149+
</div>
150+
</div>
151+
</div>
152+
</div>
153+
</end>
154+
```
155+
156+
You can use the `loading` class and your loading state element to implement CSS based loading state effects.
157+
158+
For more informations on transitions, visit [transitions](/docs/api/components/transition.md)

‎docs/api/base/backend/README.md

Lines changed: 0 additions & 43 deletions
This file was deleted.

0 commit comments

Comments
 (0)