Merge pull request railsbridge#298 from railsbridge/never-speak-mvc

De-jargon-ify MVC explanation.

Author: alexch

lib/step.rb

@@ -170,7 +170,11 @@ def goals
     end
   end
 
-  alias_method :goal, :li
+  def goal *args
+    li do
+      message *args
+    end
+  end
 
   def site_desc site_name, description
     div class: 'site-desc' do
@@ -215,6 +219,7 @@ def tip text = nil, &block
 
   ## special
 
+  # todo: i18n
   TERMINAL_CAPTION = "Type this in the terminal:"
   IRB_CAPTION = "Type this in irb:"
   RESULT_CAPTION = "Expected result:"

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

@@ -4,30 +4,24 @@ goals {
 
   message "The suggestotron has a list of topics that people can vote on. We'll store our topics in the database. In this step you'll do the following:"
 
-  goal "Create a database table for topics with a title and a description"
+  goal "Create a a simple *Table* in the database for topics with a title and a description"
+  goal "Automatically generate the corresponding *Scaffold* in Rails (namely, the *Model*, the *View*, and the *Controller*)."
 
-  message "In this step we'll learn a bit about MVC (Model-View-Controller) architecture. By the end of this step you should understand the following concepts:"
-
-  ul {
-    li "A record"
-    li "Model"
-    li "View"
-    li "Controller"
-  }
 }
 
 steps {
 
-
   step {
     console "rails generate scaffold topic title:string description:text"
     message <<-MARKDOWN
 * `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". (We're befuddled by the difference too.)
+* `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.)
+
     MARKDOWN
-    message "If you want, take some time to poke around the files listed in this step."
+    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 {
@@ -40,40 +34,14 @@ explanation {
 
   h2 "Rake"
   message <<-MARKDOWN
-`rake` _(Ruby Make)_ is a tool that allows you to run small Ruby programs (**tasks**) that you use often in your application. Here, `rake db:migrate` is a task provided by the Rails framework.
-
-You can run `rake -T` to see a list of all the `rake` commands your app currently responds to, along with a short description of each task.
-  MARKDOWN
-
-  h2 "Explaining MVC and Records"
-
-  img src: "img/mvc.png", alt: "MVC"
-
-  message "Rails implements a very specific notion of the **Model/View/Controller** pattern, which guides how you structure your web applications."
-
-  h3 "Model"
-  message <<-MARKDOWN
-* saves data to the database
-* accesses data from the database
-* bridge between the database and objects
-  MARKDOWN
+`rake` _(ruby make)_ is a tool that allows you to run small Ruby programs (**tasks**) that you use often in your application.
 
-  h3 "View"
-  message <<-MARKDOWN
-* display the data for human (or machine) consumption
-* webpages are views
-  MARKDOWN
+Here, `rake db:migrate` is a task provided by the Rails framework. It creates a bunch of new files, including a *migration*, a *model*, a *view*, and a *controller*.
 
-  h3 "Controller"
-  message <<-MARKDOWN
-* acts as the glue between the models and the views
-* combines data from multiple models
-* summarizes and filters data
   MARKDOWN
 
-  message <<-MARKDOWN
-In MVC, models, views, and controllers have very specific jobs.  Separating responsibilities like this make it easy to maintain and extend rails applications.  When responsibilities become muddied it gets much harder to debug issues and add new functionality.
-  MARKDOWN
+  tip "You can run `rake -T` to see a list of all the `rake` commands your app currently responds to, along with a short description of each task."
 }
 
+
 next_step "CRUD_with_scaffolding"

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

@@ -0,0 +1,49 @@
+goals {
+
+  goal "Create a database table for topics with a title and a description"
+
+  message "In this step we'll learn a bit about Rails architecture. By the end of this step you should understand the following concepts:"
+
+  ul {
+    li "Table"
+    li "Model"
+    li "View"
+    li "Controller"
+  }
+}
+
+explanation {
+
+  h2 "Rails architecture and its relation to the database"
+
+  img src: "img/mvc.png", alt: "MVC"
+
+  message "Rails implements a very specific notion of the **Model/View/Controller** pattern, which guides how you structure your web applications."
+
+  h3 "Model"
+  message <<-MARKDOWN
+* For all the Models we create in RailsBridge, Model objects have a corresponding record in the the database. The name of the table in the database is the plural version of the Model's class name. For example, if the Model is called 'Duck', it will automatically query or write to the 'ducks' table in the database.
+* Methods internal to Rails make it easy to automatically write records to the the database and query the database to get the records again later.
+* The Model is a bridge between the database and your application's code.
+  MARKDOWN
+
+  h3 "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.
+* (There are several other templating languages available, but in RailsBridge we always stick to ERB.)
+  MARKDOWN
+
+  h3 "Controller"
+  message <<-MARKDOWN
+* Controllers pass Ruby objects between the Models and the Views.
+* Each url corresponds to a specific method in a Controller.
+* After this step, when you visit any page in your application, that request will be handled by a method in a Controller.
+  MARKDOWN
+
+  message <<-MARKDOWN
+When Models, Views and Controllers are all put together, they follow a pattern: Given a URL, Rails will look up which Controller method (also called an "Action") to use. The Controller Action will use methods in a corresponding Model. The Model will need to read or write to the database, and return an object containing that data to the Controller. The Controller will take that object and pass it to the View. (Actions normally have a corresponding View file, and Rails will automatically find and use that file.)
+
+Models, Views and Controllers each have specific jobs.  Separating responsibilities like this make it easier to develop, especially as it gets bigger. (When each file has a clear responsibility it's easier to fix problems and add new features.)
+  MARKDOWN
+}

step_file_reference.md

@@ -24,6 +24,23 @@ Here Docs are especially useful with `message`s since you can just dump in markd
   * maintains a count of steps at the same level
   * prefixes name with e.g. "Step 1:"
 
+`goals do`
+
+  * a titled, formatted list of goals
+
+`goal "text"`
+
+  * an individual goal (marked up with \<li\>)
+  * text can be markdown
+
+`steps do`
+
+  * a titled, formatted list of steps
+
+`explanation do`
+
+  * a titled, formatted block for a summary of what the student just did
+
 `link "name"`
 
   * links to a step whose file name is `filename`
@@ -38,38 +55,32 @@ Here Docs are especially useful with `message`s since you can just dump in markd
   * creates a step which is named "Option 1: foo" instead "Step 1: foo"
   * supports nested blocks, which reset the step count again
 
-`verify`
-
-`verify "name"`
-
-  * usually contains `console` and `result` notes
-  * kind of like a step, but doesn't increment the number count
-
-`tip "name"`
-
-  * called out in a blue box
-  * the name is *not* markdown, but is a bold title for the tip box
-  * content should be inside a nested block
-  
 `insert "filename"`
 
   * inserts the contents of one file inside another
   * a way to do "partials"
   * current limitations:
     * only works with `.step` files
     * inserted file must be in same directory as inserting file
+    * prepends an underscore to the file name
 
 ## messages
 
 `message "text"`
 
   * makes a paragraph of text anywhere in the document
   * the text parameter is passed through a Markdown converter
-  
+
 `important "text"`
 
   * like a message, but called out in a red box
 
+`tip "name" do`
+
+  * called out in a blue box
+  * the name is *not* markdown, but is an optional bold title for the tip box
+  * content should be inside a nested block
+
 ## special
 
 Special elements do *not* format their text as Markdown.
@@ -85,6 +96,16 @@ Special elements do *not* format their text as Markdown.
   * indicates that the student should see some output in the terminal
   * says "expected result:" and then puts the text in a `pre` block
 
+`verify`
+
+`verify "name"`
+
+  * usually contains `console` and `result` notes
+  * kind of like a step, but doesn't increment the number count
+
+`irb "text"`
+
+  * like "console" but indicates that the student should type something into irb
 
 
 ## erector elements