diff options
5 files changed, 87 insertions, 77 deletions
diff --git a/railties/guides/source/3_0_release_notes.textile b/railties/guides/source/3_0_release_notes.textile index 66fdad8c54..622032e1ea 100644 --- a/railties/guides/source/3_0_release_notes.textile +++ b/railties/guides/source/3_0_release_notes.textile @@ -273,7 +273,7 @@ end <ruby> scope 'es' do - resources :projects, :path_names => { :edit => 'cambiar' }, :as => 'projeto' + resources :projects, :path_names => { :edit => 'cambiar' }, :path => 'projeto' end # Gives you the edit action with /es/projeto/1/cambiar diff --git a/railties/guides/source/action_controller_overview.textile b/railties/guides/source/action_controller_overview.textile index caa7646b7f..9d8426b5de 100644 --- a/railties/guides/source/action_controller_overview.textile +++ b/railties/guides/source/action_controller_overview.textile @@ -91,7 +91,7 @@ The +params+ hash is not limited to one-dimensional keys and values. It can cont GET /clients?ids[]=1&ids[]=2&ids[]=3 </pre> -NOTE: The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5b=3" as "[" and "]" are not allowed in URLs. Most of the time you don't have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind. +NOTE: The actual URL in this example will be encoded as "/clients?ids%5b%5d=1&ids%5b%5d=2&ids%5b%5d=3" as "[" and "]" are not allowed in URLs. Most of the time you don't have to worry about this because the browser will take care of it for you, and Rails will decode it back when it receives it, but if you ever find yourself having to send those requests to the server manually you have to keep this in mind. The value of +params[:ids]+ will now be +["1", "2", "3"]+. Note that parameter values are always strings; Rails makes no attempt to guess or cast the type. @@ -653,7 +653,7 @@ class ClientsController < ApplicationController # Stream a file that has already been generated and stored on disk. def download_pdf client = Client.find(params[:id]) - send_data("#{Rails.root}/files/clients/#{client.id}.pdf", + send_file("#{Rails.root}/files/clients/#{client.id}.pdf", :filename => "#{client.name}.pdf", :type => "application/pdf") end diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index a4f969efe9..7e3f2cc931 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -542,7 +542,7 @@ The +respond_to+ block handles both HTML and XML calls to this action. If you br This view iterates over the contents of the +@posts+ array to display content and links. A few things to note in the view: * +link_to+ builds a hyperlink to a particular destination -* +edit_post_path+ is a helper that Rails provides as part of RESTful routing. You'll see a variety of these helpers for the different actions that the controller includes. +* +edit_post_path+ and +new_post_path+ are helpers that Rails provides as part of RESTful routing. You'll see a variety of these helpers for the different actions that the controller includes. NOTE. In previous versions of Rails, you had to use +<%=h post.name %>+ so that any HTML would be escaped before being inserted into the page. In Rails 3.0, this is now the default. To get unescaped HTML, you now use +<%= raw post.name %>+. @@ -662,7 +662,7 @@ def create end </ruby> -The +create+ action instantiates a new Post object from the data supplied by the user on the form, which Rails makes available in the +params+ hash. After successfully saving the new post, returns the appropriate format that the user has requested (HTML in our case). It then redirects the user to the resulting post +show+ action and sets a notice to the user that the Post was successfully created. +The +create+ action instantiates a new Post object from the data supplied by the user on the form, which Rails makes available in the +params+ hash. After successfully saving the new post, +create+ returns the appropriate format that the user has requested (HTML in our case). It then redirects the user to the resulting post +show+ action and sets a notice to the user that the Post was successfully created. If the post was not successfully saved, due to a validation error, then the controller returns the user back to the +new+ action with any error messages so that the user has the chance to fix the error and try again. @@ -689,17 +689,17 @@ The +show+ action uses +Post.find+ to search for a single record in the database <p class="notice"><%= notice %></p> <p> - <strong>Name:</strong> + <b>Name:</b> <%= @post.name %> </p> <p> - <strong>Title:</strong> + <b>Title:</b> <%= @post.title %> </p> <p> - <strong>Content:</strong> + <b>Content:</b> <%= @post.content %> </p> @@ -752,7 +752,7 @@ def update end </ruby> -In the +update+ action, Rails first uses the +:id+ parameter passed back from the edit view to locate the database record that's being edited. The +update_attributes+ call then takes the rest of the parameters from the request and applies them to this record. If all goes well, the user is redirected to the post's +show+ view. If there are any problems, it's back to +edit+ to correct them. +In the +update+ action, Rails first uses the +:id+ parameter passed back from the edit view to locate the database record that's being edited. The +update_attributes+ call then takes the rest of the parameters from the request and applies them to this record. If all goes well, the user is redirected to the post's +show+ view. If there are any problems, it's back to the +edit+ view to correct them. h4. Destroying a Post @@ -774,7 +774,7 @@ The +destroy+ method of an Active Record model instance removes the correspondin h3. Adding a Second Model -Now that you've seen what's in a model built with scaffolding, it's time to add a second model to the application. The second model will handle comments on blog posts. +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. h4. Generating a Model @@ -904,17 +904,17 @@ So first, we'll wire up the Post show template (+/app/views/posts/show.html.erb+ <p class="notice"><%= notice %></p> <p> - <strong>Name:</strong> + <b>Name:</b> <%= @post.name %> </p> <p> - <strong>Title:</strong> + <b>Title:</b> <%= @post.title %> </p> <p> - <strong>Content:</strong> + <b>Content:</b> <%= @post.content %> </p> @@ -961,29 +961,29 @@ Once we have made the new comment, we send the user back to the original post us <p class="notice"><%= notice %></p> <p> - <strong>Name:</strong> + <b>Name:</b> <%= @post.name %> </p> <p> - <strong>Title:</strong> + <b>Title:</b> <%= @post.title %> </p> <p> - <strong>Content:</strong> + <b>Content:</b> <%= @post.content %> </p> <h2>Comments</h2> <% @post.comments.each do |comment| %> <p> - <strong>Commenter:</strong> + <b>Commenter:</b> <%= comment.commenter %> </p> <p> - <strong>Comment:</strong> + <b>Comment:</b> <%= comment.body %> </p> <% end %> @@ -1023,12 +1023,12 @@ First we will make a comment partial to extract showing all the comments for the <erb> <p> - <strong>Commenter:</strong> + <b>Commenter:</b> <%= comment.commenter %> </p> <p> - <strong>Comment:</strong> + <b>Comment:</b> <%= comment.body %> </p> </erb> @@ -1039,17 +1039,17 @@ Then in the +app/views/posts/show.html.erb+ you can change it to look like the f <p class="notice"><%= notice %></p> <p> - <strong>Name:</strong> + <b>Name:</b> <%= @post.name %> </p> <p> - <strong>Title:</strong> + <b>Title:</b> <%= @post.title %> </p> <p> - <strong>Content:</strong> + <b>Content:</b> <%= @post.content %> </p> @@ -1110,17 +1110,17 @@ Then you make the +app/views/posts/show.html.erb+ look like the following: <p class="notice"><%= notice %></p> <p> - <strong>Name:</strong> + <b>Name:</b> <%= @post.name %> </p> <p> - <strong>Title:</strong> + <b>Title:</b> <%= @post.title %> </p> <p> - <strong>Content:</strong> + <b>Content:</b> <%= @post.content %> </p> @@ -1149,12 +1149,12 @@ So first, let's add the delete link in the +app/views/comments/_comment.html.erb <erb> <p> - <strong>Commenter:</strong> + <b>Commenter:</b> <%= comment.commenter %> </p> <p> - <strong>Comment:</strong> + <b>Comment:</b> <%= comment.body %> </p> @@ -1191,7 +1191,7 @@ The +destroy+ action will find the post we are looking at, locate the comment wi h4. Deleting Associated Objects -If you decide at some point to delete a post, you likely want to delete the comments associated with that post as well. You can do so by taking advantage of the association option +dependent+. All you need to do is modify the +post.rb+ as follows: +If you delete a post then it's 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 @@ -1204,9 +1204,9 @@ end h3. Security -Before you publish your blog online, you will most likely want to prevent just anyone from being able to add, edit and delete posts or delete comments. +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 <tt>app/controllers/application_controller.rb</tt>: +Rails provides a very simple HTTP authentication system that will work nicely in this situation. First, we enable simple HTTP based authentication in our <tt>app/controllers/application_controller.rb</tt>: <ruby> class ApplicationController < ActionController::Base @@ -1261,7 +1261,7 @@ Now if you try to create a new post, you will be greeted with a basic HTTP Authe h3. Building a Multi-Model Form -Another piece of your average blog is the ability to tag posts. This requires that your application edits more than one thing on a single form. Rails offers support for nested forms. +Another feature of your average blog is the ability to tag posts. To implement this feature your application needs to interact with more than one model on a single form. Rails offers support for nested forms. To demonstrate this, we will 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: @@ -1298,7 +1298,16 @@ We will modify +views/posts/_form.html.erb+ to render a partial to make a tag: <erb> <% @post.tags.build %> <%= form_for(@post) do |post_form| %> - <%= post_form.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"> <%= post_form.label :name %><br /> @@ -1321,9 +1330,9 @@ We will modify +views/posts/_form.html.erb+ to render a partial to make a tag: <% end %> </erb> -This example shows another option of the render helper, being able to pass in local variables, in this case, we want the local variable +form+ in the partial to refer to the +post_form+ object. +Note that we have changed the +f+ in +form_for(@post) do |f|+ to +post_form+ to make it easier to understand what is going on. -You will also note that we also have changed the +f+ in <tt>form_for(@post) do |f|</tt> to <tt>post_form</tt> to clarify what is going on somewhat. +This example shows another option of the render helper, being able to pass in local variables, in this case, we want the local variable +form+ in the partial to refer to the +post_form+ object. We also add a <tt>@post.tags.build</tt> at the top of this form, this is to make sure there is a new tag ready to have it's name filled in by the user. If you do not build the new tag, then the form will not appear as there is no new Tag object ready to create. @@ -1350,22 +1359,22 @@ Finally, we will edit the <tt>app/views/posts/show.html.erb</tt> template to sho <p class="notice"><%= notice %></p> <p> - <strong>Name:</strong> + <b>Name:</b> <%= @post.name %> </p> <p> - <strong>Title:</strong> + <b>Title:</b> <%= @post.title %> </p> <p> - <strong>Content:</strong> + <b>Content:</b> <%= @post.content %> </p> <p> - <strong>Tags:</strong> + <b>Tags:</b> <%= @post.tags.map { |t| t.name }.join(", ") %> </p> @@ -1405,22 +1414,22 @@ Now you can edit the view in <tt>app/views/posts/show.html.erb</tt> to look like <p class="notice"><%= notice %></p> <p> - <strong>Name:</strong> + <b>Name:</b> <%= @post.name %> </p> <p> - <strong>Title:</strong> + <b>Title:</b> <%= @post.title %> </p> <p> - <strong>Content:</strong> + <b>Content:</b> <%= @post.content %> </p> <p> - <strong>Tags:</strong> + <b>Tags:</b> <%= join_tags(@post) %> </p> @@ -1455,6 +1464,7 @@ h3. Changelog "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/2 +* April 30, 2010: Fixes, editing and updating of code samples by "Rohit Arondekar":http://rohitarondekar.com * 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 diff --git a/railties/guides/source/plugins.textile b/railties/guides/source/plugins.textile index 4af00a5ace..fc7c1e2625 100644 --- a/railties/guides/source/plugins.textile +++ b/railties/guides/source/plugins.textile @@ -53,7 +53,7 @@ h4. Generate the Plugin Skeleton Rails ships with a plugin generator which creates a basic plugin skeleton. Pass the plugin name, either 'CamelCased' or 'under_scored', as an argument. Pass +--with-generator+ to add an example generator also. -This creates a plugin in 'vendor/plugins' including an 'init.rb' and 'README' as well as standard 'lib', 'task', and 'test' directories. +This creates a plugin in +vendor/plugins+ including an +init.rb+ and +README+ as well as standard +lib+, +task+, and +test+ directories. Examples: <shell> @@ -104,27 +104,27 @@ To make it easy to organize your files and to make the plugin more compatible wi `-- init.rb </shell> -*vendor/plugins/yaffle/init.rb* - <ruby> +# vendor/plugins/yaffle/init.rb + require 'yaffle' </ruby> -Now you can add any 'require' statements to 'lib/yaffle.rb' and keep 'init.rb' clean. +Now you can add any +require+ statements to +lib/yaffle.rb+ and keep +init.rb+ clean. h3. Tests In this guide you will learn how to test your plugin against multiple different database adapters using Active Record. To setup your plugin to allow for easy testing you'll need to add 3 files: - * A 'database.yml' file with all of your connection strings - * A 'schema.rb' file with your table definitions + * A +database.yml+ file with all of your connection strings + * A +schema.rb+ file with your table definitions * A test helper method that sets up the database h4. Test Setup -*vendor/plugins/yaffle/test/database.yml:* - <yaml> +# vendor/plugins/yaffle/test/database.yml + sqlite: :adapter: sqlite :dbfile: vendor/plugins/yaffle/test/yaffle_plugin.sqlite.db @@ -150,9 +150,9 @@ mysql: For this guide you'll need 2 tables/models, Hickwalls and Wickwalls, so add the following: -*vendor/plugins/yaffle/test/schema.rb:* - <ruby> +# vendor/plugins/yaffle/test/schema.rb + ActiveRecord::Schema.define(:version => 0) do create_table :hickwalls, :force => true do |t| t.string :name @@ -170,9 +170,9 @@ ActiveRecord::Schema.define(:version => 0) do end </ruby> -*vendor/plugins/yaffle/test/test_helper.rb:* - <ruby> +# vendor/plugins/yaffle/test/test_helper.rb + ENV['RAILS_ENV'] = 'test' ENV['RAILS_ROOT'] ||= File.dirname(__FILE__) + '/../../../..' @@ -213,11 +213,11 @@ Now whenever you write a test that requires the database, you can call 'load_sch h4. Run the Plugin Tests -Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct. By default rails generates a file in 'vendor/plugins/yaffle/test/yaffle_test.rb' with a sample test. Replace the contents of that file with: - -*vendor/plugins/yaffle/test/yaffle_test.rb:* +Once you have these files in place, you can write your first test to ensure that your plugin-testing setup is correct. By default rails generates a file in +vendor/plugins/yaffle/test/yaffle_test.rb+ with a sample test. Replace the contents of that file with: <ruby> +# vendor/plugins/yaffle/test/yaffle_test.rb + require File.dirname(__FILE__) + '/test_helper.rb' class YaffleTest < Test::Unit::TestCase @@ -264,7 +264,7 @@ Finished in 0.002236 seconds. 1 test, 1 assertion, 0 failures, 0 errors </shell> -By default the setup above runs your tests with sqlite or sqlite3. To run tests with one of the other connection strings specified in database.yml, pass the DB environment variable to rake: +By default the setup above runs your tests with sqlite or sqlite3. To run tests with one of the other connection strings specified in +database.yml+, pass the DB environment variable to rake: <shell> rake DB=sqlite @@ -281,9 +281,9 @@ This section will explain how to add a method to String that will be available a In this example you will add a method to String named +to_squawk+. To begin, create a new test file with a few assertions: -* *vendor/plugins/yaffle/test/core_ext_test.rb* - <ruby> +# vendor/plugins/yaffle/test/core_ext_test.rb + require File.dirname(__FILE__) + '/test_helper.rb' class CoreExtTest < Test::Unit::TestCase @@ -311,19 +311,19 @@ NoMethodError: undefined method `to_squawk' for "Hello World":String Great - now you are ready to start development. -Then in 'lib/yaffle.rb' require 'lib/core_ext.rb': - -* *vendor/plugins/yaffle/lib/yaffle.rb* +Then in +lib/yaffle.rb+ require +lib/core_ext.rb+: <ruby> +# vendor/plugins/yaffle/lib/yaffle.rb + require "yaffle/core_ext" </ruby> -Finally, create the 'core_ext.rb' file and add the 'to_squawk' method: - -* *vendor/plugins/yaffle/lib/yaffle/core_ext.rb* +Finally, create the +core_ext.rb+ file and add the +to_squawk+ method: <ruby> +# vendor/plugins/yaffle/lib/yaffle/core_ext.rb + String.class_eval do def to_squawk "squawk! #{self}".strip @@ -331,7 +331,7 @@ String.class_eval do end </ruby> -To test that your method does what it says it does, run the unit tests with +rake+ from your plugin directory. To see this in action, fire up a console and start squawking: +To test that your method does what it says it does, run the unit tests with +rake+ from your plugin directory. To see this in action, fire up a console and start squawking: <shell> $ rails console @@ -345,13 +345,13 @@ When Rails loads plugins it looks for a file named +init.rb+. However, when the NOTE: The plugins loader also looks for +rails/init.rb+, but that one is deprecated in favor of the top-level +init.rb+ aforementioned. -Under certain circumstances if you reopen classes or modules in +init.rb+ you may inadvertently create a new class, rather than reopening an existing class. A better alternative is to reopen the class in a different file, and require that file from +init.rb+, as shown above. +Under certain circumstances if you reopen classes or modules in +init.rb+ you may inadvertently create a new class, rather than reopening an existing class. A better alternative is to reopen the class in a different file, and require that file from +init.rb+, as shown above. If you must reopen a class in +init.rb+ you can use +module_eval+ or +class_eval+ to avoid any issues: -* *vendor/plugins/yaffle/init.rb* - <ruby> +# vendor/plugins/yaffle/init.rb + Hash.class_eval do def is_a_special_hash? true @@ -361,9 +361,9 @@ end Another way is to explicitly define the top-level module space for all modules and classes, like +::Hash+: -* *vendor/plugins/yaffle/init.rb* - <ruby> +# vendor/plugins/yaffle/init.rb + class ::Hash def is_a_special_hash? true diff --git a/railties/lib/rails/generators/rails/app/templates/README b/railties/lib/rails/generators/rails/app/templates/README index ded8570c42..65d1459d0e 100644 --- a/railties/lib/rails/generators/rails/app/templates/README +++ b/railties/lib/rails/generators/rails/app/templates/README @@ -45,8 +45,8 @@ suitable for development and deployment of Rails applications. If you have Ruby getting up and running with mongrel is as easy as: <tt>gem install mongrel</tt>. More info at: http://mongrel.rubyforge.org -Say other Ruby web servers like Thin and Ebb or regular web servers like Apache or LiteSpeed or -Lighttpd or IIS. The Ruby web servers are run through Rack and the latter can either be setup to use +You can also use other Ruby web servers like Thin and Ebb or regular web servers like Apache, LiteSpeed, +Lighttpd, or IIS. The Ruby web servers are run through Rack and the others can be setup to use FCGI or proxy to a pack of Mongrels/Thin/Ebb servers. == Apache .htaccess example for FCGI/CGI @@ -116,14 +116,14 @@ the Ruby logger class from inside your controllers. Example: The result will be a message in your log file along the lines of: - Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1 + Mon Oct 08 14:22:29 +1000 2007 Destroyed Weblog ID #1! More information on how to use the logger is at http://www.ruby-doc.org/core/ Also, Ruby documentation can be found at http://www.ruby-lang.org/ including: * The Learning Ruby (Pickaxe) Book: http://www.ruby-doc.org/docs/ProgrammingRuby/ -* Learn to Program: http://pine.fm/LearnToProgram/ (a beginners guide) +* Learn to Program: http://pine.fm/LearnToProgram/ (a beginner's guide) These two online (and free) books will bring you up to speed on the Ruby language and also on programming in general. |