diff options
Diffstat (limited to 'railties/guides/source/getting_started.textile')
| -rw-r--r-- | railties/guides/source/getting_started.textile | 114 |
1 files changed, 69 insertions, 45 deletions
diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 09190f5800..a4f969efe9 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -91,7 +91,7 @@ Action Dispatch handles routing of web requests and dispatches them as you want, h5. Action Mailer -Action Mailer is a framework for building e-mail services. You can use Action Mailer to send emails based on flexible templates, or to receive and process incoming email. +Action Mailer is a framework for building e-mail services. You can use Action Mailer to receive and process incoming email and send simple plain text or complex multipart emails based on flexible templates. h5. Active Model @@ -363,7 +363,6 @@ The scaffold generator will build 15 files in your application, along with some |app/views/posts/show.html.erb |A view to display a single post| |app/views/posts/new.html.erb |A view to create a new post| |app/views/posts/_form.html.erb |A partial to control the overall look and feel of the form used in edit and new views| -|app/views/layouts/posts.html.erb |A view to control the overall look and feel of the other post views| |app/helpers/posts_helper.rb |Helper functions to be used from the post views| |test/unit/post_test.rb |Unit testing harness for the posts model| |test/functional/posts_controller_test.rb |Functional testing harness for the posts controller| @@ -395,7 +394,7 @@ class CreatePosts < ActiveRecord::Migration end </ruby> -The above migration creates two methods, +up+, called when you run this migration into the database, and +down+ in case you need to reverse the changes made by this migration at a later date. The +up+ command in this case creates a +posts+ table with two string columns and a text column. It also is creating two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide. +The above migration creates two methods, +up+, called when you run this migration into the database, and +down+ in case you need to reverse the changes made by this migration at a later date. The +up+ command in this case creates a +posts+ table with two string columns and a text column. It also creates two timestamp fields to track record creation and updating. More information about Rails migrations can be found in the "Rails Database Migrations":migrations.html guide. At this point, you can use a rake command to run the migration: @@ -504,7 +503,7 @@ def index end </ruby> -This code sets the +@posts+ instance variable to an array of all posts in the database. +Post.all+ calls the +Post+ model to return all of the posts that are currently in the database, with no limiting conditions. ++Post.all+ calls the +Post+ model to return all of the posts currently in the database. The result of this call is an array containing the posts which has been saved in an instance variable called +@posts+. TIP: For more information on finding records with Active Record, see "Active Record Query Interface":active_record_querying.html. @@ -551,19 +550,19 @@ TIP: For more details on the rendering process, see "Layouts and Rendering in Ra h4. Customizing the Layout -The view is only part of the story of how HTML is displayed in your web browser. Rails also has the concept of +layouts+, which are containers for views. When Rails renders a view to the browser, it does so by putting the view's HTML into a layout's HTML. The +rails generate scaffold+ command automatically created a default layout, +app/views/layouts/posts.html.erb+, for the posts. Open this layout in your editor and modify the +body+ tag: +The view is only part of the story of how HTML is displayed in your web browser. Rails also has the concept of +layouts+, which are containers for views. When Rails renders a view to the browser, it does so by putting the view's HTML into a layout's HTML. In previous versions of Rails, the +rails generate scaffold+ command would automatically create a controller specific layout, like +app/views/layouts/posts.html.erb+, for the posts controller. However this has been changed in Rails 3.0. A application specific +layout+ is used for all the controllers and can be found in +app/views/layouts/application.html.erb+. Open this layout in your editor and modify the +body+ tag: <erb> <!DOCTYPE html> <html> <head> - <title>Posts: <%= controller.action_name %></title> - <%= stylesheet_link_tag 'scaffold' %> + <title>Blog</title> + <%= stylesheet_link_tag :all %> + <%= javascript_include_tag :defaults %> + <%= csrf_meta_tag %> </head> <body style="background: #EEEEEE;"> -<p class="notice"><%= notice %></p> - <%= yield %> </body> @@ -603,7 +602,16 @@ If you take a look at +views/posts/_form.html.erb+ file, you will see the follow <erb> <%= form_for(@post) do |f| %> - <%= f.error_messages %> + <% if @post.errors.any? %> + <div id="errorExplanation"> + <h2><%= pluralize(@post.errors.count, "error") %> prohibited this post from being saved:</h2> + <ul> + <% @post.errors.full_messages.each do |msg| %> + <li><%= msg %></li> + <% end %> + </ul> + </div> + <% end %> <div class="field"> <%= f.label :name %><br /> @@ -678,18 +686,20 @@ end The +show+ action uses +Post.find+ to search for a single record in the database by its id value. After finding the record, Rails displays it by using +show.html.erb+: <erb> +<p class="notice"><%= notice %></p> + <p> - <b>Name:</b> + <strong>Name:</strong> <%= @post.name %> </p> <p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> + <strong>Content:</strong> <%= @post.content %> </p> @@ -878,30 +888,33 @@ With the model in hand, you can turn your attention to creating a matching contr $ rails generate controller Comments </shell> -This creates four files: +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: <erb> +<p class="notice"><%= notice %></p> + <p> - <b>Name:</b> + <strong>Name:</strong> <%= @post.name %> </p> <p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> + <strong>Content:</strong> <%= @post.content %> </p> @@ -940,35 +953,37 @@ 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. For example, in the +new+ method, it calls +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 +post_path(@post)+ URL. This runs the +show+ action of the +PostsController+ which then renders the +show.html.erb+ template where we want the comment to show, so then, we'll add that to the +app/view/posts/show.html.erb+. +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/view/posts/show.html.erb+. <erb> +<p class="notice"><%= notice %></p> + <p> - <b>Name:</b> + <strong>Name:</strong> <%= @post.name %> </p> <p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> + <strong>Content:</strong> <%= @post.content %> </p> <h2>Comments</h2> <% @post.comments.each do |comment| %> <p> - <b>Commenter:</b> + <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> - <b>Comment:</b> + <strong>Comment:</strong> <%= comment.body %> </p> <% end %> @@ -1000,20 +1015,20 @@ Now you can add posts and comments to your blog and have them show up in the rig h3. Refactorization -Now that we have Posts and Comments working, we can take a look at the +app/views/posts/show.html.erb+ template, it is getting long and awkward, we can use partials to clean this up. +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. h4. Rendering Partial Collections -First will make a comment partial to extract showing all the comments for the post, so make a file +app/views/comments/_comment.html.erb+ and put into it: +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: <erb> <p> - <b>Commenter:</b> + <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> - <b>Comment:</b> + <strong>Comment:</strong> <%= comment.body %> </p> </erb> @@ -1021,18 +1036,20 @@ First will make a comment partial to extract showing all the comments for the po Then in the +app/views/posts/show.html.erb+ you can change it to look like the following: <erb> +<p class="notice"><%= notice %></p> + <p> - <b>Name:</b> + <strong>Name:</strong> <%= @post.name %> </p> <p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> + <strong>Content:</strong> <%= @post.content %> </p> @@ -1090,18 +1107,20 @@ Lets also move that new comment section out to it's own partial, again, you crea Then you make the +app/views/posts/show.html.erb+ look like the following: <erb> +<p class="notice"><%= notice %></p> + <p> - <b>Name:</b> + <strong>Name:</strong> <%= @post.name %> </p> <p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> + <strong>Content:</strong> <%= @post.content %> </p> @@ -1120,7 +1139,7 @@ Then you make the +app/views/posts/show.html.erb+ look like the following: The second render just defines the partial template we want to render, <tt>comments/form</tt>, Rails is smart enough to spot the forward slash in that string and realise that you want to render the <tt>_form.html.erb</tt> file in the <tt>app/views/comments</tt> directory. -The +@post+ object is available any partials rendered in the view because we defined it as an instance variable. +The +@post+ object is available to any partials rendered in the view because we defined it as an instance variable. h3. Deleting Comments @@ -1130,12 +1149,12 @@ So first, let's add the delete link in the +app/views/comments/_comment.html.erb <erb> <p> - <b>Commenter:</b> + <strong>Commenter:</strong> <%= comment.commenter %> </p> <p> - <b>Comment:</b> + <strong>Comment:</strong> <%= comment.body %> </p> @@ -1328,23 +1347,25 @@ Now create the folder <tt>app/views/tags</tt> and make a file in there called <t Finally, we will edit the <tt>app/views/posts/show.html.erb</tt> template to show our tags. <erb> +<p class="notice"><%= notice %></p> + <p> - <b>Name:</b> + <strong>Name:</strong> <%= @post.name %> </p> <p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> + <strong>Content:</strong> <%= @post.content %> </p> <p> - <b>Tags:</b> + <strong>Tags:</strong> <%= @post.tags.map { |t| t.name }.join(", ") %> </p> @@ -1381,23 +1402,25 @@ end Now you can edit the view in <tt>app/views/posts/show.html.erb</tt> to look like this: <erb> +<p class="notice"><%= notice %></p> + <p> - <b>Name:</b> + <strong>Name:</strong> <%= @post.name %> </p> <p> - <b>Title:</b> + <strong>Title:</strong> <%= @post.title %> </p> <p> - <b>Content:</b> + <strong>Content:</strong> <%= @post.content %> </p> <p> - <b>Tags:</b> + <strong>Tags:</strong> <%= join_tags(@post) %> </p> @@ -1432,6 +1455,7 @@ h3. Changelog "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/2 +* April 25, 2010: Couple of more minor fixups "Mikel Lindsaar":credits:html#raasdnil * April 1, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com * February 8, 2010: Full re-write for Rails 3.0-beta, added helpers and before_filters, refactored code by "Mikel Lindsaar":credits:html#raasdnil * January 24, 2010: Re-write for Rails 3.0 by "Mikel Lindsaar":credits:html#raasdnil |