kitabu 0.4.7 → 1.0.0.rc1

data/examples/RailsGuides/text/07_Adding_a_second_model.mkdn

@@ -0,0 +1,232 @@
+## Adding a Second Model
+
+Now that you’ve seen how a model built with scaffolding looks like, it’s time to add a second model to the application. The second model will handle comments on blog posts.
+
+### Generating a Model
+
+Models in Rails use a singular name, and their corresponding database tables use a plural name. For the model to hold comments, the convention is to use the name Comment. Even if you don’t want to use the entire apparatus set up by scaffolding, most Rails developers still use generators to make things like models and controllers. To create the new model, run this command in your terminal:
+
+	$ rails generate model Comment commenter:string body:text post:references
+
+This command will generate four files:
+
+* `app/models/comment.rb` – The model
+* `db/migrate/20100207235629_create_comments.rb` – The migration
+* `test/unit/comment_test.rb and test/fixtures/comments.yml` – The test harness.
+
+First, take a look at `comment.rb`:
+
+@@@ ruby
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+@@@
+
+This is very similar to the `post.rb` model that you saw earlier. The difference is the line `belongs_to :post`, which sets up an Active Record *association*. You’ll learn a little about associations in the next section of this guide.
+
+In addition to the model, Rails has also made a migration to create the corresponding database table:
+
+@@@ ruby
+class CreateComments < ActiveRecord::Migration
+  def self.up
+    create_table :comments do |t|
+      t.string :commenter
+      t.text :body
+      t.references :post
+
+      t.timestamps
+    end
+  end
+
+  def self.down
+    drop_table :comments
+  end
+end
+@@@
+
+The `t.references` line sets up a foreign key column for the association between the two models. Go ahead and run the migration:
+
+	$ rake db:migrate
+
+Rails is smart enough to only execute the migrations that have not already been run against the current database, so in this case you will just see:
+
+	==  CreateComments: migrating ============
+	-- create_table(:comments)
+	   -> 0.0017s
+	==  CreateComments: migrated (0.0018s) ===
+
+### Associating Models
+
+Active Record associations let you easily declare the relationship between two models. In the case of comments and posts, you could write out the relationships this way:
+
+* Each comment belongs to one post
+* One post can have many comments
+
+In fact, this is very close to the syntax that Rails uses to declare this association. You’ve already seen the line of code inside the Comment model that makes each comment belong to a Post:
+
+@@@ ruby
+class Comment < ActiveRecord::Base
+  belongs_to :post
+end
+@@@
+
+You’ll need to edit the `post.rb` file to add the other side of the association:
+
+@@@ ruby
+class Post < ActiveRecord::Base
+  validates :name,  :presence => true
+  validates :title, :presence => true,
+                    :length => { :minimum => 5 }
+
+  has_many :comments
+end
+@@@
+
+These two declarations enable a good bit of automatic behavior. For example, if you have an instance variable `@post` containing a post, you can retrieve all the comments belonging to that post as the array `@post.comments`.
+
+<p class="notice">
+	For more information on Active Record associations, see the <a href="http://guides.rubyonrails.org/association_basics.html" title="Ruby on Rails Guides: A Guide to Active Record Associations">Active Record Associations</a> guide.
+</p>
+
+### Adding a Route for Comments
+
+As with the `home` controller, we will need to add a route so that Rails knows where we would like to navigate to see `comments`. Open up the `config/routes.rb` file again, you will see an entry that was added automatically for posts near the top by the scaffold generator, `resources :posts`, edit it as follows:
+
+@@@ ruby
+resources :posts do
+  resources :comments
+end
+@@@
+
+This creates `comments` as a *nested resource* within `posts`. This is another part of capturing the hierarchical relationship that exists between posts and comments.
+
+<p class="notice">
+	For more information on routing, see the <a href="http://guides.rubyonrails.org/routing.html" title="Ruby on Rails Guides: Rails Routing from the Outside In">Rails Routing from the Outside In</a> guide.
+</p>
+
+### Generating a Controller
+
+With the model in hand, you can turn your attention to creating a matching controller. Again, there’s a generator for this:
+
+	$ rails generate controller Comments
+
+This creates four files and one empty directory:
+
+* `app/controllers/comments_controller.rb` – The controller
+* `app/helpers/comments_helper.rb` – A view helper file
+* `test/functional/comments_controller_test.rb` – The functional tests for the controller
+* `test/unit/helpers/comments_helper_test.rb` – The unit tests for the helper
+* `app/views/comments/` – Views of the controller are stored here
+
+Like with any blog, our readers will create their comments directly after reading the post, and once they have added their comment, will be sent back to the post show page to see their comment now listed. Due to this, our `CommentsController` is there to provide a method to create comments and delete SPAM comments when they arrive.
+
+So first, we’ll wire up the Post show template (`/app/views/posts/show.html.erb`) to let us make a new comment:
+
+@@@ html
+<p class="notice"><%= notice %></p>
+
+<p>
+  <b>Name:</b>
+  <%= @post.name %>
+</p>
+
+<p>
+  <b>Title:</b>
+  <%= @post.title %>
+</p>
+
+<p>
+  <b>Content:</b>
+  <%= @post.content %>
+</p>
+
+<h2>Add a comment:</h2>
+<%= form_for([@post, @post.comments.build]) do |f| %>
+  <div class="field">
+    <%= f.label :commenter %><br />
+    <%= f.text_field :commenter %>
+  </div>
+  <div class="field">
+    <%= f.label :body %><br />
+    <%= f.text_area :body %>
+  </div>
+  <div class="actions">
+    <%= f.submit %>
+  </div>
+<% end %>
+
+<%= link_to 'Edit Post', edit_post_path(@post) %> |
+<%= link_to 'Back to Posts', posts_path %> |
+@@@
+
+This adds a form on the Post show page that creates a new comment, which will call the `CommentsController` create action, so let’s wire that up:
+
+@@@ ruby
+class CommentsController < ApplicationController
+  def create
+    @post = Post.find(params[:post_id])
+    @comment = @post.comments.create(params[:comment])
+    redirect_to post_path(@post)
+  end
+end
+@@@
+
+You’ll see a bit more complexity here than you did in the controller for posts. That’s a side-effect of the nesting that you’ve set up; each request for a comment has to keep track of the post to which the comment is attached, thus the initial find action to the Post model to get the post in question.
+
+In addition, the code takes advantage of some of the methods available for an association. We use the `create` method on `@post.comments` to create and save the comment. This will automatically link the comment so that it belongs to that particular post.
+
+Once we have made the new comment, we send the user back to the original post using the `post_path(@post)` helper. As we have already seen, this calls the `show` action of the `PostsController` which in turn renders the `show.html.erb` template. This is where we want the comment to show, so let’s add that to the `app/views/posts/show.html.erb`.
+
+@@@ html
+<p class="notice"><%= notice %></p>
+
+<p>
+  <b>Name:</b>
+  <%= @post.name %>
+</p>
+
+<p>
+  <b>Title:</b>
+  <%= @post.title %>
+</p>
+
+<p>
+  <b>Content:</b>
+  <%= @post.content %>
+</p>
+
+<h2>Comments</h2>
+<% @post.comments.each do |comment| %>
+  <p>
+    <b>Commenter:</b>
+    <%= comment.commenter %>
+  </p>
+
+  <p>
+    <b>Comment:</b>
+    <%= comment.body %>
+  </p>
+<% end %>
+
+<h2>Add a comment:</h2>
+<%= form_for([@post, @post.comments.build]) do |f| %>
+  <div class="field">
+    <%= f.label :commenter %><br />
+    <%= f.text_field :commenter %>
+  </div>
+  <div class="field">
+    <%= f.label :body %><br />
+    <%= f.text_area :body %>
+  </div>
+  <div class="actions">
+    <%= f.submit %>
+  </div>
+<% end %>
+
+<br />
+
+<%= link_to 'Edit Post', edit_post_path(@post) %> |
+<%= link_to 'Back to Posts', posts_path %> |
+@@@
+
+Now you can add posts and comments to your blog and have them show up in the right places.

