[TASK][REFACTOR] rework 04_forms_edit_new_create_update_delete guide

Author: Nils Henning

docs/guides/essential/04_forms_edit_new_create_update_delete.md

@@ -1,31 +1,37 @@
 # 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`!
 
 ## Introduction
-In the [previous guide](guides/essential/03_index_show_transition.md), we added index and show pages for the **person** model. In this part, we will add the functionality to add new instances and edit and delete our database records using `matestack` forms.
+
+In the [previous guide](guides/essential/03_index_show_transition.md), we added index and show pages for the **person** model. In this part, we will implement the create, update and delete part of our CRUD application. For this we will introduce the matestack `forms`.
 
 In this guide, we will
-- add a **New** page and corresponding controller action to create new persons
-- add an **Edit** page and corresponding controller action to modify existing persons
-- add an action with a delete button to the "show" page and corresponding controller action to remove an existing person from the database
-- introduce the concept of `matestack` forms
-- introduce the concept of `matestack` actions
+- add a new page and action action to create new persons
+- add an edit page and action to modify existing persons
+- add an delete action to delete existing persons 
+- 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) and no uncommited changes in your project.
+We expect you to have successfully finished the [previous guide](guides/essential/03_index_show_transition.md).
 
 ## Updating the person model
-Let's make sure all the persons in our database actually end up having a name and a a role by adding those lines to `app/models/person.rb`:
+
+All persons should have a first name, last name and a role. Therefore we add validations to our person model for these three attributes in `person.rb`.
 
 ```ruby
 validates :first_name, presence: true
 validates :last_name, presence: true
 validates :role, presence: true
 ```
 
-This might not seem like a big change, but will help with validating form input later on!
+We only check for presence of this three attributes. 
 
 ## Preparing routes & controller
+
 In your `config/routes.rb`, change
 
 ```ruby
@@ -38,19 +44,15 @@ to
 resources :persons
 ```
 
-to allow further actions for the ressource.
+in order to let rails generate all CRUD routes for persons.
 
 Then, in the `persons_controller.rb`, update the contents like this:
 
 ```ruby
 class PersonsController < ApplicationController
-  before_action :set_person, only: [:show, :edit, :update, :destroy]
-
   matestack_app Demo::App
 
-  def new
-    render Demo::Pages::Persons::New
-  end
+  before_action :find_person, only: [:show, :edit, :update, :destroy]
 
   def index
     render Demo::Pages::Persons::Index
@@ -60,43 +62,42 @@ class PersonsController < ApplicationController
     render Demo::Pages::Persons::Show
   end
 
-  def edit
-    render Demo::Pages::Persons::Edit
+  def new
+    render Demo::Pages::Persons::New
   end
 
-  def update
-    @person.update person_params
-
-    @person.save
-    if @person.errors.any?
-      render json: {errors: @person.errors}, status: :unprocessable_entity
+  def create
+    person = Person.create person_params
+    if person.errors.empty?
+      render json: { transition_to: person_path(person) }, status: :created
     else
-      render json: { transition_to: person_path(id: @person.id) }, status: :ok
+      render json: { errors: person.errors }, status: :unprocessable_entity
     end
   end
 
-  def create
-    @person = Person.new(person_params)
-    @person.save
+  def edit
+    render Demo::Pages::Persons::Edit
+  end
 
-    if @person.errors.any?
-      render json: {errors: @person.errors}, status: :unprocessable_entity
+  def update
+    if @person.update person_params
+      render json: { transition_to: person_path(@person) }, status: :ok
     else
-      render json: { transition_to: person_path(id: @person.id) }, status: :created
+      render json: { errors: @person.errors }, status: :unprocessable_entity
     end
   end
 
   def destroy
     if @person.destroy
       render json: { transition_to: persons_path }, status: :ok
     else
-      render json: {errors: @person.errors}, status: :unprocessable_entity
+      render json: { errors: @person.errors }, status: :unprocessable_entity
     end
   end
 
   protected
 
-  def set_person
+  def find_person
     @person = Person.find_by(id: params[:id])
   end
 
@@ -111,23 +112,20 @@ class PersonsController < ApplicationController
 end
 ```
 
-What's going on there? We've added `render`-methods for two new `matestack` pages (**New** and **Edit**) and controller endpoints for **create**, **update** and **destroy** actions. Since we're interacting with the database directly now, we also need to sanitize the params and, to keep the code clean, have extracted some functionality into a `before_action`.
+What's going on there? We've added `render`-calls for two new matestack pages (new, edit) and controller actions for create, update and destroy. To keep the code clean, we have extracted some functionality into a `before_action` and added the `person_params` method to extract person relevant params from all params in rails safe params manner.
 
 Nothing extraordinary, but definitely stepping things up a bit!
 
