[WIP][TASK][REFACTOR] rework guides, rename and add new ones

Author: Nils Henning

docs/guides/essential/01_setup.md

@@ -1,14 +1,17 @@
 # Essential Guide 1: Setup
-Welcome to the first part of the 10-step-guide of setting up a working Rails CRUD app with `matestack-ui-core`!
+
+Welcome to the first part of our essential guide about building a web application with matestack.
 
 ## Introduction
+
 In this guide, we will
 - create a new Rails application
 - install `matestack-ui-core`
 - create and render our first 'Hello world' page
 - add a simple matestack app, wrap our page and add another one
 
 ## Prerequisites
+
 To follow along, make sure you have successfully installed
 - Ruby (Version > 2.6, [view installation details](https://www.ruby-lang.org))
 - RubyOnRails (Version >6.0, [view installation details](https://rubyonrails.org/))
@@ -19,6 +22,7 @@ To follow along, make sure you have successfully installed
 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.
 
 ## Getting started
+
 In the terminal, create a new Rails app by running
 
 ```sh
@@ -108,6 +112,7 @@ Before creating our page we add a root route which calls the `first_page` action
 ```ruby
 Rails.application.routes.draw do
   root to: 'demo#first_page'
+  get '/first_page', to: 'demo#first_page'
 end
 ```
 
@@ -130,7 +135,7 @@ class FirstPage < Matestack::Ui::Page
 
   def response
     div do
-      plain 'Hello World!'
+      heading text: 'Hello World!', size: 1
     end
   end
 
@@ -139,11 +144,11 @@ end
 
 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.
 
-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:
+In our `FirstPage` we define the response method and inside call `div` with a block and `heading` with text and size inside this block. `div` and `heading` 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. `heading` renders a html headline tag with the given size, in this case a _h1_ tag. So this response message would look like this in HTML:
 
 ```html
 <div>
-  Hello World!
+  <h1>Hello World!</h1>
 </div>
 ```
 
@@ -319,6 +324,7 @@ Again visit [localhost:3000](http://localhost:3000/). Okay now pay close attenti
 matestack `transitions` asynchronously fetch the requested page without the app layout and only replaces the page. Providing a more app like or SPA like behavior. And all you needed to do was creating an app for your pages.
 
 ## Commiting the status quo
+
 Let's save the progress so far using Git. In the repo root, run
 
 ```sh
@@ -328,6 +334,7 @@ git add . && git commit -m "Save basic Rails app with PG and matestack set up"
 to do that.
 
 ## Recap & outlook
+
 We now have a working Rails app using `matestack`.
 
 In this guide we learned how matestack pages work, how we can use matestacks components to create html and how we can use an app as a layout for pages and what benefits we get through using an app. 

docs/guides/essential/02_active_record.md

@@ -1,7 +1,9 @@
 # Essential Guide 2: ActiveRecord & Database
-Welcome to the second part of the 10-step-guide of setting up a working Rails CRUD app with `matestack-ui-core`!
+
+Welcome to the second part of our essential guide about building a web application with matestack.
 
 ## Introduction
+
 In the [previous guide](guides/essential/01_setup.md), we created a new project, installed the necessary libraries, added a demo `matestack` app featuring two `matestack` pages, and deployed it using Heroku.
 
 In this guide, we will
@@ -10,9 +12,11 @@ In this guide, we will
 - deploy the changes to the publicly running Heroku application
 
 ## Prerequisites
+
 We expect you to have successfully finished the [previous guide](guides/essential/01_setup.md).
 
 ## Adding the ActiveRecord model
+
 First, we need to create an ActiveRecord model and add the corresponding table to the database. This is quickly achieved by running
 
 ```sh
@@ -28,6 +32,7 @@ rails db:migrate
 which should update the database schema in `db/schema.rb`.
 
 ## Updating the model, adding seeds and displaying an index page
+
 The `role` database field should represent different roles which we define as an enum in our person model. Update `app/models/person.rb` to look like this:
 
 ```ruby
@@ -120,13 +125,15 @@ Run `rails s` and head over to [localhost:3000/persons/index](http://localhost:3
 Of course, this is a very basic approach that we will iterate and improve in the following parts of this guide series!
 
 ## Saving the status quo
+
 As usual, we want to commit the progress to Git. In the repo root, run
 
 ```sh
 git add . && git commit -m "Introduce person model including seeds, add it to matestack/demo/app.rb"
 ```
 
 ## Recap & outlook
+
 We have updated the app to use a working database model, added some records and displayed them on an index page.
 
 Let's continue and build even cooler stuff by heading directly to the [next part of the series](/guides/essential/03_index_show.md).

docs/guides/essential/03_index_show_transition.md

@@ -1,14 +1,17 @@
 # Essential Guide 3: Person Index, Show, Transition
-Welcome to the third part of the 10-step-guide of setting up a working Rails CRUD app with `matestack-ui-core`!
+
+Welcome to the third part of our essential guide about building a web application with matestack.
 
 ## Introduction
+
 In the [previous guide](guides/essential/02_active_record.md), we added an ActiveRecord model to our project, added some fake persons to our database and displayed them on an index page.
 
 In this guide, we will
 - a detail page for every person
 - dive more into the concept of page transitions
 
 ## Prerequisites
+
 We expect you to have successfully finished the [previous guide](guides/essential/02_active_record.md).
 
 ## Update person controller and routes
@@ -43,6 +46,7 @@ end
 ```
 
 ## Page transitions
+
 In `app/matestack/demo/app.rb`, replace the contents with the code snippet below in order to add a navigation transition to the root path in our app layout.
 
 ```ruby

docs/guides/essential/04_forms_edit_new_create_update_delete.md

@@ -1,6 +1,6 @@
 # Essential Guide 4: Forms & Actions (Create, Update, Delete)
 
-Welcome to the forth part of the 10-step-guide of setting up a working Rails CRUD app with `matestack-ui-core`!
+Welcome to the fourth part of our essential guide about building a web application with matestack.
 
 ## Introduction
 
@@ -13,8 +13,6 @@ In this guide, we will
 - introduce the concept of matestack forms
 - introduce the concept of matestack actions
 
-action with a delete button to the "show" page and corresponding controller action to remove an existing person from the database
-
 ## Prerequisites
 We expect you to have successfully finished the [previous guide](guides/essential/03_index_show_transition.md).
 
@@ -124,7 +122,7 @@ Create a new page in `app/matestack/demo/pages/persons/new.rb` and add the follo
 class Demo::Pages::Persons::New < Matestack::Ui::Page
 
   def response
-    transition path: :persons_path, text: 'All persons'
+    transition path: persons_path, text: 'All persons'
     heading size: 2, text: 'Create a new person'
     form new_person_form_config, :include do
       label text: 'First name'
@@ -254,7 +252,7 @@ Update your show page in `app/matestack/demo/pages/persons/show.rb` to look like
 class Demo::Pages::Persons::Show < Matestack::Ui::Page
 
   def response
-    transition path: :persons_path, text: 'Back to index'
+    transition path: persons_path, text: 'All persons'
     heading size: 2, text: "Name: #{@person.first_name} #{@person.last_name}"
     paragraph text: "Role: #{@person.role}"
     transition path: :edit_person_path, params: { id: @person.id }, text: 'Edit'
@@ -314,4 +312,4 @@ We got a brief introduction of the `form` and `action` components and know how t
 
 But there's still more guides coming - so what's left? In the upcoming chapters, we will dive deeper into some `matestack` concepts to further enhance both user experience and developer happiness!
 
-Take a well deserved rest and make sure to come back to the next part of this series, introducing the powerful [`async` and `collection` components](/guides/essential/04_form_create_update_delete.md).
+Take a well deserved rest and make sure to come back to the next part of this series, introducing the powerful [`toggle component`](/guides/essential/05_toggle_component.md).

docs/guides/essential/05_toggle_component.md

@@ -0,0 +1,96 @@
+# Essential Guide 5: Toggle Component
+
+Welcome to the fifth part of our essential guide about building a web application with matestack.
+
+## Introduction
+
+In this guide, we will introduce matestacks `toggle` and `onclick` components. For this we will 
+- add a show more button to the person show page
+- add more content to the show page
+
+## Prerequisites
+
+We expect you to have successfully finished the [previous guide](guides/essential/04_forms_edit_new_create_update_delete.md).
+
+## Adding a show more button with onclick
+
+Let's add a show more button to the person show page. When clicked more information about the user should be shown. In our case when it was created and when it was last updated. To do this we will use matestacks `onclick` component and later the `toggle` component.
+
+Edit the show page in `app/matestack/demo/pages/persons/show.rb`
+
+```ruby
+class Demo::Pages::Persons::Show < Matestack::Ui::Page
+
+  def response
+    transition path: persons_path, text: 'All Persons'
+    heading size: 2, text: "Name: #{@person.first_name} #{@person.last_name}"
+    paragraph text: "Role: #{@person.role}"
+
+    onclick emit: 'show_more' do
+      button text: 'Show more'
+    end
+
+    transition path: :edit_person_path, params: { id: @person.id }, text: 'Edit'
+    action delete_person_config do
+      button text: 'Delete person'
+    end
+  end
+
+  #...
+
+end
+```
+
+So what does the `onclick` component do? Onclick takes one argument called `emit`. The `onclick` component renders the given block and if its clicked emits an event with the specified name. In this case it emits an event with the name `show_more` when the button is clicked. In the next section you will find out, why this is useful.
+
+## Show more content with toggle
+
+When the show more button is clicked, we want to show more content. Above we added a button which emits a `show_more` event when clicked. So we need a component which will show its content when this event is emitted. For this we use matestacks `toggle` component. It allows us to show or hide content depending on emitted events. Let's add more content inside a `toggle` component to the show page.
+
+```ruby
+class Demo::Pages::Persons::Show < Matestack::Ui::Page
+
+  def response
+    transition path: persons_path, text: 'All Persons'
+    heading size: 2, text: "Name: #{@person.first_name} #{@person.last_name}"
+    paragraph text: "Role: #{@person.role}"
+
+    onclick emit: 'show_more' do
+      button text: 'Show more'
+    end
+
+    toggle show_on: 'show_more' do
+      paragraph text: "Created at: #{I18n.l(@person.created_at)}"
+      paragraph text: "Created at: #{I18n.l(@person.updated_at)}"
+    end
+
+    transition path: :edit_person_path, params: { id: @person.id }, text: 'Edit'
+    action delete_person_config do
+      button text: 'Delete person'
+    end
+  end
+
+  #...
+
+end
+```
+
+The `toggle` component will be hidden on page loads. When we click our 'Show more' button, the content of our `toggle` component gets visible and you can see the localized time of the person created and updated timestamp.
+
+Run `rails s` and head over to [localhost:3000](http://localhost:3000/) and open the details of one person to test it out.
+
+To learn more, check out the [complete API documentation](/docs/api/components/toggle.md) for the `toggle` component.
+
+## Saving the status quo
+
+As usual, we want to commit the progress to Git. In the repo root, run
+
+```sh
+git add . && git commit -m "add show more toggle to person show page"
+```
+
+## Recap & outlook
+
+We added a show more button to our persons show page and learned how to use the `onclick` and `toggle` components and what they can be used for.  
+
+Take a well deserved rest and make sure to come back to the next part of this series, introducing the powerful [`async` component](/guides/essential/06_async_component.md).