data/examples/RailsGuides/text/08_Refactoring.mkdn

@@ -0,0 +1,123 @@
+## Refactoring
+
+Now that we have Posts and Comments working, if we take a look at the `app/views/posts/show.html.erb` template, it’s getting long and awkward. We can use partials to clean this up.
+
+### Rendering Partial Collections
+
+First we will make a comment partial to extract showing all the comments for the post. Create the file `app/views/comments/_comment.html.erb` and put the following into it:
+
+@@@ html
+<p>
+  <b>Commenter:</b>
+  <%= comment.commenter %>
+</p>
+
+<p>
+  <b>Comment:</b>
+  <%= comment.body %>
+</p>
+@@@
+
+Then in the `app/views/posts/show.html.erb` you can change it to look like the following:
+
+@@@ html
+<p class="notice"><%= notice %></p>
+
+<p>
+  <b>Name:</b>
+  <%= @post.name %>
+</p>
+
+<p>
+  <b>Title:</b>
+  <%= @post.title %>
+</p>
+
+<p>
+  <b>Content:</b>
+  <%= @post.content %>
+</p>
+
+<h2>Comments</h2>
+<%= render :partial => "comments/comment",
+           :collection => @post.comments %>
+
+<h2>Add a comment:</h2>
+<%= form_for([@post, @post.comments.build]) do |f| %>
+  <div class="field">
+    <%= f.label :commenter %><br />
+    <%= f.text_field :commenter %>
+  </div>
+  <div class="field">
+    <%= f.label :body %><br />
+    <%= f.text_area :body %>
+  </div>
+  <div class="actions">
+    <%= f.submit %>
+  </div>
+<% end %>
+
+<br />
+
+<%= link_to 'Edit Post', edit_post_path(@post) %> |
+<%= link_to 'Back to Posts', posts_path %> |
+@@@
+
+This will now render the partial in `app/views/comments/_comment.html.erb` once for each comment that is in the `@post.comments collection`. As the render method iterates over the `@post.comments` collection, it assigns each comment to a local variable named the same as the partial, in this case comment which is then available in the partial for us to show.
+
+### Rendering a Partial Form
+
+Lets also move that new comment section out to it’s own partial, again, you create a file `app/views/comments/_form.html.erb` and in it you put:
+
+@@@ html
+<%= form_for([@post, @post.comments.build]) do |f| %>
+  <div class="field">
+    <%= f.label :commenter %><br />
+    <%= f.text_field :commenter %>
+  </div>
+  <div class="field">
+    <%= f.label :body %><br />
+    <%= f.text_area :body %>
+  </div>
+  <div class="actions">
+    <%= f.submit %>
+  </div>
+<% end %>
+@@@
+
+Then you make the `app/views/posts/show.html.erb` look like the following:
+
+@@@ html
+<p class="notice"><%= notice %></p>
+
+<p>
+  <b>Name:</b>
+  <%= @post.name %>
+</p>
+
+<p>
+  <b>Title:</b>
+  <%= @post.title %>
+</p>
+
+<p>
+  <b>Content:</b>
+  <%= @post.content %>
+</p>
+
+<h2>Comments</h2>
+<%= render :partial => "comments/comment",
+           :collection => @post.comments %>
+
+<h2>Add a comment:</h2>
+<%= render "comments/form" %>
+
+<br />
+
+<%= link_to 'Edit Post', edit_post_path(@post) %> |
+<%= link_to 'Back to Posts', posts_path %> |
+@@@
+
+The second render just defines the partial template we want to render, `comments/form`, Rails is smart enough to spot the forward slash in that string and realize that you want to render the `_form.html.erb` file in the `app/views/comments` directory.
+
+The `@post` object is available to any partials rendered in the view because we defined it as an instance variable.

