Skip to content

Commit fd60923

Browse files
jonasjabarigitbook-bot
jonasjabari
authored and
gitbook-bot
committed
GitBook: [main] 46 pages modified
1 parent 71ede1b commit fd60923

File tree

4 files changed

+225
-77
lines changed

4 files changed

+225
-77
lines changed

‎docs/README.md‎

Lines changed: 55 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -1,111 +1,89 @@
1+
---
2+
description: 'Matestack Ui Bootstrap - Beautiful, reactive web UIs, Ruby and you!'
3+
---
4+
15
# Welcome
26

37
As an extension for `matestack-ui-core`, `matestack-ui-bootstrap`ships all you need to build beautiful, reactive UIs in pure Ruby and smart CRUD components based on Bootstrap v5. Don't think about styling anymore and just create admin or application UIs faster than ever before!
48

5-
## Live Demo <a id="live-demo"></a>
6-
7-
Based on `matestack-ui-core` and `matestack-ui-bootstrap` this reactive dummy app was created in pure Ruby without writing any JavaScript, ERB/HAML/SLIM and CSS: \([check it out](https://dummy.matestack.io/) \| [source code](https://github.com/matestack/matestack-ui-bootstrap/tree/main/spec/dummy)\)
8-
9-
![https://dummy.matestack.io](https://gblobscdn.gitbook.com/assets%2F-MSlZxQYRyTJNqEznL8o%2F-MTevzmZSIIaZYSkG4fv%2F-MTfYhwWbFzn_uGOlml9%2Fimage.png?alt=media&token=cbf6d7df-7d94-450e-9925-b42eb2cb0a3f)
10-
119
{% hint style="info" %}
12-
We do not offer Sprocktes Support in order to include the JavaScript part of `matestack-ui-bootstrap`. Please use something like Webpacker instead! Sprockets support will be dropped soon for `matestack-ui-core` as well!
10+
Read about `matestack-ui-core` here: [https://docs.matestack.io/matestack-ui-core](https://docs.matestack.io/matestack-ui-core)
1311
{% endhint %}
1412

15-
## Webpacker Installation
13+
## Why?
1614

17-
```text
18-
bundle add 'matestack-ui-bootstrap'
19-
yarn add 'matestack-ui-bootstrap'
20-
```
15+
How much do you enjoy copy&pasting complex DOM structures and giant chains of CSS classes across your APP in order to create a decent looking UI?
2116

22-
`app/views/layouts/application.html.erb`
23-
24-
```text
25-
<!DOCTYPE html>
26-
<html>
27-
<head>
28-
<title>Your App</title>
29-
<meta name="viewport" content="width=device-width,initial-scale=1">
30-
<%= csrf_meta_tags %>
31-
<%= csp_meta_tag %>
32-
33-
<%= stylesheet_link_tag 'application', media: 'all'%>
34-
<%= javascript_pack_tag 'application'%>
35-
</head>
36-
37-
<body>
38-
<div id="matestack-ui">
39-
<%= yield %>
40-
</div>
41-
</body>
42-
</html>
43-
```
17+
With `matestack-ui-core` you're luckily able to build complex DOM structures ONCE in pure Ruby in a Matestack component and reuse it across your app without copy&pasting. So this component may look like this:
18+
19+
{% code title="app/matestack/components/card\_component.rb" %}
20+
```ruby
21+
class Components::CardComponent < Matestack::Ui::Component
4422

45-
`app/javascript/packs/stylesheets/application.scss`
23+
def response
24+
div class: "card shadow-sm border-0 bg-light" do
25+
img path: "...", class: "w-100"
26+
body_partial # calling the below defined instance method
27+
end
28+
end
4629

47-
```css
48-
@import "~bootstrap/scss/bootstrap.scss";
49-
```
30+
private
5031

51-
`app/javascript/packs/application.js`
32+
def body_partial
33+
div class: "card-body" do
34+
h5 "foo", class: "card-title"
35+
paragraph "bar", class: "card-text"
36+
end
37+
end
5238

53-
```javascript
54-
import Rails from "@rails/ujs"
55-
// import Turbolinks from "turbolinks"
56-
import * as ActiveStorage from "@rails/activestorage"
57-
import "channels"
39+
end
40+
```
41+
{% endcode %}
5842

59-
import "./stylesheets/application.scss";
43+
`matestack-ui-core` has no opinion about styling. That's why you need to build a Bootstrap card component \(or whatever CSS approach you prefer\) yourself. In case you're into Bootstrap: Wouldn’t it be cool to have all Bootstrap components available like that in pure Ruby?
6044

61-
import Vue from 'vue/dist/vue.esm'
62-
import Vuex from 'vuex'
45+
That's at least what we thought and why we've created `matestack-ui-bootstrap`shipping all you need to build beautiful, reactive UIs in pure Ruby and smart CRUD components based on Bootstrap v5.
6346

64-
import MatestackUiCore from 'matestack-ui-core'
65-
import MatestackUiBootstrap from "matestack-ui-bootstrap"
47+
So a card is already implemented and would be used like that:
6648

67-
let matestackUiApp = undefined
49+
```ruby
50+
bs_card title: "foo", body: "bar"
51+
```
6852

69-
document.addEventListener('DOMContentLoaded', () => {
70-
matestackUiApp = new Vue({
71-
el: "#matestack-ui",
72-
store: MatestackUiCore.store
73-
})
74-
})
53+
which renders:
7554

76-
Rails.start()
77-
// Turbolinks.start()
78-
ActiveStorage.start()
55+
```markup
56+
<div class="card">
57+
<div class="card-body">
58+
<h5 class="card-title">foo</h5>
59+
<p class="card-text">bar</p>
60+
</div>
61+
</div>
7962
```
8063

81-
`app/assets/images/icons`
64+
{% page-ref page="api/components/card.md" %}
8265

83-
* download latest compatible icons: [https://github.com/twbs/icons/releases/tag/v1.3.0](https://github.com/twbs/icons/releases/tag/v1.3.0)
84-
* extract the bootstrap-icons.svg to this path: app/assets/images/icons \(served via assets pipeline\)
66+
You can see, how the prebuilt card component save you from writing 6 lines of HTML. And that's just a simple example. When using all kinds prebuilt components, you will stop writing a ton of HTML or copy&pasting DOM structure around. Do you what that makes with the readability and maintainability of your app? Not to speak about developer happiness...
8567

86-
## Usage
8768

88-
Create Matestack apps, pages and components as described in the docs of `matestack-ui-core` and utilize the components described in the API section in order to create your UI. Just make sure to include the additional Registry in your desired controllers
8969

90-
`app/controllers/application_controller.rb`
70+
## Live Demo <a id="live-demo"></a>
9171

92-
```ruby
93-
class ApplicationController < ActionController::Base
72+
Based on `matestack-ui-core` and `matestack-ui-bootstrap` this reactive dummy app was created in pure Ruby without writing any JavaScript, ERB/HAML/SLIM and CSS: \([check it out](https://dummy.matestack.io/) \| [source code](https://github.com/matestack/matestack-ui-bootstrap/tree/main/spec/dummy)\)
9473

95-
include Matestack::Ui::Core::Helper # described in Core docs
74+
![https://dummy.matestack.io](https://gblobscdn.gitbook.com/assets%2F-MSlZxQYRyTJNqEznL8o%2F-MTevzmZSIIaZYSkG4fv%2F-MTfYhwWbFzn_uGOlml9%2Fimage.png?alt=media&token=cbf6d7df-7d94-450e-9925-b42eb2cb0a3f)
9675

97-
end
98-
```
76+
## Getting Started
9977

100-
and include the registry wherever you want to use the components via methods like "bs\_btn" instead of calling the namespaced classes
78+
Before you dive into `matestack-ui-bootstrap`, make sure to have a solid understanding of `matestack-ui-core` first: [https://docs.matestack.io/matestack-ui-core/getting-started/concepts-rails-integration](https://docs.matestack.io/matestack-ui-core/getting-started/concepts-rails-integration)
10179

102-
`app/matestack/application_component.rb`
80+
After that, it might be a good idea to get into using `matestack-ui-bootstrap` following the quick start guide:
10381

104-
```ruby
105-
class ApplicationComponent < Matestack::Ui::Component
82+
{% page-ref page="getting-started/quick-start.md" %}
10683

107-
include Matestack::Ui::Bootstrap::Registry # use methods like "bs_btn" instead of calling the namespaced classes
84+
If you know how to use matestack-ui-bootstrap, the API documentation should serve you well:
10885

109-
end
110-
```
86+
## Roadmap
87+
88+
Do you want to know what we're currently working on and what's planned for the next releases? Check out our GitHub Project board: [https://github.com/orgs/matestack/projects/1](https://github.com/orgs/matestack/projects/1)
11189

‎docs/SUMMARY.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22

33
* [Welcome](README.md)
44

5+
## Getting Started
6+
7+
* [Installation & Update](getting-started/installation-update.md)
8+
* [Quick Start \[WIP\]](getting-started/quick-start.md)
9+
510
## API
611

712
* [Templates](api/templates/README.md)

‎docs/getting-started/installation-update.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Installation & Update
2+
3+
## Installation
4+
5+
Make sure to install and get to know `matestack-ui-core` first! [https://docs.matestack.io/matestack-ui-core](https://docs.matestack.io/matestack-ui-core)
6+
7+
Add the Ruby gem and NPM package:
8+
9+
```text
10+
bundle add 'matestack-ui-bootstrap'
11+
yarn add 'matestack-ui-bootstrap'
12+
```
13+
14+
Adjust the relevant application layout and add a div with the ID `matestack-ui`
15+
16+
`app/views/layouts/application.html.erb`
17+
18+
```text
19+
<!DOCTYPE html>
20+
<html>
21+
<head>
22+
<title>Your App</title>
23+
<meta name="viewport" content="width=device-width,initial-scale=1">
24+
<%= csrf_meta_tags %>
25+
<%= csp_meta_tag %>
26+
27+
<%= stylesheet_link_tag 'application', media: 'all'%>
28+
<%= javascript_pack_tag 'application'%>
29+
</head>
30+
31+
<body>
32+
<div id="matestack-ui">
33+
<%= yield %>
34+
</div>
35+
</body>
36+
</html>
37+
```
38+
39+
Tell Webpack to import Bootstraps CSS:
40+
41+
`app/javascript/packs/stylesheets/application.scss`
42+
43+
```css
44+
@import "~bootstrap/scss/bootstrap.scss";
45+
```
46+
47+
Import the required JS libraries and mount MatestackUiCore and MatestackUiBootstrap properly. We recommend to remove Turbolinks, as it might interfere with some of the reactivity feature of Matestack:
48+
49+
`app/javascript/packs/application.js`
50+
51+
```javascript
52+
import Rails from "@rails/ujs"
53+
// import Turbolinks from "turbolinks"
54+
import * as ActiveStorage from "@rails/activestorage"
55+
import "channels"
56+
57+
import "./stylesheets/application.scss";
58+
59+
import Vue from 'vue/dist/vue.esm'
60+
import Vuex from 'vuex'
61+
62+
import MatestackUiCore from 'matestack-ui-core'
63+
import MatestackUiBootstrap from "matestack-ui-bootstrap"
64+
65+
let matestackUiApp = undefined
66+
67+
document.addEventListener('DOMContentLoaded', () => {
68+
matestackUiApp = new Vue({
69+
el: "#matestack-ui",
70+
store: MatestackUiCore.store
71+
})
72+
})
73+
74+
Rails.start()
75+
// Turbolinks.start()
76+
ActiveStorage.start()
77+
```
78+
79+
Download and import Bootstraps icons:
80+
81+
`app/assets/images/icons`
82+
83+
* download latest compatible icons: [https://github.com/twbs/icons/releases/tag/v1.3.0](https://github.com/twbs/icons/releases/tag/v1.3.0)
84+
* extract the bootstrap-icons.svg to this path: app/assets/images/icons \(currently served via assets pipeline, we had issues serving the icons via Webpack\)
85+
86+
and finally compile the code with webpack:
87+
88+
```text
89+
$ bin/webpack --watch
90+
```
91+
92+
{% hint style="warning" %}
93+
When you update the `matestack-ui-bootstrap` Ruby gem, make sure to update the npm package as well!
94+
{% endhint %}
95+
96+
## Update
97+
98+
### Ruby Gem
99+
100+
Depending on the entry in your Gemfile, you might need to adjust the allowed version ranges in order to update the Gem. After checked and adjusted the version ranges, run:
101+
102+
```bash
103+
bundle update matestack-ui-bootstrap
104+
```
105+
106+
and then check the installed version:
107+
108+
```bash
109+
bundle info matestack-ui-bootstrap
110+
```
111+
112+
### JavaScript Package
113+
114+
If you've installed the JavaScript dependecies via Yarn/Webpacker you need to update the JavaScript assets via yarn:
115+
116+
```bash
117+
yarn update matestack-ui-bootstrap
118+
```
119+
120+
and finally check if the correct version is installed:
121+
122+
```bash
123+
yarn list --pattern "matestack-ui-bootstrap"
124+
```
125+
126+
{% hint style="warning" %}
127+
The Ruby gem version and the NPM package version should match!
128+
{% endhint %}
129+

‎docs/getting-started/quick-start.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# Quick Start \[WIP\]
2+
3+
{% hint style="info" %}
4+
We're about to add much more content to this guide. Stay tuned!
5+
6+
Until we have more content in place here, it might be a good idea to review the source code of the [dummy app](https://dummy.matestack.io), which can be found here: [https://github.com/matestack/matestack-ui-bootstrap/tree/main/spec/dummy](https://github.com/matestack/matestack-ui-bootstrap/tree/main/spec/dummy)
7+
8+
That should already give you a good idea how to use `matestack-ui-bootstrap`
9+
{% endhint %}
10+
11+
## Usage
12+
13+
Create Matestack apps, pages and components as described in the docs of `matestack-ui-core` and utilize the components described in the API section in order to create your UI. Just make sure to include the additional Registry in your desired controllers
14+
15+
`app/controllers/application_controller.rb`
16+
17+
```ruby
18+
class ApplicationController < ActionController::Base
19+
20+
include Matestack::Ui::Core::Helper # described in Core docs
21+
22+
end
23+
```
24+
25+
and include the registry wherever you want to use the components via methods like "bs\_btn" instead of calling the namespaced classes
26+
27+
`app/matestack/application_component.rb`
28+
29+
```ruby
30+
class ApplicationComponent < Matestack::Ui::Component
31+
32+
include Matestack::Ui::Bootstrap::Registry # use methods like "bs_btn" instead of calling the namespaced classes
33+
34+
end
35+
```
36+

0 commit comments

Comments
 (0)