add request cycle and more detailed explanation of mvc

sites/en/intro-to-rails/CRUD_with_scaffolding.step

@@ -17,20 +17,19 @@ steps {
 
   step {
     console "rails server"
-
     tip "Now is a good time to figure out how to have multiple tabs or windows of your terminal or command prompt. Starting and stopping the Rails server all day is tedious, so it's good to have one terminal tab or window for running commands, and a separate one for the server."
   }
 
   step {
     message "Point your browser to [http://localhost:3000/topics](http://localhost:3000/topics)"
-    message "You should see the \"Topics\" page with headers for title and description, and a link to add a new topic:"
+    message 'You should see the "Listing Topics" page with headers for title and description, and a link to add a new topic:'
 
     img src: "img/Seattle_topic_list_page.png", alt: "Screenshot of topic list page"
   }
 
   step {
     message <<-MARKDOWN
-  * Click "New Topic"
+  * Click on "New Topic"
   * Fill in the form and click "Create Topic"
   * You should see a page showing your new topic with a message that your topic was successfully created:
     MARKDOWN
@@ -40,70 +39,21 @@ steps {
 
   step {
     message <<-MARKDOWN
-      * Click "Back"
+      * Click on "Back"
       * You should see the topic list again, this time with your new topic listed:
 
       ![Screenshot of topic list with new topic](img/Seattle_list_with_topic.png)
 
-      * Try the "Show", "Edit", and "Destroy" links to see what they do
-      * You've created a basic database driven web site, congrats!
+      * Try the "show", "edit", and "destroy" links to see what they do
+      * You've created a basic database-driven web site. Congratulations!
     MARKDOWN
   }
 }
 
 explanation {
-
   message <<-MARKDOWN
-  How did all those pages get created and hooked together? The Rails scaffold did it for you.
-
-  Let's take a closer look at some of the files Rails created:
-
-  * `app/models/topic.rb`
-    * This file contains code for our topic model. If you look at it,
-      it's nearly blank. Creating, reading, updating, and deleting
-      records are built into Rails.
-
-  * `app/views/topics`
-    * This folder contains all the views for our topics model. This is
-      where the code for the forms you used above is stored. Rails
-      created all of these pages as part of the scaffold.
-    * If you've written HTML before, many lines in the views should
-      look familiar. Rails views are HTML with some extra code added
-      to display data from the database.
-
-  * `app/views/topics/index.html.erb`
-    * This is the code for the page that lists all the topics.
-    * Index is the name given to the "default" page for a web site or a
-      section of a web site. When you navigate to
-      http://localhost:3000/topics the topics index page is what is
-      sent to your computer.
-
-  * `app/views/topics/show.html.erb`
-    * This is the page you get when you click the "Show" link on the
-      "Listing topics" page.
-
-  * `app/views/topics/new.html.erb`
-    * This is the page you get when you click "New Topic".
-
-  * `app/views/topics/edit.html.erb`
-    * This is the page you get when you click "Edit".
-
-  * `app/views/topics/_form.html.erb`
-    * You may have noticed that the page for new topics and the page
-      to edit topics looked similar. That's because they both use the
-      code from this file to show a form. This file is called a
-      partial since it only contains code for part of a page. Partials
-      always have filenames starting with an underscore character.
-
-    * Challenge question: Can you find the line of code in new.html.erb
-      and edit.html.erb that makes the form partial appear?
-
-  * `app/controllers/topics_controller.rb`
-    * This is the controller file that Rails created as part of the scaffold
-    * If you look you'll see a method (a line beginning with
-      <code>def</code>) for each of the views listed above (except
-      `_form.html.erb`)
-    MARKDOWN
+  How did all those pages get created and hooked together? `rails scaffold` did it for you.
+  MARKDOWN
 }
 
-next_step "setting_the_default_page"
+next_step "the_request_cycle_and_rails_architecture"

sites/en/intro-to-rails/creating_a_migration.step

@@ -17,11 +17,9 @@ steps {
 * `generate scaffold` tells Rails to create everything necessary to get up and running with topics.
 * `topic` tells Rails the name of the new model.
 * `title:string` says that topics have a title, which is a "string".
-* `description:text` says that topics have a description which is a "text". (What's the difference between "string" and "text"? Basically "text" is for strings that might be very long.)
+* `description:text` says that topics have a description which is a "text". A "text" is like a "string" that might be very long.
 
     MARKDOWN
-    message "If you want, take some time to poke around the files listed in this step. You can learn about them in the [Rails Architecture](rails_architecture) page."
-    link "rails_architecture"
   }
 
   step {
@@ -31,14 +29,35 @@ steps {
 }
 
 explanation {
+  h2 "Databases don't create tables by themselves - they need instructions."
 
   message <<-MARKDOWN
-Here, `rails db:migrate` is a command provided by the Rails framework. It uses the migration file we just created (`db/migrate/201xxxxxxxxxxx_create_topics.rb`) to change the database. Database migration files can be crucial to code collaboration.
+    One of the files the scaffold command created will be named something like
+    `db/migrate/20140515115208_create_topics.rb`. The numbers in the name are
+    the date and time the file was made, so yours will be named differently.
+
+    The file contains Ruby code that describes what the table will look like.
+    This is called a migration file.  It tells the database how to transform
+    itself into the new configuration.
+
+    ```ruby
+    class CreateTopics < ActiveRecord::Migration
+      def change
+        create_table :topics do |t|
+          t.string :title
+          t.text :description
+
+          t.timestamps
+        end
+      end
+    end
+    ```
+
+    `rake db:migrate` is a task provided by the Rails framework. It uses the migration file we just created (`db/migrate/201xxxxxxxxxxx_create_topics.rb`) to change the database. 
 
   MARKDOWN
 
-  tip "You can run `rails --help` to see a list of all the `rails` commands your app currently responds to, along with a short description of each one."
+  tip "You can run `rails -T` to see a list of all the `rails` commands your app currently responds to, along with a short description of each task."
 }
 
-
 next_step "CRUD_with_scaffolding"

sites/en/intro-to-rails/the_request_cycle_and_rails_architecture.step

@@ -0,0 +1,89 @@
+goals {
+
+  message "In this step we'll learn about how the files created by scaffold work together. By the end of this step you should understand the following concepts:"
+
+  ul {
+    li "Request Cycle"
+    li "Model View Controller (MVC) Architecture"
+  }
+}
+
+explanation {
+
+  h1 "Request Cycle"
+
+  message "<img src='img/request-cycle.png'>"
+
+  discussion_box "What is this diagram?", <<-MARKDOWN
+    Talk through this diagram of the request cycle!
+  MARKDOWN
+
+  h1 "Model View Controller (MVC) Architecture"
+
+  message "Rails implements a very specific notion of the **Model/View/Controller** pattern, which guides how you structure your web applications."
+
+  h2 "Controller"
+  message <<-MARKDOWN
+  * When you visit any page in your application, that request will be handled by a method in a Controller.
+  * Controllers use the Models to create, read, update, and delete data from the database.
+  * Controllers pass Ruby objects to the Views.
+
+  MARKDOWN
+
+  message "**Let's take a look at the Controller file in suggestotron:**"
+
+  message <<-MARKDOWN
+    * `app/controllers/topics_controller.rb`
+  MARKDOWN
+
+  message "You'll see a method (a line beginning with
+      <code>def</code>) for each of the views listed above (except
+      _form.html.erb)."
+
+  h2 "Model"
+  message <<-MARKDOWN
+  * The Model is a bridge between the database and your application's code.
+  * For all the Models we create in RailsBridge, Model objects have a corresponding record in the database. The name of the table in the database is the plural version of the Model's class name.
+  MARKDOWN
+
+  message "**Let's take a look at the Topic Model in suggestotron:**"
+
+  message <<-MARKDOWN
+  * `app/models/topic.rb`
+  MARKDOWN
+
+  h2 "View"
+  message <<-MARKDOWN
+  * The View generates the HTML that will be displayed in the browser.
+  * View files are written in ERB, a templating language. It contains HTML with Ruby code embedded in it. The ruby variables in the view stand as placeholders for content that will be filled in when a user requests the page.
+  MARKDOWN
+
+  message "**Let's take a look at the Topic View files in suggestotron and match each View file with the corresponding page in the browser.**"
+
+  message <<-MARKDOWN
+  The file **`app/views/topics/index.html.erb`** in your **text editor (Sublime)**:
+
+  ![Screenshot of topic index view file in Sublime](img/Topics_Index_File_Viewed_In_Sublime.png)
+
+  Creates this **page** in your **web browser**:
+
+  ![Screenshot of topic index page in a web browser read](img/Seattle_list_with_topic.png)
+
+  Match the rest of the Topic View files (in your text editor, Sublime) to a page in your web browser:
+  MARKDOWN
+  message <<-MARKDOWN
+    * `app/views/topics/show.html.erb`
+    * `app/views/topics/new.html.erb`
+    * `app/views/topics/edit.html.erb`
+    * `app/views/topics/_form.html.erb`
+  MARKDOWN
+
+  message "You may have noticed that the page for new topics and the page to edit topics looked similar. That's because they both use the
+  code from this file to show a form. This file is called a
+  partial since it only contains code for part of a page. Partials
+  always have filenames starting with an underscore character."
+
+  message "**Challenge question:** Can you find the line of code in `new.html.erb` and `edit.html.erb` that makes the form partial appear?"
+}
+
+next_step "setting_the_default_page"