-## Adding the **New** and **Edit** pages
+## Adding the new and edit pages with forms
+
 Create a new page in `app/matestack/demo/pages/persons/new.rb` and add the following content:
 
 ```ruby
 class Demo::Pages::Persons::New < Matestack::Ui::Page
 
-  def prepare
-    @person = Person.new
-  end
-
   def response
-    transition path: :persons_path, text: 'Back to index page'
-    heading size: 2, text: 'Create new person'
+    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'
       form_input key: :first_name, type: :text
@@ -136,7 +134,7 @@ class Demo::Pages::Persons::New < Matestack::Ui::Page
       form_input key: :last_name, type: :text
       br
       label text: 'Person role'
-      form_select key: :role, type: :radio, options: Person.roles.keys
+      form_radio key: :role, options: Person.roles.keys
       br
       form_submit do
         button text: 'Create person'
@@ -146,9 +144,9 @@ class Demo::Pages::Persons::New < Matestack::Ui::Page
 
   def new_person_form_config
     {
-      for: @person,
+      for: Person.new,
       method: :post,
-      path: :persons_path,
+      path: persons_path,
       success: {
         transition: {
           follow_response: true
@@ -161,11 +159,21 @@ end
 ```
 
 What's going on here? Let's break it down:
-- in the `prepare` method, an empty person record is created so we can fill it later
-- within the `response` method, there's a link back to the **Show** page, a heading and the first `matestack` form, featuring two text input fields, radio select fields and a submit button
-- the `new_person_form_config` tells the form which data to use (the empty person, in this case), where to send the inputs upon submission and how to handle successful (and, potentially, unsuccessful) response messages from the controller!
 
-Take a moment to familiarize yourself with everything going on in the file, and then go ahead and create another page in `app/matestack/demo/pages/persons/edit.rb`, featuring similar content:
+Within our response method we have at first a transition to the person index page. After that comes _h2_ tag as a headline stating 'Create a new person'. Nothing new so long. Afterwards comes an unfamiliar call of `form`.
+
+Let's take a closer look. Like in Rails with `form_for` you can create a form in matestack with `form`. It takes a hash as first argument for configuration. In this case we defined `new_person_form_config` to return the config hash for our form. In the config hash you can set the http request method, a path, success and failure configs and a for key, which will be explained soon. This form gets submitted as a POST request to the `persons_path`. 
+
+The `for` key let's us define for what this form is. In this case we pass a empty model to the form component, which will therefore submitt the form inputs wrapped by the model name following the Rails behavior and conventions.
+
+The 'success' key let's us define a behavior when the form was submitted successful, which means the server returned a status code of 2XX. In this case we tell the form that if successful it should follow the transition path we return in our controller action. So a page transition will happen to the detail page of our newly created model. We could also configure a failure behavior by specifying the `failure` key.
+
+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/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:
 
 ```ruby
 class Demo::Pages::Persons::Edit < Matestack::Ui::Page
@@ -208,19 +216,39 @@ class Demo::Pages::Persons::Edit < Matestack::Ui::Page
 end
 ```
 
-Again, we're using a form within the `response` method and define its behaviour in the `person_edit_form_config`. Since this time, an existing person is looked up in the database, the form gets initialized with his/her data.
+Again, we're using a form within the `response` method and define its behaviour in the `person_edit_form_config`. Since this time, an existing person is looked up in the database, the form gets initialized with his/her data as described above.
+
+## Updating the index page
 
-## Updating the **Index** page
 Within the `response` block on the **Index** page (`app/matestack/demo/pages/persons/index.rb`), add the following line:
 
 ```ruby
 transition path: :new_person_path, text: 'Create new person'
 ```
 
-As you might have guessed, this takes us to the **New** page and you can add a new person to the database there!
+As you might have guessed, this takes us to the **New** page and you can create a new person there.
+
+## Further introduction: Forms
+
+During this article, you've got a general idea of how matestack forms handle data input. But since this is only an introductory guide, we can't cover all the possible use cases and functionality in here.
 
