From a4ff4fd2c38175b38af928da2b5cae2b6bb19da7 Mon Sep 17 00:00:00 2001 From: Mike Gunderloy Date: Sun, 1 Feb 2009 10:21:17 -0600 Subject: Regenerate HTML --- railties/doc/guides/html/2_3_release_notes.html | 22 ++ .../guides/html/getting_started_with_rails.html | 225 +++++++++++++++------ 2 files changed, 184 insertions(+), 63 deletions(-) diff --git a/railties/doc/guides/html/2_3_release_notes.html b/railties/doc/guides/html/2_3_release_notes.html index 67cfbb56ca..51b2b39b26 100644 --- a/railties/doc/guides/html/2_3_release_notes.html +++ b/railties/doc/guides/html/2_3_release_notes.html @@ -452,6 +452,23 @@ Lead Contributor: Frederick Cheung Lead Contributor: Dov Murik

+
  • +

    +More information: +

    +
    +

    • 3.9. Other Active Record Changes

    diff --git a/railties/doc/guides/html/getting_started_with_rails.html b/railties/doc/guides/html/getting_started_with_rails.html index a79d9903aa..564d5c7c00 100644 --- a/railties/doc/guides/html/getting_started_with_rails.html +++ b/railties/doc/guides/html/getting_started_with_rails.html @@ -129,6 +129,9 @@
  • + Building a Multi-Model Form +
    • +
  • What’s Next?
  • @@ -164,6 +167,14 @@ How to quickly generate the starting pieces of a Rails application.

    • +
    + + + +
    +Note +This Guide is based on Rails 2.3. Some of the code shown here will not work in older versions of Rails.
    +

    1. This Guide Assumes

    @@ -186,7 +197,7 @@ A working installation of SQLite (preferred

    -

    It is highly recommended that you familiarize yourself with Ruby before diving into Rails. You will find it much easier to follow what’s going on with a Rails application if you understand basic Ruby syntax. Rails isn’t going to magically revolutionize the way you write web applications if you have no experience with the language it uses. There are some good free resources on the net for learning Ruby, including:

    +

    It is highly recommended that you familiarize yourself with Ruby before diving into Rails. You will find it much easier to follow what’s going on with a Rails application if you understand basic Ruby syntax. Rails isn’t going to magically revolutionize the way you write web applications if you have no experience with the language it uses. There are some good free resources on the internet for learning Ruby, including:

    Change the username and password in the development section as appropriate.

    @@ -548,6 +569,14 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    $ rake db:create
    +
    + + + +
    +Note +Rake is a general-purpose command-runner that Rails uses for many things. You can see the list of available rake commands in your application by running rake -T.
    +

    4. Hello, Rails!

    @@ -581,7 +610,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    $ script/server
    -

    This will fire up the lightweight Webrick web server by default. To see your application in action, open a browser window and navigate to http://localhost:3000. You should see Rails' default information page:

    +

    This will fire up an instance of the Mongrel web server by default (Rails can also use several other web servers). To see your application in action, open a browser window and navigate to http://localhost:3000. You should see Rails' default information page:

    Welcome Aboard screenshot

    @@ -593,7 +622,7 @@ http://www.gnu.org/software/src-highlite --> To stop the web server, hit Ctrl+C in the terminal window where it’s running. In development mode, Rails does not generally require you to stop the server; changes you make in files will be automatically picked up by the server. -

    The "Welcome Aboard" page is the smoke test for a new Rails application: it makes sure that you have your software configured correctly enough to serve a page. To view the page you just created, navigate to http://localhost:3000/home/index.

    +

    The "Welcome Aboard" page is the smoke test for a new Rails application: it makes sure that you have your software configured correctly enough to serve a page. To view the page you just created, navigate to http://localhost:3000/home/index.

    4.2. Setting the Application Home Page

    You’d probably like to replace the "Welcome Aboard" page with your own application’s home page. The first step to doing this is to delete the default page from your application:

    @@ -650,7 +679,7 @@ http://www.gnu.org/software/src-highlite --> While scaffolding will get you up and running quickly, the "one size fits all" code that it generates is unlikely to be a perfect fit for your application. In most cases, you’ll need to customize the generated code. Many experienced Rails developers avoid scaffolding entirely, preferring to write all or most of their source code from scratch.
    -

    The scaffold generator will build 13 files in your application, along with some folders, and edit one more. Here’s a quick overview of what it creates:

    +

    The scaffold generator will build 14 files in your application, along with some folders, and edit one more. Here’s a quick overview of what it creates:

    - + @@ -721,12 +750,16 @@ cellspacing="0" cellpadding="4"> + + + +

    The Post model

    db/migrate/20081013124235_create_posts.rb

    db/migrate/20090113124235_create_posts.rb

    Migration to create the posts table in your database (your name will include a different timestamp)

    test/unit/post_test.rb

    Unit testing harness for the posts model

    test/unit/helpers/posts_helper_test.rb

    Unit testing harness for the posts helper

    6.1. Running a Migration

    One of the products of the script/generate scaffold command is a database migration. Migrations are Ruby classes that are designed to make it simple to create and modify database tables. Rails uses rake commands to run migrations, and it’s possible to undo a migration after it’s been applied to your database. Migration filenames include a timestamp to ensure that they’re processed in the order that they were created.

    -

    If you look in the db/migrate/20081013124235_create_posts.rb file (remember, yours will have a slightly different name), here’s what you’ll find:

    +

    If you look in the db/migrate/20090113124235_create_posts.rb file (remember, yours will have a slightly different name), here’s what you’ll find:

    by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -
    $ rake db:create
-$ rake db:migrate
    +
    $ rake db:migrate
    +

    Remember, you can’t run migrations before running rake db:create to create your database, as we covered earlier.

    - +
    @@ -842,7 +875,7 @@ title: nil, Tip Unlike the development web server, the console does not automatically load your code afresh for each line. If you make changes, type reload! at the console prompt to load them.Unlike the development web server, the console does not automatically load your code afresh for each line. If you make changes to your models while the console is open, type reload! at the console prompt to load them.

    6.7. Listing All Posts

    @@ -1155,7 +1188,7 @@ http://www.gnu.org/software/src-highlite -->

    At this point, it’s worth looking at some of the tools that Rails provides to eliminate duplication in your code. In particular, you can use partials to clean up duplication in views and filters to help with duplication in controllers.

    7.1. Using Partials to Eliminate View Duplication

    -

    As you saw earlier, the scaffold-generated views for the new and edit actions are largely identical. You can pull the shared code out into a partial template. This requires editing the new and edit views, and adding a new template. The new _form.html.erb template should be saved in the same app/views/posts folder as the files from which it is being extracted:

    +

    As you saw earlier, the scaffold-generated views for the new and edit actions are largely identical. You can pull the shared code out into a partial template. This requires editing the new and edit views, and adding a new template. The new _form.html.erb template should be saved in the same app/views/posts folder as the files from which it is being extracted. Note that the name of this file begins with an underscore; that’s the Rails naming convention for partial templates.

    new.html.erb:

    end end

    Rails runs before filters before any action in the controller. You can use the :only clause to limit a before filter to only certain actions, or an :except clause to specifically skip a before filter for certain actions. Rails also allows you to define after filters that run after processing an action, as well as around filters that surround the processing of actions. Filters can also be defined in external classes to make it easy to share them between controllers.

    -

    For more information on filters, see the Action Controller Basics guide.

    +

    For more information on filters, see the Action Controller Basics guide.

    8. Adding a Second Model

    @@ -1286,7 +1319,7 @@ http://www.gnu.org/software/src-highlite -->

  • -+db/migrate/20081013214407_create_comments.rb - The migration ++db/migrate/20091013214407_create_comments.rb - The migration

  • @@ -1333,7 +1366,7 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
    $ rake db:migrate
    • -

    Rails is smart enough to only execute the migrations that have not already been run against this particular database.

    +

    Rails is smart enough to only execute the migrations that have not already been run against the current database.

    8.2. 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:

    8.3. Adding a Route

    -

    Routes are entries in the config/routes.rb file that tell Rails how to match incoming HTTP requests to controller actions. Open up that file and find the existing line referring to posts. Then edit it as follows:

    +

    Routes are entries in the config/routes.rb file that tell Rails how to match incoming HTTP requests to controller actions. Open up that file and find the existing line referring to posts (it will be right at the top of the file). Then edit it as follows:

    -
    map.resources :posts do |post|
-  post.resources :comments
-end
    +
    map.resources :posts, :has_many => :comments

    This creates comments as a nested resource within posts. This is another part of capturing the hierarchical relationship that exists between posts and comments.

    @@ -1442,7 +1473,7 @@ http://www.gnu.org/software/src-highlite -->

    -

    The controller will be generated with empty methods for each action that you specified in the call to script/generate controller:

    +

    The controller will be generated with empty methods and views for each action that you specified in the call to script/generate controller:

    end end + def destroy + @post = Post.find(params[:post_id]) + @comment = Comment.find(params[:id]) + @comment.destroy + + respond_to do |format| + format.html { redirect_to post_comments_path(@post) } + format.xml { head :ok } + end + 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.

    In addition, the code takes advantage of some of the methods available for an association. For example, in the new method, it calls

    @@ -1521,7 +1563,7 @@ http://www.gnu.org/software/src-highlite -->

    This creates a new Comment object and sets up the post_id field to have the id from the specified Post object in a single operation.

    8.5. Building Views

    Because you skipped scaffolding, you’ll need to build views for comments "by hand." Invoking script/generate controller will give you skeleton views, but they’ll be devoid of actual content. Here’s a first pass at fleshing out the comment views.

    -

    The index.html.erb view:

    +

    The views/comments/index.html.erb view:

    <%= link_to 'New comment', new_post_comment_path(@post) %> <%= link_to 'Back to Post', @post %>
    -

    The new.html.erb view:

    +

    The views/comments/new.html.erb view:

    <% end %> <%= link_to 'Back', post_comments_path(@post) %>
    -

    The show.html.erb view:

    +

    The views/comments/show.html.erb view:

    <%= link_to 'Edit', edit_post_comment_path(@post, @comment) %> | <%= link_to 'Back', post_comments_path(@post) %>
    -

    The edit.html.erb view:

    +

    The views/comments/edit.html.erb view:

    <%= link_to 'Show', post_comment_path(@post, @comment) %> | <%= link_to 'Back', post_comments_path(@post) %>
    -

    Again, the added complexity here (compared to the views you saw for managing comments) comes from the necessity of juggling a post and its comments at the same time.

    +

    Again, the added complexity here (compared to the views you saw for managing posts) comes from the necessity of juggling a post and its comments at the same time.

    8.6. Hooking Comments to Posts

    -

    As a final step, I’ll modify the show.html.erb view for a post to show the comments on that post, and to allow managing those comments:

    +

    As a next step, I’ll modify the views/posts/show.html.erb view to show the comments on that post, and to allow managing those comments:

    </p> <% end %> -<%= link_to 'Edit', edit_post_path(@post) %> | -<%= link_to 'Back', posts_path %> +<%= link_to 'Edit Post', edit_post_path(@post) %> | +<%= link_to 'Back to Posts', posts_path %> | <%= link_to 'Manage Comments', post_comments_path(@post) %>

    Note that each post has its own individual comments collection, accessible as @post.comments. That’s a consequence of the declarative associations in the models. Path helpers such as post_comments_path come from the nested route declaration in config/routes.rb.

    -

    9. What’s Next?

    +

    9. Building a Multi-Model Form

    +
    +

    Comments and posts are edited on two separate forms - which makes sense, given the flow of this mini-application. But what if you want to edit more than one thing on a single form? Rails 2.3 offers new support for nested forms. Let’s add support for giving each post multiple tags, right in the form where you create the post. First, create a new model to hold the tags:

    +
    +
    +
    $ script/generate model tag name:string post:references
    +

    Run the migration to create the database table:

    +
    +
    +
    $ rake db:migrate
    +

    Next, edit the post.rb file to create the other side of the association, and to tell Rails that you intend to edit tags via posts:

    +
    +
    +
    class Post < ActiveRecord::Base
+  validates_presence_of :name, :title
+  validates_length_of :title, :minimum => 5
+  has_many :comments
+  has_many :tags
+
+  accepts_nested_attributes_for :tags, :allow_destroy => :true  ,
+        :reject_if => proc { |attrs| attrs.all? { |k, v| v.blank? } }
+end
    +

    The :allow_destroy option on the nested attribute declaration tells Rails to display a "remove" checkbox on the view that you’ll build shortly. The :reject_if option prevents saving new tags that do not have any attributes filled in.

    +

    You’ll also need to modify views/posts/_form.html.erb to include the tags:

    +
    +
    +
    <% @post.tags.build if @post.tags.empty? %>
+<% form_for(@post) do |post_form| %>
+  <%= post_form.error_messages %>
+
+  <p>
+    <%= post_form.label :name %><br />
+    <%= post_form.text_field :name %>
+  </p>
+  <p>
+    <%= post_form.label :title, "title" %><br />
+    <%= post_form.text_field :title %>
+  </p>
+  <p>
+    <%= post_form.label :content %><br />
+    <%= post_form.text_area :content %>
+  </p>
+  <h2>Tags</h2>
+  <% post_form.fields_for :tags do |tag_form| %>
+    <p>
+      <%= tag_form.label :name, 'Tag:' %>
+      <%= tag_form.text_field :name %>
+    </p>
+    <% unless tag_form.object.nil? || tag_form.object.new_record? %>
+      <p>
+        <%= tag_form.label :_delete, 'Remove:' %>
+        <%= tag_form.check_box :_delete %>
+      </p>
+    <% end %>
+  <% end %>
+
+  <p>
+    <%= post_form.submit "Save" %>
+  </p>
+<% end %>
    +

    With these changes in place, you’ll find that you can edit a post and its tags directly on the same view.

    +
    +
    + + +
    +Note +You may want to use javascript to dynamically add additional tags on a single form. For an example of this and other advanced techniques, see the nested model sample application.
    +
    + +

    10. What’s Next?

    Now that you’ve seen your first Rails application, you should feel free to update it and experiment on your own. But you don’t have to do everything without help. As you need assistance getting up and running with Rails, feel free to consult these support resources:

      @@ -1701,41 +1825,16 @@ Running rake doc:rails will put a full copy of the API documentation fo
    -

    10. Changelog

    +

    11. Changelog

    Lighthouse ticket

    -
      -
    • -

      -November 3, 2008: Formatting patch from Dave Rothlisberger -

      -
      • -
    • -

      -November 1, 2008: First approved version by Mike Gunderloy -

      -
      • -
    • -

      -October 16, 2008: Revised based on feedback from Pratik Naik by Mike Gunderloy (not yet approved for publication) -

      -
      • -
    • -

      -October 13, 2008: First complete draft by Mike Gunderloy (not yet approved for publication) -

      -
      • -
    • -

      -October 12, 2008: More detail, rearrangement, editing by Mike Gunderloy (not yet approved for publication) -

      -
      • -
    • -

      -September 8, 2008: initial version by James Miller (not yet approved for publication) -

      -
      • -
    +

    * +* November 3, 2008: Formatting patch from Dave Rothlisberger +* November 1, 2008: First approved version by Mike Gunderloy +* October 16, 2008: Revised based on feedback from Pratik Naik by Mike Gunderloy (not yet approved for publication) +* October 13, 2008: First complete draft by Mike Gunderloy (not yet approved for publication) +* October 12, 2008: More detail, rearrangement, editing by Mike Gunderloy (not yet approved for publication) +* September 8, 2008: initial version by James Miller (not yet approved for publication)

    -- cgit v1.2.3