[TASK] update essential guides, essential guides overview, devise guide

Nils Henning · Nils Henning · commit 89189d6025b3 · 2020-09-07T17:21:33.000+02:00
diff --git a/docs/coming_soon.png b/docs/coming_soon.png
diff --git a/docs/guides/1-installation/README.md b/docs/guides/1-installation/README.md
@@ -69,7 +69,7 @@ Require 'matestack-ui-core' in your `app/assets/stylesheets/application.css`
 
 Since `0.7.5`, matestack-ui-core is compatible with activated [turbolinks](https://github.com/turbolinks/turbolinks).
 
-We recommend to (remove/deactivate)(https://stackoverflow.com/a/38649595) turbolinks, as there is no real reason to use it alongside matetack-ui-core UI dynamics and there might appear some strange side effects. If you encounter strange page-transition/form-submit/action-submit behavior and have turbolinks activated, try to deactivate it first.
+We recommend to (remove/deactivate)(https://stackoverflow.com/a/38649595) turbolinks, as there is no reason to use it alongside matestack-ui-core UI dynamics and there might appear some strange side effects. If you encounter strange page-transition/form-submit/action-submit behavior and have turbolinks activated, try to deactivate it first.
 
 ## Matestack Folder
 
diff --git a/docs/guides/2-essential/00_introduction.md b/docs/guides/2-essential/00_introduction.md
@@ -1,5 +1,8 @@
 # Getting Started with Matestack
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 ## Guide Assumptions
 
 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.
@@ -30,13 +33,15 @@ To enable you to write your apps, pages and components in Ruby, matestack provid
 
 #### `Matestack::Ui::Component`'s
 
-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/api/2-components/) for more information about `Matestack::Ui::Component`'s.
+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/api/2-components/) for more information about `Matestack::Ui::Component`'s.
 
 #### `Matestack::Ui::VueJsComponent`'s
 
-VueJsComponents 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. VueJsComponents 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/api/2-components/) for more information about `Matestack::Ui::VueJsComponent`'s.
+VueJsComponents 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. VueJsComponents 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/api/2-components/) for more information about `Matestack::Ui::VueJsComponent`'s.
 
 ## Recap & outlook
 
 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.
 Read the following guides to get started with matestack and get a better understanding about how apps, pages, components work.
+
+Let's setup a rails app with matestack by following the [next guide](/docs/guides/2-essential/01_setup.md)
diff --git a/docs/guides/2-essential/01_setup.md b/docs/guides/2-essential/01_setup.md
@@ -1,5 +1,8 @@
 # Essential Guide 1: Setup
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the first part of our essential guide about building a web application with matestack.
 
 ## Introduction
@@ -22,10 +25,18 @@ To follow along, make sure you have successfully installed
 In the terminal, create a new Rails app by running
 
 ```sh
-rails new matestack-demo-application
+rails new matestack-demo-application --skip-turbolinks
 ```
 
-and switch into the newly created project via
+We skip turbolinks, because matestack has it's own loading api which makes turbolinks unnecessary. Using turbolinks in a matestack application can result in unwanted behavior and errors.
+
+<details>
+<summary>Remove turbolinks if installed</summary>
+We encourage you to remove turbolinks if it's installed. To do so remove the line <code>gem 'turbolinks', '~> 5'</code> from your Gemfile and remove <code>require("turbolinks").start()</code> from the <code>app/javascript/packs/application.js</code> file. To clean things up remove the two <code>"data-turbolinks-track": "reload"</code> key/value pairs from your <code>app/views/application.html.erb</code>. 
+</details>
+<br/>
+
+Switch into the newly created project via
 
 ```sh
 cd matestack-demo-application
@@ -83,8 +94,8 @@ And add an element with the id `matestack_ui` to your layout, by changing your `
     <%= csrf_meta_tags %>
     <%= csp_meta_tag %>
 
-    <%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
-    <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
+    <%= stylesheet_link_tag 'application', media: 'all' %>
+    <%= javascript_pack_tag 'application' %>
   </head>
 
   <body>
diff --git a/docs/guides/2-essential/02_active_record.md b/docs/guides/2-essential/02_active_record.md
@@ -1,5 +1,8 @@
 # Essential Guide 2: ActiveRecord & Database
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the second part of our essential guide about building a web application with matestack.
 
 ## Introduction
diff --git a/docs/guides/2-essential/03_index_show_transition.md b/docs/guides/2-essential/03_index_show_transition.md
@@ -1,5 +1,8 @@
 # Essential Guide 3: Person Index, Show, Transition
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the third part of our essential guide about building a web application with matestack.
 
 ## Introduction
@@ -125,7 +128,7 @@ When you want to change between different pages within the same `matestack` app,
 
 For links that go outside your `matestack` app, require a full page reload or reference URLs outside your domain, make sure to use the [link component](/docs/api/2-components/link.md) instead!
 
