[TASK][REFACTOR] rework 02_active_record guide

Author: Nils Henning

docs/guides/essential/02_active_record.md

@@ -10,7 +10,7 @@ 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) and no uncommited changes in your project.
+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
@@ -19,24 +19,24 @@ First, we need to create an ActiveRecord model and add the corresponding table t
 rails generate model Person first_name:string last_name:string role:integer
 ```
 
-in the terminal. After the command has finished, you should see a new migration in `db/migrations/` and a newly added model in `app/models/person.rb`. To then apply those changes, you need to run
+in the terminal. After the command has finished, you should see a new migration in `db/migrations/` and a newly added model `app/models/person.rb`. To then apply those changes, you need to run
 
 ```sh
-rake db:migrate
+rails db:migrate
 ```
 
 which should update the database schema in `db/schema.rb`.
 
-## Updating the model, adding seeds and displaying app
-To make use of the `role`-enum we already prepared in the database, update `app/models/person.rb` to look like this:
+## 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
 class Person < ApplicationRecord
 	enum role: [:client, :partner, :staff]
 end
 ```
 
-Great! Now, let's populate the database with some "fake" persons. Therefor, add the following content to `db/seeds.rb`:
+Great! Now, let's populate the database with some "fake" persons. Therefore add the following content to `db/seeds.rb`:
 
 ```ruby
 seeded_persons = [
@@ -61,35 +61,49 @@ end
 and run
 
 ```sh
-rake db:seed
+rails db:seed
 ```
 
-to add those first persons to the database!
+to add those persons to the database!
 
-To finish things up for now, let's display all the new persons within the `matestack` app! To achieve this, update the contents of `app/matestack/demo/app.rb` to look like this:
+To finish things up for now, let's display all the new persons on an index page inside our app! To achieve this, we add an index route for our person model in `routes.rb`.
 
 ```ruby
-class Demo::App < Matestack::Ui::App
+Rails.application.routes.draw do
+  root to: 'demo#first_page' 
+  get '/second_page' to: 'demo#second_page' 
+
+  resources :persons, only: [:index]
+end
+```
+
+After that we create the corresponding person controller in `app/controllers/person_controller.rb` which will handle the index action. The index action should render the persons index page which we will create afterwards.
+
+```ruby
+class PersonsController < ApplicationController
+
+  def index
+    render Demo::Pages::Persons::Index
+  end
+
+end
+```
+
+Now we create our person index page. Because it should be rendered inside our demo app, it belongs to the demo namespace and as a page under the pages section. So we create our person index page under `app/matestack/demo/pages/persons` with the name `index.rb`. This index page should render a list of all persons.
+
+```ruby
+class Demo::Pages::Persons::Index
 
   def prepare
     @persons = Person.all
   end
 
   def response
-    header do
-      heading size: 1, text: 'Demo App'
-      transition path: :first_page_path, text: 'First page'
-      br
-      transition path: :second_page_path, text: 'Second page'
-    end
-    main do
-      page_content
-      ul do
-        @persons.each do |person|
-          li do
-            plain person.first_name
-            strong text: person.last_name
-          end
+    ul do
+      @persons.each do |person|
+        li do
+          plain person.first_name
+          strong text: person.last_name
         end
       end
     end
@@ -98,9 +112,11 @@ class Demo::App < Matestack::Ui::App
 end
 ```
 
-What happens here? In the `prepare`-statement, you're fetching all the person instances from your database, and within the `main`-tag each person's name gets displayed (last names in **bold** for extra emphasis) inside an unordered list (`ul`). Run `rails s` and head over to [localhost:3000](http://localhost:3000/) to check the result!
+What happens in this page? Before calling the `response` method of a page, app or component the `prepare` method gets evaluated. In this case we fetch all the persons from the database and assign the result to the instance variable `@persons` in the `prepare` statement. Inside our response method we can access this instance variable and iterate over it to create _li_ tags containing the plain person first name and the lastname inside a _strong_ tag.
+
+Run `rails s` and head over to [localhost:3000/persons/index](http://localhost:3000/persons/index) to check the result!
 
-Of course, this is a very basic approach that we will iterate upon in the following parts of this guide series!
+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
@@ -109,34 +125,7 @@ As usual, we want to commit the progress to Git. In the repo root, run
 git add . && git commit -m "Introduce person model including seeds, add it to matestack/demo/app.rb"
 ```
 
-## Deployment
-After you've finished all your changes and commited them to Git, trigger another deployment via
-
- ```sh
- git push heroku master
- ```
-
-to publish your changes. If you visit your site now, you will find that it is broken! But no worries, this is easily fixed: This time, since we've changed the schema in the database, we also need to take an extra step and migrate the database by running
-
-```sh
-heroku run rake db:migrate
-```
-
-After the migration finished successfully, your site is available again, but there's no visible change - there are no persons in the database yet. To change this, trigger the seeds by running
-
-```sh
-heroku run rake db:seed
-```
-
-Finally, you should be able to check the changes via
-
-```sh
-heroku open
-```
-
-and see a list of all the persons in your database - nice!
-
 ## Recap & outlook
-We have updated the app to use a working database model, added some dummy records and displayed them in the `matestack` app.
+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).