You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/guides/essential/00_introduction.md
+25-19Lines changed: 25 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,35 +3,41 @@
3
3
## Guide Assumptions
4
4
5
5
* Required knowledge etc
6
+
This guide is designed for Ruby on Rails beginners, advanced and experienced developers. We assume that you have basic knowledge about how Ruby on Rails routing and action controllers work. In this series of guides we will cover the basic principles and usage of matestack and further down the road introduce more complex principles and example use cases.
6
7
7
8
## What is Matestack?
8
9
9
-
* Ruby Gem for easier development...
10
-
* Steal from home page ;P
10
+
Matestack deeply integrates a Vue.js based UI into Ruby on Rails, offering prebuilt components. Use these prebuild components to write dynamic Web-UIs mostly in pure Ruby and with minimum effort. Matestack enables you to develop rich SPA like interfaces in no time and without touching javascript. And if you need to go deeper you can always create your own custom components to do so.
11
+
12
+
## Concept
13
+
14
+
Matestack's UI concept consists of apps, pages and components. An app works like a layout in Rails, pages are the equivalent of views and components represent reusable UI elements.
11
15
12
16
### Apps
13
17
14
-
* Konzept von Apps erklären
15
-
* Allgemeiner Wrapper mit immer darzustellenden Content
16
-
* Gefühl einer App/SinglePageApplication erzeugen ohne den Entwicklungsaufwand
17
-
* Eine Webanwendung kann aus mehreren Apps bestehen, gliedern Bereiche der Anwendung
18
+
Views in Rails are usually wrapped in a layout. Often the Layout contains ui parts like navigation bars or footers which should be rendered around every view. With Matestack an app replaces the concept of the layout. Application wide ui parts like navigation bars or footers are defined inside an app. Pages can be rendered inside an app and the app will take care of transitioning between pages without reloading and rerendering the whole browser page. Thereby switching between pages feels more app like or SPA like and requires no additional coding on your side.
19
+
20
+
A web application can consist of multiple apps. For example an online shop can have a public app, which defines the navigation and footer for lets say a product index and show page and the cart etc. And the online shop has another administration app, which defines a navigation sidebar and manages all administration pages like index, edit and new pages for products.
18
21
19
22
### Pages
20
23
21
-
* Pages sind wechselnder Content in einer App, was üblicherweise neue Seitenaufrufe sind, sind in Matestack Aufrufe von Pages
22
-
* Pages werden in App gerendert und App verändert nicht ihren Zustand, wird nicht neu gerendert
24
+
Matestack introduces pages which replace Rails views. So instead of for example an index and show page you would have an index and show page. Whatever you would do in views you can do in pages. Pages can be rendered standalone or wrapped by an app. Like described above, when pages are wrapped by an app it is possible to transition between pages without a reload of the browser page.
23
25
24
-
### Core Components
26
+
### Components
25
27
26
-
* Core Components teilen sich in zwei Gruppen
27
-
***Components**
28
-
* Um UIs vollständig in Ruby zu schreiben existieren für fast alle HTML5 Tags entsprechende Core Components
29
-
* Verwendung einfach und fasst immer gleich, für Details in die API Doku der jeweiligen Komponente gucken
30
-
***Vue Components**
31
-
* Vue Components sind komplexere Komponenten, welche Funktionalitäten abdecken für die meist Javascript benötigt wird
32
-
* Ermöglichen Frontend Features in Ruby Backend Code zu schreiben
28
+
Components are UI elements. You can create components and use them in your apps, pages or other components. Use components to structure your view code and create reusable elements. For example a component can be a simple customized button or a more complex card containing a title, image and your custom button.
33
29
34
-
### Components
30
+
To enable you to write your apps, pages and components in Ruby, matestack provides a large set of prebuild components. These Components are divided into two groups. There are `Matestack::Ui::Component`'s and `Matestack::Ui::VueComponent`'s.
31
+
32
+
#### `Matestack::Ui::Component`'s
33
+
34
+
For nearly all existing HTML5 Tags there is a component in order to create a ui element with this tag. Visit the [components API documentation](docs/components/) for more information about `Matestack::Ui::Component`'s.
35
+
36
+
#### `Matestack::Ui::VueComponent`'s
37
+
38
+
VueComponents are more complex components. These always have a Vue.js counterpart and enable easy development of dynamic ui elements which would usually require you to write javascript code. VueComponents provide an abstraction so you don't have to write javascript code and instead create rich interfaces in Ruby. Visit the [components API documentation](docs/components/) for more information about `Matestack::Ui::VueComponent`'s.
39
+
40
+
## Recap & outlook
35
41
36
-
* Selber erstellbare Komponenten um UIs in kleinere Teile aufzubrechen
37
-
* Sind wiederverwendbar, bedeutet UI Parts können an verschiedensten Stellen erneut verwendet werden
42
+
We introduced you to the apps, pages and components concepts of matestack. In order to unterstand better how matestack works, we create an application from the ground up using matestack and enhancing it step by step while leveraging more and more features of matestack.
43
+
Read the following guides to get started with matestack and get a better understanding about how apps, pages, components work.
[//]: <>(TODO # maybe remove or rewrite this content block)
25
19
The contents of this article are heavily inspired by [Getting Started on Heroku with Rails 6.x](https://devcenter.heroku.com/articles/getting-started-with-rails6), but goes beyond it by introducing the `matestack-ui-core` gem and setting it up with some example content. Both beginners and experienced Ruby/Rails developers should be able to follow along.
26
20
27
21
## Getting started
@@ -103,7 +97,78 @@ And add an element with the id `matestack_ui` to your layout, by changing your `
103
97
104
98
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.
105
99
106
-
## Add a demo page
100
+
## Create our first page
101
+
102
+
Apps, Pages and Components will live in a Matestack directory inside your `app` directory. So lets create a directory called `matestack` inside `app`.
103
+
104
+
Now lets create our first page featuring the well known "Hello World!" greeting.
105
+
106
+
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.
107
+
108
+
```ruby
109
+
Rails.application.routes.draw do
110
+
root to:'demo#first_page'
111
+
end
112
+
```
113
+
114
+
Accordingly to our route we create a new controller called `demo_controller.rb` within `app/controllers/`.
115
+
116
+
```ruby
117
+
classDemoController < ApplicationController
118
+
119
+
deffirst_page
120
+
# later we will render our page here
121
+
end
122
+
123
+
end
124
+
```
125
+
126
+
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.
127
+
128
+
```ruby
129
+
classFirstPage < Matestack::Ui::Page
130
+
131
+
defresponse
132
+
div do
133
+
plain 'Hello World!'
134
+
end
135
+
end
136
+
137
+
end
138
+
```
139
+
140
+
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.
141
+
142
+
In our `FirstPage` we define the response method and inside call `div` with a block and `plain` with text inside this block. `div` and `plain` 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. `plain` renders the given argument plainly. So this response message would look like this in HTML:
143
+
144
+
```html
145
+
<div>
146
+
Hello World!
147
+
</div>
148
+
```
149
+
150
+
Okay, so now lets render this page and take a look at it in the browser.
151
+
152
+
To render a page matestack provides a `render` helper through the module you included earlier in the `ApplicationController`.
153
+
154
+
Rendering the page is as simple as calling `render FirstPage`. Change your `DemoController` to look like this.
155
+
156
+
```ruby
157
+
classDemoController < ApplicationController
158
+
159
+
deffirst_page
160
+
render FirstPage
161
+
end
162
+
163
+
end
164
+
```
165
+
166
+
We successfully rendered our first page displaying "Hello World" without writing any HTML code.
167
+
168
+
## Create our first app
169
+
170
+
TODO write create app chapter
171
+
107
172
Within your `app` directory, create a directory called `matestack` - this is where `matestack`**apps**, **pages** and, later on, **components**, will live.
108
173
109
174
Now, create a file called `app.rb` in `app/matestack/demo/`, and add the following content:
0 commit comments