-To learn more, check out the [complete API documentation](docs/api/2-components/transition.md) for the `transition` component.
+To learn more, check out the [complete API documentation](/docs/api/2-components/transition.md) for the `transition` component.
 
 ## Local testing
 
diff --git a/docs/guides/2-essential/04_forms_edit_new_create_update_delete.md b/docs/guides/2-essential/04_forms_edit_new_create_update_delete.md
@@ -1,5 +1,8 @@
 # Essential Guide 4: Forms & Actions (Create, Update, Delete)
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the fourth part of our essential guide about building a web application with matestack.
 
 ## Introduction
@@ -169,7 +172,7 @@ The 'success' key let's us define a behavior when the form was submitted success
 Inside our form component we have calls to normal html components like `label, br, button` which render the corresponding html tag and we have calls for form inputs and a form submit. Let's take a closer look at the `form_input` call. A form input at least requires a key and a type. The type can be any html input type possible. The key defines the input name as which it will get submitted. If the model specified by the `for` key in the form config responds to the key the input will be prefilled with the value the model returns. `form_radio, form_select, form_checkbox` helpers can take an array or hash in the `options` key. They render for example a radio button for each option in the array or hash. In case of an array the label and value are the same for each radio button, in case of a hash the keys are used as labels and the values as values.
 To enable the user to submit the form, we added a button to click. This button needs to be wrapped inside a `form_submit` call, which will take care of triggering the form submit if the contents inside the given block is clicked.
 
-To learn more, check out the [complete API documentation](docs/api/2-components/form.md) for the `form` component.
+To learn more, check out the [complete API documentation](/docs/api/2-components/form.md) for the `form` component.
 
 Take a moment to familiarize yourself with everything going on and then go ahead and create another page in `app/matestack/demo/pages/persons/edit.rb`, featuring similar content:
 
@@ -240,7 +243,7 @@ Beyond that, here's some suggestions of what you could try to add in the future:
 - using other Ruby objects than ActiveRecord collections
 - fetching data from and sending data to third party APIs
 
-To learn more, check out the [complete API documentation](docs/api/2-components/form.md) for the `form` component.
+To learn more, check out the [complete API documentation](/docs/api/2-components/form.md) for the `form` component.
 
 ## Adding a delete button for persons
 
@@ -290,7 +293,7 @@ Beyond that, here's some suggestions of what you could try to add in the future:
 - sending an advanced payload with the HTTP request
 - re-rendering parts of a page on successful request
 
-To learn more, check out the [complete API documentation](docs/api/2-components/action.md) for the `action` component.
+To learn more, check out the [complete API documentation](/docs/api/2-components/action.md) for the `action` component.
 
 ## Local testing
 
diff --git a/docs/guides/2-essential/05_toggle_component.md b/docs/guides/2-essential/05_toggle_component.md
@@ -1,5 +1,8 @@
 # Essential Guide 5: Toggle Component
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the fifth part of our essential guide about building a web application with matestack.
 
 ## Introduction
diff --git a/docs/guides/2-essential/06_async_component.md b/docs/guides/2-essential/06_async_component.md
@@ -1,5 +1,8 @@
 # Essential Guide 6: Async Component
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the sixth part of our essential guide about building a web application with matestack.
 
 ## Introduction
diff --git a/docs/guides/2-essential/07_partials_and_custom_components.md b/docs/guides/2-essential/07_partials_and_custom_components.md
@@ -1,5 +1,8 @@
 # Essential Guide 7: Partials and custom components
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the seventh part of our essential guide about building a web application with matestack.
 
 ## Introduction
@@ -277,7 +280,7 @@ By leveraging useful namespaces and calling custom components within other custo
 
 Side note: Custom components also give you a neat way of reusing your `*.haml` views with matestack (erb and slim support will be added soon).
 
-To learn more, check out the [extend API documentation](docs/extend/custom_static_components.md) for custom static components.
+To learn more, check out the [extend API documentation](/docs/extend/custom_static_components.md) for custom static components.
 
 ## Saving the status quo
 
diff --git a/docs/guides/2-essential/08_collection_async.md b/docs/guides/2-essential/08_collection_async.md
@@ -1,5 +1,8 @@
 # Essential Guide 8: Collection and async component
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the eighth part of our essential guide about building a web application with matestack.
 
 ## Introduction
@@ -231,7 +234,7 @@ From the developer's perspective, here is a more detailed overview of the main b
 
 That's a lot of input, so it may take some time to get used to this powerful component - but it's an investment that will pay off down the road and will make your life easier.
 
-To learn more, check out the [API documentation](docs/api/2-components/collection.md) for the `collection` component.
+To learn more, check out the [API documentation](/docs/api/2-components/collection.md) for the `collection` component.
 
 ## Saving the status quo
 
diff --git a/docs/guides/2-essential/09_custom_vue_js_components.md b/docs/guides/2-essential/09_custom_vue_js_components.md
@@ -1,5 +1,8 @@
 # Essential Guide 9: Custom vue.js components
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the ninth part of our essential guide about building a web application with matestack.
 
 ## Introduction