-## Adding the **delete** button to the **Show** page
-Update your **Show** page in `app/matestack/demo/pages/persons/show.rb` to look like this:
+Let's do a quick recap: The `form` component can be used like other components we have seen before, but requires a hash as parameter for configuration. Within the hash, various configurations like HTTP method, submission path, payload and handling of success/failure responses can be set.
+
+Beyond that, here's some suggestions of what you could try to add in the future:
+- uploading files
+- handling failure
+- different input types like email, password, textfield, range or dropdown
+- re-rendering parts of a page instead of doing a page transition
+- 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/components/form.md) for the `form` component.
+
+## Adding a delete button for persons
+
+We want to add the ability to delete persons. For that we add a delete button to the persons show page, which will destroy the person model when it was clicked. To achieve this we will use matestacks `action` component.
+
+Update your show page in `app/matestack/demo/pages/persons/show.rb` to look like this:
 
 ```ruby
 class Demo::Pages::Persons::Show < Matestack::Ui::Page
@@ -236,12 +264,9 @@ class Demo::Pages::Persons::Show < Matestack::Ui::Page
   end
 
   def delete_person_config
-    return {
+    {
       method: :delete,
-      path: :person_path,
-      params: {
-        id: @person.id
-      },
+      path: person_path(@person),
       success: {
         transition: {
           follow_response: true
@@ -256,63 +281,37 @@ class Demo::Pages::Persons::Show < Matestack::Ui::Page
 end
 ```
 
-This is the first time we encounter another powerful `matestack` component: The `action` component! In the example above, the delete button gets wrapped into an `action` that receives a `*_config*` parameter. The configuration then is specified below, sending the currently displayed person's `id` to the **delete** action in the `person controller`. Upon a positive response from our controller, we configure our `action` component to follow the redirect specified in the **delete** action.
-
-## Further introduction: Forms
-During this article, you've got a general idea of how `matestack` forms handle data input. But since this is only an introductory guide, we can't cover all the possible use cases and functionality in here.
-
-Let's do a quick recap: The `form` component can be used like the other components we have seen before, but requires a `*_config` parameter. Within the `*_config`, various parameters like HTTP method, submission path, payload and handling of success/error responses can be set.
-
-Beyond that, here's some suggestions of what you could try to add in the future:
-- uploading files
-- handling failure
-- different input types like email, password, textfield, range or dropdown
-- re-rendering parts of a page instead of doing a page transition
-- using other Ruby objects than ActiveRecord collections
-- fetching data from and sending data to third party APIs instead of interacting with your database
-
-To learn more, check out the [complete API documentation](docs/components/form.md) for the `form` component.
+As you see we wrap our delete button inside an `action` component. Like the `form` component, an `action` component also takes a hash as first parameter for configuration. An action component triggers a asynchronous request when someone clicks on the wrapped content. The request target and http method are again configured in the hash. In this case when the action component is clicked it will send an DELETE request to `/persons/:id`. For a successful request we configured our `action` component to follow the redirect specified by the delete action. With the `confirm` keyword we can configure that when the button is clicked a confirm dialog pops up and needs to be confirmed before the request is send.
 
 ## Further introduction: Actions
 As we've seen with the delete button, `matestack` actions are a convenient way to trigger HTTP requests without having to write a lot of code.
 
-Let's do a quick recap: Similar to the `form`, an `action` component requires a `*_config` parameter and wraps other content, for example a button. This content is then clickable and triggers whatever HTTP request is specified in the configuration.
+Let's do a quick recap: Similar to the `form`, an `action` component requires a hash as parameter for configuration and wraps other content, for example a button. This content is then clickable and triggers whatever HTTP request is specified in the configuration.
 
 Beyond that, here's some suggestions of what you could try to add in the future:
 - sending an advanced payload with the HTTP request
-- adding a confirmation window
 - re-rendering parts of a page on successful request
 
 To learn more, check out the [complete API documentation](docs/components/action.md) for the `action` component.
 
 ## Local testing
+
 Run `rails s` and head over to [localhost:3000](http://localhost:3000/) to test the changes! You should be able to create new persons as well as edit and delete existing ones!
 
 ## 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 edit/new matestack pages for person model (incl. create/update controller, routes), add delete button (incl. controller action & route) to person show page"
 ```
 
-## Deployment
-After you've finished all your changes and commited them to Git, run
-
-```sh
-git push heroku master
-```
-
-to deploy your latest changes (again, no migrations are needed as the database schema is still unchanged). Check the results via
-
-```sh
-heroku open
-```
-
-and celebrate your progress by creating some new persons, modifying existing ones and delete one or two!
-
 ## Recap & outlook
+
 By now, we have already implemented the complete **CRUD** (**C**reate-**R**ead-**U**pdate-**D**elete) functionality around the person model. Neat!
 
-But there's still six out of ten guides open - 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!
+We got a brief introduction of the `form` and `action` components and know how to use them. 
+
+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).