Merge pull request #454 from matestack/20200824_update-essential-guides

Update essential guides and introduce more guides

Author: NdotHenning

app/helpers/matestack/ui/core/application_helper.rb

@@ -14,6 +14,7 @@ module ApplicationHelper
         def self.included(base)
           base.extend(ClassMethods)
         end
+        
         module ClassMethods
           def matestack_app _class
             @matestack_app_class = _class

docs/coming_soon.png

@@ -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
 

docs/guides/1-installation/README.md

@@ -1,3 +1,3 @@
 # Active Storage
 
-In Progress...
+![Coming Soon](../../coming_soon.png)

docs/guides/11-active_storage/README.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)

docs/guides/2-essential/00_introduction.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>

docs/guides/2-essential/01_setup.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

docs/guides/2-essential/02_active_record.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
 

docs/guides/2-essential/03_index_show_transition.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
 

docs/guides/2-essential/04_forms_edit_new_create_update_delete.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