@@ -150,7 +153,7 @@ As with custom components, there are hardly any limits for your creativity. You
 - use custom dynamic components to fetch, display, modify and update records from your database
 - tweak and extend core components according to your situational, specific needs
 
-To learn more, check out the [guides](docs/guides/4-custom_components.md) for custom custom components.
+To learn more, check out the [guides](/docs/guides/4-custom_components.md) for custom custom components.
 
 ## Recap & outlook
 
diff --git a/docs/guides/2-essential/10_styling_notifications.md b/docs/guides/2-essential/10_styling_notifications.md
@@ -1,5 +1,8 @@
 # Essential Guide 8: Styling and Notifications
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the tenth part of our essential guide about building a web application with matestack.
 
 ## Introduction
@@ -60,8 +63,8 @@ Before we begin putting bootstrap to use, we need to prepare the `app/view/layou
   <%= csrf_meta_tags %>
   <%= csp_meta_tag %>
 
-  <%= stylesheet_pack_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %>
-  <%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>
+  <%= stylesheet_pack_tag 'application', media: 'all' %>
+  <%= javascript_pack_tag 'application' %>
 </head>
 ```
 
diff --git a/docs/guides/2-essential/11_authentication_devise.md b/docs/guides/2-essential/11_authentication_devise.md
@@ -1,5 +1,8 @@
 # Essential Guide 11: Authentication
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the eleventh part of our essential guide about building a web application with matestack.
 
 ## Introduction
@@ -658,8 +661,8 @@ Notice that we added `layout 'administration'` inside our admin controllers. Thi
     <%= csrf_meta_tags %>
     <%= csp_meta_tag %>
 
-    <%= stylesheet_pack_tag 'administration', media: 'all', 'data-turbolinks-track': 'reload' %>
-    <%= javascript_pack_tag 'administration', 'data-turbolinks-track': 'reload' %>
+    <%= stylesheet_pack_tag 'administration', media: 'all' %>
+    <%= javascript_pack_tag 'administration' %>
   </head>
 
   <body>
@@ -676,7 +679,6 @@ Add a new file in `app/javascript/packs/administration.js`, with the following c
 
 ```js
 require("@rails/ujs").start()
-require("turbolinks").start()
 require("@rails/activestorage").start()
 require("channels")
 
diff --git a/docs/guides/2-essential/12_heroku_deployment.md b/docs/guides/2-essential/12_heroku_deployment.md
@@ -1,5 +1,8 @@
 # Essential Guide 12: Heroku Deployment with Postgres
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 ## Introduction
 In this guide, we will
 - install and use PostgreSQL instead of SQLite3
diff --git a/docs/guides/2-essential/13_wrap_up.md b/docs/guides/2-essential/13_wrap_up.md
@@ -1,5 +1,8 @@
 # Essential Guide 13: Wrap Up & Outlook
 
+Demo: [Matestack Demo](https://demo.matestack.io)<br>
+Github Repo: [Matestack Demo Application](https://github.com/matestack/matestack-demo-application)
+
 Welcome to the thirteenth part of our essential guide about building a web application with matestack.
 
 ## Quick recap
diff --git a/docs/guides/2-essential/README.md b/docs/guides/2-essential/README.md
@@ -1,5 +1,7 @@
 # Essential Guide
 
+In this series of guides we teach you how to create a rails app from the ground up with matestack and encounter how matestack makes your life easier and takes away the frontend hustle. We build a demo CRUD application which you can take a look at [here](https://demo.matestack.io). The source code of the complete application can be found on [github](https://github.com/matestack/matestack-demo-application).
+
 0. [Introduction](/docs/guides/2-essential/00_introduction.md)
 1. [Setup](/docs/guides/2-essential/01_setup.md)
 2. [Active Record](/docs/guides/2-essential/02_active_record.md)
diff --git a/docs/guides/3-forms/README.md b/docs/guides/3-forms/README.md
@@ -1,3 +1,5 @@
 # Forms
 
-In Progress...
+## Table of contents
+
+![Coming Soon](../../coming_soon.png)
diff --git a/docs/guides/4-custom_components/README.md b/docs/guides/4-custom_components/README.md
@@ -1,3 +1,3 @@
 # Custom Components
 
-In Progress...
+![Coming Soon](../../coming_soon.png)
diff --git a/docs/guides/5-authorization_authentication/README.md b/docs/guides/5-authorization_authentication/README.md
@@ -1,6 +1,4 @@
 # Authentication and Authorization
 
-In Progress...
-
 1. [Devise](/docs/guides/authorization_authentication/devise.md)
 2. [Pundit and CanCanCan](/docs/guides/authorization_authentication/pundit_or_cancancan.md)
diff --git a/docs/guides/5-authorization_authentication/devise.md b/docs/guides/5-authorization_authentication/devise.md
diff --git a/docs/guides/README.md b/docs/guides/README.md