data/examples/RailsGuides/text/09_Deleting_comments.mkdn

@@ -0,0 +1,57 @@
+## Deleting Comments
+
+Another important feature on a blog is being able to delete SPAM comments. To do this, we need to implement a link of some sort in the view and a `DELETE` action in the `CommentsController`.
+
+So first, let’s add the delete link in the `app/views/comments/_comment.html.erb` partial:
+
+@@@ html
+<p>
+  <b>Commenter:</b>
+  <%= comment.commenter %>
+</p>
+
+<p>
+  <b>Comment:</b>
+  <%= comment.body %>
+</p>
+
+<p>
+  <%= link_to 'Destroy Comment', [comment.post, comment],
+               :confirm => 'Are you sure?',
+               :method => :delete %>
+</p>
+@@@
+
+Clicking this new “Destroy Comment” link will fire off a `DELETE /posts/:id/comments/:id` to our `CommentsController`, which can then use this to find the comment we want to delete, so let’s add a `destroy` action to our controller:
+
+@@@ ruby
+class CommentsController < ApplicationController
+  def create
+    @post = Post.find(params[:post_id])
+    @comment = @post.comments.create(params[:comment])
+    redirect_to post_path(@post)
+  end
+
+  def destroy
+    @post = Post.find(params[:post_id])
+    @comment = @post.comments.find(params[:id])
+    @comment.destroy
+    redirect_to post_path(@post)
+  end
+end
+@@@
+
+The `destroy` action will find the post we are looking at, locate the comment within the `@post.comments` collection, and then remove it from the database and send us back to the `show` action for the post.
+
+### Deleting Associated Objects
+
+If you delete a post then its associated comments will also need to be deleted. Otherwise they would simply occupy space in the database. Rails allows you to use the `dependent` option of an association to achieve this. Modify the `Post` model, `app/models/post.rb`, as follows:
+
+@@@ ruby
+class Post < ActiveRecord::Base
+  validates :name,  :presence => true
+  validates :title, :presence => true,
+                    :length => { :minimum => 5 }
+  has_many :comments, :dependent => :destroy
+end
+@@@

