rails 4.0.0.rc1 → 4.0.0.rc2

data/guides/source/getting_started.md

@@ -64,7 +64,7 @@ Creating a New Rails Project
 The best way to use this guide is to follow each step as it happens, no code or
 step needed to make this example application has been left out, so you can
 literally follow along step by step. You can get the complete code
-[here](https://github.com/lifo/docrails/tree/master/guides/code/getting_started).
+[here](https://github.com/rails/docrails/tree/master/guides/code/getting_started).
 
 By following along with this guide, you'll create a Rails project called
 `blog`, a
@@ -165,7 +165,7 @@ TIP: Compiling CoffeeScript to JavaScript requires a JavaScript runtime and the
 
 This will fire up WEBrick, a webserver built into Ruby by default. To see your application in action, open a browser window and navigate to <http://localhost:3000>. You should see the Rails default information page:
 
-![Welcome Aboard screenshot](images/rails_welcome.png)
+![Welcome Aboard screenshot](images/getting_started/rails_welcome.png)
 
 TIP: To stop the web server, hit Ctrl+C in the terminal window where it's running. To verify the server has stopped you should see your command prompt cursor again. For most UNIX-like systems including Mac OS X this will be a dollar sign `$`. In development mode, Rails does not generally require you to restart the server; changes you make in files will be automatically picked up by the server.
 
@@ -252,29 +252,43 @@ Now that you've seen how to create a controller, an action and a view, let's cre
 
 In the Blog application, you will now create a new _resource_. A resource is the term used for a collection of similar objects, such as posts, people or animals. You can create, read, update and destroy items for a resource and these operations are referred to as _CRUD_ operations.
 
-In the next section, you will add the ability to create new posts in your application and be able to view them. This is the "C" and the "R" from CRUD: creation and reading. The form for doing this will look like this:
+Rails provides a `resources` method which can be used to declare a
+standard REST resource. Here's how `config/routes.rb` will look like.
 
-![The new post form](images/getting_started/new_post.png)
+```ruby
+Blog::Application.routes.draw do
 
-It will look a little basic for now, but that's ok. We'll look at improving the styling for it afterwards.
+  resources :posts
 
-### Laying down the ground work
+  root to: "welcome#index"
+end
+```
 
-The first thing that you are going to need to create a new post within the application is a place to do that. A great place for that would be at `/posts/new`. If you attempt to navigate to that now — by visiting <http://localhost:3000/posts/new> — Rails will give you a routing error:
+If you run `rake routes`, you'll see that all the routes for the 
+standard RESTful actions.
 
-![A routing error, no route matches /posts/new](images/getting_started/routing_error_no_route_matches.png)
+```bash
+$ rake routes
+    posts GET    /posts(.:format)          posts#index
+          POST   /posts(.:format)          posts#create
+ new_post GET    /posts/new(.:format)      posts#new
+edit_post GET    /posts/:id/edit(.:format) posts#edit
+     post GET    /posts/:id(.:format)      posts#show
+          PATCH  /posts/:id(.:format)      posts#update
+          PUT    /posts/:id(.:format)      posts#update
+          DELETE /posts/:id(.:format)      posts#destroy
+     root        /                         welcome#index
+```
 
-This is because there is nowhere inside the routes for the application — defined inside `config/routes.rb` — that defines this route. By default, Rails has no routes configured at all, besides the root route you defined earlier, and so you must define your routes as you need them.
+In the next section, you will add the ability to create new posts in your application and be able to view them. This is the "C" and the "R" from CRUD: creation and reading. The form for doing this will look like this:
 
- To do this, you're going to need to create a route inside `config/routes.rb` file, on a new line between the `do` and the `end` for the `draw` method:
+![The new post form](images/getting_started/new_post.png)
 
-```ruby
-get "posts/new"
-```
+It will look a little basic for now, but that's ok. We'll look at improving the styling for it afterwards.
 
-This route is a super-simple route: it defines a new route that only responds to `GET` requests, and that the route is at `posts/new`. But how does it know where to go without the use of the `:to` option? Well, Rails uses a sensible default here: Rails will assume that you want this route to go to the new action inside the posts controller.
+### Laying down the ground work
 
-With the route defined, requests can now be made to `/posts/new` in the application. Navigate to <http://localhost:3000/posts/new> and you'll see another routing error:
+The first thing that you are going to need to create a new post within the application is a place to do that. A great place for that would be at `/posts/new`.  With the route already defined, requests can now be made to `/posts/new` in the application. Navigate to <http://localhost:3000/posts/new> and you'll see a routing error:
 
 ![Another routing error, uninitialized constant PostsController](images/getting_started/routing_error_no_controller.png)
 
@@ -377,14 +391,10 @@ like this is called "create", and so the form should be pointed to that action.
 Edit the `form_for` line inside `app/views/posts/new.html.erb` to look like this:
 
 ```html+erb
-<%= form_for :post, url: { action: :create } do |f| %>
+<%= form_for :post, url: posts_path do |f| %>
 ```
 
-In this example, a `Hash` object is passed to the `:url` option. What Rails will do with this is that it will point the form to the `create` action of the current controller, the `PostsController`, and will send a `POST` request to that route. For this to work, you will need to add a route to `config/routes.rb`, right underneath the one for "posts/new":
-
-```ruby
-post "posts" => "posts#create"
-```
+In this example, the `posts_path` helper is passed to the `:url` option. What Rails will do with this is that it will point the form to the `create` action of the current controller, the `PostsController`, and will send a `POST` request to that route.
 
 By using the `post` method rather than the `get` method, Rails will define a route that will only respond to POST methods. The POST method is the typical method used by forms all over the web.
 
@@ -521,21 +531,28 @@ and change the `create` action to look like this:
 
 ```ruby
 def create
-  @post = Post.new(params[:post])
-
+  @post = Post.new(post_params)
+ 
   @post.save
-  redirect_to action: :show, id: @post.id
+  redirect_to @post
 end
+
+private
+  def post_params
+    params.require(:post).permit(:title, :text)
+  end
 ```
 
 Here's what's going on: every Rails model can be initialized with its
 respective attributes, which are automatically mapped to the respective
 database columns. In the first line we do just that (remember that
-`params[:post]` contains the attributes we're interested in). Then,
+`post_params` contains the attributes we're interested in). Then,
 `@post.save` is responsible for saving the model in the database.
 Finally, we redirect the user to the `show` action,
 which we'll define later.
 
+TIP: Note that `def post_params` is private. This new approach prevents an attacker from setting the model's attributes by manipulating the hash passed to the model. For more information, refer to [this blog post about Strong Parameters](http://weblog.rubyonrails.org/2012/3/21/strong-parameters/).
+
 TIP: As we'll see later, `@post.save` returns a boolean indicating
 whether the model was saved or not.
 
@@ -543,16 +560,14 @@ whether the model was saved or not.
 
 If you submit the form again now, Rails will complain about not finding
 the `show` action. That's not very useful though, so let's add the
-`show` action before proceeding. Open `config/routes.rb` and add the following route:
+`show` action before proceeding. 
 
 ```ruby
-get "posts/:id" => "posts#show"
+post GET    /posts/:id(.:format)      posts#show
 ```
 
 The special syntax `:id` tells rails that this route expects an `:id`
-parameter, which in our case will be the id of the post. Note that this
-time we had to specify the actual mapping, `posts#show` because
-otherwise Rails would not know which action to render.
+parameter, which in our case will be the id of the post. 
 
 As we did before, we need to add the `show` action in
 `app/controllers/posts_controller.rb` and its respective view.
@@ -601,7 +616,7 @@ look like this:
     @post = Post.new(params[:post].permit(:title, :text))
 
     @post.save
-    redirect_to action: :show, id: @post.id
+    redirect_to @post
   end
 ```
 
@@ -613,11 +628,11 @@ Visit <http://localhost:3000/posts/new> and give it a try!
 
 ### Listing all posts
 
-We still need a way to list all our posts, so let's do that. As usual,
-we'll need a route placed into `config/routes.rb`:
+We still need a way to list all our posts, so let's do that. 
+We'll use a specific route from `config/routes.rb`:
 
 ```ruby
-get "posts" => "posts#index"
+posts GET    /posts(.:format)          posts#index
 ```
 
 And an action for that route inside the `PostsController` in the `app/controllers/posts_controller.rb` file:
@@ -669,7 +684,7 @@ for posts.
 Let's add links to the other views as well, starting with adding this "New Post" link to `app/views/posts/index.html.erb`, placing it above the `<table>` tag:
 
 ```erb
-<%= link_to 'New post', action: :new %>
+<%= link_to 'New post', new_post_path %>
 ```
 
 This link will allow you to bring up the form that lets you create a new post. You should also add a link to this template — `app/views/posts/new.html.erb` — to go back to the `index` action. Do this by adding this underneath the form in this template:
@@ -679,7 +694,7 @@ This link will allow you to bring up the form that lets you create a new post. Y
   ...
 <% end %>
 
-<%= link_to 'Back', action: :index %>
+<%= link_to 'Back', posts_path %>
 ```
 
 Finally, add another link to the `app/views/posts/show.html.erb` template to go back to the `index` action as well, so that people who are viewing a single post can go back and view the whole list again:
@@ -695,7 +710,7 @@ Finally, add another link to the `app/views/posts/show.html.erb` template to go
   <%= @post.text %>
 </p>
 
-<%= link_to 'Back', action: :index %>
+<%= link_to 'Back', posts_path %>
 ```
 
 TIP: If you want to link to an action in the same controller, you don't
@@ -755,7 +770,7 @@ def create
   @post = Post.new(params[:post].permit(:title, :text))
 
   if @post.save
-    redirect_to action: :show, id: @post.id
+    redirect_to @post 
   else
     render 'new'
   end
@@ -776,7 +791,7 @@ something went wrong. To do that, you'll modify
 `app/views/posts/new.html.erb` to check for error messages:
 
 ```html+erb
-<%= form_for :post, url: { action: :create } do |f| %>
+<%= form_for :post, url: posts_path do |f| %>
   <% if @post.errors.any? %>
   <div id="errorExplanation">
     <h2><%= pluralize(@post.errors.count, "error") %> prohibited
@@ -803,7 +818,7 @@ something went wrong. To do that, you'll modify
   </p>
 <% end %>
 
-<%= link_to 'Back', action: :index %>
+<%= link_to 'Back', posts_path %>
 ```
 
 A few things are going on. We check if there are any errors with
@@ -832,14 +847,6 @@ We've covered the "CR" part of CRUD. Now let's focus on the "U" part, updating p
 
 The first step we'll take is adding an `edit` action to `posts_controller`.
 
-Start by adding a route to `config/routes.rb`:
-
-```ruby
-get "posts/:id/edit" => "posts#edit"
-```
-
-And then add the controller action:
-
 ```ruby
 def edit
   @post = Post.find(params[:id])
@@ -853,7 +860,7 @@ it look as follows:
 ```html+erb
 <h1>Editing post</h1>
 
-<%= form_for :post, url: { action: :update, id: @post.id },
+<%= form_for :post, url: post_path(@post.id) },
 method: :patch do |f| %>
   <% if @post.errors.any? %>
   <div id="errorExplanation">
@@ -881,7 +888,7 @@ method: :patch do |f| %>
   </p>
 <% end %>
 
-<%= link_to 'Back', action: :index %>
+<%= link_to 'Back', posts_path %>
 ```
 
 This time we point the form to the `update` action, which is not defined yet
@@ -893,21 +900,14 @@ via the `PATCH` HTTP method which is the HTTP method you're expected to use to
 
 TIP: By default forms built with the _form_for_ helper are sent via `POST`.
 
-Next, we need to add the `update` action. The file
-`config/routes.rb` will need just one more line:
-
-```ruby
-patch "posts/:id" => "posts#update"
-```
-
-And then create the `update` action in `app/controllers/posts_controller.rb`:
+Next we need to create the `update` action in `app/controllers/posts_controller.rb`:
 
 ```ruby
 def update
   @post = Post.find(params[:id])
 
   if @post.update(params[:post].permit(:title, :text))
-    redirect_to action: :show, id: @post.id
+    redirect_to @post
   else
     render 'edit'
   end
@@ -941,8 +941,8 @@ appear next to the "Show" link:
   <tr>
     <td><%= post.title %></td>
     <td><%= post.text %></td>
-    <td><%= link_to 'Show', action: :show, id: post.id %></td>
-    <td><%= link_to 'Edit', action: :edit, id: post.id %></td>
+    <td><%= link_to 'Show', post_path %></td>
+    <td><%= link_to 'Edit', edit_post_path(post) %></td>
   </tr>
 <% end %>
 </table>
@@ -955,8 +955,8 @@ the template:
 ```html+erb
 ...
 
-<%= link_to 'Back', action: :index %>
-| <%= link_to 'Edit', action: :edit, id: @post.id %>
+<%= link_to 'Back', posts_path %>
+| <%= link_to 'Edit', edit_post_path(@post) %>
 ```
 
 And here's how our app looks so far:
@@ -1016,7 +1016,7 @@ completely:
 
 <%= render 'form' %>
 
-<%= link_to 'Back', action: :index %>
+<%= link_to 'Back', posts_path %>
 ```
 
 Then do the same for the `app/views/posts/edit.html.erb` view:
@@ -1026,66 +1026,17 @@ Then do the same for the `app/views/posts/edit.html.erb` view:
 
 <%= render 'form' %>
 
-<%= link_to 'Back', action: :index %>
+<%= link_to 'Back', posts_path %>
 ```
 
-Point your browser to <http://localhost:3000/posts/new> and
-try creating a new post. Everything still works. Now try editing the
-post and you'll receive the following error:
-
-![Undefined method post_path](images/getting_started/undefined_method_post_path.png)
-
-To understand this error, you need to understand how `form_for` works.
-When you pass an object to `form_for` and you don't specify a `:url`
-option, Rails will try to guess the `action` and `method` options by
-checking if the passed object is a new record or not. Rails follows the
-REST convention, so to create a new `Post` object it will look for a
-route named `posts_path`, and to update a `Post` object it will look for
-a route named `post_path` and pass the current object. Similarly, rails
-knows that it should create new objects via POST and update them via
-PATCH.
-
-If you run `rake routes` from the console you'll see that we already
-have a `posts_path` route, which was created automatically by Rails when we
-defined the route for the index action.
-However, we don't have a `post_path` yet, which is the reason why we
-received an error before. With your server running you can view your routes by visiting [localhost:3000/rails/info/routes](http://localhost:3000/rails/info/routes), or you can generate them from the command line by running `rake routes`:
-
-```bash
-$ rake routes
-
-    posts GET   /posts(.:format)            posts#index
-posts_new GET   /posts/new(.:format)        posts#new
-          POST  /posts(.:format)            posts#create
-          GET   /posts/:id(.:format)        posts#show
-          GET   /posts/:id/edit(.:format)   posts#edit
-          PATCH /posts/:id(.:format)        posts#update
-     root       /                           welcome#index
-```
-
-To fix this, open `config/routes.rb` and modify the `get "posts/:id"`
-line like this:
-
-```ruby
-get "posts/:id" => "posts#show", as: :post
-```
-
-The `:as` option tells the `get` method that we want to make routing helpers
-called `post_url` and `post_path` available to our application. These are
-precisely the methods that the `form_for` needs when editing a post, and so now
-you'll be able to update posts again.
-
-NOTE: The `:as` option is available on the `post`, `patch`, `put`, `delete` and `match`
-routing methods also.
-
 ### Deleting Posts
 
 We're now ready to cover the "D" part of CRUD, deleting posts from the
-database. Following the REST convention, we're going to add a route for
-deleting posts to `config/routes.rb`:
+database. Following the REST convention, the route for
+deleting posts in the `config/routes.rb` is:
 
 ```ruby
-delete "posts/:id" => "posts#destroy"
+DELETE /posts/:id(.:format)      posts#destroy
 ```
 
 The `delete` routing method should be used for routes that destroy
@@ -1105,7 +1056,7 @@ def destroy
   @post = Post.find(params[:id])
   @post.destroy
 
-  redirect_to action: :index
+  redirect_to posts_path
 end
 ```
 
@@ -1132,18 +1083,17 @@ together.
   <tr>
     <td><%= post.title %></td>
     <td><%= post.text %></td>
-    <td><%= link_to 'Show', action: :show, id: post.id %></td>
-    <td><%= link_to 'Edit', action: :edit, id: post.id %></td>
-    <td><%= link_to 'Destroy', { action: :destroy, id: post.id },
+    <td><%= link_to 'Show', post_path %></td>
+    <td><%= link_to 'Edit', edit_post_path(post) %></td>
+    <td><%= link_to 'Destroy', post_path(post),
                     method: :delete, data: { confirm: 'Are you sure?' } %></td>
   </tr>
 <% end %>
 </table>
 ```
 
-Here we're using `link_to` in a different way. We wrap the
-`:action` and `:id` attributes in a hash so that we can pass those two keys in
-first as one argument, and then the final two keys as another argument. The `:method` and `:'data-confirm'`
+Here we're using `link_to` in a different way. We pass the named route as the first argument, 
+and then the final two keys as another argument. The `:method` and `:'data-confirm'`
 options are used as HTML5 attributes so that when the link is clicked,
 Rails will first show a confirm dialog to the user, and then submit the link with method `delete`.
 This is done via the JavaScript file `jquery_ujs` which is automatically included
@@ -1153,62 +1103,11 @@ generated the application. Without this file, the confirmation dialog box wouldn
 ![Confirm Dialog](images/getting_started/confirm_dialog.png)
 
 Congratulations, you can now create, show, list, update and destroy
-posts. In the next section will see how Rails can aid us when creating
-REST applications, and how we can refactor our Blog app to take
-advantage of it.
-
-### Going Deeper into REST
-
-We've now covered all the CRUD actions of a REST app. We did so by
-declaring separate routes with the appropriate verbs into
-`config/routes.rb`. Here's how that file looks so far:
-
-```ruby
-get "posts" => "posts#index"
-get "posts/new"
-post "posts" => "posts#create"
-get "posts/:id" => "posts#show", as: :post
-get "posts/:id/edit" => "posts#edit"
-patch "posts/:id" => "posts#update"
-delete "posts/:id" => "posts#destroy"
-```
-
-That's a lot to type for covering a single **resource**. Fortunately,
-Rails provides a `resources` method which can be used to declare a
-standard REST resource. Here's how `config/routes.rb` looks after the
-cleanup:
-
-```ruby
-Blog::Application.routes.draw do
-
-  resources :posts
-
-  root to: "welcome#index"
-end
-```
-
-If you run `rake routes`, you'll see that all the routes that we
-declared before are still available:
-
-```bash
-$ rake routes
-    posts GET    /posts(.:format)          posts#index
-          POST   /posts(.:format)          posts#create
- new_post GET    /posts/new(.:format)      posts#new
-edit_post GET    /posts/:id/edit(.:format) posts#edit
-     post GET    /posts/:id(.:format)      posts#show
-          PATCH  /posts/:id(.:format)      posts#update
-          PUT    /posts/:id(.:format)      posts#update
-          DELETE /posts/:id(.:format)      posts#destroy
-     root        /                         welcome#index
-```
-
-Also, if you go through the motions of creating, updating and deleting
-posts the app still works as before.
+posts. 
 
 TIP: In general, Rails encourages the use of resources objects in place
-of declaring routes manually. It was only done in this guide as a learning
-exercise. For more information about routing, see
+of declaring routes manually.
+For more information about routing, see
 [Rails Routing from the Outside In](routing.html).
 
 Adding a Second Model
@@ -1722,7 +1621,7 @@ class CommentsController < ApplicationController
 Now if you try to create a new post, you will be greeted with a basic HTTP
 Authentication challenge
 
-![Basic HTTP Authentication Challenge](images/challenge.png)
+![Basic HTTP Authentication Challenge](images/getting_started/challenge.png)
 
 What's Next?
 ------------