data/examples/RailsGuides/text/09_Security.mkdn

@@ -0,0 +1,56 @@
+## Security
+
+If you were to publish your blog online, anybody would be able to add, edit and delete posts or delete comments.
+
+Rails provides a very simple HTTP authentication system that will work nicely in this situation. First, we enable simple HTTP based authentication in our `app/controllers/application_controller.rb`:
+
+@@@ ruby
+class ApplicationController < ActionController::Base
+  protect_from_forgery
+
+  private
+
+  def authenticate
+    authenticate_or_request_with_http_basic do |user_name, password|
+      user_name == 'admin' && password == 'password'
+    end
+  end
+end
+@@@
+
+You can obviously change the username and password to whatever you want. We put this method inside of `ApplicationController` so that it is available to all of our controllers.
+
+Then in the `PostsController` we need to have a way to block access to the various actions if the person is not authenticated, here we can use the Rails `before_filter` method, which allows us to specify that Rails must run a method and only then allow access to the requested action if that method allows it.
+
+To use the before filter, we specify it at the top of our `PostsController`, in this case, we want the user to be authenticated on every action, except for `index` and `show`, so we write that:
+
+@@@ ruby
+class PostsController < ApplicationController
+
+  before_filter :authenticate, :except => [:index, :show]
+
+  # GET /posts
+  # GET /posts.xml
+  def index
+    @posts = Post.all
+    respond_to do |format|
+# snipped for brevity
+@@@
+
+<p class="figure">
+	<img src="../images/challenge.png" alt="Basic Auth challenge window" />
+</p>
+
+We also only want to allow authenticated users to delete comments, so in the `CommentsController` we write:
+
+@@@ ruby
+class CommentsController < ApplicationController
+
+  before_filter :authenticate, :only => :destroy
+
+  def create
+    @post = Post.find(params[:post_id])
+# snipped for brevity
+@@@
+
+Now if you try to create a new post, you will be greeted with a basic HTTP Authentication challenge.